rosapps/sysutils/regexpl/RegistryKey.h

   1 /* $Id$ */
   2
   3 // RegistryKey.h: interface for the CRegistryKey class.
   4 //
   5 //////////////////////////////////////////////////////////////////////
   6
   7 #if !defined(REGISTRYKEY_H__FEF419ED_6EB6_11D3_907D_204C4F4F5020__INCLUDED_)
   8 #define REGISTRYKEY_H__FEF419ED_6EB6_11D3_907D_204C4F4F5020__INCLUDED_
   9
  10 class CRegistryKey
  11 {
  12 public:
  13   // Constructor. Call InitXXX methods to make real construct.
  14   CRegistryKey();
  15
  16   // Call this key to init root key.
  17   //
  18   // Parameters:
  19   //   pszMachineName - pointer to buffer containing machine name. NULL means local machine.
  20   //
  21   // Return value:
  22   //   S_OK - All ok.
  23   //   E_XXX - Error.
  24         HRESULT InitRoot(const TCHAR *pszMachineName = NULL);
  25
  26   // Call this method to init normal key.
  27   //
  28   // Parameters:
  29   //   hKey - handle to opened key.
  30   //   pszPath - optional path string. NULL if pszKeyName is the needed name.
  31   //   pszKeyName - pointer to buffer conatining name of key.
  32   //   CurrentAccess - Access of hKey.
  33   //
  34   // Remarks:
  35   //   Constructs key object from handle.
  36   //   The constructed object hold the handle and closes it on destruction. Do not close handle outside.
  37   //   If pszPath is not NULL, it is concatenated with pszKeyName.
  38   //
  39   // Return value:
  40   //   S_OK - All ok.
  41   //   E_XXX - Error.
  42   HRESULT Init(HKEY hKey, const TCHAR *pszPath, const TCHAR *pszKeyName, REGSAM CurrentAccess);
  43
  44   // Call this method to uninitialize the object.
  45   //
  46   // Return value:
  47   //   S_OK - All ok.
  48   //   E_XXX - Error.
  49   HRESULT Uninit();
  50
  51   // Destructor
  52         virtual ~CRegistryKey();
  53
  54   // Call ths function to check if handle to key is handle to hive root.
  55   //
  56   // Parameters:
  57   //   hKey - handle to check.
  58   //
  59   // Return value:
  60   //   TRUE - hKey is handle to hive root.
  61   //   FALSE - hKey is not handle to hive root.
  62   static BOOL IsHive(HKEY hKey);
  63
  64   // Call this method to get name of key represented by  this object.
  65   //
  66   // Return value:
  67   //   Pointer to buffer containing key name. Return value is valid until next call to this object method.
  68         const TCHAR * GetKeyName();
  69
  70   BOOL IsRoot();
  71
  72   // Call this method to open existing subkey of this key.
  73   //
  74   // Parameters:
  75   //   samDesired - deisred access.
  76   //   pszSubkeyName - pointer to bufer containing name of key to open.
  77   //   rhKey - reference to variable that receives handle of opened key. If method fails, variable value is unchanged.
  78   //
  79   // Return value:
  80   //   If the method succeeds, the return value is ERROR_SUCCESS.
  81   //   If the method fails, the return value is a nonzero error code defined in winerror.h.
  82         LONG OpenSubkey(REGSAM samDesired, const TCHAR *pszSubkeyName, HKEY &rhKey);
  83
  84   // Call this method to open existing subkey of this key.
  85   //
  86   // Parameters:
  87   //   samDesired - deisred access.
  88   //   pszSubkeyName - pointer to bufer containing name of key to open.
  89   //   rKey - reference to CRegistryKey object. If method succeeds, rKey is initialized with newly opened key.
  90   //
  91   // Return value:
  92   //   If the method succeeds, the return value is ERROR_SUCCESS.
  93   //   If the method fails, the return value is a nonzero error code defined in winerror.h.
  94         LONG OpenSubkey(REGSAM samDesired, const TCHAR *pszSubkeyName, CRegistryKey &rKey);
  95
  96   // Call this method to get the length in TCHARs of longest subkey name, including terminating null.
  97   //
  98   // Parameters:
  99   //   rdwMaxSubkeyNameLength, reference to variable that receives size in TCHARs of longest subkey name.
 100   //
 101   // Return value.
 102   //   If the method succeeds, the return value is ERROR_SUCCESS.
 103   //   If the method fails, the return value is a nonzero error code defined in winerror.h.
 104         LONG GetSubkeyNameMaxLength(DWORD &rdwMaxSubkeyNameLength);
 105
 106   // Call this method to init subkey enumeration. I.e. before first call to GetSubkeyName()
 107   //
 108   // Parameters:
 109   //   pchSubkeyNameBuffer - pointer to buffer receiving subkey name.
 110   //   dwBufferSize - size, in TCHARs of buffer pointed by pchSubkeyNameBuffer.
 111   //
 112         void InitSubkeyEnumeration(TCHAR *pchSubkeyNameBuffer, DWORD dwBufferSize);
 113
 114   // Call this method to get next subkey name. Name is stored in buffer specified in call to InitSubKeyEnumeration.
 115   //
 116   // Parameters:
 117   //   pdwActualSize - optional pointer to variable receiving actual size, in TCHARs, of key name. The count returned does not include the terminating null.
 118   //
 119   // Return value:
 120   //   If the method succeeds, the return value is ERROR_SUCCESS.
 121   //   If the method fails, the return value is a nonzero error code defined in winerror.h.
 122   //   If no more items available, return error is ERROR_NO_MORE_ITEMS.
 123         LONG GetNextSubkeyName(DWORD *pdwActualSize = NULL);
 124
 125   // Call this method to get count of subkeys.
 126   //
 127   // Parameters:
 128   //   rdwSubkeyCount - reference to variable that receives subkey count.
 129   //
 130   // Return value:
 131   //   If the method succeeds, the return value is ERROR_SUCCESS.
 132   //   If the method fails, the return value is a nonzero error code defined in winerror.h.
 133         LONG GetSubkeyCount(DWORD &rdwSubkeyCount);
 134
 135   // Call this method to get the length in TCHARs of longest value name, including terminating null.
 136   //
 137   // Parameters:
 138   //   rdwMaxValueNameBufferSize receives the length, in TCHARs, of the key's longest value name.
 139   //
 140   // Return value:
 141   //   If the method succeeds, the return value is ERROR_SUCCESS.
 142   //   If the method fails, the return value is a nonzero error code defined in winerror.h.
 143         LONG GetMaxValueNameLength(DWORD& rdwMaxValueNameBufferSize);
 144
 145   // Call this method to get the size of larges value data.
 146   //
 147   // Parameters:
 148   //   rdwMaxValueDataBufferSize receives the length, in bytes, of the longest data component among the key's values.
 149   //
 150   // Return value:
 151   //   If the method succeeds, the return value is ERROR_SUCCESS.
 152   //   If the method fails, the return value is a nonzero error code defined in winerror.h.
 153         LONG GetMaxValueDataSize(DWORD& rdwMaxValueDataBufferSize);
 154
 155   // Call this method to init subkey enumeration. I.e. before first call to GetSubkeyName()
 156   //
 157   // Parameters:
 158   //   pszValueNameBuffer - pointer to buffer receiving value name. If NULL, value name in not received upon iteration.
 159   //   dwValueNameBufferSize - size, in TCHARs of buffer pointed by pszValueNameBuffer. If pszValueNameBuffer is NULL, parameter is ignored.
 160   //   pbValueDataBuffer - pointer to buffer receiving value name. If NULL, value data is not received upon iteration.
 161   //   dwValueDataBufferSize - size, in bytes of buffer pointed by pbValueDataBuffer. If pbValueDataBuffer is NULL, parameter is ignored.
 162   //   pdwType - pointer to variable receiving value type. If NULL, value type is not received upon iteration.
 163         void InitValueEnumeration(TCHAR *pszValueNameBuffer,
 164                             DWORD dwValueNameBufferSize,
 165                             BYTE *pbValueDataBuffer,
 166                             DWORD dwValueDataBufferSize,
 167                             DWORD *pdwType);
 168
 169   // Call this method to get next value  name/data/type. Name/data/type is/are stored in buffer(s) specified in call to InitValueEnumeration.
 170   //
 171   // Parameters:
 172   //   pdwNameActualSize - optional pointer to variable receiving actual size, in TCHARs, of value name. The count returned includes the terminating null.
 173   //   pdwActualSize - optional pointer to variable receiving actual size, in bytes, of key name. The count returned does not include the terminating null.
 174   //
 175   // Return value:
 176   //   If the method succeeds, the return value is ERROR_SUCCESS.
 177   //   If the method fails, the return value is a nonzero error code defined in winerror.h.
 178   //   If no more items available, return error is ERROR_NO_MORE_ITEMS.
 179         LONG GetNextValue(DWORD *pdwNameActualSize = NULL, DWORD *pdwDataActualSize = NULL);
 180
 181   // Call this method to get count of values.
 182   //
 183   // Parameters:
 184   //   rdwValueCount - reference to variable that receives value count.
 185   //
 186   // Return value:
 187   //   If the method succeeds, the return value is ERROR_SUCCESS.
 188   //   If the method fails, the return value is a nonzero error code defined in winerror.h.
 189         LONG GetValueCount(DWORD& rdwValueCount);
 190
 191   // Call this method to get data and/or type of default value.
 192   //
 193   // Parameters:
 194   //   pdwType - optional pointer to variable receiving default value type. NULL if not requred.
 195   //   pbValueDataBuffer - optional pointer to buffer receiving default value data. NULL if not requred.
 196   //   dwValueDataBufferSize - size of buffer pointer by pbValueDataBuffer. Ignored if pbValueDataBuffer is NULL.
 197   //   pdwValueDataActualSize - optional pointer to variable receiving size, in bytes, of data stored into buffer. If pbValueDataBuffer is NULL, returned value is size of default value data, in bytes.
 198   //
 199   // Return value:
 200   //   If the method succeeds, the return value is ERROR_SUCCESS.
 201   //   If the method fails, the return value is a nonzero error code defined in winerror.h.
 202         LONG GetDefaultValue(DWORD *pdwType, BYTE *pbValueDataBuffer, DWORD dwValueDataBufferSize, DWORD *pdwValueDataActualSize);
 203
 204   // Call this function to get text representation of value type.
 205   //
 206   // Parameters:
 207   //   dwType - type to get text representation from.
 208   //
 209   // Return value:
 210   //   text representation od value type.
 211         static const TCHAR * GetValueTypeName(DWORD dwType);
 212
 213         DWORD GetValue(TCHAR *pchValueName, DWORD *pdwType, LPBYTE lpValueDataBuffer, DWORD *pdwValueDataSize);
 214
 215   // Call this method to create subkey of this key.
 216   //
 217   // Parameters:
 218   //   samDesired - deisred access.
 219   //   pszKeyName - pointer to bufer containing name of key to create.
 220   //   rhKey - reference to variable that receives handle of opened key. If method fails, variable value is unchanged.
 221   //   pblnOpened - optional pointer to variable that receives create/open status. If subkey is opened value is TRUE. If key is created value is FALSE.
 222   //   blnVolatile - opitional parameter specifining if created key is volatile.
 223   //
 224   // Return value:
 225   //   If the method succeeds, the return value is ERROR_SUCCESS.
 226   //   If the method fails, the return value is a nonzero error code defined in winerror.h.
 227         LONG CreateSubkey(REGSAM samDesired, const TCHAR *pszKeyName, HKEY &rhKey, BOOL *pblnOpened = NULL, BOOL blnVolatile = FALSE);
 228
 229         LONG GetLastWriteTime(SYSTEMTIME& st);
 230         const TCHAR * GetLastWriteTime();
 231
 232         LONG DeleteValue(const TCHAR *pszValueName);
 233         LONG DeleteSubkey(const TCHAR *pszPatternSubkeyName);
 234
 235         LONG SetValue(LPCTSTR pszValueName, DWORD dwType, BYTE *lpData, DWORD dwDataSize);
 236         TCHAR * GetSubKeyNameByIndex(DWORD dwIndex);
 237         LONG GetSecurityDescriptor(SECURITY_INFORMATION SecurityInformation, PSECURITY_DESCRIPTOR pSecurityDescriptor, LPDWORD lpcbSecurityDescriptor);
 238         LONG GetSecurityDescriptorLength(DWORD *pdwSecurityDescriptor);
 239         BOOL IsPredefined();
 240         operator HKEY(){return m_hKey;};
 241 private:
 242         DWORD m_dwCurrentSubKeyIndex;
 243   TCHAR *m_pchSubkeyNameBuffer;
 244   DWORD m_dwSubkeyNameBufferSize;
 245
 246         DWORD m_dwCurrentValueIndex;
 247   TCHAR *m_pszValueNameBuffer;
 248   DWORD m_dwValueNameBufferSize;
 249   BYTE *m_pbValueDataBuffer;
 250   DWORD m_dwValueDataBufferSize;
 251   DWORD *m_pdwType;
 252
 253         HKEY m_hKey;
 254         TCHAR *m_pszKeyName;
 255         TCHAR *m_pszMachineName;
 256         REGSAM m_CurrentAccess;
 257 };
 258
 259 #endif // !defined(REGISTRYKEY_H__FEF419ED_6EB6_11D3_907D_204C4F4F5020__INCLUDED_)