diff options
Diffstat (limited to 'docs/docbook/devdoc/modules.xml')
| -rw-r--r-- | docs/docbook/devdoc/modules.xml | 328 |
1 files changed, 0 insertions, 328 deletions
diff --git a/docs/docbook/devdoc/modules.xml b/docs/docbook/devdoc/modules.xml deleted file mode 100644 index 3adf130911..0000000000 --- a/docs/docbook/devdoc/modules.xml +++ /dev/null @@ -1,328 +0,0 @@ -<chapter id="modules"> -<chapterinfo> - <author> - <firstname>Jelmer</firstname><surname>Vernooij</surname> - <affiliation> - <orgname>Samba Team</orgname> - <address><email>jelmer@samba.org</email></address> - </affiliation> - </author> - <author> - <firstname>Stefan</firstname><surname>Metzmacher</surname> - <affiliation> - <address><email>metze@metzemix.de</email></address> - </affiliation> - <contrib>events interface</contrib> - </author> - <pubdate> 17 September 2003 </pubdate> -</chapterinfo> - -<title>Modules</title> - -<sect1> -<title>Advantages</title> - -<para> -The new modules system has the following advantages: -</para> - -<simplelist> -<member>Transparent loading of static and shared modules (no need -for a subsystem to know about modules)</member> -<member>Simple selection between shared and static modules at configure time</member> -<member>"preload modules" option for increasing performance for stable modules</member> -<member>No nasty #define stuff anymore</member> -<member>All backends are available as plugin now (including pdb_ldap and pdb_tdb)</member> -</simplelist> -</sect1> - -<sect1> -<title>Loading modules</title> - -<para> -Some subsystems in samba use different backends. These backends can be -either statically linked in to samba or available as a plugin. A subsystem -should have a function that allows a module to register itself. For example, -the passdb subsystem has: -</para> - -<para><programlisting> -NTSTATUS smb_register_passdb(int version, const char *name, pdb_init_function init); -</programlisting></para> - -<para> -This function will be called by the initialisation function of the module to -register itself. -</para> - -<sect2> -<title>Static modules</title> - -<para> -The modules system compiles a list of initialisation functions for the -static modules of each subsystem. This is a define. For example, -it is here currently (from <filename>include/config.h</filename>): -</para> - -<para><programlisting> -/* Static init functions */ -#define static_init_pdb { pdb_mysql_init(); pdb_ldap_init(); pdb_smbpasswd_init(); pdb_tdbsam_init(); pdb_guest_init();} -</programlisting></para> - -<para> -These functions should be called before the subsystem is used. That -should be done when the subsystem is initialised or first used. -</para> - -</sect2> - -<sect2> -<title>Shared modules</title> - -<para> -If a subsystem needs a certain backend, it should check if it has -already been registered. If the backend hasn't been registered already, -the subsystem should call smb_probe_module(char *subsystem, char *backend). -This function tries to load the correct module from a certain path -($LIBDIR/subsystem/backend.so). If the first character in 'backend' -is a slash, smb_probe_module() tries to load the module from the -absolute path specified in 'backend'. -</para> - -<para>After smb_probe_module() has been executed, the subsystem -should check again if the module has been registered. -</para> - -</sect2> -</sect1> - -<sect1> -<title>Writing modules</title> - -<para> -Each module has an initialisation function. For modules that are -included with samba this name is '<replaceable>subsystem</replaceable>_<replaceable>backend</replaceable>_init'. For external modules (that will never be built-in, but only available as a module) this name is always 'init_module'. (In the case of modules included with samba, the configure system will add a #define subsystem_backend_init() init_module()). -The prototype for these functions is: -</para> - -<para><programlisting> -NTSTATUS init_module(void); -</programlisting></para> - -<para>This function should call one or more -registration functions. The function should return NT_STATUS_OK on success and -NT_STATUS_UNSUCCESSFUL or a more useful nt error code on failure.</para> - -<para>For example, pdb_ldap_init() contains: </para> - -<para><programlisting> -NTSTATUS pdb_ldap_init(void) -{ -smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam", pdb_init_ldapsam); -smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam_nua", pdb_init_ldapsam_nua); - return NT_STATUS_OK; -} -</programlisting></para> - -<sect2> -<title>Static/Shared selection in configure.in</title> - -<para> -Some macros in configure.in generate the various defines and substs that -are necessary for the system to work correct. All modules that should -be built by default have to be added to the variable 'default_modules'. -For example, if ldap is found, pdb_ldap is added to this variable. -</para> - -<para> -On the bottom of configure.in, SMB_MODULE() should be called -for each module and SMB_SUBSYSTEM() for each subsystem. -</para> - -<para>Syntax:</para> - -<para><programlisting> -SMB_MODULE(<replaceable>subsystem</replaceable>_<replaceable>backend</replaceable>, <replaceable>object files</replaceable>, <replaceable>plugin name</replaceable>, <replaceable>subsystem name</replaceable>, <replaceable>static_action</replaceable>, <replaceable>shared_action</replaceable>) -SMB_SUBSYSTEM(<replaceable>subsystem</replaceable>,<replaceable>depfile</replaceable>) -</programlisting></para> - -<para>The depfile for a certain subsystem is the file that calls the -initialisation functions for the statically built in modules.</para> - -<para> -<replaceable>@SUBSYSTEM_MODULES@</replaceable> in Makefile.in will -be replaced with the names of the plugins to build. -</para> - -<para>You must make sure all .c files that contain defines that can -be changed by ./configure are rebuilded in the 'modules_clean' make target. -Practically, this means all c files that contain <command>static_init_subsystem;</command> calls need to be rebuilded. -</para> - -<note> -<para> -There currently also is a configure.in command called SMB_MODULE_PROVIVES(). -This is used for modules that register multiple things. It should not -be used as probing will most likely disappear in the future.</para> -</note> - -</sect2> -</sect1> - -<sect1> -<title>Registration of events</title> - -<sect2> -<title>Intention</title> - -<para> -For some modules it is necessary to drop idle database connections, -or do other things periodically. -Some modules need to do close database connections or similar things -when the server exits. -</para> - -</sect2> - -<sect2> -<title>Advantages</title> - -<para> -The event registration system has the following advantages: -</para> - -<simplelist> -<member>Every module is able to register/unregister idle or exit handlers called from the main server loop</member> -<member>No need for hacking the main server anymore</member> -</simplelist> - -</sect2> - -<sect2> -<title>General stuff</title> - -<para> -Each event has an event_id of type smb_event_id_t, which identifies the event in its event list. -(Take a look at <filename>include/module.h</filename> and <filename>lib/module.c</filename>.) -There are currently two event types: -</para> - -<simplelist> -<member>idle events</member> -<member>exit events</member> -</simplelist> - -</sect2> - -<sect2> -<title>Type: idle event</title> - -<para> -Idle events are called periodically from the main server loop. -if the specified interval is less or equal than 0, the default SMB_IDLE_EVENT_DEFAULT_INTERVAL (180 s) is used. -if the specified interval is less than SMB_IDLE_EVENT_MIN_INTERVAL (30 s), SMB_IDLE_EVENT_MIN_INTERVAL is used. -In any other case the specified interval is used. -</para> - -<note><para> -the real interval can be differ from the specified interval about up to +/- 30 s. -</para></note> - -<para> -Idle events can be registered via the -<programlisting> -smb_event_id_t smb_register_idle_event(smb_idle_event_fn *fn, void *data, time_t interval); -</programlisting> function. -</para> - -<variablelist> - -<varlistentry><term>fn</term> -<listitem><para> -the function pointer to idle handler function. -this function must have the following prototype! -<programlisting> -void example_idle_event_fn(void **data, time_t *interval, time_t now); -</programlisting> -</para></listitem> -</varlistentry> - -<varlistentry><term>data</term> -<listitem><para>this is a pointer to private data which is passed to the idle function when it's called.</para></listitem> -</varlistentry> - -<varlistentry><term>interval</term> -<listitem><para> -this is a pointer to the time_t interval in witch the idle handler function is called. -the idle handler is able to change it's interval. -</para></listitem> -</varlistentry> -</variablelist> - -<para> -the event_id is returned on succes, on failure SMB_EVENT_ID_INVALID is returned. -</para> - -<para> -Idle events can be unregistered via the -<programlisting> -BOOL smb_unregister_idle_event(smb_event_id_t id); -</programlisting> function. -</para> - -<para> -True is returned on success, False on failure. -</para> - -</sect2> - -<sect2> -<title>Type: exit event</title> - -<para>Exit events are called when the server exits</para> - -<para> -Exit events can be registered via the -<programlisting> -smb_event_id_t smb_register_exit_event(smb_exit_event_fn *fn, void *data); -</programlisting> function. -</para> - -<variablelist> - -<varlistentry><term>fn</term> -<listitem><para> -the function pointer to exit handler function. -this function must have the following prototype! -<programlisting> -void example_exit_event_fn(void **data); -</programlisting> -</para></listitem> -</varlistentry> - -<varlistentry><term>data</term> -<listitem><para>this is a pointer to private data which is passed to the exit function when it's called.</para></listitem> -</varlistentry> - -</variablelist> - -<para> -the event_id is returned on success, on failure SMB_EVENT_ID_INVALID is returned. -</para> - -<para> -Exit events can be unregistered via the -<programlisting> -BOOL smb_unregister_exit_event(smb_event_id_t id); -</programlisting> function. -</para> - -<para> -True is returned on succes, False on failure. -</para> - -</sect2> - -</sect1> - -</chapter> |