SMPPApp

SMPP Application Configuration

The SMPP Application is responsible for sending and receiving SMPP short messages as an SME or SMSC.

The SMPP Application does not initiate any user content itself. It exists only as an agent to send/receive requests (e.g. deliver_sm or submit_sm) on behalf of another application.

Typical uses of the SMPP Application are:

See the N2SVCD Configuration Overview for more information on how the SMPP Application interacts with other components.

An example SMPP Application configuration (without connection details; see SMPP Application Connection Modes below ) might be:

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="SMPP-App" module="SMPPApp">
      <include>
        <lib>../apps/smpp/lib</lib>
      </include>
      <parameters>
        <parameter name="trace_level" value="1"/>
        <parameter name="password" value="MYPASS"/>
        <parameter name="ping_interval" value="300"/>
        <!-- connection details -->
        <parameter name="flash_encode_mode" value="smpp_strict"/>
        <parameter name="flash_decode_alphabet_7bit" value="gsm7bit-default"/>
        <parameter name="flash_decode_alphabet_8bit" value="gsm8bit-default"/>
        <parameter name="flash_decode_alphabet_16bit" value="ucs2"/>
      </parameters>
      <config>
        <handlers>
          <handler application="IN Tester"/>
        </handlers>
        <data_coding_mapping>
          <mapping encoding="gsm8-default" value="0" />
          <mapping encoding="ascii" value="1" />
          <mapping encoding="ucs2" value="8" />
        </data_coding_mapping>
      </config>
    </application>
    ...
  </application>
  ...
</n2svcd>

SMPP Application Connection Modes

The SMPP Application may connect to SMSCs as an SME client (connect mode) or may be connected to by SMEs as an SMSC server (listen mode).

Connections to and from the N2SVCD SMPP Application are made via the SMPP bind_* operations. The SMPP outbind operation is not supported.

The following example parameters could be used for an SMPP Application TCP Server instance.

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="SMPP-Server" module="SMPPApp">
      ...
      <parameters>
        ...
        <parameter name="num_client_connections" value="2"/>
        <parameter name="socket_mode" value="listen"/>
        <parameter name="local_host" value="0.0.0.0"/>
        <parameter name="local_port" value="4001"/>
      </parameters>
      ...
    </application>
    ...
  </application>
  ...
</n2svcd>

The following example parameters could be used for an SMPP Application TCP Client instance.

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="SMPP-Server" module="SMPPApp">
      ...
      <parameters>
        ...
        <parameter name="socket_mode" value="connect"/>
        <parameter name="reconnect_interval" value="60"/>
        <parameter name="remote_host" value="localhost"/>
        <parameter name="remote_port" value="4001"/>
      </parameters>
      ...
    </application>
    ...
  </application>
  ...
</n2svcd>

Configuration Details

The application element attributes for an SMPP Application instance may include the below.

For details of the various parameter types used, refer to Common Configuration.

Parameter Name Type XML Type Description
See: Common Application configuration
See: TCP Application configuration
module String Attribute [Required] SMPPApp
include.lib String Element [Required] ../apps/smpp/lib
parameters Array Element [Required] As per Common Configuration Application parameters.
"edr_enabled" - - This value is ignored; the SMPP Application does not support writing EDRs.
"local_port" Positive Integer Attribute As per common TCP configuration for local_port.
(Default = 2775)
"remote_port" Positive Integer Attribute As per common TCP configuration for remote_port.
(Default = 2775)
"bind" String Attribute One of none, transmitter, receiver or transceiver.
For a Client, this is the bind mode that we will use when binding.
For a Server, this is the bind mode that we will accept.
(Server Default = transceiver, Client Default = transmitter)
"system_id" String Attribute The SMPP System Identifer by which this endpoint identifies itself.
"password" String Attribute For a Client, this is the password that we will use when binding.
For a Server, this is the password that we will accept.
"flash_encode_mode" String Attribute The encoding that the SMPP Application should use when encoding flash class short messages The supported values and their meanings are listed under Outbound Flash Message Encoding.
(Default = smpp_loose)
"flash_decode_alphabet_7bit" String Attribute The encoding alphabet that the SMPP Application should use when receiving flash class short messages that have been encoded with a 7-bit alphabet. The supported values and their meanings are listed under Available Alphabets.
(Default = gsm7bit-default)
"flash_decode_alphabet_8bit" String Attribute The encoding alphabet that the SMPP Application should use when receiving flash class short messages that have been encoded with an 8-bit alphabet. The supported values and their meanings are listed under Available Alphabets.
(Default = gsm8bit-default)
"flash_decode_alphabet_16bit" String Attribute The encoding alphabet that the SMPP Application should use when receiving flash class short messages that have been encoded with a 16-bit alphabet. The supported values and their meanings are listed under Available Alphabets.
(Default = ucs2)
config Object Element Container for extended configuration for this Application instance.
.handlers Array Element Array of SMPP handler elements for selecting the owning Application for inbound SMPP operations.
.data_coding_mapping Array Element Array of data coding mapping elements, specifying the encoding language to data coding value rules for encoding and decoding short messages.

SMPP Handlers

Handler rules define which application is used to process inbound submit_sm and deliver_sm operations. Each handler Object in the config.handlers Array is configured as follows.

