<?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="sms.parameters" xmlns:xi="http://www.w3.org/2001/XInclude">
    <sectioninfo>
    </sectioninfo>

    <title>Parameters</title>

    <section id="modems">
	<title><varname>modems</varname> (string)</title>
	<para>
	    Define and configure one or more <acronym>GSM</acronym> modems.
	</para>
	<programlisting>
modems_value     = modem_definition *( ";" modem_definition )
modem_definition = modem_name "[" list_of_params "]"
list_of_params   = modem_param *( ";" modem_param )
modem_param      = name "=" value
	</programlisting>
	<para>
	    The following parameters can be used:
	</para>
	<itemizedlist>
	    <listitem>
		<para>
		    d=device (mandatory) - Device associated with modem (/dev/ttyS0, /dev/modem,
		    etc.).
		</para>
	    </listitem>
	    <listitem>
		<para>
		    p=pin (optional) - <acronym>SIM</acronym> <acronym>PIN</acronym> - default
		    is NULL.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    m=mode (optional) - Modem working mode
		    ("ASCII","OLD","DIGICOM","NEW"). Default value is "NEW".
		</para>
	    </listitem>
	    <listitem>
		<para>
		    c=SMS_Center (optional) - <acronym>SMS</acronym> center
		    number for that modem. Default is the
		    <acronym>SMS</acronym> center set on the
		    <acronym>SIM</acronym> card.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    b=baudrate (optional) - Default is 19600.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    r=retry (optional) - How many times to try to re-send a
		    <acronym>SMS</acronym> that reported error. Default is twice.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    l=looping (optional) - Time for modem to wait before performing a new check
		    for incomimg/outgoing <acronym>SMS</acronym>/SIP_MSG. Default is 20.
		</para>
	    </listitem>
	    <listitem>
		<para>
		   t=to (optional) - uri for sip header TO.  Default is NULL.
		</para>
	    </listitem>
	    <listitem>
		<para>
		    s=scan (optional) - Values: 
		        	0: NOT SCAN uri from body sms, use URI in t=to.
			1: SCAN uri from body sms (normal mode,
			default mode, clasic mode)
			2: SCAN MIX (both modes), First SCAN 
			Default is 1 (SCAN).
		</para>
	    </listitem>
	</itemizedlist>
	<note>
	    <para>
		No default value, the parameter is mandatory.		
	    </para>
	</note>
	<example>
	    <title>Set <varname>modems</varname> parameter</title>
	    <programlisting>
...
modparam("sms", "modems", "Nokia[d=/dev/ttyS1;s=0;t=sip:p-cscf@cidra.com.ar]") 
modparam("sms", "modems", "Nokia [d=/dev/ttyS1;b=9600;m=new;l=30] ")
modparam("sms", "modems", "Nokia[d=/dev/ttyS1];Siemens[d=/dev/ttyS2]")
...
	    </programlisting>
	</example>
    </section>
    
    <section id="networks">
	<title><varname>networks</varname> (string)</title>
	<para>
	    Define and configure used <acronym>GSM</acronym> networks.
	</para>
	<programlisting>
networks_value = net_definition *( ";" net_definition )
net_definition = net_name "[" list_of_params "]"
list_of_params = set_param *( ";" set_param )
set_param      = name "=" value
	</programlisting>
	<para>
	    The following parameters can be used:
	</para>
	<itemizedlist>
	    <listitem>
		<para>
		    m=msx_sms_per_call (optional) - Maximum number of
		    <acronym>SMS</acronym> send / received from that net in one
		    modem loop. Default is 10. This parameter was introduced to
		    avoid starvation.
		</para>
		<para>
		    Example of the starvation--a modem can send
		    <acronym>SMS</acronym> for more than 1 networks. If you
		    have a huge number of <acronym>SMS</acronym> for the first
		    network and the number of incoming SIP messages is equal
		    to the sent <acronym>SMS</acronym> per same unit of time,
		    the modem will never get to send <acronym>SMS</acronym> for
		    the next networks.
		</para>
	    </listitem>
	</itemizedlist>
	<note>
	    <para>
		No default value, the parameter is mandatory.		
	    </para>
	</note>
	<example>
	    <title>Set <varname>networks</varname> parameter</title>
	    <programlisting>
