src/WINNT/client_creds/settings.h

   1 #ifndef SETTINGS_H
   2 #define SETTINGS_H
   3
   4 /*
   5  * DEFINITIONS ________________________________________________________________
   6  *
   7  */
   8
   9 #ifndef EXPORTED
  10 #define EXPORTED
  11 #endif
  12
  13 #ifndef HKCR
  14 #define HKCR            HKEY_CLASSES_ROOT
  15 #endif
  16
  17 #ifndef HKCU
  18 #define HKCU            HKEY_CURRENT_USER
  19 #endif
  20
  21 #ifndef HKLM
  22 #define HKLM            HKEY_LOCAL_MACHINE
  23 #endif
  24
  25 #ifndef HIBYTE
  26 #define HIBYTE(_w)      (BYTE)(((_w) >> 8) & 0x00FF)
  27 #endif
  28
  29 #ifndef LOBYTE
  30 #define LOBYTE(_w)      (BYTE)((_w) & 0x00FF)
  31 #endif
  32
  33 #ifndef MAKEVERSION
  34 #define MAKEVERSION(_h,_l)  ( ((((WORD)(_h)) << 8) & 0xFF00) | (((WORD)(_l)) & 0xFF) )
  35 #endif
  36
  37
  38
  39 /*
  40  * PROTOTYPES _________________________________________________________________
  41  *
  42  * Summary:
  43  *
  44  *    Store/RestoreSettings() are pretty simple--they're just convenience
  45  *    wrappers for providing version-controlled storage of a structure in
  46  *    the registry. You provide the structure and supply a version number;
  47  *    when your program loads, call RestoreSettings() to see if you've saved
  48  *    anything previously.  When your program exits, call StoreSettings()
  49  *    so you don't lose anything--effectively, you'll have global variables
  50  *    that won't change from one run of your program to the next.  Again,
  51  *    this is really pretty elementary stuff, but I find I write it a lot
  52  *    so I stuck it in a common source file.
  53  *
  54  *
  55  * About version numbers:
  56  *
  57  *    Don't just pick them at random--there's actually an algorithm here.
  58  *    A typical version number is composed of two parts--a major and a
  59  *    minor component.  Start with a version of 1.0, just for grins.
  60  *    Whenever you *add* something to the structure, increment the minor
  61  *    version--and make sure you add to the end of the structure.  If you
  62  *    have to do anything else to the structure--get rid of an element,
  63  *    reorder things, change the size of an element--increment the major
  64  *    version number.
  65  *
  66  *    Why?  Because it provides backward compatibility.  StoreSettings()
  67  *    always writes out the version number that you provide it... but
  68  *    RestoreSettings() is picky about what versions it will load:
  69  *
  70  *       (1) Restore fails if the stored major version != the expected version
  71  *       (2) Restore fails if the stored minor version < the expected version
  72  *
  73  *    Another way of looking at that is,
  74  *
  75  *       (1) Restore succeeds only if the major versions are identical
  76  *       (2) Restore succeeds only if the stored version is higher or equal
  77  *
  78  *    So if you run a 1.4 program and it tries to read a 1.7 level stored
  79  *    structure, it will succeed!!  Why?  Because a 1.4 structure is just
  80  *    like a 1.7 structure--only missing some stuff at the end, which
  81  *    RestoreSettings will just ignore (the 1.4 program didn't know about
  82  *    it anyway, and obviously did just fine without it).
  83  *
  84  *
  85  * Examples:
  86  *
  87  *    struct {
  88  *       RECT rWindow;
  89  *       TCHAR szLastDirectory[ MAX_PATH ];
  90  *       TCHAR szUserName[ MAX_PATH ];
  91  *    } globals_restored;
  92  *
  93  *    #define wVerGLOBALS MAKEVERSION(1,0)  // major version 1, minor version 0
  94  *
  95  *    #define cszPathGLOBALS  TEXT("Software\\MyCompany\\MyProgram")
  96  *    #define cszValueGLOBALS TEXT("Settings")
  97  *
  98  *    ...
  99  *
 100  *    if (!RestoreSettings (HKLM, cszPathGLOBALS, cszValueGLOBALS,
 101  *                          &globals_restored, sizeof(globals_restored),
 102  *                          wVerGLOBALS))
 103  *       {
 104  *       memset (&globals_restored, 0x00, sizeof(globals_restored));
 105  *       lstrcpy (globals_restored.szUserName, TEXT("unknown"));
 106  *       // set any other default, first-time-run values here
 107  *       }
 108  *
 109  *    ...
 110  *
 111  *    StoreSettings (HKLM, cszPathGLOBALS, cszValueGLOBALS,
 112  *                   &globals_restored, sizeof(globals_restored),
 113  *                   wVerGLOBALS);
 114  *
 115  */
 116
 117 EXPORTED void EraseSettings (HKEY hkParent,
 118                              LPCTSTR pszBase,
 119                              LPCTSTR pszValue);
 120
 121 EXPORTED BOOL RestoreSettings (HKEY hkParent,
 122                                LPCTSTR pszBase,
 123                                LPCTSTR pszValue,
 124                                PVOID pStructure,
 125                                size_t cbStructure,
 126                                WORD wVerExpected);
 127
 128 EXPORTED BOOL StoreSettings   (HKEY hkParent,
 129                                LPCTSTR pszBase,
 130                                LPCTSTR pszValue,
 131                                PVOID pStructure,
 132                                size_t cbStructure,
 133                                WORD wVersion);
 134
 135 EXPORTED size_t GetRegValueSize (HKEY hk,
 136                                  LPCTSTR pszBase,
 137                                  LPCTSTR pszValue);
 138
 139 EXPORTED BOOL GetBinaryRegValue (HKEY hk,
 140                                  LPCTSTR pszBase,
 141                                  LPCTSTR pszValue,
 142                                  PVOID pData,
 143                                  size_t cbData);
 144
 145 EXPORTED BOOL SetBinaryRegValue (HKEY hk,
 146                                  LPCTSTR pszBase,
 147                                  LPCTSTR pszValue,
 148                                  PVOID pData,
 149                                  size_t cbData);
 150
 151 EXPORTED BOOL RegDeltreeKey (HKEY hk, LPTSTR pszKey);
 152
 153
 154 #endif
 155