SMS Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview

              1.1.1. Hardware Requirements
              1.1.2. Numbering Plan
              1.1.3. Address Mapping

        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. modems (string)
              1.3.2. networks (string)
              1.3.3. links (string)
              1.3.4. default_net (string)
              1.3.5. max_sms_parts (integer)
              1.3.6. domain (string)
              1.3.7. use_contact (integer)
              1.3.8. sms_report_type (integer)

        1.4. Exported Functions

              1.4.1. sms_send_msg_to_net(network_name)
              1.4.2. sms_send_msg()

   2. Developer Guide
   3. Contributors

        3.1. By Commit Statistics
        3.2. By Commit Activity

   4. Documentation

        4.1. Contributors

   List of Tables

   3.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   3.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set modems parameter
   1.2. Set networks parameter
   1.3. Set links parameter
   1.4. Set default_net parameter
   1.5. Set max_sms_parts parameter
   1.6. Set domain_str parameter
   1.7. Set use_contact parameter
   1.8. Set sms_report_type parameter
   1.9. sms_send_msg_to_net usage
   1.10. sms_send_msg usage

Chapter 1. Admin Guide

1.1. Overview

   This module provides a way of communication between SIP network
   (via SIP MESSAGE) and GSM networks (via ShortMessageService).
   Communication is possible from SIP to SMS and vice versa. The
   module provides facilities like SMS confirmation--the gateway
   can confirm to the SIP user if his message really reached its
   destination as a SMS--or multi-part messages--if a SIP messages
   is too long it will be split and sent as multiple SMS.

   Errors occurred because of an invalid number or a too long
   message or because of an internal modem malfunction are
   reported back to the SIP user via a SIP message containing
   explanations regarding the error.

1.1.1. Hardware Requirements

   The SMS module needs a GSM modem to be able to send/receive the
   SMS messages. Usually, this kind of modems are externals,
   linked to the machine via serial cable. The modem can be a
   dedicated one (as the ones provided by FALCOM) or can be a GSM
   telephone that has an internal modem (as the latest mobile
   phones from NOKIA and ERICSSON).

1.1.2. Numbering Plan

   The gateway accepts and advertises phone numbers in
   international format, more specific like: +(international
   code)(area code)(number). Ex: Germany, D1 = +49 170 5678181
   Romania, Connex = +40 722 123456. A number in this format is
   expected to be placed as username into RURI or in the To
   header. If RURI misses the username, the To header will be
   consider. Also, the gateway will advertise in this format the
   username in Contact headers (in SIP replies and requests) and
   in From headers (in SIP requests).

1.1.3. Address Mapping

   To identify the destination number of the SMS, the gateway
   expects to have a mobile number in username of the SIP
   destination address (for example
   sip:+401704678811@sidomain.net). For the reverse direction,
   because the gateway has only one GSM number, the destination
   SIP address has to be encapsulated into the SMS body. The
   gateway expects to find a SIP address at the beginning of the
   SMS body in “sip:user.host” format. Everything before the SIP
   address will be discarded, the useful text begins exactly after
   the address (for example SMS=“For sip:user@host hello world!!”
   -> SIP= “hello world”) In order to facilitate replying, the
   gateway sends all the SMS messages with a header containing the
   source SIP address in the following format: “From sip:user@host
   (if you reply DONOT remove it)<new_line>”. When an SMS-reply is
   received having this header (all of it or truncated at the
   end), the header will be left out (it will not be in the SIP
   message).

1.2. Dependencies

1.2.1. OpenSIPS Modules

   The following modules must be loaded before this module:
     * tm - Transaction Manager.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * None.

1.3. Exported Parameters

1.3.1. modems (string)

   Define and configure one or more GSM modems.
modems_value     = modem_definition *( ";" modem_definition )
modem_definition = modem_name "[" list_of_params "]"
list_of_params   = modem_param *( ";" modem_param )
modem_param       = name "=" value

   The following parameters can be used:
     * d=device (mandatory) - Device associated with modem
       (/dev/ttyS0, /dev/modem, etc.).
     * p=pin (optional) - SIM PIN - default is NULL.
     * m=mode (optional) - Modem working mode
       (“ASCII”,“OLD”,“DIGICOM”, “NEW”). Default value is “NEW”.
     * c=SMS_Center (optional) - SMS center number for that modem.
       Default is the SMS center set on the SIM card.
     * b=baudrate (optional) - Default is 19600.
     * r=retry (optional) - How many times to try to re-send a SMS
       that reported error. Default is twice.
     * l=looping (optional) - Time for modem to wait before
       performing a new check for incomimg/outgoing SMS/SIP_MSG.
       Default is 20.

   No default value, the parameter is mandatory.

   Example 1.1. Set modems parameter
