reg_key.hpp

用STL的方式封装了WindowsAPI、COM调用、ACE、ATL、MFC、WTL等多种组件

     *  then the instance constructed will be empty, as denoted by a <code>NULL</code>
     *  value returned from the get_key_handle() method.
     */
    basic_reg_key(class_type const &rhs, REGSAM accessMask);

    /// \brief Destructor
    ///
    /// Releases any resources allocated by the instance, including closing the
    /// underlying registry key.
    ~basic_reg_key() stlsoft_throw_0();

    /// \brief Copy assignment operator
    class_type &operator =(class_type const &rhs);
/// @}

/// \name Attributes
/// @{
public:
    /// \brief The name of the key
    string_type const       &name() const;
    /// \brief The registry class of the key
    string_type             reg_class() const;
    /// \brief The number of sub-keys
    ///
    /// \note This is not a constant-time operation
    size_type               num_sub_keys() const;
    /// \brief The number of values
    ///
    /// \note This is not a constant-time operation
    size_type               num_values() const;

    /** \brief The handle to the underlying Registry API key.
     *
     * \note If \ref page__exception_agnostic "exception handling is not enabled",
     *  then this method will return <code>NULL</code> in the case where an
     *  instance constructor failed to open the key with the requested permissions.
     */
    hkey_type               get_key_handle() const;
    /// \brief The handle to the underlying Registry API key.
    ///
    /// \note Equivalent to get_key_handle()
    hkey_type               get() const;

#if 0
    subkeys_collection_type subkeys() const;
    value_collection_type   values() const;
#endif /* 0 */

    /// \brief The access mask associated with the key
    REGSAM                  get_access_mask() const;
/// @}

/// \name Sub-key operations
/// @{
public:
    /// \brief Opens the named sub-key of this key
    class_type  open_sub_key(char_type const *subKeyName, REGSAM accessMask = KEY_ALL_ACCESS);
#ifdef STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT
    template <ss_typename_param_k S>
    class_type  open_sub_key(S const &subKeyName, REGSAM accessMask = KEY_ALL_ACCESS)
    {
        return open_sub_key_(stlsoft_ns_qual(c_str_ptr)(subKeyName), accessMask);
    }
#endif /* STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT */

    /** \brief Creates a named sub-key of this key
     *
     * \param subKeyName Name of the subkey to created. If <code>NULL</code> or the
     *  empty string, then the function returns a copy of the callee.
     * \param accessMask A mask of <code>KEY_*</code> flags that define the
     *  required access to the key.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown indicating why the given key could not be created. If not,
     *  then the instance constructed will be empty, as denoted by a <code>NULL</code>
     *  value returned from the get_key_handle() method.
     */
    class_type  create_sub_key(char_type const *subKeyName, REGSAM accessMask = KEY_ALL_ACCESS);
#ifdef STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT
    /** \brief Creates a named sub-key of this key
     *
     * \param subKeyName Name of the subkey to created. If <code>NULL</code> or the
     *  empty string, then the function returns a copy of the callee.
     * \param accessMask A mask of <code>KEY_*</code> flags that define the
     *  required access to the key.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown indicating why the given key could not be created. If not,
     *  then the instance constructed will be empty, as denoted by a <code>NULL</code>
     *  value returned from the get_key_handle() method.
     */
    template <ss_typename_param_k S>
    class_type  create_sub_key(S const &subKeyName, REGSAM accessMask = KEY_ALL_ACCESS)
    {
        return create_sub_key_(stlsoft_ns_qual(c_str_ptr)(subKeyName), accessMask);
    }
#endif /* STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT */

    /** \brief Deletes the named sub-key of this key
     *
     * \param subKeyName The name of the sub-key to be deleted.
     *
     * \return Indicates whether the sub-key was deleted.
     * \retval true The sub-key existed and was successfully deleted.
     * \retval false The sub-key does not exist. (<b>Note</b>:
     *  if \ref page__exception_agnostic "exception handling is not enabled",
     *  then false will also be returned for any other reason, and the
     *  reason will be available via <code>::GetLastError()</code>.)
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the sub-key exists but cannot be deleted.
     */
    bool_type   delete_sub_key(char_type const *subKeyName);
#ifdef STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT
    /** \brief Deletes the named sub-key of this key
     *
     * \param subKeyName The name of the sub-key to be deleted.
     *
     * \return Indicates whether the sub-key was deleted.
     * \retval true The sub-key existed and was successfully deleted.
     * \retval false The sub-key does not exist. (<b>Note</b>:
     *  if \ref page__exception_agnostic "exception handling is not enabled",
     *  then false will also be returned for any other reason, and the
     *  reason will be available via <code>::GetLastError()</code>.)
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the sub-key exists but cannot be deleted.
     */
    template <ss_typename_param_k S>
    class_type  delete_sub_key(S const &subKeyName)
    {
        return delete_sub_key_(stlsoft_ns_qual(c_str_ptr)(subKeyName));
    }
#endif /* STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT */
/// @}

    /// \brief Returns a duplicate of the key's handle, if any.
    /// 
    /// \param accessMask The access mask for the 
    /// \param result A pointer to a variable (of type result_type) into
    ///   which will be written the result of the underlying registry API
    ///   call.
    ///
    /// \return 
    ///
    /// \note The handle returned from this method <b>must</b> be closed with RegCloseKey()
    hkey_type   dup_key_handle( REGSAM      accessMask  =   KEY_ALL_ACCESS
                            ,   result_type *result     =   NULL);