Parameter Name Type XML Type Description
pdu String Attribute [Required] The inbound operation type: submit_sm or deliver_sm.
destination Hex String Attribute A full address, matched against the destination address of the inbound operation.
Only one of destination or destination_prefix may be specified.
destination_prefix Hex String Attribute An address prefix, matched against the destination address of the inbound operation.
Only one of destination or destination_prefix may be specified.
source Hex String Attribute A full address, matched against the source address of the inbound operation.
Only one of source or source_prefix may be specified.
source_prefix Hex String Attribute An address prefix, matched against the source address of the inbound operation.
Only one of source or source_prefix may be specified.
application String Attribute [Required] The name of the application which should process matching messages.
This will normally refer to a LogicApp or TesterApp instance.

The handlers will be checked in order, and the first matching handler will be used.

SMPP Data Coding

Available Alphabets

When defining Data Coding Alphabet Mapping or Inbound Flash Message Decoding, several alphabets are available for use:

Configuration Name Character Width (Bits) Description
gsm7bit-default 7 GSM 7-bit Default Alphabet
gsm8bit-default 8 GSM 8-bit Default Alphabet
iso-8859-1 8 ISO/IEC 8859-1 Latin 1
iso-8859-5 8 ISO/IEC 8859-5 Latin/Cyrillic
iso-8859-8 8 ISO/IEC 8859-8 Latin/Hebrew
iso-8859-15 8 ISO/IEC 8859-15 Latin 9
windows-1252 8 Windows CP 1252
ascii 8 IA5 (CCITT T.50)/ASCII (ANSI X3.4)
ucs2 16 UCS-2
utf8 16 UTF-8

Data Coding Alphabet Mapping

When sending or receiving SMPP messages, the N2SVCD SMPP Application must have a mapping provided in order to correctly tie on-the-wire data coding values with the encoding alphabet used by either side of the message. This is specified in the data_coding_mapping configuration block with each mapping taking the following parameters:

Parameter Type Description
encoding String The data coding mapping to use. Must be an available alphabet.
value Integer The data coding value to send when encoding outbound short messages with this alphabet. Also the key for inbound short messages that must be decoded; the first match in the data_coding_mapping array being used.

If no data coding alphabet mapping configuration is provided, the following will be used by default:

        <data_coding_mapping>
          <mapping encoding="gsm8-default" value="0" />
          <mapping encoding="ascii" value="1" />
          <mapping encoding="iso-8859-1" value="3" />
          <mapping encoding="ucs2" value="8" />
        </data_coding_mapping>

Note that if any data coding alphabet mapping is provided, the default mappings will not apply. Data coding alphabet mappings must be provided in full.

Flash Messaging

Note that the reference information given here is minimal; for further details please refer to the Short Message Peer to Peer Protocol Specification v3.4 / v5.0 and/or GSM TS 03.38 / ETSI TS 123 038 (3GPP TS 23.038).

When SMPP short messages are created by N2SVCD or external entities, it is possible to specify that the message is a “flash” message (AKA GSM “message class 0”). Such messages are displayed on the user’s handset, but are not saved.

Different flash message modes options are provided by the SMPP Application because a strict interpretation of the SMPP standard supports only 7-bit and 8-bit text via GSM message class control using a data_coding value of 1111xxxx. The remaining bits are then filled according to GSM 23.038 in the format 0zaa, where:

However, as this format does not allow for 16-bit encoding, there is an alternate encoding method from the same GSM standard that is sometimes used, despite being explicitly outside the SMPP defined values. This alternate encoding has a data coding value of 00xyzzaa, where:

Finally, the SMPP standard alternately suggests using the TLV dest_addr_subunit to carry the message class, with the values:

Outbound Flash Message Encoding

For the reasons given under Flash Messaging, the SMPP Application offers the following modes for flash message data coding when creating outbound short messages:

Mode Description
smpp_loose (Default) Use the standard SMPP 11110x00 format for 7-bit and 8-bit encodings, and use the GSM 0001xx00 format for 16-bit encodings.
smpp_strict Use only the standard SMPP 11110x00 format for 7-bit and 8-bit encodings, with no support for 16-bit encodings.
gsm Use only the GSM 0001xx00 format for 7-bit, 8-bit, and 16-bit encodings.
subunit Use the SMPP standard 0000xxxx data coding and set the dest_addr_subunit TLV to 1.

Note that none of these options have any impact for the data coding value generated for non-flash short messages, which is always set according to the standard SMPP data coding format of 0000xxxx based on the data coding mapping used.

Outbound short messages are created using the SMPP-C-REQUEST message type. Refer to the specific message type documentation for full details of this message type, including how to specify the message class and non-encoded text in input to the SMPP Application.

Inbound Flash Message Decoding

When SMS are received for processing by the SMPP Application, the data coding value is analyzed to determine the appropriate alphabet to use for the message text decode.

For normal messages, the configured mapping mechanism described under Data Coding Alphabet Mapping is used.

For flash messages, the SMPP Application will determine which of the flash message modes (as described under Flash Messaging) the external entity has used to signal the message class. This includes the encoding alphabet character width that was used. The SMPP Application will then decode the received message text according to the configured flash decoding alphabet parameters:

Parameter Type Description
flash_decode_alphabet_7bit Integer Specifies the alphabet to use when decoding 7-bit flash message text.
(Default: gsm7bit-default)
flash_decode_alphabet_8bit Integer Specifies the alphabet to use when decoding 8-bit flash message text.
(Default: gsm8bit-default)
flash_decode_alphabet_16bit Integer Specifies the alphabet to use when decoding 16-bit flash message text.
(Default: ucs2)

For all flash decoding alphabet parameters, the possible values are as specified under Available Alphabets.

Inbound short messages are sent to handling applications using the SMPP-S-REQUEST message type. Refer to the specific message type documentation for full details of this message type, including how the message class and text are specified in input to the handling application.

Message Handling

In addition to the common Application management messages, the SMPPApp uses the following messages: