modiface.sgml

用来作为linux中SIP SERVER,完成VOIP网络电话中服务器的功能

		
struct param_export_ {
	char* name;             /* null terminated param. name */
	modparam_t type;        /* param. type */
	void* param_pointer;    /* pointer to the param. memory location */
};

typedef struct param_export_ param_export_t;
</programlisting>
	    <itemizedlist>
		<title>Meaning of the fields:</title>
		<listitem>
		    <simpara><varname>char* name</varname></simpara>
		    <simpara>
			This is null-terminated name of the parameters as it will be used in the
			scripts. Usually this is the same as the name of the variable holding the
			value.
		    </simpara>
		</listitem>
		<listitem>
		    <simpara><varname>modparam_t type</varname></simpara>
		    <simpara>
			Type of the parameter. Currently only two types are defined. INT_PARAM for
			integer parameters (corresponding variable must be of type int) and
			STR_PARAM for string parameters (corresponding variable must be of type
			char*).
		    </simpara>
		</listitem>
		<listitem>
		    <simpara><varname>void* param_pointer</varname></simpara>
		    <simpara>
			Pointer to the corresponding variable (stored as void* pointer, make sure
			that the variable has appropriate type depending on the type of the
			parameter !).
		    </simpara>
		</listitem>
	    </itemizedlist>
	</section>
	<section>
	    <title>Module Initialization</title>
	    <simpara>
		If you need to initialize your module before the server starts processing
		<acronym>SIP</acronym> messages, you should provide initialization function. Each
		module can provide two initialization functions, main initialization function and
		child-specific initialization function.  Fields holding pointers to both
		initialization functions are in main export structure (will be described
		later). Simply pass 0 instead of function pointer if you don't need one or both
		initialization functions.
	    </simpara>
	    <simpara>
		The main initialization function will be called before any other function exported
		by the module. The function will be called only once, before the main process
		forks. This function is good for initialization that is common for all the children
		(processes). The function should return 0 if everything went OK and a negative error
		code otherwise. Server will abort if the function returns a negative value.
	    </simpara>
	    <simpara>
		Per-child initialization function will be called <emphasis>after</emphasis> the main
		process forks. The function will be called for each child separately. The function
		should perform initialization that is specific for each child. For example each
		child process might open it's own database connection to avoid locking of a single
		connection shared by many processes. Such connections can be opened in the per-child
		initialization function. The function accepts one parameter which is rank (integer)
		of child for which the function is being executed. This allows developers to
		distinguish different children and perform different initialization for each
		child. The meaning of return value is same as in the main initialization function.
	    </simpara>
	</section>
	<section>
	    <title>Module Clean-up</title>
	    <simpara>
		A module can also export a clean-up function that will be called by the main process
		when the server shuts down. The function accepts no parameters and return no value.
	    </simpara>
	</section>
	<section>
	    <title>Module Callbacks</title>
	    <para>
		TBD.
	    </para>
	</section>
	<section>
	    <title><structname>exports</structname> Structure - Assembling the Pieces Together</title>
	    <simpara>
		We have already described how a module can export functions and parameters, but we
		haven't yet described how to pass this information to the core. Each module must
		have variable named <varname>exports</varname> which is structure
		module_exports. The variable will be looked up by the core immediately after it
		loads the module. The structure contains pointers to both arrays (functions,
		parameters), pointers to both initialization functions, destroy function and the
		callbacks. So the structure contains everything the core will need.
	    </simpara>
	    <simpara>The structure looks like the follows:</simpara>
	    <programlisting format="linespecific">
struct module_exports{
    char* name;                     /* null terminated module name */
    cmd_export_t* cmds;             /* null terminated array of the exported commands */
    param_export_t* params;         /* null terminated array of the exported module 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>
	    <itemizedlist>
		<title>Field description:</title>
		<listitem>
		    <simpara><varname>char* name</varname></simpara>
		    <simpara>Null terminated name of the module</simpara>
		</listitem>
		<listitem>
		    <simpara><varname>cmd_exports* cmds</varname></simpara>
		    <simpara>
			Pointer to the array of exported functions
		    </simpara>
		</listitem>
		<listitem>
		    <simpara><varname>param_export_t* params</varname></simpara>
		    <simpara>
			Pointer to the array of exported parameters
		    </simpara>
		</listitem>
		<listitem>
		    <simpara><varname>init_function init_f</varname></simpara>
		    <simpara>Pointer to the module initialization function</simpara>
		</listitem>
		<listitem>
		    <simpara><varname>response_function response_f</varname></simpara>
		    <simpara>Pointer to function processing responses</simpara>
		</listitem>
		<listitem>
		    <simpara><varname>destroy_function destroy_f</varname></simpara>
		    <simpara>Pointer to the module clean-up function</simpara>
		</listitem>
		<listitem>
		    <simpara><varname>onbreak_function onbreak_f</varname></simpara>
		    <simpara>TBD</simpara>
		</listitem>
		<listitem>
		    <simpara><varname>child_init_function init_child_f</varname></simpara>
		    <simpara>Pointer to the per-child initialization function</simpara>
		</listitem>
	    </itemizedlist>
	</section>
	<section>
	    <title>Example - Simple Module Interface</title>
	    <para>
		Let's suppose that we are going to write a simple module. The module will export two functions - 
		<function moreinfo="none">foo_req</function> which will be processing <acronym>SIP</acronym> requests and 
		<function moreinfo="none">foo_int</function> which is an internal function that can be called by other modules only.
		Both functions will take 2 parameters.
	    </para>
	    <programlisting format="linespecific">
/* Prototypes */
int foo_req(struct sip_msg* msg, char* param1, char* param2);
int foo_res(struct sip_msg* msg, char* param1, char* param2);

static cmd_export cmds[] = {
    {"foo_req", foo_req, 2, 0, ROUTE_REQUEST},
    {"foo_int", foo_int, 2, 0, 0            },
    {0, 0, 0, 0}
};
</programlisting>
	    <para>
		The module will also have two parameters, foo_bar of type integer and bar_foo of type string.
	    </para>
	    <programlisting format="linespecific">
int foo_bar = 0;
char* bar_foo = "default value";

static param_export params[] = {
    {"foo_bar", INT_PARAM, &amp;foo_bar},
    {"bar_foo", STR_PARAM, bar_foo     },
    {0, 0, 0}
}; 
</programlisting>
	    <para>
		We will also create both initialization functions and a clean-up function:
	    </para>
	    <programlisting format="linespecific">
static int mod_init(void)
{
    printf("foo module initializing\n");
}

static int child_init(int rank)
{
    printf("child nr. %d initializing\n", rank);
    return 0;
}

static void destroy(void)
{
    printf("foo module cleaning up\n");
}
</programlisting>
	    <para>
		And finally we put everything into the exports structure:
	    </para>
	    <programlisting format="linespecific">
struct module_exports exports = {
    "foobar",   /* Module name */
    cmds,       /* Exported functions */
    params,     /* Exported parameters */
    mod_init,   /* Module initialization function */
    0,          /* Response function */
    destroy,    /* Clean-up function */
    0,          /* On Cancel function */
    child_init  /* Per-child init function */
};
</programlisting>
	    <simpara>And that's it.</simpara>
	</section>
    </chapter>
</book>