diff options
Diffstat (limited to 'docs/docbook/devdoc/registry.xml')
| -rw-r--r-- | docs/docbook/devdoc/registry.xml | 209 |
1 files changed, 0 insertions, 209 deletions
diff --git a/docs/docbook/devdoc/registry.xml b/docs/docbook/devdoc/registry.xml deleted file mode 100644 index b331ebce7f..0000000000 --- a/docs/docbook/devdoc/registry.xml +++ /dev/null @@ -1,209 +0,0 @@ -<chapter id="registry"> - <chapterinfo> - &author.jelmer; - <pubdate>24 September 2003</pubdate> - </chapterinfo> - - <title>The registry subsystem</title> - - <sect1><title>Planned backends</title> - -<para> - The new registry subsystem will work with several different backends: -</para> - -<itemizedlist> - <listitem><para>NT4 (NT4 registry files)</para></listitem> - <listitem><para>TDB (Samba TDB files)</para></listitem> - <listitem><para>RPC (Remote Registry over RPC, reg pipe)</para></listitem> - <listitem><para>wine (Wine Registry Files)</para></listitem> - <listitem><para>gconf (The GNOME configuration backend)</para></listitem> -</itemizedlist> - -</sect1> - -<sect1><title>Data structures</title> - -<para> -The following structure describes a registry key: -</para> - -<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; -</programlisting> - -<para>The following structure describes a registry value:</para> - -<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; -</programlisting> - -<para>The following structures are used for lists of subkeys or values:</para> - -<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; -</programlisting> - -<para> -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). -</para> - -<programlisting> -typedef struct reg_handle_s { - REGISTRY_OPS *functions; - REG_KEY *root; /* NULL if not available */ - void *backend_data; -} REG_HANDLE; -</programlisting> - -</sect1> - -<sect1> - <title>External interface</title> - -<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): -</programlisting> - -</sect1> - -<sect1> - <title>Utility functions</title> - - <para>The following helper functions are available:</para> - - <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 ); -</programlisting> - -</sect1> - -<sect1> - <title>Writing backends</title> - -<para>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.</para> - -<para>This interface aims to support both types. </para> - -<para>A registry backend should provide the following functions:</para> - -<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; -</programlisting> - -<para>open_root_key() is optional. It's only called if the - <parameter>root</parameter> field of the REG_HANDLE struct is NULL.</para> - -<para>open_key_abs() is optional. If it's NULL, the frontend will - provide a replacement, using open_key_rel().</para> - -<para>get_values() and get_value() are optional. They're only called if -the <parameter>values</parameter> field of the REG_KEY struct is NULL.</para> - -<para>get_subkeys() and get_key() are optional. THey're only called - if the <parameter>subkeys</parameter> field of the REG_KEY struct is NULL.</para> - -</sect1> - -<sect1><title>Memory allocation</title> - -<para>Okay, so who's responsible for what parts of the memory? </para> - -<para>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.</para> - -<para>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. -</para> - -</sect1> - -</chapter> |