00001 /* 
00002  * File:        winstl_reg_key.h
00003  *
00004  * Purpose:     Contains the basic_reg_key template class, and ANSI
00005  *              and Unicode specialisations thereof.
00006  *
00007  * Created:     19th January 2002
00008  * Updated:     11th September 2004
00009  *
00010  * Home:        http://stlsoft.org/
00011  *
00012  * Copyright (c) 2002-2004, Matthew Wilson and Synesis Software
00013  * All rights reserved.
00014  *
00015  * Redistribution and use in source and binary forms, with or without
00016  * modification, are permitted provided that the following conditions are met:
00017  *
00018  * - Redistributions of source code must retain the above copyright notice, this
00019  *   list of conditions and the following disclaimer.
00020  * - Redistributions in binary form must reproduce the above copyright notice,
00021  *   this list of conditions and the following disclaimer in the documentation
00022  *   and/or other materials provided with the distribution.
00023  * - Neither the name(s) of Matthew Wilson and Synesis Software nor the names of
00024  *   any contributors may be used to endorse or promote products derived from
00025  *   this software without specific prior written permission.
00026  *
00027  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00028  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00029  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00030  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
00031  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00032  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00033  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00034  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00035  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00036  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00037  * POSSIBILITY OF SUCH DAMAGE.
00038  *
00039  * 
00040 
00041 
00045 
00046 #ifndef WINSTL_INCL_H_WINSTL_REG_KEY
00047 #define WINSTL_INCL_H_WINSTL_REG_KEY
00048 
00049 #ifndef __STLSOFT_DOCUMENTATION_SKIP_SECTION
00050 # define WINSTL_VER_H_WINSTL_REG_KEY_MAJOR      2
00051 # define WINSTL_VER_H_WINSTL_REG_KEY_MINOR      0
00052 # define WINSTL_VER_H_WINSTL_REG_KEY_REVISION   1
00053 # define WINSTL_VER_H_WINSTL_REG_KEY_EDIT       61
00054 #endif /* !__STLSOFT_DOCUMENTATION_SKIP_SECTION */
00055 
00056 /* 
00057  * Includes
00058  */
00059 
00060 #ifndef WINSTL_INCL_H_WINSTL
00061 # include "winstl.h"                        // Include the WinSTL root header
00062 #endif /* !WINSTL_INCL_H_WINSTL */
00063 #ifndef WINSTL_INCL_H_WINSTL_REG_DEFS
00064 # include "winstl_reg_defs.h"               // The WinSTL reg API standard types
00065 #endif /* WINSTL_INCL_H_WINSTL_REG_DEFS */
00066 #ifndef WINSTL_INCL_H_WINSTL_REG_TRAITS
00067 # include "winstl_reg_traits.h"             // The WinSTL reg API reg_traits class
00068 #endif /* WINSTL_INCL_H_WINSTL_REG_TRAITS */
00069 #ifndef STLSOFT_INCL_H_STLSOFT_AUTO_DESTRUCTOR
00070 # include "stlsoft_auto_buffer.h"           // Include the STLSoft auto_buffer
00071 #endif /* STLSOFT_INCL_H_STLSOFT_AUTO_DESTRUCTOR */
00072 #ifndef WINSTL_INCL_H_WINSTL_AUTO_DESTRUCTOR
00073 # include "winstl_processheap_allocator.h"  // winstl::processheap_allocator
00074 #endif /* WINSTL_INCL_H_WINSTL_AUTO_DESTRUCTOR */
00075 #ifndef STLSOFT_INCL_H_STLSOFT_STRING_ACCESS
00076 # include "stlsoft_string_access.h"         // stlsoft::c_str_ptr
00077 #endif /* !STLSOFT_INCL_H_STLSOFT_STRING_ACCESS */
00078 
00079 /* 
00080  * Namespace
00081  */
00082 
00083 #ifndef _WINSTL_NO_NAMESPACE
00084 # if defined(_STLSOFT_NO_NAMESPACE) || \
00085      defined(__STLSOFT_DOCUMENTATION_SKIP_SECTION)
00086 /* There is no stlsoft namespace, so must define ::winstl */
00087 namespace winstl
00088 {
00089 # else
00090 /* Define stlsoft::winstl_project */
00091 
00092 namespace stlsoft
00093 {
00094 
00095 namespace winstl_project
00096 {
00097 
00098 # endif /* _STLSOFT_NO_NAMESPACE */
00099 #endif /* !_WINSTL_NO_NAMESPACE */
00100 
00101 #if !defined(__STLSOFT_COMPILER_IS_MWERKS)
00102 stlsoft_ns_using(c_str_ptr)
00103 #endif /* compiler */
00104 
00105 /* 
00106 
00109 
00110 /* 
00111  * Forward declarations
00112  */
00113 
00114 #ifndef __STLSOFT_DOCUMENTATION_SKIP_SECTION
00115 
00116 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00117 class basic_reg_value_sequence;
00118 
00119 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00120 class basic_reg_key_sequence;
00121 
00122 #endif /* !__STLSOFT_DOCUMENTATION_SKIP_SECTION */
00123 
00124 /* 
00125  * Classes
00126  */
00127 
00136 template<   ss_typename_param_k C
00137 #ifdef __STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT
00138         ,   ss_typename_param_k T = reg_traits<C>
00139         ,   ss_typename_param_k A = processheap_allocator<C>
00140 #else
00141         ,   ss_typename_param_k T /* = reg_traits<C> */
00142         ,   ss_typename_param_k A /* = processheap_allocator<C> */
00143 #endif /* __STLSOFT_CF_TEMPLATE_CLASS_DEFAULT_CLASS_ARGUMENT_SUPPORT */
00144         >
00145 class basic_reg_key
00146 {
00147 public:
00149     typedef C                                           char_type;
00151     typedef T                                           traits_type;
00153     typedef A                                           allocator_type;
00155     typedef basic_reg_key<C, T, A>                      class_type;
00157     typedef ss_typename_type_k traits_type::size_type   size_type;
00159     typedef ss_typename_type_k traits_type::string_type string_type;
00161 #if defined(__STLSOFT_COMPILER_IS_MSVC) && \
00162     _MSC_VER == 1100
00163     /* WSCB: VC5 has an internal compiler error if use traits_type::hkey_type */
00164     typedef HKEY                                        hkey_type;
00165 #else
00166     typedef ss_typename_type_k traits_type::hkey_type   hkey_type;
00167 #endif /* 0 */
00168 
00169 // Construction
00170 public:
00172     basic_reg_key();
00174     basic_reg_key(hkey_type hkeyParent, string_type const &key_name, REGSAM samDesired = KEY_READ)
00175         : m_hkey(open_key_(hkeyParent, c_str_ptr(key_name), samDesired))
00176         , m_name(key_name)
00177     {} // Implementation is within class, otherwise VC5 will not link
00179     basic_reg_key(class_type const &keyParent, string_type const &key_name, REGSAM samDesired = KEY_READ)
00180         : m_hkey(open_key_(keyParent.get_key_handle(), c_str_ptr(key_name), samDesired))
00181         , m_name(key_name)
00182     {} // Implementation is within class, otherwise VC5 will not link
00183 
00185     basic_reg_key(class_type const &rhs);
00190     basic_reg_key(class_type const &rhs, REGSAM samDesired);
00191 
00192 protected:
00193     basic_reg_key(hkey_type *hkey, string_type const &key_name);
00194 public:
00196     ~basic_reg_key() winstl_throw_0();
00197 
00199     class_type &operator =(class_type const &rhs);
00200 
00201 // Attributes
00202 public:
00204     string_type const   &name() const;
00206     string_type         reg_class() const;
00208     ws_uint_t           num_sub_keys() const;
00210     ws_uint_t           num_values() const;
00211 
00213     hkey_type           get_key_handle() const;
00214 
00215 // Operations
00216 public:
00218     class_type  open_sub_key(char_type const *sub_key_name, REGSAM samDesired = KEY_READ);
00219 #ifdef __STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT
00220     template <ss_typename_param_k S>
00221     class_type  open_sub_key(S const &sub_key_name, REGSAM samDesired = KEY_READ)
00222     {
00223         return open_sub_key(c_str_ptr(sub_key_name), samDesired);
00224     }
00225 #endif /* __STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT */
00226 
00228     class_type  create_sub_key(char_type const *sub_key_name, REGSAM samDesired = KEY_READ);
00229 #ifdef __STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT
00230     template <ss_typename_param_k S>
00231     class_type  create_sub_key(S const &sub_key_name, REGSAM samDesired = KEY_READ)
00232     {
00233         return create_sub_key(c_str_ptr(sub_key_name), samDesired);
00234     }
00235 #endif /* __STLSOFT_CF_MEMBER_TEMPLATE_FUNCTION_SUPPORT */
00236 
00237     /* The handle returned from this method MUST be closed with RegCloseKey() */
00238     hkey_type   dup_key_handle(REGSAM samDesired = KEY_ALL_ACCESS);
00239 
00240 // Implementation
00241 private:
00242     static hkey_type    open_key_(hkey_type hkeyParent, char_type const *key_name, REGSAM samDesired);
00243     void                swap_(class_type &rhs) winstl_throw_0();
00244 
00245 // Members
00246 private:
00247     friend  class basic_reg_value_sequence<C, T, A>;
00248     friend  class basic_reg_key_sequence<C, T, A>;
00249 
00250     hkey_type   m_hkey; // The parent key
00251     string_type m_name; // The name
00252 };
00253 
00254 /* Typedefs to commonly encountered types. */
00256 typedef basic_reg_key<ws_char_a_t, reg_traits<ws_char_a_t>, processheap_allocator<ws_char_a_t> >    reg_key_a;
00258 typedef basic_reg_key<ws_char_w_t, reg_traits<ws_char_w_t>, processheap_allocator<ws_char_w_t> >    reg_key_w;
00260 typedef basic_reg_key<TCHAR, reg_traits<TCHAR>, processheap_allocator<TCHAR> >                      reg_key;
00261 
00262 /* 
00263  * Handle access shims
00264  */
00265 
00266 /* get_handle */
00267 
00269 template<   ss_typename_param_k C
00270         ,   ss_typename_param_k T
00271         ,   ss_typename_param_k A
00272         >
00273 inline HKEY get_handle(basic_reg_key<C, T, A> const &key)
00274 {
00275     return key.get_key_handle();
00276 }
00277 
00279 // Unit-testing
00280 
00281 #ifdef STLSOFT_UNITTEST
00282 
00283 namespace unittest
00284 {
00285     ss_bool_t test_winstl_reg_key(unittest_reporter *r)
00286     {
00287         using stlsoft::unittest::unittest_initialiser;
00288 
00289         ss_bool_t               bSuccess    =   true;
00290 
00291         unittest_initialiser    init(r, "WinSTL", "reg_key", __FILE__);
00292 
00293 #if 0
00294         if(<<TODO>>)
00295         {
00296             r->report("<<TODO>> failed ", __LINE__);
00297             bSuccess = false;
00298         }
00299 #endif /* 0 */
00300 
00301         return bSuccess;
00302     }
00303 
00304     unittest_registrar    unittest_winstl_reg_key(test_winstl_reg_key);
00305 
00306 } // namespace unittest
00307 
00308 #endif /* STLSOFT_UNITTEST */
00309 
00310 /* 
00311  * Implementation
00312  */
00313 
00314 #ifndef __STLSOFT_DOCUMENTATION_SKIP_SECTION
00315 
00316 template<   ss_typename_param_k C
00317         ,   ss_typename_param_k T
00318         ,   ss_typename_param_k A
00319         >
00320 #if (   defined(__STLSOFT_COMPILER_IS_MSVC) && \
00321         _MSC_VER < 1100) || \
00322     defined(__STLSOFT_COMPILER_IS_VECTORC)
00323 inline /* static */ ss_typename_type_k basic_reg_key<C, T, A>::hkey_type basic_reg_key<C, T, A>::open_key_(hkey_type hkeyParent, char_type const *key_name, REGSAM samDesired)
00324 #else
00325 inline /* static */ ss_typename_type_k basic_reg_key<C, T, A>::hkey_type basic_reg_key<C, T, A>::open_key_(ss_typename_param_k basic_reg_key<C, T, A>::hkey_type hkeyParent, ss_typename_param_k basic_reg_key<C, T, A>::char_type const *key_name, REGSAM samDesired)
00326 #endif /* __STLSOFT_COMPILER_IS_MSVC && _MSC_VER < 1100 */
00327 {
00328     hkey_type   hkey;
00329 
00330     return (0 == traits_type::reg_open_key(hkeyParent, key_name, &hkey, samDesired)) ? hkey : NULL;
00331 }
00332 
00333 // Construction
00334 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00335 inline basic_reg_key<C, T, A>::basic_reg_key()
00336     : m_hkey(NULL)
00337 {}
00338 
00339 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00340 inline basic_reg_key<C, T, A>::basic_reg_key(ss_typename_type_k basic_reg_key<C, T, A>::hkey_type *hkey, ss_typename_type_k basic_reg_key<C, T, A>::string_type const &key_name)
00341     : m_hkey(*hkey)
00342     , m_name(key_name)
00343 {}
00344 
00345 #if 0 /* These methods are inline, as VC5 will not link otherwise. (Both 4.2 & 6 will!) */
00346 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00347 inline basic_reg_key<C, T, A>::basic_reg_key(hkey_type hkeyParent, basic_reg_key<C, T, A>::string_type const &key_name)
00348     : m_hkey(open_key_(hkeyParent, c_str_ptr(key_name), samDesired))
00349     , m_name(key_name)
00350 {}
00351 
00352 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00353 inline basic_reg_key<C, T, A>::basic_reg_key(ss_typename_param_k basic_reg_key<C, T, A>::class_type const &keyParent, ss_typename_param_k basic_reg_key<C, T, A>::string_type const &key_name, REGSAM samDesired /* = KEY_READ */)
00354     : m_hkey(open_key_(keyParent.get_key_handle(), c_str_ptr(key_name), samDesired))
00355     , m_name(key_name)
00356 {}
00357 #endif /* 0 */
00358 
00359 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00360 inline basic_reg_key<C, T, A>::basic_reg_key(class_type const &rhs)
00361     : m_hkey(traits_type::key_dup(rhs.m_hkey))
00362     , m_name(rhs.m_name)
00363 {}
00364 
00365 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00366 inline basic_reg_key<C, T, A>::basic_reg_key(class_type const &rhs, REGSAM samDesired)
00367     : m_hkey(traits_type::key_dup(rhs.m_hkey, samDesired))
00368     , m_name(rhs.m_name)
00369 {}
00370 
00371 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00372 inline basic_reg_key<C, T, A>::~basic_reg_key() winstl_throw_0()
00373 {
00374     if(m_hkey != NULL)
00375     {
00376         ::RegCloseKey(m_hkey);
00377     }
00378 }
00379 
00380 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00381 inline void basic_reg_key<C, T, A>::swap_(ss_typename_type_k basic_reg_key<C, T, A>::class_type &rhs) winstl_throw_0()
00382 {
00383     m_name.swap(rhs.m_name);
00384 
00385     hkey_type   _hkey       =   m_hkey;
00386                 m_hkey      =   rhs.m_hkey;
00387                 rhs.m_hkey  =   _hkey;
00388 }
00389 
00390 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00391 inline ss_typename_type_k basic_reg_key<C, T, A>::class_type &basic_reg_key<C, T, A>::operator =(ss_typename_type_k basic_reg_key<C, T, A>::class_type const &rhs)
00392 {
00393     class_type  _this(rhs);
00394 
00395     swap_(_this);
00396 
00397     return *this;
00398 }
00399 
00400 // Attributes
00401 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00402 inline ss_typename_type_k basic_reg_key<C, T, A>::string_type const &basic_reg_key<C, T, A>::name() const
00403 {
00404     return m_name;
00405 }
00406 
00407 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00408 inline ss_typename_type_k basic_reg_key<C, T, A>::string_type basic_reg_key<C, T, A>::reg_class() const
00409 {
00410     size_type   cch_key_class   =   0;
00411     ws_long_t   res             =   traits_type::reg_query_info(m_hkey, NULL, &cch_key_class, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL);
00412 
00413     if(res == 0)
00414     {
00415         stlsoft_ns_qual(auto_buffer)<char_type, allocator_type, CCH_REG_API_AUTO_BUFFER>  p(++cch_key_class);
00416 
00417         res = traits_type::reg_query_info(m_hkey, p, &cch_key_class, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL);
00418 
00419         if(res == 0)
00420         {
00421             return string_type(p, cch_key_class);
00422         }
00423     }
00424 
00425     return string_type();
00426 }
00427 
00428 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00429 inline ws_uint_t basic_reg_key<C, T, A>::num_sub_keys() const
00430 {
00431     ws_uint_t   c_sub_keys;
00432     ws_long_t   res         =   traits_type::reg_query_info(m_hkey, NULL, NULL, &c_sub_keys, NULL, NULL, NULL, NULL, NULL, NULL, NULL);
00433 
00434     if(res != 0)
00435     {
00436         c_sub_keys = 0;
00437     }
00438 
00439     return c_sub_keys;
00440 }
00441 
00442 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00443 inline ws_uint_t basic_reg_key<C, T, A>::num_values() const
00444 {
00445     ws_uint_t   c_values;
00446     ws_long_t   res         =   traits_type::reg_query_info(m_hkey, NULL, NULL, NULL, NULL, NULL, &c_values, NULL, NULL, NULL, NULL);
00447 
00448     if(res != 0)
00449     {
00450         c_values = 0;
00451     }
00452 
00453     return c_values;
00454 }
00455 
00456 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00457 inline ss_typename_type_k basic_reg_key<C, T, A>::hkey_type basic_reg_key<C, T, A>::get_key_handle() const
00458 {
00459     return m_hkey;
00460 }
00461 
00462 // Operations
00463 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00464 inline ss_typename_type_k basic_reg_key<C, T, A>::class_type basic_reg_key<C, T, A>::open_sub_key(char_type const *sub_key_name, REGSAM samDesired /* = KEY_READ */)
00465 {
00466     return class_type(m_hkey, sub_key_name);
00467 }
00468 
00469 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00470 inline ss_typename_type_k basic_reg_key<C, T, A>::class_type basic_reg_key<C, T, A>::create_sub_key(char_type const *sub_key_name, REGSAM samDesired /* = KEY_READ */)
00471 {
00472     hkey_type hkey;
00473 
00474     return (ERROR_SUCCESS != traits_type::reg_create_key(m_hkey, sub_key_name, &hkey, samDesired)) ? class_type() : class_type(&hkey, sub_key_name);
00475 }
00476 
00477 /* The handle returned from this method MUST be closed with RegCloseKey() */
00478 template <ss_typename_param_k C, ss_typename_param_k T, ss_typename_param_k A>
00479 inline ss_typename_type_k basic_reg_key<C, T, A>::hkey_type basic_reg_key<C, T, A>::dup_key_handle(REGSAM samDesired /* = KEY_ALL_ACCESS */)
00480 {
00481     return traits_type::key_dup(m_hkey);
00482 }
00483 
00484 #endif /* !__STLSOFT_DOCUMENTATION_SKIP_SECTION */
00485 
00486 /* 
00487 
00489 
00490 /* 
00491 
00492 #ifndef _WINSTL_NO_NAMESPACE
00493 # if defined(_STLSOFT_NO_NAMESPACE) || \
00494      defined(__STLSOFT_DOCUMENTATION_SKIP_SECTION)
00495 } // namespace winstl
00496 # else
00497 } // namespace winstl_project
00498 } // namespace stlsoft
00499 # endif /* _STLSOFT_NO_NAMESPACE */
00500 #endif /* !_WINSTL_NO_NAMESPACE */
00501 
00502 /* 
00503 
00504 #endif /* WINSTL_INCL_H_WINSTL_REG_KEY */
00505 
00506 /*