reg_key.hpp

新版本TR1的stl

        : m_hkey(open_key_(keyParent.get_key_handle(), keyName, accessMask))
        , m_name(keyName)
        , m_accessMask(accessMask)
    {} // Implementation is within class, otherwise VC5 will not link
#ifdef STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT
    /** \brief Construct from the named sub-key of the given parent
     *
     * \param keyParent A handle to the parent key, whose named subkey is
     *  to be opened.
     * \param keyName The name of the subkey to open. If <code>NULL</code>
     *  or the empty string, then a copy of <code>keyParent</code> will be
     *  opened.
     * \param accessMask A mask of <code>KEY_*</code> flags that define the
     *  required access to the key. Defaults to KEY_ALL_ACCESS.
     *
     * \exception winstl::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 opened. 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>
    basic_reg_key(class_type const& keyParent, S const& keyName, REGSAM accessMask = KEY_ALL_ACCESS)
        : m_hkey(open_key_(keyParent.get_key_handle(), stlsoft_ns_qual(c_str_ptr)(keyName), accessMask))
        , m_name(keyName)
        , m_accessMask(accessMask)
    {} // Implementation is within class, otherwise VC5 will not link
#endif /* STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT */
    /** \brief Constructs an instance as a (logical) copy of another.
     *
     * \param rhs Instance whose key will be opened by the new instance.
     *
     * \note The instance will hold a <i>different</i> handle to the
     *  <i>same</i> registry key.
     *
     * \exception winstl::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 opened. If not,
     *  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);
    /** \brief Constructs an instance as a (logical) copy of another, but with different permissions.
     *
     * \param rhs Instance whose key will be opened by the new instance.
     * \param accessMask The permissions for the new instance.
     *
     * \note The instance will hold a <i>different</i> handle to the
     *  <i>same</i> registry key.
     *
     * \exception winstl::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 opened. If not,
     *  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. Defaults to KEY_ALL_ACCESS.
     *
     * \exception winstl::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. Defaults to KEY_ALL_ACCESS.
     *
     * \exception winstl::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 Creates a named sub-key of a given key
     *
     * \param hkey The parent registry 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. Defaults to KEY_ALL_ACCESS.
     *
     * \exception winstl::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.
     */
    static class_type create_key(HKEY hkey, 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 key The parent registry 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. Defaults to KEY_ALL_ACCESS.
     *
     * \exception winstl::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 H, ss_typename_param_k S>
    static class_type create_key(H const& key, S const& subKeyName, REGSAM accessMask = KEY_ALL_ACCESS)
    {
        return create_key(get_HKEY(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 winstl::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 winstl::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 res 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 *res        =   NULL);

/// \name Value operations
/// @{
public:
    /** \brief Sets the named value to the value of the given 32-bit integer.
     *
     * \exception winstl::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 winstl::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 winstl::registry_exception If \ref page__exception_agnostic "exception handling is enabled",
     *  an instance of \link winstl::registry_exception registry_exception\endlink