1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�12.�The registry subsystem</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.66.1"><link rel="start" href="index.html" title="SAMBA Developers Guide"><link rel="up" href="pt03.html" title="Part�III.�Samba Subsystems"><link rel="prev" href="vfs.html" title="Chapter�11.�VFS Modules"><link rel="next" href="parsing.html" title="Chapter�13.�The smb.conf file"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter�12.�The registry subsystem</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="vfs.html">Prev</a>�</td><th width="60%" align="center">Part�III.�Samba Subsystems</th><td width="20%" align="right">�<a accesskey="n" href="parsing.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="registry"></a>Chapter�12.�The registry subsystem</h2></div><div><div class="author"><h3 class="author"><span class="firstname">Jelmer</span> <span class="othername">R.</span> <span class="surname">Vernooij</span></h3><div class="affiliation"><span class="orgname">The Samba Team<br></span><div class="address"><p><tt class="email"><<a href="mailto:jelmer@samba.org">jelmer@samba.org</a>></tt></p></div></div></div></div><div><p class="pubdate">24 September 2003</p></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="registry.html#id2536921">Planned backends</a></span></dt><dt><span class="sect1"><a href="registry.html#id2536959">Data structures</a></span></dt><dt><span class="sect1"><a href="registry.html#id2537028">External interface</a></span></dt><dt><span class="sect1"><a href="registry.html#id2537052">Utility functions</a></span></dt><dt><span class="sect1"><a href="registry.html#id2537084">Writing backends</a></span></dt><dt><span class="sect1"><a href="registry.html#id2537168">Memory allocation</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2536921"></a>Planned backends</h2></div></div></div><p> 2 The new registry subsystem will work with several different backends: 3</p><div class="itemizedlist"><ul type="disc"><li><p>NT4 (NT4 registry files)</p></li><li><p>TDB (Samba TDB files)</p></li><li><p>RPC (Remote Registry over RPC, reg pipe)</p></li><li><p>wine (Wine Registry Files)</p></li><li><p>gconf (The GNOME configuration backend)</p></li></ul></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2536959"></a>Data structures</h2></div></div></div><p> 4The following structure describes a registry key: 5</p><pre class="programlisting"> 6typedef struct reg_key_s { 7 char *name; /* Name of the key */ 8 smb_ucs2_t *class_name; /* Name of key class */ 9 int type; /* One of REG_ROOT_KEY or REG_SUB_KEY */ 10 NTTIME last_mod; /* Time last modified */ 11 struct reg_key_s *owner; 12 struct key_list_s *sub_keys; /* NULL indicates keys not available in memory, function should be called */ 13 struct val_list_s *values; /* NULL indicates values not available in memory, function should be called */ 14 SEC_DESC *security; 15 REG_HANDLE *handle; /* Pointer to REG_HANDLE this key belongs to */ 16 void *backend_data; /* Pointer used by the backend */ 17} REG_KEY; 18</pre><p>The following structure describes a registry value:</p><pre class="programlisting"> 19typedef struct val_key_s { 20 char *name; /* NULL if name not available */ 21 int data_type; 22 int data_len; 23 void *data_blk; /* Might want a separate block */ 24 REG_HANDLE *handle; /* Pointer to REG_HANDLE this key belongs to */ 25 void *backend_data; 26} REG_VAL; 27</pre><p>The following structures are used for lists of subkeys or values:</p><pre class="programlisting"> 28/* container for registry subkey names */ 29typedef struct key_list_s { 30 TALLOC_CTX *ctx; 31 uint32 num_subkeys; 32 REG_KEY **subkeys; 33} REG_KEY_LIST; 34 35/* container for registry values */ 36typedef struct val_list_s { 37 TALLOC_CTX *ctx; 38 uint32 num_vals; 39 REG_VAL **vals; 40} REG_VAL_LIST; 41</pre><p> 42And 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). 43</p><pre class="programlisting"> 44typedef struct reg_handle_s { 45 REGISTRY_OPS *functions; 46 REG_KEY *root; /* NULL if not available */ 47 void *backend_data; 48} REG_HANDLE; 49</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2537028"></a>External interface</h2></div></div></div><pre class="programlisting"> 50REG_HANDLE *reg_open(char *backend, char *location, BOOL try_full_load); 51REG_KEY *reg_open_key(REG_KEY *parent, char *name); 52REG_VAL *reg_key_get_val(REG_KEY *key, char *name); 53REG_VAL_LIST *reg_key_get_vals(REG_KEY *key); 54REG_KEY_LIST *reg_key_get_subkeys(REG_KEY *key); 55BOOL reg_key_del(REG_KEY *key); 56BOOL reg_val_del(REG_VAL *val); 57BOOL reg_key_add(REG_KEY *parent, REG_KEY *key); 58BOOL reg_val_add(REG_KEY *parent, REG_VAL *val): 59BOOL reg_val_update(REG_VAL *val); 60BOOL reg_key_update(REG_KEY *key); 61void reg_free_key(REG_KEY *key); 62void reg_free_val(REG_VAL *val); 63void reg_free(REG_HANDLE *h); 64void reg_free_key_list(REG_KEY_LIST *list): 65void reg_free_val_list(REG_VAL_LIST *list): 66</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2537052"></a>Utility functions</h2></div></div></div><p>The following helper functions are available:</p><pre class="programlisting"> 67void reg_key_list_init( REG_KEY_LIST *ctr ); 68int reg_key_list_addkey( REG_KEY_LIST *ctr, const char *keyname ); 69int reg_key_list_numkeys( REG_KEY_LIST *ctr ); 70char* reg_key_list_specific_key( REG_KEY_LIST *ctr, uint32 key_index ); 71void reg_key_list_destroy( REG_KEY_LIST *ctr ); 72void reg_val_list_init( REG_VAL_LIST *ctr ); 73int reg_val_list_numvals( REG_VAL_LIST *ctr ); 74void free_registry_value( REG_VAL *val ); 75uint8* regval_data_p( REG_VAL *val ); 76int regval_size( REG_VAL *val ); 77char* regval_name( REG_VAL *val ); 78uint32 regval_type( REG_VAL *val ); 79TALLOC_CTX* reg_val_list_getctx( REG_VAL_LIST *val ); 80int reg_val_list_addvalue( REG_VAL_LIST *ctr, const char *name, uint16 type, 81 const char *data_p, size_t size ); 82int reg_val_list_copyvalue( REG_VAL_LIST *ctr, REG_VAL *val ); 83int reg_val_list_delvalue( REG_VAL_LIST *ctr, const char *name ); 84void reg_val_list_destroy( REG_VAL_LIST *ctr ); 85</pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2537084"></a>Writing backends</h2></div></div></div><p>There are basically two ways of reading data from the registry: loading 86it all into memory and then working in this copy in memory, or 87re-reading/re-opening it every time necessary.</p><p>This interface aims to support both types. </p><p>A registry backend should provide the following functions:</p><pre class="programlisting"> 88typedef struct { 89 REG_HANDLE *(*open_registry) (const char *location, BOOL try_complete_load); 90 REG_KEY *(*open_root_key) (REG_HANDLE *); 91 REG_KEY *(*open_key_rel) (REG_KEY *parent, const char *name); 92 /* if open_key_abs is set to NULL, a default implementation will be provided. */ 93 REG_KEY *(*open_key_abs) (REG_HANDLE *, const char *name); 94 REG_KEY_LIST *(*get_subkeys) (REG_KEY *); 95 REG_VAL_LIST *(*get_values) (REG_KEY *); 96 BOOL (*add_key)(REG_KEY *, REG_KEY *); 97 BOOL (*update_key)(REG_KEY *); 98 BOOL (*del_key)(REG_KEY *); 99 BOOL (*add_value)(REG_KEY *, REG_VAL *); 100 BOOL (*update_value)(REG_VAL *); 101 BOOL (*del_value)(REG_VAL *); 102 REG_VAL *(*get_value) (REG_KEY *, const char *name); 103 /* It is not guaranteed that no data has been stored before save() 104 * has been called. This function is only useful for backends that 105 * store the data in memory and then write out the whole registry at once */ 106 BOOL (*save)(REG_HANDLE *, const char *location); 107 BOOL (*close_registry) (REG_HANDLE *); 108 void (*free_key)(REG_KEY *); 109 void (*free_value)(REG_VAL *); 110} REGISTRY_OPS; 111</pre><p>open_root_key() is optional. It's only called if the 112 <i class="parameter"><tt>root</tt></i> field of the REG_HANDLE struct is NULL.</p><p>open_key_abs() is optional. If it's NULL, the frontend will 113 provide a replacement, using open_key_rel().</p><p>get_values() and get_value() are optional. They're only called if 114the <i class="parameter"><tt>values</tt></i> field of the REG_KEY struct is NULL.</p><p>get_subkeys() and get_key() are optional. THey're only called 115 if the <i class="parameter"><tt>subkeys</tt></i> field of the REG_KEY struct is NULL.</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2537168"></a>Memory allocation</h2></div></div></div><p>Okay, so who's responsible for what parts of the memory? </p><p>The memory is basically maintained by the backends. When the user 116is finished using a particular structure, it should call the related free 117function for the structure it's freeing.</p><p>The backend should then decide what to do with the structure. It may 118choose to free it, or, if it's maintaining single copies of everything in 119memory, may choose to ignore the free and free it when the registry is closed. 120</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="vfs.html">Prev</a>�</td><td width="20%" align="center"><a accesskey="u" href="pt03.html">Up</a></td><td width="40%" align="right">�<a accesskey="n" href="parsing.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter�11.�VFS Modules�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Chapter�13.�The smb.conf file</td></tr></table></div></body></html> 121