path: root/docs/docbook/devdoc/modules.xml

<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>