home / products / comet / documentation
Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Namespace Members | Class Members | File Members | Related Pages

comet::registry::key< error_policy > Class Template Reference

#include <comet/registry.h>

List of all members.

Public Types

typedef value< error_policy > mapped_type
typedef info< error_policy > info_type
 Type returned by enumerate().
typedef info_type::subkeys_type subkeys_type
 Type returned by enumerate().subkeys().
typedef info_type::values_type values_type
 Type returned by enumerate().values().
typedef info_type::value_names_type value_names_type
 Type returned by enumerate().value_names().

Public Member Functions

 key (HKEY key_handle=0)
 key (const key &rhs)
 Copy a key.
 key (const impl::key_base &rhs)
 Copy a key.
void swap (key &rhs)
 operator const void * () const throw ()
 Operator overload to allow you to put key instances in a conditional.
key open (const tstring &subkey, REGSAM sam_desired=KEY_ALL_ACCESS) const
 Open a subkey.
key open_nothrow (const tstring &subkey, REGSAM sam_desired=KEY_ALL_ACCESS, LONG *errcode=0) const
 Open a subkey, no exceptions.
key create (const tstring &subkey, DWORD options=REG_OPTION_NON_VOLATILE, REGSAM sam_desired=KEY_ALL_ACCESS, LPSECURITY_ATTRIBUTES security_attributes=0, LPDWORD disposition=0) const
 Create a subkey.
key create_nothrow (const tstring &subkey, DWORD options=REG_OPTION_NON_VOLATILE, REGSAM sam_desired=KEY_ALL_ACCESS, LPSECURITY_ATTRIBUTES security_attributes=0, LPDWORD disposition=0, LONG *errcode=0) const
 Create a subkey - no exceptions.
void flush () const
 Call RegFlushKey with the contained key.
LONG flush_nothrow () const
 Call RegFlushKey with the contained key - no exceptions.
void delete_subkey (const tstring &subkey) const
 Delete the subkey.
LONG delete_subkey_nothrow (const tstring &subkey) const
 Delete the subkey.
void delete_value (const tstring &value_name) const
 delete a value
LONG delete_value_nothrow (const tstring &value_name) const
 delete a value - no exceptions
void close ()
 Release reference to the key.
HKEY get () const
 Get access to the raw key without releasing ownership.
mapped_type get_value (const tstring &value_name=_T("")) const
 Get a reference to a value in the registry.
mapped_type operator[] (const tstring &value_name) const
 Subscript operator overload - syntactic sugar for get_value().
info_type enumerate () const
 Enumerate the subkeys, values or value_names, or obtain other information about the key. See also info.
key & operator * ()
 Part of making key into an output iterator.
template<typename T> key & operator= (const T &val)
 Assignment. This is designed to work with 'std::pair's - the value type of map classes.
key & operator= (const key &rhs)
key & operator++ ()
 Noop increment.
key & operator++ (int)
 Noop decrement.

Detailed Description

template<class error_policy>
class comet::registry::key< error_policy >

Registry key wrapper. Because an HKEY cannot be duplicated in a platform independent way, reference counting is used to enable copying of key objects.

Methods with the _nothrow suffix do not throw exceptions other than std::bad_alloc.

Key instances can be used as output iterators for std::pair assignments. The second argument of each pair must be assignable to an instance of regkey::mapped_type. Currently, this means that the second member of each pair must be convertable to either an int, unsigned int, or std::basic_string<TCHAR>. Example: 

                   regkey the_key = regkey(HKEY_LOCAL_MACHINE).open("Software\\Comet");
                   map<string,string> names;
                   names["one"] = "one";
                   names["two"] = "two";
                   copy(names.begin(), names.end(), the_key);
                   map<string,int> values;
                   values["three"] = 3;
                   values["four"] = 4;
                   copy(values.begin(), values.end(), the_key);

Constructor & Destructor Documentation

template<class error_policy>
comet::registry::key< error_policy >::key (  const key< error_policy > &  rhs  )  [inline]
 

Copy a key.

In reality this only increments a reference count. We have to use reference counting because ::DuplicateHandle does not work for registry keys on windows 95/98.

template<class error_policy>
comet::registry::key< error_policy >::key (  const impl::key_base &  rhs  )  [inline]
 

Copy a key.

This is useful for attaching to keys from a name iterator.

Member Function Documentation

template<class error_policy>
void comet::registry::key< error_policy >::close (   )  [inline]
 

Release reference to the key.

Note that this will only call ::RegCloseKey if this was the last reference to the outstanding key. This method is implicitly called by the destructor.

template<class error_policy>
void comet::registry::key< error_policy >::delete_subkey (  const tstring &  subkey  )  const [inline]
 

Delete the subkey.

Warning - the behaviour is different between WinNT and Win95/98 if sub keys are present. See documentation for ::RegDeleteKey for more information.

template<class error_policy>
LONG comet::registry::key< error_policy >::delete_subkey_nothrow (  const tstring &  subkey  )  const [inline]
 

Delete the subkey.

Warning - the behaviour is different between WinNT and Win95/98 if sub keys are present. See documentation for ::RegDeleteKey for more information.

template<class error_policy>
info_type comet::registry::key< error_policy >::enumerate (   )  const [inline]
 

Enumerate the subkeys, values or value_names, or obtain other information about the key. See also info.

The enumerate() method effectively calls RegQueryInfoKey, so you should minimize the number of calls to enumerate() if efficiency is a concern. e.g. The following 

                        regkey::info_type info = key.enumerate();
                        copy(info.values().begin(), info.values().end(), inserter(value_map, value_map.end()));
is more efficient than 
                        copy(key.enumerate().values().begin(), key.enumerate().values().end(), inserter(value_map, value_map.end()));
The second version will end up calling RegQueryInfoKey twice.

template<class error_policy>
mapped_type comet::registry::key< error_policy >::get_value (  const tstring &  value_name = _T("")  )  const [inline]
 

Get a reference to a value in the registry.

The returned value can be used on both sides of an assignment. Example: 

                        key.get_value("Name") = "Paul";
                        string name = key.get_value("Name");
                        cout << key.get_value("Name").str() << endl;

template<class error_policy>
comet::registry::key< error_policy >::operator const void * (   )  const throw () [inline]
 

Operator overload to allow you to put key instances in a conditional.

This operator allows you to write code like this: 

                        if(subkey = key(HKEY_LOCAL_MACHINE).open_nothrow(_T("Software")))
                        {
                           ...
                        };
const void * is used instead of the more obvious "bool" to disable implicit conversions to int and the like. Example: 
                        int success = key(HKEY_LOCAL_MACHINE).open_nothrow(_T("Software")); // Won't compile fortunately!!

template<class error_policy>
key& comet::registry::key< error_policy >::operator= (  const key< error_policy > &  rhs  )  [inline]
 

Exception safe assignment operator. Can still throw std::bad_alloc due to reference counting.

template<class error_policy>
mapped_type comet::registry::key< error_policy >::operator[] (  const tstring &  value_name  )  const [inline]
 

Subscript operator overload - syntactic sugar for get_value().

Example: 

                                key["Name"] = "Paul";
                                string name = key["Name"];
                                cout << key["Name"].str() << endl;

The documentation for this class was generated from the following file:
Copyright 2002 Sofus Mortensen. All rights reserved.