docs/devel/registry.xml

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