...
modparam("sms", "modems", "Nokia [d=/dev/ttyS1;b=9600;m=new;l=30] ")
modparam("sms", "modems", "Nokia[d=/dev/ttyS1];Siemens[d=/dev/ttyS2]")
...

1.3.2. networks (string)

   Define and configure used GSM networks.
networks_value = net_definition *( ";" net_definition )
net_definition = net_name "[" list_of_params "]"
list_of_params = set_param *( ";" set_param )
set_param         = name "=" value

   The following parameters can be used:
     * m=msx_sms_per_call (optional) - Maximum number of SMS send
       / received from that net in one modem loop. Default is 10.
       This parameter was introduced to avoid starvation.
       Example of the starvation--a modem can send SMS for more
       than 1 networks. If you have a huge number of SMS for the
       first network and the number of incoming SIP messages is
       equal to the sent SMS per same unit of time, the modem will
       never get to send SMS for the next networks.

   No default value, the parameter is mandatory.

   Example 1.2. Set networks parameter
...
modparam("sms", "networks", "D1 [m=10] ;d2[ m=20]")
...

1.3.3. links (string)

   Define from which network each modem should send SMS.
links_value = modem_assoc *( ";" modem_assoc )
modem_assoc = modem_name "[" list_of_networks "]"
list_of_networks = network *( ";" network )

   No default value, the parameter is mandatory.

   Example 1.3. Set links parameter
...
modparam("sms", "links", "NOKIA[D1;d2]")
...

   The modem NOKIA will send SMS from D1 and D2 net (in this order
   !). if in a net queue are more then max_sms_per_call SMS the
   modem will not sleep before starting the next loop ! Shortly,
   if messages are waiting to be sent, the modem will not go in
   sleep.

1.3.4. default_net (string)

   The default network to use. If no one specified, the first
   defined network is used. This parameter is useful only if the
   “sms_send_msg” exported function is used (see
   exported_functions).

   Example 1.4. Set default_net parameter
...
modparam("sms", "default_net", "D1")
...

1.3.5. max_sms_parts (integer)

   Shows in how many parts (SMS messages) a SIP message can be
   split. If exceeded, the SIP message will be sent truncated and
   the SIP user will get back another message containing the
   unsent part.

   Default value is 4.

   Example 1.5. Set max_sms_parts parameter
...
modparam("sms", "max_sms_parts", 10)
...

1.3.6. domain (string)

   Specify a fake domain name to be used by the gateway. The
   Contact headers and the From header from request will be
   construct based on this fake domain name. It's useful when the
   gateway is transparently hidden behind a proxy/register
   (located on different machines).

   Default is the name of the machine the gateway is running on.

   Example 1.6. Set domain_str parameter
...
modparam("sms", "domain_str", "foo.bar")
...

1.3.7. use_contact (integer)

   If a contact header should be added to the outgoing SIP
   messages. Even if the SIP draft forbids this, some UAS require
   it.

   Default is 0 (no).

   Example 1.7. Set use_contact parameter
...
modparam("sms", "use_contact", 1)
...

1.3.8. sms_report_type (integer)

   If the modem should ask for SMS confirmation from the SMS
   Center. If the SMSC reply with an error code, the gateway will
   send back to SIP user a SIP message containing the text (or
   part of it) that couldn't be send. Two report mechanisms are
   implemented:
     * 1 - the reports are delivered by the GSM device as SMS
       reports (so far supported only by Nokia modems);
     * 2 - the reports are delivered as async. CDS responses
       (supported by almost all modems, except Ericsson).

   Default is 0 (no report).

   Example 1.8. Set sms_report_type parameter
...
modparam("sms", "sms_report_type", 1)
...

1.4. Exported Functions

1.4.1.  sms_send_msg_to_net(network_name)

   Put the SIP msg in the specified network queue. The function
   return error if the number encapsulated into SIP message is
   malformed, if the content_type is incorrect or because of some
   internal failures.

   Meaning of the parameters is as follows:
     * network_name (string) - Name of network.

   This function can be used from REQUEST_ROUTE.

   Example 1.9. sms_send_msg_to_net usage
