docs/Samba3-Developers-Guide/registry.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <chapter id="registry">
   4         <chapterinfo>
   5                 &author.jelmer;
   6                 <pubdate>24 September 2003</pubdate>
   7         </chapterinfo>
   8
   9         <title>The registry subsystem</title>
  10
  11         <sect1><title>Planned backends</title>
  12
  13 <para>
  14         The new registry subsystem will work with several different backends:
  15 </para>
  16
  17 <itemizedlist>
  18         <listitem><para>NT4 (NT4 registry files)</para></listitem>
  19         <listitem><para>TDB (Samba TDB files)</para></listitem>
  20         <listitem><para>RPC (Remote Registry over RPC, reg pipe)</para></listitem>
  21         <listitem><para>wine (Wine Registry Files)</para></listitem>
  22         <listitem><para>gconf (The GNOME configuration backend)</para></listitem>
  23 </itemizedlist>
  24
  25 </sect1>
  26
  27 <sect1><title>Data structures</title>
  28
  29 <para>
  30 The following structure describes a registry key:
  31 </para>
  32
  33 <programlisting>
  34 typedef struct reg_key_s {
  35   char *name;         /* Name of the key                    */
  36   smb_ucs2_t *class_name; /* Name of key class */
  37   int type;           /* One of REG_ROOT_KEY or REG_SUB_KEY */
  38   NTTIME last_mod; /* Time last modified                 */
  39   struct reg_key_s *owner;
  40   struct key_list_s *sub_keys; /* NULL indicates keys not available in memory, function should be called */
  41   struct val_list_s *values; /* NULL indicates values not available in memory, function should be called */
  42   SEC_DESC *security;
  43   REG_HANDLE *handle; /* Pointer to REG_HANDLE this key belongs to */
  44   void *backend_data; /* Pointer used by the backend */
  45 } REG_KEY;
  46 </programlisting>
  47
  48 <para>The following structure describes a registry value:</para>
  49
  50 <programlisting>
  51 typedef struct val_key_s {
  52   char *name; /* NULL if name not available */
  53   int data_type;
  54   int data_len;
  55   void *data_blk;    /* Might want a separate block */
  56   REG_HANDLE *handle; /* Pointer to REG_HANDLE this key belongs to */
  57   void *backend_data;
  58 } REG_VAL;
  59 </programlisting>
  60
  61 <para>The following structures are used for lists of subkeys or values:</para>
  62
  63 <programlisting>
  64 /* container for registry subkey names */
  65 typedef struct key_list_s {
  66         TALLOC_CTX      *ctx;
  67         uint32      num_subkeys;
  68         REG_KEY     **subkeys;
  69 } REG_KEY_LIST;
  70
  71 /* container for registry values */
  72 typedef struct val_list_s {
  73         TALLOC_CTX *ctx;
  74     uint32 num_vals;
  75     REG_VAL **vals;
  76 } REG_VAL_LIST;
  77 </programlisting>
  78
  79 <para>
  80 And this structure is used for an instance of a registry (a registry file that's opened, a remote registry pipe we're connected to, etc).
  81 </para>
  82
  83 <programlisting>
  84 typedef struct reg_handle_s {
  85         REGISTRY_OPS *functions;
  86         REG_KEY *root; /* NULL if not available */
  87         void *backend_data;
  88 } REG_HANDLE;
  89 </programlisting>
  90
  91 </sect1>
  92
  93 <sect1>
  94         <title>External interface</title>
  95
  96 <programlisting>
  97 REG_HANDLE *reg_open(char *backend, char *location, BOOL try_full_load);
  98 REG_KEY *reg_open_key(REG_KEY *parent, char *name);
  99 REG_VAL *reg_key_get_val(REG_KEY *key, char *name);
 100 REG_VAL_LIST *reg_key_get_vals(REG_KEY *key);
 101 REG_KEY_LIST *reg_key_get_subkeys(REG_KEY *key);
 102 BOOL reg_key_del(REG_KEY *key);
 103 BOOL reg_val_del(REG_VAL *val);
 104 BOOL reg_key_add(REG_KEY *parent, REG_KEY *key);
 105 BOOL reg_val_add(REG_KEY *parent, REG_VAL *val):
 106 BOOL reg_val_update(REG_VAL *val);
 107 BOOL reg_key_update(REG_KEY *key);
 108 void reg_free_key(REG_KEY *key);
 109 void reg_free_val(REG_VAL *val);
 110 void reg_free(REG_HANDLE *h);
 111 void reg_free_key_list(REG_KEY_LIST *list):
 112 void reg_free_val_list(REG_VAL_LIST *list):
 113 </programlisting>
 114
 115 </sect1>
 116
 117 <sect1>
 118         <title>Utility functions</title>
 119
 120         <para>The following helper functions are available:</para>
 121
 122         <programlisting>
 123 void reg_key_list_init( REG_KEY_LIST *ctr );
 124 int reg_key_list_addkey( REG_KEY_LIST *ctr, const char *keyname );
 125 int reg_key_list_numkeys( REG_KEY_LIST *ctr );
 126 char* reg_key_list_specific_key( REG_KEY_LIST *ctr, uint32 key_index );
 127 void reg_key_list_destroy( REG_KEY_LIST *ctr );
 128 void reg_val_list_init( REG_VAL_LIST *ctr );
 129 int reg_val_list_numvals( REG_VAL_LIST *ctr );
 130 void free_registry_value( REG_VAL *val );
 131 uint8* regval_data_p( REG_VAL *val );
 132 int regval_size( REG_VAL *val );
 133 char* regval_name( REG_VAL *val );
 134 uint32 regval_type( REG_VAL *val );
 135 TALLOC_CTX* reg_val_list_getctx( REG_VAL_LIST *val );
 136 int reg_val_list_addvalue( REG_VAL_LIST *ctr, const char *name, uint16 type,
 137                          const char *data_p, size_t size );
 138 int reg_val_list_copyvalue( REG_VAL_LIST *ctr, REG_VAL *val );
 139 int reg_val_list_delvalue( REG_VAL_LIST *ctr, const char *name );
 140 void reg_val_list_destroy( REG_VAL_LIST *ctr );
 141 </programlisting>
 142
 143 </sect1>
 144
 145 <sect1>
 146         <title>Writing backends</title>
 147
 148 <para>There are basically two ways of reading data from the registry: loading
 149 it all into memory and then working in this copy in memory, or
 150 re-reading/re-opening it every time necessary.</para>
 151
 152 <para>This interface aims to support both types. </para>
 153
 154 <para>A registry backend should provide the following functions:</para>
 155
 156 <programlisting>
 157 typedef struct {
 158         REG_HANDLE *(*open_registry) (const char *location, BOOL try_complete_load);
 159         REG_KEY *(*open_root_key) (REG_HANDLE *);
 160         REG_KEY *(*open_key_rel) (REG_KEY *parent, const char *name);
 161         /* if open_key_abs is set to NULL, a default implementation will be provided. */
 162         REG_KEY *(*open_key_abs) (REG_HANDLE *, const char *name);
 163         REG_KEY_LIST *(*get_subkeys) (REG_KEY *);
 164     REG_VAL_LIST *(*get_values) (REG_KEY *);
 165         BOOL (*add_key)(REG_KEY *, REG_KEY *);
 166         BOOL (*update_key)(REG_KEY *);
 167         BOOL (*del_key)(REG_KEY *);
 168         BOOL (*add_value)(REG_KEY *, REG_VAL *);
 169         BOOL (*update_value)(REG_VAL *);
 170         BOOL (*del_value)(REG_VAL *);
 171         REG_VAL *(*get_value) (REG_KEY *, const char *name);
 172         /* It is not guaranteed that no data has been stored before save()
 173          * has been called. This function is only useful for backends that
 174          * store the data in memory and then write out the whole registry at once */
 175         BOOL (*save)(REG_HANDLE *, const char *location);
 176         BOOL (*close_registry) (REG_HANDLE *);
 177         void (*free_key)(REG_KEY *);
 178         void (*free_value)(REG_VAL *);
 179 } REGISTRY_OPS;
 180 </programlisting>
 181
 182 <para>open_root_key() is optional. It's only called if the
 183         <parameter>root</parameter> field of the REG_HANDLE struct is NULL.</para>
 184
 185 <para>open_key_abs() is optional. If it's NULL, the frontend will
 186         provide a replacement, using open_key_rel().</para>
 187
 188 <para>get_values() and get_value() are optional. They're only called if
 189 the <parameter>values</parameter> field of the REG_KEY struct is NULL.</para>
 190
 191 <para>get_subkeys() and get_key() are optional. THey're only called
 192         if the <parameter>subkeys</parameter> field of the REG_KEY struct is NULL.</para>
 193
 194 </sect1>
 195
 196 <sect1><title>Memory allocation</title>
 197
 198 <para>Okay, so who's responsible for what parts of the memory? </para>
 199
 200 <para>The memory is basically maintained by the backends. When the user
 201 is finished using a particular structure, it should call the related free
 202 function for the structure it's freeing.</para>
 203
 204 <para>The backend should then decide what to do with the structure. It may
 205 choose to free it, or, if it's maintaining single copies of everything in
 206 memory, may choose to ignore the free and free it when the registry is closed.
 207 </para>
 208
 209 </sect1>
 210
 211 </chapter>