/// \name Value operations
/// @{
public:
    /** \brief Sets the named value to the value of the given 32-bit integer.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the value cannot be set.
     */
    bool_type   set_value(char_type const *valueName, DWORD value);
#ifdef STLSOFT_CF_64BIT_INT_SUPPORT
    /** \brief Sets the named value to the value of the given 64-bit integer.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the value cannot be set.
     */
    bool_type   set_value(char_type const *valueName, ws_uint64_t value);
#endif /* STLSOFT_CF_64BIT_INT_SUPPORT */
    /** \brief Sets the named value to the value of the given string.
    ///
    /// \param valueName The name of the value.
    /// \param value The value of the value
    /// \param type The type of the value. Must be one of REG_SZ, REG_EXPAND_SZ or REG_MULTI_SZ.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the value cannot be set.
     */
    bool_type   set_value(char_type const *valueName, char_type const *value, ws_uint_t type = REG_SZ);
    /** \brief Sets the named value to the values of the given string array.
    ///
    /// \param valueName The name of the value.
    /// \param values The string array.
    /// \param numValues Number of elements in the string array.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the value cannot be set.
     */
    bool_type   set_value(char_type const *valueName, char_type const **values, size_type numValues);
    /** \brief Sets the named value to the given binary value.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the value cannot be set.
     */
    bool_type   set_value(char_type const *valueName, void const *value, size_type cbValue);

#ifdef STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT
    /** \brief Sets the named value to the value of the given 32-bit integer.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the value cannot be set.
     */
    template <ss_typename_param_k S>
    bool_type   set_value(S const &valueName, DWORD value)
    {
        return set_value_(stlsoft_ns_qual(c_str_ptr)(valueName), value);
    }
#endif /* STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT */
#ifdef STLSOFT_CF_64BIT_INT_SUPPORT
# ifdef STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT
    /** \brief Sets the named value to the value of the given 64-bit integer.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the value cannot be set.
     */
    template <ss_typename_param_k S>
    bool_type   set_value(S const &valueName, ws_uint64_t value)
    {
        return set_value_(stlsoft_ns_qual(c_str_ptr)(valueName), value);
    }
# endif /* STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT */
#endif /* STLSOFT_CF_64BIT_INT_SUPPORT */
#ifdef STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT
    /** \brief Sets the named value to the value of the given string.
    ///
    /// \param valueName The name of the value.
    /// \param value The value of the value
    /// \param type The type of the value. Must be one of REG_SZ, REG_EXPAND_SZ or REG_MULTI_SZ.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the value cannot be set.
     */
    template <ss_typename_param_k S>
    bool_type   set_value(S const &valueName, char_type const *value, ws_uint_t type = REG_SZ)
    {
        return set_value_(stlsoft_ns_qual(c_str_ptr)(valueName), value, type);
    }
#endif /* STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT */
#ifdef STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT
    /** \brief Sets the named value to the values of the given string array.
    ///
    /// \param valueName The name of the value.
    /// \param values The string array.
    /// \param numValues Number of elements in the string array.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the value cannot be set.
     */
    template <ss_typename_param_k S>
    bool_type   set_value(S const &valueName, char_type const **values, size_type numValues)
    {
        return set_value_(stlsoft_ns_qual(c_str_ptr)(valueName), values, numValues);
    }
#endif /* STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT */
#ifdef STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT
    /** \brief Sets the named value to the given binary value.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the value cannot be set.
     */
    template <ss_typename_param_k S>
    bool_type   set_value(S const &valueName, void const *value, size_type cbValue)
    {
        return set_value_(stlsoft_ns_qual(c_str_ptr)(valueName), value, cbValue);
    }
#endif /* STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT */
    /** \brief Sets the named value to the given integer (stored as an unsigned value).
    ///
    /// \note This method is provided solely to disambiguate between the DWORD and ws_uint64_t overloads
    /// when using integer literals.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the value cannot be set.
     */
    bool_type   set_value(char_type const *valueName, int value);
#ifdef STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT
    /** \brief Sets the named value to the given integer (stored as an unsigned value).
    ///
    /// \note This method is provided solely to disambiguate between the DWORD and ws_uint64_t overloads
    /// when using integer literals.
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink
     *  will be thrown if the value cannot be set.
     */
    template <ss_typename_param_k S>
    bool_type   set_value(S const &valueName, int value)
    {
        return set_value_(stlsoft_ns_qual(c_str_ptr)(valueName), value);
    }
#endif /* STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT */
    /** \brief Deletes the named value.
     *
     * \param valueName The name of the value to be deleted.
     *
     * \return Indicates whether the value was deleted.
     * \retval true The value existed and was successfully deleted.
     * \retval false The value does not exist. (<b>Note</b>:
     *  if \ref page__exception_agnostic "exception handling is not enabled",
     *  then false will also be returned for any other reason, and the
     *  reason will be available via <code>::GetLastError()</code>.)
     *
     * \exception registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink