git.sip-router.org Git - sip-router/blob - 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