<!-- Module User's Guide -->

<chapter>
	<title>&adminguide;</title>

	<section id="overview" xreflabel="Overview">
		<title>Overview</title>
		<para>
			This module offers interoperability between SIP and SMPP
			(Short Message Peer-to-Peer) protocols. It provides the
			means to build a messaging gateway/bridge between the two
			protocols, being able to convert messages from both directions.
		</para>

		<para>
		<itemizedlist>
			<listitem><para>
			SIP to SMPP - messages coming from SIP can be converted to a
			SMPP PDU (Protocol Data Unit) message and sent further to a
			SMSC (Short Message Service Center).
			</para></listitem>
			<listitem><para>
			SMPP to SIP - the module can act as an ESME (External Short
			Messaging Entity), receiving messages from a SMSC and converting
			them to a SIP Message that is sent further to a SIP proxy.
			</para></listitem>
		</itemizedlist>
		</para>
		<para>
			The module is compatible with the
			<ulink url="http://opensmpp.org/specs/SMPP_v3_4_Issue1_2.pdf">
				SMPP v3.4</ulink> specifications.
		</para>
	</section>

	<section>
		<title>SIP to SMPP bridging</title>
		<para>
			In order to convert a SIP message to a SMPP all you need to do
			is to call the <xref linkend="func_send_smpp_message"/> function,
			indicating the SMSc you want to send the message to. The module
			will build the PDU according to the parameters provisioned
			in the database.
		</para>
	</section>

	<section>
		<title>SMPP to SIP bridging</title>
		<para>
			When bridging a message received over the SMPP interface,
			OpenSIPS builds a SIP Message and sends it to the outbound
			proxy identified by the <xref linkend="param_smpp_outbound_uri"/>
			module's parameter.
		</para>
	</section>

	<section>
		<title>SMSC binding</title>
		<para>
			In order to be able to deliver messages to SMSc, an ESME needs to
			first bind to the SMSc. This is done at &osips; startup by sending
			a SMPP <emphasis>bind_transciever</emphasis> command to connect
			to the SMSc, or an <emphasis>outbind</emphasis> command to inform
			an SMSc it can now bind to our gateway.
		</para>
		<para>
			The description of all SMSc servers is provisioned in the database.
			For each server, one can cofigure the following information:
			<itemizedlist>
			<listitem><para><emphasis>Name</emphasis> - an unique name given to
			the SMSc that is used to reference this SMSc in the &osips; script.
			</para></listitem>
			<listitem><para><emphasis>IP</emphasis> - The IP the SMSc is listening
			on for new bindings/connections.
			</para></listitem>
			<listitem><para><emphasis>Port</emphasis> - The TCP port that the SMSc
			is listening on for new bindings/connections.
			</para></listitem>
			<listitem><para><emphasis>System ID</emphasis> - Also known as the
			User name that is used to authenticate to the SMSc.
			</para></listitem>
			<listitem><para><emphasis>Password</emphasis> - A password used to
			authenticate to the SMSc.
			</para></listitem>
			<listitem><para><emphasis>System Type</emphasis> - Usually
			<quote>SMPP</quote>, this field is required by some SMPP providers.
			</para></listitem>
			<listitem><para><emphasis>Source Type of Number (TON)</emphasis> - Specifies
			the format of the number used to send messages from. Some comon values are:
			<itemizedlist>
				<listitem><para><emphasis>0</emphasis> - Unknown</para></listitem>
				<listitem><para><emphasis>1</emphasis> - International</para></listitem>
				<listitem><para><emphasis>2</emphasis> - National</para></listitem>
				<listitem><para><emphasis>3</emphasis> - Network Specific</para></listitem>
				<listitem><para><emphasis>4</emphasis> - Subscriber Number</para></listitem>
				<listitem><para><emphasis>5</emphasis> - Alphanumeric</para></listitem>
				<listitem><para><emphasis>6</emphasis> - Abbreviated</para></listitem>
			</itemizedlist>
			Default value is <emphasis>0 - Unknown</emphasis>.
			</para></listitem>
			<listitem><para><emphasis>Source Number Plan Indicator (NPI)</emphasis> - Specifies
			the numbering scheme of the number used to send messages from. Some comon values are:
			<itemizedlist>
				<listitem><para><emphasis>0</emphasis> - Unknown</para></listitem>
				<listitem><para><emphasis>1</emphasis> - ISDN/telephone numbering plan (E163/E164)</para></listitem>
				<listitem><para><emphasis>3</emphasis> - Data numbering plan (X.121)</para></listitem>
				<listitem><para><emphasis>4</emphasis> - Telex numbering plan (F.69)</para></listitem>
				<listitem><para><emphasis>6</emphasis> - Land Mobile (E.212)</para></listitem>
				<listitem><para><emphasis>8</emphasis> - National numbering plan</para></listitem>
				<listitem><para><emphasis>9</emphasis> - Private numbering plan</para></listitem>
				<listitem><para><emphasis>10</emphasis> - ERMES numbering plan (ETSI DE/PS 3 01-3) </para></listitem>
				<listitem><para><emphasis>13</emphasis> - Internet (IP)</para></listitem>
				<listitem><para><emphasis>18</emphasis> - WAP Client Id (to be defined by WAP Forum)</para></listitem>
			</itemizedlist>
			Default value is <emphasis>0 - Unknown</emphasis>.
			</para></listitem>
			<listitem><para><emphasis>Destination Type of Number (TON)</emphasis> - Specifies
			the format of the number used to send messages to. Can have the same values as
			<emphasis>Source Type of Number (TON)</emphasis> and default value is <emphasis>0 -
			Unknown</emphasis>.
			</para></listitem>
			<listitem><para><emphasis>Destination Number Plan Indicator (NPI)</emphasis> -
			Specifies the numbering scheme of the number used to send messages to. Can have
			the same values as <emphasis>Source Number Plan Indicator (NPI)</emphasis>
			and default value is <emphasis>0 - Unknown</emphasis>.
			</para></listitem>
			<listitem><para><emphasis>Session Type</emphasis> - Specifies what type of session
			should be used to connecto th the SMSc. Possible values are:
			<itemizedlist>
				<listitem><para><emphasis>1</emphasis> - Transciever</para></listitem>
				<listitem><para><emphasis>2</emphasis> - Transmitter</para></listitem>
				<listitem><para><emphasis>3</emphasis> - Receiver</para></listitem>
				<listitem><para><emphasis>4</emphasis> - Outbind</para></listitem>
			</itemizedlist>
			Default value is <emphasis>1 - Transciever</emphasis>.
			</para></listitem>
			</itemizedlist>
		</para>
		<para>
			When &osips; starts up, it reads all SMSc specifications from the
			database and triggers a binding with them. <emphasis>Note: </emphasis>
			reloading the SMSc database is not yet supported, but it is a work in
			progress.
		</para>
		<para>
			Each SMPP connection is periodically pinged (currently every 5 seconds)
			using <emphasis>enquire_link</emphasis> SMPP commands to keep the
			connection active.
		</para>
	</section>

	<section id="dependencies" xreflabel="Dependencies">
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>database</emphasis> -- Any database module
			</para>
			</listitem>
                    </itemizedlist>
		</para>
	</section>
	<section>
		<title>Dependencies of external libraries</title>
		<para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
		<title>&osips; Exported parameters</title>
		<para>
		All these parameters can be used from the opensips.cfg file,
		to configure the behavior of &osips;-SMPP gateway.
		</para>

	<section id="param_db_url" xreflabel="db_url">
		<title><varname>db_url</varname> (string)</title>
		<para>
			The database handler where the SMPP connection will be
			stored. This parameter is mandatory.
		</para>
		<para>
		<emphasis>
			Default value is <emphasis>unset</emphasis>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "db_url", "&exampledb;")
