src/WINNT/afsapplib/settings.h

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