...
modparam("sms", "networks", "D1 [m=10] ;d2[ m=20]")
...
	    </programlisting>
	</example>
    </section>
    
    <section id="links">
	<title><varname>links</varname> (string)</title>
	<para>
	    Define from which network each modem should send
	    <acronym>SMS</acronym>.
	</para>
	<programlisting>
links_value = modem_assoc *( ";" modem_assoc )
modem_assoc = modem_name "[" list_of_networks "]"
list_of_networks = network *( ";" network )
	</programlisting>
	<note>
	    <para>
		No default value, the parameter is mandatory.		
	    </para>
	</note>
	<example>
	    <title>Set <varname>links</varname> parameter</title>
	    <programlisting>
...
modparam("sms", "links", "NOKIA[D1;d2]")
...
	    </programlisting>
	</example>
	<para>
	    The modem NOKIA will send <acronym>SMS</acronym> from D1 and D2 net
	    (in this order !). if in a net queue are more then max_sms_per_call
	    <acronym>SMS</acronym> the modem will <emphasis>not
	    sleep</emphasis> before starting the next loop ! Shortly, if
	    messages are waiting to be sent, the modem will not go in sleep.
	</para>
    </section>
    
    <section id="default_net">
	<title><varname>default_net</varname> (string)</title>
	<para>
	    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 <xref
	    linkend="sms.functions"/>).
	</para>
	<example>
	    <title>Set <varname>default_net</varname> parameter</title>
	    <programlisting>
...
modparam("sms", "default_net", "D1")
...
	    </programlisting>
	</example>
    </section>
    
    <section id="max_sms_parts">
	<title><varname>max_sms_parts</varname> (integer)</title>
	<para>
	    Shows in how many parts (<acronym>SMS</acronym> 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.
	</para>
	<para>
	    Default value is 4.
	</para>
	<example>
	    <title>Set <varname>max_sms_parts</varname> parameter</title>
	    <programlisting>
...
modparam("sms", "max_sms_parts", 10)
...
	    </programlisting>
	</example>
    </section>

    <section id="domain_str">
	<title><varname>domain_str</varname> (string)</title>
	<para>
	    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).
	</para>
	<para>
	    Default is the name of the machine the gateway is running on.
	</para>
	<example>
	    <title>Set <varname>domain_str</varname> parameter</title>
	    <programlisting>
...
modparam("sms", "domain_str", "foo.bar")
...
	    </programlisting>
	</example>
    </section>

    <section id="sms.use_contact">
	<title><varname>use_contact</varname> (integer)</title>
	<para>
	    If a contact header should be added to the outgoing SIP messages. Even if the
	    SIP draft forbids this, some UAS require it. 
	</para>
	<para>
	    Default is 0 (no).
	</para>
	<example>
	    <title>Set <varname>use_contact</varname> parameter</title>
	    <programlisting>
...
modparam("sms", "use_contact", 1)
...
	    </programlisting>
	</example>
    </section>
    
    <section id="sms_report_type">
	<title><varname>sms_report_type</varname> (integer)</title>
	<para>
	    If the modem should ask for <acronym>SMS</acronym> confirmation
	    from the <acronym>SMS</acronym> Center. If the
	    <acronym>SMSC</acronym> 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:
	</para>
	<itemizedlist>
	    <listitem>
		<para>
		    1 - the reports are delivered by the <acronym>GSM</acronym> device as
		    <acronym>SMS</acronym> reports (so far supported only by Nokia modems);
		</para>
	    </listitem>
	    <listitem>
		<para>
		    2 - the reports are delivered as async. <acronym>CDS</acronym> responses
		    (supported by almost all modems, except Ericsson).
		</para>
	    </listitem>
	</itemizedlist>
	<para>
	    Default is 0 (no report).
	</para>
	<example>
	    <title>Set <varname>sms_report_type</varname> parameter</title>
	    <programlisting>
...
modparam("sms", "sms_report_type", 1)
...
	    </programlisting>
	</example>
    </section>
</section>