...
if (sms_send_msg_to_net("D1"))
{
        if (!t_reply(202, "yes sir, SMS sent over"))
        {
                # if replying failed, retry statelessly
                sl_reply_error();
        };
} else {
        if (!t_reply(502, "Bad gateway - SMS error"))
        {
                # if replying failed, retry statelessly
                sl_reply_error();
        };
        exit;
};
...

1.4.2.  sms_send_msg()

   The same as the previous one, but use the default network
   queue.

   This function can be used from REQUEST_ROUTE.

   Example 1.10. sms_send_msg usage
...
if (sms_send_msg_to_net())
{
        if (!t_reply(202, "yes sir, SMS sent over"))
        {
                # if replying failed, retry statelessly
                sl_reply_error();
        };
} else {
        if (!t_reply(502, "Bad gateway - SMS error"))
        {
                # if replying failed, retry statelessly
                sl_reply_error();
        };
        exit;
};
...

Chapter 2. Developer Guide

   Each modem forks its own process for sending /fetching SMS.
   Communication and queuing between OpenSIPS working processes
   and modem processes is done with pipes.

Chapter 3. Contributors

3.1. By Commit Statistics

   Table 3.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Bogdan-Andrei Iancu (@bogdan-iancu) 167 83 5538 2203
   2. Jan Janak (@janakj) 17 9 674 86
   3. Andrei Pelinescu-Onciul 15 12 78 78
   4. Razvan Crainea (@razvancrainea) 13 11 34 29
   5. Daniel-Constantin Mierla (@miconda) 12 10 27 22
   6. Liviu Chircu (@liviuchircu) 11 8 34 56
   7. Henning Westerholt (@henningw) 9 6 12 60
   8. Jiri Kuthan (@jiriatipteldotorg) 7 4 204 7
   9. Anca Vamanu 7 1 146 181
   10. Vlad Patrascu (@rvlad-patrascu) 6 4 33 28

   All remaining contributors: Elena-Ramona Modroiu, Julián Moreno
   Patiño, Konstantin Bokarius, John Riordan, Dan Pascu
   (@danpascu), Jesus Rodrigues, Peter Lemenkov (@lemenkov), Edson
   Gellert Schubert, Walter Doekes (@wdoekes).

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

3.2. By Commit Activity

   Table 3.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Bogdan-Andrei Iancu (@bogdan-iancu) May 2002 - May 2019
   2.  Razvan Crainea (@razvancrainea)     Oct 2011 - May 2019
   3.  Vlad Patrascu (@rvlad-patrascu)     May 2017 - Apr 2019
   4.  Peter Lemenkov (@lemenkov)          Jun 2018 - Jun 2018
   5.  Liviu Chircu (@liviuchircu)         Mar 2014 - Jun 2018
   6.  Julián Moreno Patiño                Feb 2016 - Feb 2016
   7.  Walter Doekes (@wdoekes)            May 2014 - May 2014
   8.  John Riordan                        May 2009 - May 2009
   9.  Henning Westerholt (@henningw)      Aug 2007 - Jun 2008
   10. Daniel-Constantin Mierla (@miconda) Nov 2006 - Mar 2008

   All remaining contributors: Konstantin Bokarius, Edson Gellert
   Schubert, Jesus Rodrigues, Anca Vamanu, Elena-Ramona Modroiu,
   Dan Pascu (@danpascu), Jan Janak (@janakj), Andrei
   Pelinescu-Onciul, Jiri Kuthan (@jiriatipteldotorg).

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 4. Documentation

4.1. Contributors

   Last edited by: Vlad Patrascu (@rvlad-patrascu), Peter Lemenkov
   (@lemenkov), Liviu Chircu (@liviuchircu), Bogdan-Andrei Iancu
   (@bogdan-iancu), Razvan Crainea (@razvancrainea),
   Daniel-Constantin Mierla (@miconda), Konstantin Bokarius, Edson
   Gellert Schubert, Jesus Rodrigues, Henning Westerholt
   (@henningw), Elena-Ramona Modroiu, Jan Janak (@janakj).

   Documentation Copyrights:

   Copyright © 2003 FhG FOKUS