...
</programlisting>
		</example>
	</section>

	<section id="param_smpp_port" xreflabel="smpp_port">
		<title><varname>smpp_port</varname> (integer)</title>
		<para>
			Used to change the default value of the SMPP port used to
			listen for new connections.
		</para>
		<para><emphasis>
			Default value is 2775.
		</emphasis></para>
		<example>
		<title>Set <varname>smpp_port</varname> variable</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "smpp_port", 27775)
...
		</programlisting>
		</example>
	</section>

	<section id="param_smpp_max_msg_chunks" xreflabel="smpp_max_msg_chunks">
		<title><varname>smpp_max_msg_chunks</varname> (integer)</title>
		<para>
			The maximum number of chunks in which a SMPP message is expected to
			arrive via TCP. If a received packet is more fragmented than this,
			the connection is dropped (either the connection is very
			overloaded and this leads to high fragmentation - or we are the
			victim of an ongoing attack where the attacker is sending very
			fragmented traffic in order to decrease server performance).
		</para>
		<para>
		<emphasis>
			Default value is 8.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>smpp_max_msg_chunks</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "smpp_max_msg_chunks", 32)
...
</programlisting>
		</example>
	</section>

	<section id="param_smpp_send_timeout" xreflabel="smpp_send_timeout">
		<title><varname>smpp_send_timeout</varname> (integer)</title>
		<para>
		Time in milliseconds after a TCP connection will be closed if it is
		not available for blocking writing in this interval (and &osips; wants
		to send something on it).
		</para>
		<para>
		<emphasis>
			Default value is 100 ms.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>smpp_send_timeout</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "smpp_send_timeout", 200)
