<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.64.1"><link rel="home" href="index.html" title="SAMBA Developers Guide"><link rel="up" href="pt03.html" title="Part III. Samba Subsystems"><link rel="previous" 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></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="registry.html#id2517116">Planned backends</a></span></dt><dt><span class="sect1"><a href="registry.html#id2517154">Data structures</a></span></dt><dt><span class="sect1"><a href="registry.html#id2517224">External interface</a></span></dt><dt><span class="sect1"><a href="registry.html#id2517248">Utility functions</a></span></dt><dt><span class="sect1"><a href="registry.html#id2517280">Writing backends</a></span></dt><dt><span class="sect1"><a href="registry.html#id2517363">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="id2517116"></a>Planned backends</h2></div></div><div></div></div><p> The new registry subsystem will work with several different backends: </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="id2517154"></a>Data structures</h2></div></div><div></div></div><p> The following structure describes a registry key: </p><pre class="programlisting"> typedef struct reg_key_s { char *name; /* Name of the key */ smb_ucs2_t *class_name; /* Name of key class */ int type; /* One of REG_ROOT_KEY or REG_SUB_KEY */ NTTIME last_mod; /* Time last modified */ struct reg_key_s *owner; struct key_list_s *sub_keys; /* NULL indicates keys not available in memory, function should be called */ struct val_list_s *values; /* NULL indicates values not available in memory, function should be called */ SEC_DESC *security; REG_HANDLE *handle; /* Pointer to REG_HANDLE this key belongs to */ void *backend_data; /* Pointer used by the backend */ } REG_KEY; </pre><p>The following structure describes a registry value:</p><pre class="programlisting"> typedef struct val_key_s { char *name; /* NULL if name not available */ int data_type; int data_len; void *data_blk; /* Might want a separate block */ REG_HANDLE *handle; /* Pointer to REG_HANDLE this key belongs to */ void *backend_data; } REG_VAL; </pre><p>The following structures are used for lists of subkeys or values:</p><pre class="programlisting"> /* container for registry subkey names */ typedef struct key_list_s { TALLOC_CTX *ctx; uint32 num_subkeys; REG_KEY **subkeys; } REG_KEY_LIST; /* container for registry values */ typedef struct val_list_s { TALLOC_CTX *ctx; uint32 num_vals; REG_VAL **vals; } REG_VAL_LIST; </pre><p> 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). </p><pre class="programlisting"> typedef struct reg_handle_s { REGISTRY_OPS *functions; REG_KEY *root; /* NULL if not available */ void *backend_data; } REG_HANDLE; </pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2517224"></a>External interface</h2></div></div><div></div></div><pre class="programlisting"> REG_HANDLE *reg_open(char *backend, char *location, BOOL try_full_load); REG_KEY *reg_open_key(REG_KEY *parent, char *name); REG_VAL *reg_key_get_val(REG_KEY *key, char *name); REG_VAL_LIST *reg_key_get_vals(REG_KEY *key); REG_KEY_LIST *reg_key_get_subkeys(REG_KEY *key); BOOL reg_key_del(REG_KEY *key); BOOL reg_val_del(REG_VAL *val); BOOL reg_key_add(REG_KEY *parent, REG_KEY *key); BOOL reg_val_add(REG_KEY *parent, REG_VAL *val): BOOL reg_val_update(REG_VAL *val); BOOL reg_key_update(REG_KEY *key); void reg_free_key(REG_KEY *key); void reg_free_val(REG_VAL *val); void reg_free(REG_HANDLE *h); void reg_free_key_list(REG_KEY_LIST *list): void reg_free_val_list(REG_VAL_LIST *list): </pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2517248"></a>Utility functions</h2></div></div><div></div></div><p>The following helper functions are available:</p><pre class="programlisting"> void reg_key_list_init( REG_KEY_LIST *ctr ); int reg_key_list_addkey( REG_KEY_LIST *ctr, const char *keyname ); int reg_key_list_numkeys( REG_KEY_LIST *ctr ); char* reg_key_list_specific_key( REG_KEY_LIST *ctr, uint32 key_index ); void reg_key_list_destroy( REG_KEY_LIST *ctr ); void reg_val_list_init( REG_VAL_LIST *ctr ); int reg_val_list_numvals( REG_VAL_LIST *ctr ); void free_registry_value( REG_VAL *val ); uint8* regval_data_p( REG_VAL *val ); int regval_size( REG_VAL *val ); char* regval_name( REG_VAL *val ); uint32 regval_type( REG_VAL *val ); TALLOC_CTX* reg_val_list_getctx( REG_VAL_LIST *val ); int reg_val_list_addvalue( REG_VAL_LIST *ctr, const char *name, uint16 type, const char *data_p, size_t size ); int reg_val_list_copyvalue( REG_VAL_LIST *ctr, REG_VAL *val ); int reg_val_list_delvalue( REG_VAL_LIST *ctr, const char *name ); void reg_val_list_destroy( REG_VAL_LIST *ctr ); </pre></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2517280"></a>Writing backends</h2></div></div><div></div></div><p>There are basically two ways of reading data from the registry: loading it all into memory and then working in this copy in memory, or re-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"> typedef struct { REG_HANDLE *(*open_registry) (const char *location, BOOL try_complete_load); REG_KEY *(*open_root_key) (REG_HANDLE *); REG_KEY *(*open_key_rel) (REG_KEY *parent, const char *name); /* if open_key_abs is set to NULL, a default implementation will be provided. */ REG_KEY *(*open_key_abs) (REG_HANDLE *, const char *name); REG_KEY_LIST *(*get_subkeys) (REG_KEY *); REG_VAL_LIST *(*get_values) (REG_KEY *); BOOL (*add_key)(REG_KEY *, REG_KEY *); BOOL (*update_key)(REG_KEY *); BOOL (*del_key)(REG_KEY *); BOOL (*add_value)(REG_KEY *, REG_VAL *); BOOL (*update_value)(REG_VAL *); BOOL (*del_value)(REG_VAL *); REG_VAL *(*get_value) (REG_KEY *, const char *name); /* It is not guaranteed that no data has been stored before save() * has been called. This function is only useful for backends that * store the data in memory and then write out the whole registry at once */ BOOL (*save)(REG_HANDLE *, const char *location); BOOL (*close_registry) (REG_HANDLE *); void (*free_key)(REG_KEY *); void (*free_value)(REG_VAL *); } REGISTRY_OPS; </pre><p>open_root_key() is optional. It's only called if the <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 provide a replacement, using open_key_rel().</p><p>get_values() and get_value() are optional. They're only called if the <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 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="id2517363"></a>Memory allocation</h2></div></div><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 is finished using a particular structure, it should call the related free function for the structure it's freeing.</p><p>The backend should then decide what to do with the structure. It may choose to free it, or, if it's maintaining single copies of everything in memory, may choose to ignore the free and free it when the registry is closed. </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>