reg_key.hpp

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

/* /////////////////////////////////////////////////////////////////////////
 * File:        winstl/registry/reg_key.hpp (formerly winstl_reg_key.h)
 *
 * Purpose:     Contains the basic_reg_key class template, and ANSI
 *              and Unicode specialisations thereof.
 *
 * Created:     19th January 2002
 * Updated:     10th June 2006
 *
 * Home:        http://stlsoft.org/
 *
 * Copyright (c) 2002-2006, Matthew Wilson and Synesis Software
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * - Redistributions of source code must retain the above copyright notice, this
 *   list of conditions and the following disclaimer.
 * - Redistributions in binary form must reproduce the above copyright notice,
 *   this list of conditions and the following disclaimer in the documentation
 *   and/or other materials provided with the distribution.
 * - Neither the name(s) of Matthew Wilson and Synesis Software nor the names of
 *   any contributors may be used to endorse or promote products derived from
 *   this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 *
 * ////////////////////////////////////////////////////////////////////// */


/// \file winstl/registry/reg_key.hpp
/// \brief [C++ only] Definition of the \link winstl::basic_reg_key basic_reg_key\endlink class template. (\ref group__library__windows_registry "Windows Registry" Library.)

#ifndef WINSTL_INCL_WINSTL_REGISTRY_HPP_REG_KEY
#define WINSTL_INCL_WINSTL_REGISTRY_HPP_REG_KEY

#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
# define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_KEY_MAJOR       3
# define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_KEY_MINOR       3
# define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_KEY_REVISION    10
# define WINSTL_VER_WINSTL_REGISTRY_HPP_REG_KEY_EDIT        103
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

/* /////////////////////////////////////////////////////////////////////////
 * Includes
 */

#ifndef WINSTL_INCL_WINSTL_H_WINSTL
# include <winstl/winstl.h>
#endif /* !WINSTL_INCL_WINSTL_H_WINSTL */
#ifndef WINSTL_INCL_WINSTL_REGISTRY_HPP_REGFWD
# include <winstl/registry/regfwd.hpp>
#endif /* !WINSTL_INCL_WINSTL_REGISTRY_HPP_REGFWD */
#ifndef WINSTL_INCL_WINSTL_REGISTRY_HPP_DEFS
# include <winstl/registry/defs.hpp>
#endif /* !WINSTL_INCL_WINSTL_REGISTRY_HPP_DEFS */
#ifndef WINSTL_INCL_WINSTL_REGISTRY_HPP_REG_TRAITS
# include <winstl/registry/reg_traits.hpp>
#endif /* !WINSTL_INCL_WINSTL_REGISTRY_HPP_REG_TRAITS */
#ifndef WINSTL_INCL_WINSTL_REGISTRY_HPP_EXCEPTIONS
# include <winstl/registry/exceptions.hpp>
#endif /* !WINSTL_INCL_WINSTL_REGISTRY_HPP_EXCEPTIONS */
#ifndef STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER
# include <stlsoft/memory/auto_buffer.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_MEMORY_HPP_AUTO_BUFFER */
#ifndef WINSTL_INCL_WINSTL_MEMORY_HPP_PROCESSHEAP_ALLOCATOR
# include <winstl/memory/processheap_allocator.hpp>
#endif /* !WINSTL_INCL_WINSTL_MEMORY_HPP_PROCESSHEAP_ALLOCATOR */
#ifndef STLSOFT_INCL_STLSOFT_HPP_STRING_ACCESS
# include <stlsoft/string_access.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_HPP_STRING_ACCESS */
#ifndef STLSOFT_INCL_STLSOFT_META_HPP_YESNO
# include <stlsoft/meta/yesno.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_META_HPP_YESNO */
#ifndef STLSOFT_INCL_STLSOFT_UTIL_HPP_STD_SWAP
# include <stlsoft/util/std_swap.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_UTIL_HPP_STD_SWAP */
#ifndef STLSOFT_INCL_STLSOFT_ITERATORS_HPP_TRANSFORM_ITERATOR
# include <stlsoft/iterators/transform_iterator.hpp>
#endif /* !STLSOFT_INCL_STLSOFT_ITERATORS_HPP_TRANSFORM_ITERATOR */
#include <numeric>

#ifdef STLSOFT_UNITTEST
# include <winstl/registry/reg_value.hpp>
#endif /* STLSOFT_UNITTEST */

/* /////////////////////////////////////////////////////////////////////////
 * Namespace
 */