...
</programlisting>
		</example>
	</section>

	<section id="param_smpp_outbound_uri" xreflabel="outbound_uri">
		<title><varname>outbound_uri</varname> (string)</title>
		<para>
		This parameter represents the URI of the outbound proxy used to send
		a message converted from SMPP to SIP.
		</para>
		<para>
		<emphasis>
			Default value is <emphasis>None</emphasis>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>outbound_uri</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "outbound_uri", "sip:127.0.0.1:5060")
...
</programlisting>
		</example>
	</section>

	<section id="param_smpp_table" xreflabel="smpp_table">
		<title><varname>smpp_table</varname> (string)</title>
		<para>
			The name of the database table containing definitions
			of the SMSc servers used to connect to.
		</para>
		<para>
		<emphasis>
			Default value is <quote>smpp</quote>.
		</emphasis>
		</para>

		<example>
		<title>Set <varname>smpp_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "smpp_table", "smsc")
...

</programlisting>
		</example>
	</section>

	<section id="param_smpp_name_col" xreflabel="smpp_name_col">
		<title><varname>name_col</varname> (string)</title>
		<para>
			The name of the column that holds the SMSc identifier used by
			the <emphasis>send_smpp_message()</emphasis> function.
		</para>
		<para>
		<emphasis>
			Default value is <quote>name</quote>.
		</emphasis>
		</para>

		<example>
		<title>Set <varname>name_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "name_col", "smsc_name")
...

</programlisting>
		</example>
	</section>

	<section id="param_smpp_ip_col" xreflabel="smpp_ip_col">
		<title><varname>ip_col</varname> (string)</title>
		<para>
			The name of the column that holds the IP of the SMSc.
		</para>
		<para>
		<emphasis>
			Default value is <quote>ip</quote>.
		</emphasis>
		</para>

		<example>
		<title>Set <varname>ip_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "ip_col", "smsc_ip")
...

</programlisting>
		</example>
	</section>

	<section id="param_smpp_port_col" xreflabel="smpp_port_col">
		<title><varname>port_col</varname> (string)</title>
		<para>
			The name of the column that holds the SMSc port.
		</para>
		<para>
		<emphasis>
			Default value is <quote>port</quote>.
		</emphasis>
		</para>

		<example>
		<title>Set <varname>port_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "port_col", "smsc_port")
...

</programlisting>
		</example>
	</section>

	<section id="param_smpp_system_id_col" xreflabel="smpp_system_id_col">
		<title><varname>system_id_col</varname> (string)</title>
		<para>
			The name of the column that holds the SMSc System ID.
		</para>
		<para>
		<emphasis>
			Default value is <quote>system_id</quote>.
		</emphasis>
		</para>

		<example>
		<title>Set <varname>system_id_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "system_id_col", "smsc_system_id")
...

</programlisting>
		</example>
	</section>

	<section id="param_smpp_password_col" xreflabel="smpp_password_col">
		<title><varname>password_col</varname> (string)</title>
		<para>
			The name of the password column used to authenticate the SMSc.
		</para>
		<para>
		<emphasis>
			Default value is <quote>password</quote>.
		</emphasis>
		</para>

		<example>
		<title>Set <varname>password_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "password_col", "smsc_password")
...

</programlisting>
		</example>
	</section>

	<section id="param_smpp_system_type_col" xreflabel="smpp_system_type_col">
		<title><varname>system_type_col</varname> (string)</title>
		<para>
			The name of the System Type column used to bind the SMSc.
		</para>
		<para>
		<emphasis>
			Default value is <quote>system_type</quote>.
		</emphasis>
		</para>

		<example>
		<title>Set <varname>system_type_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "system_type_col", "smsc_system_type")
...

</programlisting>
		</example>
	</section>

	<section id="param_smpp_src_ton_col" xreflabel="smpp_src_ton_col">
		<title><varname>src_ton_col</varname> (string)</title>
		<para>
			The name of the column that holds the Source TON values.
		</para>
		<para>
		<emphasis>
			Default value is <quote>src_ton</quote>.
		</emphasis>
		</para>

		<example>
		<title>Set <varname>src_ton_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "src_ton_col", "smsc_src_ton")
