sms(s): delete after copy to common directory
[sip-router] / modules_k / sms / doc / sms_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13         
14         <title>&adminguide;</title>
15         
16         <section>
17         <title>Overview</title>
18         <para>
19                 This module provides a way of communication between &sip; network 
20                 (via &sip; MESSAGE) and <acronym>GSM</acronym> networks 
21                 (via ShortMessageService). Communication is possible from
22                 &sip; to <acronym>SMS</acronym> and vice versa. The module provides 
23                 facilities like <acronym>SMS</acronym> confirmation--the gateway can 
24                 confirm to the &sip; user if his message really reached its 
25                 destination as a <acronym>SMS</acronym>--or multi-part
26                 messages--if a &sip; messages is too long it will be split and sent 
27                 as multiple
28                 <acronym>SMS</acronym>.
29         </para>
30         <para>
31                 Errors occurred because of an invalid number or a too long message or 
32                 because of an internal modem malfunction are reported back to the 
33                 &sip; user via a &sip; message containing explanations regarding the 
34                 error.
35         </para>
36         <section>
37                 <title>Hardware Requirements</title>
38                 <para>
39                 The <acronym>SMS</acronym> module needs a <acronym>GSM</acronym> modem 
40                 to be able to send/receive the <acronym>SMS</acronym> messages. 
41                 Usually, this kind of modems are externals, linked to the machine via 
42                 serial cable. The modem can be a dedicated one (as the ones provided 
43                 by FALCOM) or can be a <acronym>GSM</acronym> telephone that
44                 has an internal modem (as the latest mobile phones from NOKIA and 
45                 ERICSSON).
46                 </para>
47         </section>
48         <section>
49                 <title>Numbering Plan</title>
50                 <para>
51                 The gateway accepts and advertises phone numbers in international 
52                 format, more specific like: +(international code)(area code)(number). 
53                 Ex: Germany, D1 = +49 170 5678181 Romania, Connex = +40 722 123456. 
54                 A number in this format is expected to be placed as username into 
55                 <acronym>RURI</acronym> or in the To header. If <acronym>RURI</acronym> 
56                 misses the username, the To header will be consider. Also,
57                 the gateway will advertise in this format the username in Contact
58                 headers (in &sip; replies and requests) and in From headers 
59                 (in &sip; requests).
60                 </para>
61         </section>
62         <section>
63                 <title>Address Mapping</title>
64                 <para>
65                 To identify the destination number of the <acronym>SMS</acronym>, the 
66                 gateway expects to have a mobile number in username of the &sip; 
67                 destination address (for example sip:+401704678811@sidomain.net). For 
68                 the reverse direction, because the gateway has only one 
69                 <acronym>GSM</acronym> number, the destination &sip; address has to be
70                 encapsulated into the <acronym>SMS</acronym> body. The gateway expects 
71                 to find a &sip; address at the beginning of the <acronym>SMS</acronym> 
72                 body in <quote>sip:user.host</quote> format. Everything before the 
73                 &sip; address will be discarded, the useful text begins exactly after 
74                 the address (for example 
75                 SMS=<quote>For sip:user@host hello world!!</quote> -> SIP=
76                 <quote>hello world</quote>) In order to facilitate replying, the 
77                 gateway sends all the <acronym>SMS</acronym> messages with a header 
78                 containing the source &sip; address in the following format: 
79                 <quote>From sip:user@host (if you reply DONOT remove 
80                 it)&lt;new_line&gt;</quote>. When an <acronym>SMS</acronym>-reply is 
81                 received having this header (all of it or truncated at the end), the 
82                 header will be left out (it will not be in the &sip; message).
83                 </para>
84         </section>
85         </section>
86
87         <section>
88         <title>Dependencies</title>
89         <section>
90                 <title>&kamailio; Modules</title>
91                 <para>
92                 The following modules must be loaded before this module:
93                         <itemizedlist>
94                         <listitem>
95                         <para>
96                                 <emphasis>tm - Transaction Manager</emphasis>.
97                         </para>
98                         </listitem>
99                         </itemizedlist>
100                 </para>
101         </section>
102         <section>
103                 <title>External Libraries or Applications</title>
104                 <para>
105                 The following libraries or applications must be installed before running
106                 &kamailio; with this module loaded:
107                         <itemizedlist>
108                         <listitem>
109                         <para>
110                                 <emphasis>None</emphasis>.
111                         </para>
112                         </listitem>
113                         </itemizedlist>
114                 </para>
115         </section>
116         </section>
117
118         <section>
119         <title>Exported Parameters</title>
120         <section>
121                 <title><varname>modems</varname> (string)</title>
122                 <para>
123                 Define and configure one or more <acronym>GSM</acronym> modems.
124                 </para>
125                 <programlisting format="linespecific">
126 modems_value     = modem_definition *( ";" modem_definition )
127 modem_definition = modem_name "[" list_of_params "]"
128 list_of_params   = modem_param *( ";" modem_param )
129 modem_param       = name "=" value
130 </programlisting>
131                 <para>
132                 The following parameters can be used:
133                 </para>
134                 <itemizedlist>
135                 <listitem>
136                         <para>
137                         d=device (mandatory) - Device associated with modem 
138                         (/dev/ttyS0, /dev/modem, etc.).
139                         </para>
140                 </listitem>
141                 <listitem>
142                         <para>
143                         p=pin (optional) - <acronym>SIM</acronym> <acronym>PIN</acronym> - 
144                         default is NULL.
145                         </para>
146                 </listitem>
147                 <listitem>
148                         <para>
149                         m=mode (optional) - Modem working mode
150                         (<quote>ASCII</quote>,<quote>OLD</quote>,<quote>DIGICOM</quote>,
151                         <quote>NEW</quote>). Default value is <quote>NEW</quote>.
152                         </para>
153                 </listitem>
154                 <listitem>
155                         <para>
156                         c=SMS_Center (optional) - <acronym>SMS</acronym> center number for 
157                         that modem. Default is the <acronym>SMS</acronym> center set on the
158                         <acronym>SIM</acronym> card.
159                         </para>
160                 </listitem>
161                 <listitem>
162                         <para>
163                         b=baudrate (optional) - Default is 19600.
164                         </para>
165                 </listitem>
166                 <listitem>
167                         <para>
168                         r=retry (optional) - How many times to try to re-send a
169                         <acronym>SMS</acronym> that reported error. Default is twice.
170                         </para>
171                 </listitem>
172                 <listitem>
173                         <para>
174                         l=looping (optional) - Time for modem to wait before performing a 
175                         new check for incomimg/outgoing <acronym>SMS</acronym>/SIP_MSG.
176                         Default is 20.
177                         </para>
178                 </listitem>
179                 </itemizedlist>
180                 <para>
181                 <emphasis>
182                         No default value, the parameter is mandatory.
183                 </emphasis>
184                 </para>
185                 <example>
186                 <title>Set <varname>modems</varname> parameter</title>
187                 <programlisting format="linespecific">
188 ...
189 modparam("sms", "modems", "Nokia [d=/dev/ttyS1;b=9600;m=new;l=30] ")
190 modparam("sms", "modems", "Nokia[d=/dev/ttyS1];Siemens[d=/dev/ttyS2]")
191 ...
192 </programlisting>
193                 </example>
194         </section>
195
196         <section>
197                 <title><varname>networks</varname> (string)</title>
198                 <para>
199                 Define and configure used <acronym>GSM</acronym> networks.
200                 </para>
201                 <programlisting format="linespecific">
202 networks_value = net_definition *( ";" net_definition )
203 net_definition = net_name "[" list_of_params "]"
204 list_of_params = set_param *( ";" set_param )
205 set_param         = name "=" value
206 </programlisting>
207                 <para>
208                 The following parameters can be used:
209                 </para>
210                 <itemizedlist>
211                 <listitem>
212                         <para>
213                         m=msx_sms_per_call (optional) - Maximum number of 
214                         <acronym>SMS</acronym> send / received from that net in one modem 
215                         loop. Default is 10. This parameter was introduced to avoid 
216                         starvation.
217                         </para>
218                         <para>
219                         Example of the starvation--a modem can send 
220                         <acronym>SMS</acronym> for more than 1 networks. If you have a 
221                         huge number of <acronym>SMS</acronym> for the first network and 
222                         the number of incoming &sip; messages is equal to the sent
223                         <acronym>SMS</acronym> per same unit of time, the modem will 
224                         never get to send <acronym>SMS</acronym> for the next networks.
225                         </para>
226                 </listitem>
227                 </itemizedlist>
228                 <para>
229                 <emphasis>
230                         No default value, the parameter is mandatory.
231                 </emphasis>
232                 </para>
233                 <example>
234                 <title>Set <varname>networks</varname> parameter</title>
235                 <programlisting format="linespecific">
236 ...
237 modparam("sms", "networks", "D1 [m=10] ;d2[ m=20]")
238 ...
239 </programlisting>
240                 </example>
241         </section>
242
243         <section>
244                 <title><varname>links</varname> (string)</title>
245                 <para>
246                 Define from which network each modem should send <acronym>SMS</acronym>.
247                 </para>
248                 <programlisting format="linespecific">
249 links_value = modem_assoc *( ";" modem_assoc )
250 modem_assoc = modem_name "[" list_of_networks "]"
251 list_of_networks = network *( ";" network )
252 </programlisting>
253                 <para>
254                 <emphasis>
255                         No default value, the parameter is mandatory.
256                 </emphasis>
257                 </para>
258                 <example>
259                 <title>Set <varname>links</varname> parameter</title>
260                 <programlisting format="linespecific">
261 ...
262 modparam("sms", "links", "NOKIA[D1;d2]")
263 ...
264 </programlisting>
265                 </example>
266                 <para>
267                 The modem NOKIA will send <acronym>SMS</acronym> from D1 and D2 net 
268                 (in this order !). if in a net queue are more then max_sms_per_call 
269                 <acronym>SMS</acronym> the modem will <emphasis>not sleep</emphasis> 
270                 before starting the next loop ! Shortly, if messages are waiting to
271                 be sent, the modem will not go in sleep.
272                 </para>
273         </section>
274
275         <section>
276                 <title><varname>default_net</varname> (string)</title>
277                 <para>
278                 The default network to use. If no one specified, the first defined
279                 network is used. This parameter is useful only if the 
280                 <quote>sms_send_msg</quote> exported function is used 
281                 (see <xref linkend="sec-exported-functions"/>).
282                 </para>
283                 <example>
284                 <title>Set <varname>default_net</varname> parameter</title>
285                 <programlisting format="linespecific">
286 ...
287 modparam("sms", "default_net", "D1")
288 ...
289 </programlisting>
290                 </example>
291         </section>
292
293         <section>
294                 <title><varname>max_sms_parts</varname> (integer)</title>
295                 <para>
296                 Shows in how many parts (<acronym>SMS</acronym> messages) a &sip; 
297                 message can be split. If exceeded, the &sip; message will be sent 
298                 truncated and the &sip; user will get back another message containing 
299                 the unsent part.
300                 </para>
301                 <para>
302                 <emphasis>
303                         Default value is 4.
304                 </emphasis>
305                 </para>
306                 <example>
307                 <title>Set <varname>max_sms_parts</varname> parameter</title>
308                 <programlisting format="linespecific">
309 ...
310 modparam("sms", "max_sms_parts", 10)
311 ...
312 </programlisting>
313                 </example>
314         </section>      
315
316         <section>
317                 <title><varname>domain</varname> (string)</title>
318                 <para>
319                 Specify a fake domain name to be used by the gateway. The Contact 
320                 headers and the From header from request will be construct based on 
321                 this fake domain name. It's useful when the gateway is transparently 
322                 hidden behind a proxy/register (located on different machines).
323                 </para>
324                 <para>
325                 <emphasis>
326                         Default is the name of the machine the gateway is running on.
327                 </emphasis>
328                 </para>
329                 <example>
330                 <title>Set <varname>domain_str</varname> parameter</title>
331                 <programlisting format="linespecific">
332 ...
333 modparam("sms", "domain_str", "foo.bar")
334 ...
335 </programlisting>
336                 </example>
337         </section>
338
339         <section>
340                 <title><varname>use_contact</varname> (integer)</title>
341                 <para>
342                 If a contact header should be added to the outgoing &sip; messages. 
343                 Even if the &sip; draft forbids this, some &uas; require it. 
344                 </para>
345                 <para>
346                 <emphasis>
347                         Default is 0 (no).
348                 </emphasis>
349                 </para>
350                 <example>
351                 <title>Set <varname>use_contact</varname> parameter</title>
352                 <programlisting format="linespecific">
353 ...
354 modparam("sms", "use_contact", 1)
355 ...
356 </programlisting>
357                 </example>
358         </section>
359
360         <section>
361                 <title><varname>sms_report_type</varname> (integer)</title>
362                 <para>
363                 If the modem should ask for <acronym>SMS</acronym> confirmation from the
364                 <acronym>SMS</acronym> Center. If the <acronym>SMSC</acronym> reply 
365                 with an error code, the gateway will send back to &sip; user a &sip; 
366                 message containing the text (or part of it) that couldn't be send. Two 
367                 report mechanisms are implemented:
368                 </para>
369                 <itemizedlist>
370                 <listitem>
371                         <para>
372                         1 - the reports are delivered by the <acronym>GSM</acronym> device 
373                         as <acronym>SMS</acronym> reports (so far supported only by Nokia 
374                         modems);
375                         </para>
376                 </listitem>
377                 <listitem>
378                         <para>
379                         2 - the reports are delivered as async. <acronym>CDS</acronym> 
380                         responses (supported by almost all modems, except Ericsson).
381                         </para>
382                 </listitem>
383                 </itemizedlist>
384                 <para>
385                 <emphasis>
386                         Default is 0 (no report).
387                 </emphasis>
388                 </para>
389                 <example>
390                 <title>Set <varname>sms_report_type</varname> parameter</title>
391                 <programlisting format="linespecific">
392 ...
393 modparam("sms", "sms_report_type", 1)
394 ...
395 </programlisting>
396                 </example>
397         </section>      
398
399         </section>
400         <section id="sec-exported-functions">
401         <title>Exported Functions</title>
402         <section>
403                 <title>
404                 <function moreinfo="none">sms_send_msg_to_net(network_name)</function>
405                 </title>
406                 <para>
407                 Put the &sip; msg in the specified network queue. The function return 
408                 error if the number encapsulated into &sip; message is malformed, if 
409                 the content_type is incorrect or because of some internal failures.
410                 </para>
411                 <para>Meaning of the parameters is as follows:</para>
412                 <itemizedlist>
413                 <listitem>
414                         <para>
415                         <emphasis>network_name</emphasis> - Name of network.
416                         </para>
417                 </listitem>
418                 </itemizedlist>
419                 <para>
420                 This function can be used from REQUEST_ROUTE.
421                 </para>
422                 <example>
423                 <title><function>sms_send_msg_to_net</function> usage</title>
424                 <programlisting format="linespecific">
425 ...
426 if (sms_send_msg_to_net("D1"))
427 {
428         if (!t_reply("202", "yes sir, SMS sent over"))
429         {
430                 # if replying failed, retry statelessly
431                 sl_reply_error();
432         };
433 } else {
434         if (!t_reply("502", "Bad gateway - SMS error"))
435         {
436                 # if replying failed, retry statelessly
437                 sl_reply_error();
438         };
439         exit;
440 };
441 ...
442 </programlisting>
443                 </example>
444         </section>
445
446         <section>
447                 <title>
448                 <function moreinfo="none">sms_send_msg()</function>
449                 </title>
450                 <para>
451                 The same as the previous one, but use the default network queue.
452                 </para>
453                 <para>
454                 This function can be used from REQUEST_ROUTE.
455                 </para>
456                 <example>
457                 <title><function>sms_send_msg</function> usage</title>
458                 <programlisting format="linespecific">
459 ...
460 if (sms_send_msg_to_net())
461 {
462         if (!t_reply("202", "yes sir, SMS sent over"))
463         {
464                 # if replying failed, retry statelessly
465                 sl_reply_error();
466         };
467 } else {
468         if (!t_reply("502", "Bad gateway - SMS error"))
469         {
470                 # if replying failed, retry statelessly
471                 sl_reply_error();
472         };
473         exit;
474 };
475 ...
476 </programlisting>
477                 </example>
478         </section>
479         </section>
480 </chapter>
481