-
Notifications
You must be signed in to change notification settings - Fork 909
/
module_exports.xml
316 lines (314 loc) · 10.7 KB
/
module_exports.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
<?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>