...

</programlisting>
		</example>
	</section>

	<section id="param_smpp_src_npi_col" xreflabel="smpp_src_npi_col">
		<title><varname>src_npi_col</varname> (string)</title>
		<para>
			The name of the column that holds the Source NPI values.
		</para>
		<para>
		<emphasis>
			Default value is <quote>src_npi</quote>.
		</emphasis>
		</para>

		<example>
		<title>Set <varname>src_npi_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "src_npi_col", "smsc_src_npi")
...

</programlisting>
		</example>
	</section>

	<section id="param_smpp_dst_ton_col" xreflabel="smpp_dst_ton_col">
		<title><varname>dst_ton_col</varname> (string)</title>
		<para>
			The name of the column that holds the Destination TON values.
		</para>
		<para>
		<emphasis>
			Default value is <quote>dst_ton</quote>.
		</emphasis>
		</para>

		<example>
		<title>Set <varname>dst_ton_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "dst_ton_col", "smsc_dst_ton")
...

</programlisting>
		</example>
	</section>

	<section id="param_smpp_dst_npi_col" xreflabel="smpp_dst_npi_col">
		<title><varname>dst_npi_col</varname> (string)</title>
		<para>
			The name of the column that holds the Destination NPI values.
		</para>
		<para>
		<emphasis>
			Default value is <quote>dst_npi</quote>.
		</emphasis>
		</para>

		<example>
		<title>Set <varname>dst_npi_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "dst_npi_col", "smsc_dst_npi")
...

</programlisting>
		</example>
	</section>

	<section id="param_smpp_session_type_col" xreflabel="smpp_session_type_col">
		<title><varname>session_type_col</varname> (string)</title>
		<para>
			The name of the column that holds the Session Type of the SMSc.
		</para>
		<para>
		<emphasis>
			Default value is <quote>session_type</quote>.
		</emphasis>
		</para>

		<example>
		<title>Set <varname>session_type_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("proto_smpp", "session_type_col", "smsc_session_type")
...

</programlisting>
		</example>
	</section>

	</section>

	<section id="exported_functions" xreflabel="exported_functions">
	<title>Exported Functions</title>

	<section id="func_send_smpp_message" xreflabel="send_smpp_message()">
		<title>
		<function moreinfo="none">send_smpp_message(smsc_name, [from],[to],[body],[utf-16],[delivery_receipt])</function>
		</title>
		<para>
			This function is used to convert a SIP message received in the
			&osips; script to a SMPP PDU and send it to the
			<emphasis>smsc_name (string)</emphasis> received as parameter.
			The SMPP parameters used to construct the PDU are provisione
			in the database, and the command sent is either
			<emphasis>submit_sm</emphasis> or <emphasis>deliver_sm</emphasis>,
			depending on the type of the SMSc.
		</para>
		<para>
			The function returns <emphasis>-2</emphasis> if the SMSc
			the message should be sent does not exist in the database,
			<emphasis>-1</emphasis> if there was an internal error,
			or positive value in case of success.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
			<listitem>
				<para><emphasis>sms_name (string)</emphasis> - name of the SMS
					to be used for sending the SMPP traffic.
				</para>
			</listitem>
			<listitem>
			<para><emphasis>from (string, optional)</emphasis> - the source number.
				If missing, the SIP message from username is used.
			</para>
			</listitem>
			<listitem>
			<para><emphasis>to (string, optional)</emphasis> - the destination number.
				If missing, the SIP request URI username is used.
			</para>
			</listitem>
			<listitem>
			<para><emphasis>body (string, optional)</emphasis> - the body of the SMS.
				If missing, the SIP message body is used.
			</para>
			</listitem>
			<listitem>
			<para><emphasis>UTF-16 (int, optional)</emphasis> - set to
				<emphasis>1</emphasis> if the body of the message is in UTF-16.
				format. If missing or <emphasis>0</emphasis>, UTF-8 is used.
			</para>
			</listitem>
			<listitem>
			<para><emphasis>delivery_receipt (int, optional)</emphasis> - Whether
				the SMSC should confirm delivery for this SMS or not
			</para>
			</listitem>
		</itemizedlist>

		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE
			or BRANCH_ROUTE.
		</para>
		<example>
		<title><function>send_smpp_message()</function> usage</title>
		<programlisting format="linespecific">
...
    if (is_method("MESSAGE"))
			send_smpp_message("MY_SMSC");
...
</programlisting>
		</example>
	</section>
	</section>

</chapter>
