mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
317 lines
11 KiB
317 lines
11 KiB
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
|
|
|
<section id="module_exports" xmlns:xi="http://www.w3.org/2001/XInclude">
|
|
<sectioninfo>
|
|
<revhistory>
|
|
<revision>
|
|
<revnumber>$Revision$</revnumber>
|
|
<date>$Date$</date>
|
|
</revision>
|
|
</revhistory>
|
|
</sectioninfo>
|
|
|
|
<title>Structure <structname>module_exports</structname></title>
|
|
<para>
|
|
This structure describes interface that must be exported by each
|
|
module. Every module must have a global variable named
|
|
<varname>exports</varname> which is of type <structname>struct
|
|
module_exports</structname>.
|
|
</para>
|
|
<para>
|
|
Immediately after <function>dlopen</function> the server will try to
|
|
find symbol named <varname>exports</varname> in the module to be
|
|
loaded. This symbol is a structure describing interface of the
|
|
module. Pointer to the symbol will be then put in
|
|
<structfield>exports</structfield> field of
|
|
<structname>sr_module</structname> structure representing the module in
|
|
the server.
|
|
</para>
|
|
<para>
|
|
Detailed description of the structure follows:
|
|
</para>
|
|
<programlisting>
|
|
struct module_exports{
|
|
char* name; /* null terminated module name */
|
|
char** cmd_names; /* cmd names registered
|
|
* by this module */
|
|
cmd_function* cmd_pointers; /* pointers to the
|
|
* corresponding functions */
|
|
int* param_no; /* number of parameters used by
|
|
* the function */
|
|
fixup_function* fixup_pointers; /* pointers to functions
|
|
* called to "fix"
|
|
* the params, e.g: precompile
|
|
* a re */
|
|
int cmd_no; /* number of registered commands
|
|
* (size of cmd_{names,pointers}
|
|
*/
|
|
char** param_names; /* parameter names registered
|
|
* by this module */
|
|
modparam_t* param_types; /* Type of parameters */
|
|
void** param_pointers; /* Pointers to the corresponding
|
|
* memory locations */
|
|
int par_no; /* number of registered parameters */
|
|
init_function init_f; /* Initialization function */
|
|
response_function response_f; /* function used for responses,
|
|
* returns yes or no; can be null
|
|
*/
|
|
destroy_function destroy_f; /* function called when the module
|
|
* should be "destroyed", e.g: on
|
|
* ser exit;
|
|
* can be null */
|
|
onbreak_function onbreak_f;
|
|
child_init_function init_child_f; /* function called by all
|
|
* processes after the fork */
|
|
};
|
|
</programlisting>
|
|
<para>
|
|
<emphasis>Fields and their description</emphasis>:
|
|
</para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<structfield>name</structfield> - Name of the module.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>cmd_names</structfield> - Array of names of
|
|
exported commands.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>cmd_pointers</structfield> - Array of pointers to
|
|
functions implementing commands specified in
|
|
<structfield>cmd_names</structfield> array.
|
|
</para>
|
|
<para>
|
|
<emphasis>Function Prototype</emphasis>:
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>cmd_function</function></funcdef>
|
|
<paramdef>struct sip_msg* <parameter>msg</parameter></paramdef>
|
|
<paramdef>char* <parameter>param1</parameter></paramdef>
|
|
<paramdef>char* <parameter>param2</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The first parameter is <structname>sip_msg</structname>
|
|
currently being processed. Remaining parameters are parameters
|
|
from the config file. If the function accepts only one
|
|
parameter, <parameter>param2</parameter> will be set to zero,
|
|
if the function accepts no parameters,
|
|
<parameter>param1</parameter> and <parameter
|
|
moreinfo="none">param2</parameter> will be set to zero.
|
|
</para>
|
|
<para>
|
|
The function should return number > 0 if everything went OK
|
|
and processing of the message should continue. The function
|
|
should return 0 if processing of the message should be stopped.
|
|
The function should return number < 0 on an error.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>param_no</structfield> - Array of number of
|
|
parameters of exported commands.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>fixup_pointer</structfield> - Array of pointers to
|
|
fixup functions, each fixup function for one exported
|
|
command. If there is no fixup function for a particular
|
|
exported function, corresponding field in the array will
|
|
contain zero.
|
|
</para>
|
|
<para>
|
|
<emphasis>Function Prototype</emphasis>:
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>fixup_function</function></funcdef>
|
|
<paramdef>void** <parameter>param</parameter></paramdef>
|
|
<paramdef>int <parameter>param_no</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The first parameter is pointing to variable to be fixed. The
|
|
second parameter is order of the variable.
|
|
</para>
|
|
<para>
|
|
The function should return 0 if everything went OK and number
|
|
< 0 on an error.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>cmd_no</structfield> - Number of exported commands.
|
|
</para>
|
|
<important>
|
|
<para>
|
|
<structfield>cmd_names</structfield>,
|
|
<structfield>cmd_pointers</structfield>,
|
|
<structfield>param_no</structfield> and
|
|
<structfield>fixup_pointer</structfield> arrays must have
|
|
at least <structfield>cmd_no</structfield> elements ! (It
|
|
might even kill your cat if you fail to fulfill this
|
|
condition).
|
|
</para>
|
|
</important>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>param_names</structfield> - Array of names of
|
|
exported parameters.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>param_types</structfield> - Array of types of
|
|
parameters, each field of the array can be either PARAM_STR/PARAM_STRING or
|
|
PARAM_INT (currently only three parameter types are defined).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>param_pointers</structfield> - Array of pointers
|
|
to variables, that hold values of the parameters.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>param_no</structfield> - Number of exported
|
|
parameters.
|
|
</para>
|
|
<important>
|
|
<para>
|
|
<structfield>param_names</structfield>,
|
|
<structfield>param_types</structfield> and
|
|
<structfield>param_pointers</structfield> arrays must have
|
|
at least <structfield>param_no</structfield> elements !
|
|
(Remember the previous note about your cat ? The same might
|
|
happen to your dog if you fail to fulfill the condition
|
|
second time !).
|
|
</para>
|
|
</important>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>init_f</structfield> - Pointer to module's
|
|
initialization function, 0 if the module doesn't need
|
|
initialization function.
|
|
</para>
|
|
<para>
|
|
<emphasis>Function Prototype</emphasis>:
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>init_function</function></funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The function should return 0 if everything went OK and number
|
|
< 0 on an error;
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>response_f</structfield> - If a module is
|
|
interested in seeing responses, it will provide pointer to a
|
|
function here. The function will be called when a response
|
|
comes. The field will contain 0 if the module doesn't want to
|
|
see responses.
|
|
</para>
|
|
<para>
|
|
<emphasis>Function Prototype</emphasis>:
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>response_function</function></funcdef>
|
|
<paramdef>struct sip_msg* <parameter>msg</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The function accepts one parameter which is structure
|
|
representing the response currently being processed.
|
|
</para>
|
|
<para>
|
|
The function should return 0 if the response should be dropped.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>destroy_f</structfield> - Destroy function. The
|
|
function will be called when the server is shutting down. Can
|
|
be 0 if the module doesn't need destroy function.
|
|
</para>
|
|
<para>
|
|
<emphasis>Function Prototype</emphasis>:
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>destroy_function</function></funcdef>
|
|
<void/>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>onbreak_f</structfield> - On break function. The
|
|
function will be called when processing of a route statement
|
|
was aborted. Can be 0 if module doesn't need this function.
|
|
</para>
|
|
<para>
|
|
<emphasis>Function Prototype</emphasis>:
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>void <function>onbreak_function</function></funcdef>
|
|
<paramdef>struct sip_msg* <parameter>msg</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The function accepts one parameter which is message currently
|
|
being processed.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<structfield>init_child_f</structfield> - Child initialization
|
|
function. This is an additional initialization
|
|
function. <structfield>init_f</structfield> will be called from
|
|
the main process <emphasis>BEFORE</emphasis> the main process
|
|
forks children. <structfield>init_child_f</structfield> will be
|
|
called from all children <emphasis>AFTER</emphasis> the fork.
|
|
</para>
|
|
<para>
|
|
Per-child specific initialization can be done here. For
|
|
example, each child can open its own database connection in the
|
|
function, and so on.
|
|
</para>
|
|
<para>
|
|
<emphasis>Function Prototype</emphasis>:
|
|
</para>
|
|
<funcsynopsis>
|
|
<funcprototype>
|
|
<funcdef>int <function>child_init_function</function></funcdef>
|
|
<paramdef>int <parameter>rank</parameter></paramdef>
|
|
</funcprototype>
|
|
</funcsynopsis>
|
|
<para>
|
|
The function accepts one parameter, which is rank (starting
|
|
from 0) of child executing the function.
|
|
</para>
|
|
<para>
|
|
The function should return 0 if everything went OK and number
|
|
< 0 on an error.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|