#ifndef _WINSTL_NO_NAMESPACE
# if defined(_STLSOFT_NO_NAMESPACE) || \
     defined(STLSOFT_DOCUMENTATION_SKIP_SECTION)
/* There is no stlsoft namespace, so must define ::winstl */
namespace winstl
{
# else
/* Define stlsoft::winstl_project */

namespace stlsoft
{

namespace winstl_project
{

# endif /* _STLSOFT_NO_NAMESPACE */
#endif /* !_WINSTL_NO_NAMESPACE */

/* /////////////////////////////////////////////////////////////////////////
 * Classes
 */

/** \brief Represents a registry key, and provides methods for manipulating its
 * values and sub-keys.
 *
 * \ingroup group__library__windows_registry
 *
 * This class acts as the value type of classes that manipulate registry keys
 * and encapsulates the concept of a registry key.
 *
 * \param C The character type
 * \param T The traits type. On translators that support default template arguments this defaults to reg_traits<C>
 * \param A The allocator type. On translators that support default template arguments this defaults to processheap_allocator<C>
 */
template<   ss_typename_param_k C
#ifdef STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT
        ,   ss_typename_param_k T = reg_traits<C>
        ,   ss_typename_param_k A = processheap_allocator<C>
#else /* ? STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT */
        ,   ss_typename_param_k T /* = reg_traits<C> */
        ,   ss_typename_param_k A /* = processheap_allocator<C> */
#endif /* STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT */
        >
class basic_reg_key
{
/// \name Member Types
/// @{
public:
    /// \brief The character type
    typedef C                                           char_type;
    /// \brief The traits type
    typedef T                                           traits_type;
    /// \brief The allocator type
    typedef A                                           allocator_type;
    /// \brief The current parameterisation of the type
    typedef basic_reg_key<C, T, A>                      class_type;
    /// \brief The size type
    typedef ss_typename_type_k traits_type::size_type   size_type;
    /// \brief The string type
    typedef ss_typename_type_k traits_type::string_type string_type;
    /// \brief The key type
#if defined(STLSOFT_COMPILER_IS_MSVC) && \
    _MSC_VER == 1100
    /* WSCB: VC5 has an internal compiler error if use traits_type::hkey_type */
    typedef HKEY                                        hkey_type;
#else /* ? compiler */
    typedef ss_typename_type_k traits_type::hkey_type   hkey_type;
#endif /* compiler */
    /// \brief The Boolean type
    typedef ws_bool_t                                   bool_type;
    /// \brief The type of the key's values
    typedef basic_reg_value<C, T, A>                    key_value_type;
#if 0
    /// \brief The type of the sub-key collection
    typedef basic_reg_key_sequence<C, T, A>             subkeys_collection_type;
    /// \brief The type of the value collection
    typedef basic_reg_value_sequence<C, T, A>           value_collection_type;
#endif /* 0 */
private:
    /// \brief The results type of the Registry API
    typedef ss_typename_type_k traits_type::result_type result_type;
/// @}

/// \name Construction
/// @{
private:
#ifndef STLSOFT_DOCUMENTATION_SKIP_SECTION
    friend class basic_reg_value_sequence<C, T, A>;
    friend class basic_reg_key_sequence<C, T, A>;
#endif /* !STLSOFT_DOCUMENTATION_SKIP_SECTION */

#if defined(STLSOFT_COMPILER_IS_MSVC) && \
    (   _MSC_VER == 1200 || \
        _MSC_VER == 1300)
public:
#endif /* compiler */
    basic_reg_key(hkey_type *hkey, string_type const &keyName, REGSAM accessMask);
public:
    /// \brief Default constructor
    basic_reg_key();
    /** \brief Construct from the named sub-key of the given parent
     *
     * \param hkeyParent 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>hkeyParent</code> will be
     *  opened.
     * \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 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(hkey_type hkeyParent, char_type const *keyName, REGSAM accessMask = KEY_ALL_ACCESS)
        : m_hkey(open_key_(hkeyParent, 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 hkeyParent 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>hkeyParent</code> will be
     *  opened.
     * \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 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(hkey_type hkeyParent, S const &keyName, REGSAM accessMask = KEY_ALL_ACCESS)
        : m_hkey(open_key_(hkeyParent, 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 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.
     *
     * \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 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 &keyParent, char_type const *keyName, REGSAM accessMask = KEY_ALL_ACCESS)
        : 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.
     *
     * \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 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 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 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,