Provided by: libnet-smpp-perl_1.19-3_all bug

NAME

       Net::SMPP - pure Perl implementation of SMPP 3.4 over TCP

SYNOPSIS

         use Net::SMPP;
         $smpp = Net::SMPP->new_transceiver($host, port=>$port,
                               system_id => 'yourusername',
                               password  => 'secret',
                               ) or die;

DESCRIPTION

       Implements Short Message Peer to Peer protocol, which is frequently used to pass short
       messages between mobile operators implementing short message service (SMS). This is
       applicable to both european GSM and american CDMA/TDMA systems.

       This documentation is not intended to be complete reference to SMPP protocol - use the
       SMPP specification documents (see references section) to obtain exact operation and
       parameter names and their meaning. You may also need to obtain site specific documentation
       about the remote end and any protocol extensions that it supports or demands before you
       start a project. This document follows the convention of spelling parameter names exactly
       as they appear in the SMPP v3.4 documentation. SMPP v4.0 support also follows the
       respective documentation, except where v4.0 usage is in conflict with v3.4 usage, in which
       case the latter prevails (in practise I believe no such conflicts remain in the madule at
       present). For a complete list of error code and optional parameter enumerations, the
       reader is encouraged to consult the source code or SMPP speciofications.

       Despite its name, SMPP protocol defines a client (ESME) and a server (often called SMSC in
       the mobile operator world). Client usually initiates the TCP connection and does bind to
       log in. After binding, a series of request response pairs, called PDUs (protocol data
       units) is exchanged. Request can be initiated by either end (hence "peer-to-peer"?) and
       the other end reponds. Requests are numbered with a sequence number and each response has
       corresponding sequence number. This allows several requests to be pending at the same
       time. Conceptually this is similar to IMAP or LDAP message IDs.  Usually the $smpp object
       maintains the sequence numbers by itself and the programmer need not concern himself with
       their exact values, but should a need to override them arise, the seq argument can be
       supplied to any request or response method.

       Normally this module operates in synchronous mode, meaning that a method that sends a
       request will also block until it gets the corresponding response. Internal command used
       for waiting for response is

           $resp_pdu = $smpp->wait_pdu($cmd_id, $seq);

       If, while waiting for a particular response, other PDUs are received they are either
       handled by handlers (set up by constructor) or discarded. Both command code and sequence
       number must match. Typically a handler for enquire command is set up while all other
       commands are silently dropped. This practise may not be very suitable for transceiver mode
       of operation and certainly is not suitable for implementing a SMSC.

       Synchronous operation makes it impossible to interleave SMPP operations, thus it should be
       regarded as a simplified programming model for simple tasks. Anyone requiring more
       advanced control has to use the asynchronous mode and take up the burden of understanding
       and implementing more of the message flow logic in his own application.

       In synchronous mode request PDU methods return a Net::SMPP::PDU object representing the
       response, if all went well protocolwise, or undef if there was a protocol level error. If
       undef was returned, the reason for the failure can be extracted from ${*$smpp}{smpperror}
       and ${*$smpp}{smpperrorcode} (actual codes are undocumented at the moment, but are
       guaranteed not to change) variables and the global variable $!. These variables are
       meaningless if anything else than undef was returned. The response itself may be an error
       response if there was an application level error in the remote end. In this case the
       application level error can be determined from $pdu->{status} field. Some responses also
       have optional parameters that further clarify the failure, see documentation for each
       operation.

       If a protocol level error happens, probably the only safe action is to destroy the
       connection object (e.g. undef $smpp). If an application level error happens, then
       depending on how the remote end has been implemented it may be possible to continue
       operation.

       Module can also be used asynchronously by specifying async=>1 to the constructor. In this
       mode command methods return immediately with the sequence number of the PDU and user
       should poll for any responses using

           $pdu = $smpp->wait_pdu($cmd_id, $seq);

       Typically wait_pdu() is used to wait for a response, but if wait_pdu() is used to wait for
       a command, the caller should generate appropriate response.

       If caller wants to receive next available PDU, he can call

           $pdu = $smpp->read_pdu();

       which will block until a PDU is received from the stream. The caller would then have to
       check if the PDU is a response or a request and take appropriate action. The smsc.pl
       example program supplied with this distribution demonstrates a possible framework for
       handling both requests and responses.

       If the caller does not want to block on wait_pdu() or read_pdu(), he must use select() to
       determine if the socket is readable (*** what if SSL layer gets inserted?). Even if the
       socket selects for reading, there may not be enough data to complete the PDU, so the call
       may still block. Currently there is no reliable mechanism for avoiding this. If this
       bothers you, you may consider allocating a separate process for each connection so that
       blocking does not matter, or you may set up some sort of timeout (see perlipc(1) man page)
       or you may rewrite this module and contribute patches.

       Response methods always return the sequence number, irrespective of synchronous or
       asynchronous mode, or undef if an error happened.

CONSTRUCTORS

       new()
           Do not call. Has special internal meaning during accepting connections from listening
           socket.

       new_connect()
           Create a new SMPP client object and open conncetion to SMSC host

               $smpp = Net::SMPP->new_connect($host,
                  system_id => 'username',   # usually needed (default '')
                  password => 'secret',      # usually needed (default '')
                  system_type => '',         # default ok, often not needed
                  interface_version => 0x34, # default ok, almost never needed
                  addr_ton => 0x00,          # default ok, type of number unknwn
                  addr_npi => 0x00,          # default ok, number plan indicator
                  address_range => '',       # default ok, regex matching nmbrs
                  ) or die;

           Usually this constructor is not called directly. Use new_transceiver(),
           new_transmitter(), and new_receiver() instead.

       new_transceiver()
       new_transmitter()
       new_receiver()
           These constructors first construct the object using new_connect() and then bind using
           given type of bind request. See bind family of methods, below. These constructors are
           usually used to implement ESME type functionality.

       new_listen('localhost', port=>2251)
           Create new SMPP server object and open socket to listen on given port. This
           constructor is usually used to implement a SMSC.

REQUEST PDU METHODS

       Each request PDU method constructs a PDU from list of arguments supplied and sends it to
       the wire.

       If async mode has been enabled (by specifying "async=>1" in the constructor or as an
       argument to the method), the methods return sequence number of the PDU just sent. This
       number can be later used to match up the response, like this:

           $seq = $smpp->query_sm(message_id => $msg_id) or die;
           ...
           $resp_pdu = $smpp->wait_pdu(Net::SMPP::CMD_query_sm_resp, $seq)
              or die;
           die "Response indicated error: " . $resp_pdu->explain_status()
              if $resp_pdu->status;

       If async mode is not enabled (i.e. "async=>1" was not specified neither in constructor nor
       the method), the method will wait for the corresponding response and return Net::SMPP::PDU
       object representing that response. The application should check the outcome of the
       operation from the status field of the response PDU, like this:

           $resp_pdu = $smpp->query_sm(message_id => $msg_id) or die;
           die "Response indicated error: " . $resp_pdu->explain_status()
              if $resp_pdu->status;

       All request PDU methods optionally take "seq=>123" argument that allows explicit
       specification of the sequence number. The default is to increment internally stored
       sequence number by one and use that.

       Most PDUs have mandatory parameters and optional parameters. If mandatory parameter is not
       supplied, it is inherited from the smpp object. This means that the parameter can either
       be set as an argument to the constructor or it is inherited from built-in defaults in the
       innards of Net::SMPP (see "Default" table from line 217 onwards). Some mandatory
       parameters can not be defaulted - if they are missing a die results. In descriptions
       below, defaultable mandatory parameters are show with the default value and comment
       indicating that its defaultable.

       Optional parameters can be supplied to all PDUs (although the SMPP spec does not allow
       optional parameters for some PDUs, the module does not check for this) by listing them in
       the order that they should be appended to the end of the PDU. Optional parameters can not
       be defaulted - if the parameter is not supplied, it simply is not included in the PDU.
       Optional parameters are not supported by previous versions of the SMPP protocol (up to and
       including 3.3).  Applications wishing to be downwards compatible should not make use of
       optional parameters.

       Standard optional parameters can be supplied by their name (see "param_tab" in the
       Net::SMPP source code, around line 345, for list of known optional parameters), but the
       programmer still needs to supply the value of the parameter in the expected format (one
       often has to use pack to construct the value). Consult SMPP specifications for the correct
       format.

       It is possible to supply arbitrary unsupported optional parameters by simply supplying the
       parameter tag as a decimal number. Consult your site dependent documentation to figure out
       the correct tags and to determine the correct format for the value.

       When optional parameters are returned in response PDUs, they are decoded and made
       available under both numeric tag and symbolic tag, if known. For example the
       delivery_failure_reson of data_sm_resp can be accessed both as
       $resp->{delivery_failure_reson} and $resp->{1061}.  The application needs to interpret the
       formatting of optional parameters itself. The module always assumes they are strings,
       while often they actually are interpretted as integers. Consult SMPP specifications and
       site dependent documentation for correct format and use unpack to obtain the numbers.

       If an unknown nonnumeric parameter tags are supplied a warning is issued and parameter is
       skipped.

       In general the Net::SMPP module does not enforce SMPP specifications. This means that it
       will happily accept too long or too short values for manatory or optional parameters. Also
       the internal formatting of the parameter values is not checked in any way. The programmer
       should consult the SMPP specifications to learn the correct length and format of each
       mandatory and optional parameter.

       Similarly, if the remote end returns incorrect PDUs and Net::SMPP is able to parse them
       (usually because length fields match), then Net::SMPP will not perform any further checks.
       This means that some fields may be longer than allowed for in the specifications.

       I opted to leave the checks out at this stage because I needed a flexible module that
       allowed me to explore even nonconformant SMSC implementations.  If the lack of sanity
       checks bothers you, formulate such checks and submit me a patch. Ideally one could at
       construction time supply an argument like "strict=>1" to enable the sanity checks.

       alert_notification() (4.12.1, p.108)
           Sent by SMSC to ESME when particular mobile subscriber has become available.
           source_addr specifies which mobile subscriber. esme_addr specifies which esme the
           message is destined to. Alert notifications can arise if delivery pending flag had
           been set for the subscriber from previous data_sm operation.

           There is no response PDU.

               $smpp->alert_notification(
                                         source_addr_ton => 0x00, # default ok
                                         source_addr_npi => 0x00, # default ok
                                         source_addr => '',       # default ok
                                         esme_addr_ton => 0x00,   # default ok
                                         esme_addr_npi => 0x00,   # default ok
                                         esme_addr => $esme_addr, # mandatory
                                         ) or die;

       bind_transceiver() (4.1.5, p.51)
       bind_transmitter() (4.1.1, p.46)
       bind_receiver() (4.1.3, p.48)
           Bind family of methods is used to authenticate the client (ESME) to the server (SMSC).
           Usually bind happens as part of corresponding constructor "new_transceiver()",
           "new_transmitter()", or "new_receiver()" so these methods are rarely called directly.
           These methods take a plethora of options, which are largely the same as the options
           taken by the constructors and can safely be defaulted.

               $smpp->bind_transceiver(
                  system_id => 'username',   # usually needed (default '')
                  password => 'secret',      # usually needed (default '')
                  system_type => '',         # default ok, often not needed
                  interface_version => 0x34, # default ok, almost never needed
                  addr_ton => 0x00,          # default ok, type of number unkwn
                  addr_npi => 0x00,          # default ok, number plan indic.
                  address_range => '',       # default ok, regex matching tels
                  ) or die;

           Typically it would be called like:

               $resp_pdu = $smpp->bind_transceiver(system_id => 'username',
                                                   password => 'secret') or die;
               die "Response indicated error: " . $resp_pdu->explain_status()
                  if $resp_pdu->status;

           or to inform SMSC that you can handle all Spanish numbers:

               $resp_pdu = $smpp->bind_transceiver(system_id => 'username',
                                                   password => 'secret',
                                                   address_range => '^\+?34')
                  or die;
               die "Response indicated error: " . $resp_pdu->explain_status()
                  if $resp_pdu->status;

       cancel_sm() (4.9.1, p.98)
           Issued by ESME to cancel one or more short messages. Two principal modes of operation
           are:

           1. if message_id is supplied, other fields can be left at defaults. This mode deletes
           just one message.

           2. if message_id is not supplied (or is empty string), then the other fields must be
           supplied and all messages matching the criteria reflected by the other fields are
           deleted.

               $smpp->cancel_sm(
                                service_type => '',      # default ok
                                message_id => '', # default ok, but often given
                                source_addr_ton => 0x00, # default ok
                                source_addr_npi => 0x00, # default ok
                                source_addr => '',       # default ok
                                dest_addr_ton => 0x00,   # default ok
                                dest_addr_npi => 0x00,   # default ok
                                destination_addr => '',  # default ok
                              ) or die;

           For example

              $resp_pdu = $smpp->submit_sm(destination_addr => '+447799658372',
                                            short_message => 'test message')
                 or die;
              die "Response indicated error: " . $resp_pdu->explain_status()
                  if $resp_pdu->status;
              $msg_id = $resp_pdu->{message_id};

              $resp_pdu = $smpp->query_sm(message_id => $msg_id) or die;
              die "Response indicated error: " . $resp_pdu->explain_status()
                  if $resp_pdu->status;
              print "Message state is $resp_pdu->{message_state}\n";

              $resp_pdu = $smpp->replace_sm(message_id => $msg_id,
                                            short_message => 'another test')
                 or die;
              die "Response indicated error: " . $resp_pdu->explain_status()
                  if $resp_pdu->status;

              $resp_pdu = $smpp->cancel_sm(message_id => $msg_id) or die;
              die "Response indicated error: " . $resp_pdu->explain_status()
                  if $resp_pdu->status;

       data_sm() (4.7.1, p.87)
           Newer alternative to submit_sm and deliver_sm. In addition to that data_sm can be used
           to pass special messages such as SMSC Delivery Receipt, SME Delivery Acknowledgement,
           SME Manual/User Acknowledgement, Intermediate notification.

           Unlike submit_sm and deliver_sm, the short_message parameter is not mandatory. Never-
           the-less, the optional parameter message_payload must be supplied for things to work
           correctly.

               $smpp->data_sm(
                              service_type => '',      # default ok
                              source_addr_ton => 0x00, # default ok
                              source_addr_npi => 0x00, # default ok
                              source_addr => '',       # default ok
                              dest_addr_ton => 0x00,   # default ok
                              dest_addr_npi => 0x00,   # default ok
                              destination_addr => $tel,  # mandatory
                              esm_class => 0x00,       # default ok
                              registered_delivery => 0x00, #default ok
                              data_coding => 0x00,     # default ok
                              message_payload => 'test msg', # opt, but needed
                              ) or die;

           For example

              $resp_pdu = $smpp->data_sm(destination_addr => '+447799658372',
                                         message_payload => 'test message')
                 or die;
              die "Response indicated error: " . $resp_pdu->explain_status()
                  if $resp_pdu->status;

       deliver_sm() (4.6.1, p.79)
           Issued by SMSC to send message to an ESME. Further more SMSC can transfer following
           special messages: 1. SMSC delivery receipt, 2. SME delivery acknowledgement, 3. SME
           Manual/User Acknowledgement, 4. Intermediate notification. These messages are sent in
           response to SMS message whose registered_delivery parameter requested them.

           If message data is longer than 254 bytes, the optional parameter "message_payload"
           should be used to store the message and "short_message" should be set to empty string.
           N.B. although protocol has mechanism for sending fairly large messages, the underlying
           mobile network usually does not support very large messages. GSM supports only up to
           160 characters, other systems 128 or even just 100 characters.

               $smpp->deliver_sm(
                              service_type => '',      # default ok
                              source_addr_ton => 0x00, # default ok
                              source_addr_npi => 0x00, # default ok
                              source_addr => '',       # default ok
                              dest_addr_ton => 0x00,   # default ok
                              dest_addr_npi => 0x00,   # default ok
                              destination_addr => $t,  # mandatory
                              esm_class => 0x00,       # default ok
                              protocol_id => 0x00,     # default ok on CDMA,TDMA
                                                       #   on GSM value needed
                              priority_flag => 0x00,   # default ok
                              schedule_delivery_time => '', # default ok
                              validity_period => '',        # default ok
                              registered_delivery => 0x00,  # default ok
                              replace_if_present_flag => 0x00, # default ok
                              data_coding => 0x00,     # default ok
                              sm_default_msg_id => 0x00,    # default ok
                              short_message => '',     # default ok, but
                                                       #   usually supplied
                              ) or die;

           For example

              $resp_pdu = $smpp->deliver_sm(destination_addr => '+447799658372',
                                            short_message => 'test message')
                 or die;
              die "Response indicated error: " . $resp_pdu->explain_status()
                  if $resp_pdu->status;

       enquire_link() (4.11.1, p.106)
           Used by either ESME or SMSC to "ping" the other side. Takes no parameters.

               $smpp->enquire_link() or die;

       outbind() (4.1.7, p.54, 2.2.1, p.16)
           Used by SMSC to signal ESME to originate a "bind_receiver" request to the SMSC.
           "system_id" and "password" authenticate the SMSC to the ESME.  The "outbind" is used
           when SMSC initiates the TCP session and needs to trigger ESME to perform a
           "bind_receiver". It is not needed if the ESME initiates the TCP connection (e.g. sec
           2.7.1, p.27).

           There is not response PDU for "outbind", instead the ESME is expected to issue
           "bind_receiver".

               $smpp->outbind(
                              system_id => '',  # default ok, but usually given
                              password => '',   # default ok, but usually given
                              ) or die;

       query_sm() (4.8.1, p.95)
           Used by ESME to query status of a submitted short message. Both message_id and
           source_addr must match (if source_addr was defaulted to NULL during submit, it must be
           NULL here, too). See example near "cancel_sm".

               $smpp->query_sm(
                              message_id => $msg_id,   # mandatory
                              source_addr_ton => 0x00, # default ok
                              source_addr_npi => 0x00, # default ok
                              source_addr => '',       # default ok
                              ) or die;

       replace_sm() (4.10.1, p.102)
           Used by ESME to replace a previously submitted short message, provided it is still
           pending delivery. Both message_id and source_addr must match (if source_addr was
           defaulted to NULL during submit, it must be NULL here, too). See example near
           "cancel_sm".

               $smpp->replace_sm(
                              message_id => $msg_id,   # mandatory
                              source_addr_ton => 0x00, # default ok
                              source_addr_npi => 0x00, # default ok
                              source_addr => '',       # default ok
                              schedule_delivery_time => '', # default ok
                              validity_period => '',        # default ok
                              registered_delivery => 0x00,  # default ok
                              sm_default_msg_id => 0x00,    # default ok
                              short_message => '',     # default ok, but
                                                       #   usually supplied
                              ) or die;

       submit_sm() (4.4.1, p.59)
           Used by ESME to submit short message to the SMSC for onward transmission to the
           specified short message entity (SME). The submit_sm does not support the transaction
           message mode.

           If message data is longer than 254 bytes, the optional parameter "message_payload"
           should be used to store the message and "short_message" should be set to empty string.
           N.B. although protocol has mechanism for sending fairly large messages, the underlying
           mobile network usually does not support very large messages. GSM supports only up to
           160 characters.

               $smpp->submit_sm(
                              service_type => '',      # default ok
                              source_addr_ton => 0x00, # default ok
                              source_addr_npi => 0x00, # default ok
                              source_addr => '',       # default ok
                              dest_addr_ton => 0x00,   # default ok
                              dest_addr_npi => 0x00,   # default ok
                              destination_addr => $t,  # mandatory
                              esm_class => 0x00,       # default ok
                              protocol_id => 0x00,     # default ok on CDMA,TDMA
                                                       #   on GSM value needed
                              priority_flag => 0x00,   # default ok
                              schedule_delivery_time => '', # default ok
                              validity_period => '',        # default ok
                              registered_delivery => 0x00,  # default ok
                              replace_if_present_flag => 0x00, # default ok
                              data_coding => 0x00,     # default ok
                              sm_default_msg_id => 0x00,    # default ok
                              short_message => '',     # default ok, but
                                                       #   usually supplied
                              ) or die;

           For example

              $resp_pdu = $smpp->submit_sm(destination_addr => '+447799658372',
                                            short_message => 'test message')
                 or die;
              die "Response indicated error: " . $resp_pdu->explain_status()
                  if $resp_pdu->status;

           Or

              $resp_pdu = $smpp->submit_sm(destination_addr => '+447799658372',
                                           short_message => '',
                                           message_payload => 'a'x500) or die;
              die "Response indicated error: " . $resp_pdu->explain_status()
                  if $resp_pdu->status;

       submit_multi() (4.5.1, p.69)
           Used by ESME to submit short message to the SMSC for onward transmission to the
           specified short message entities (SMEs). This command is especially destined for
           multiple recipients.

           If message data is longer than 254 bytes, the optional parameter "message_payload"
           should be used to store the message and "short_message" should be set to empty string.
           N.B. although protocol has mechanism for sending fairly large messages, the underlying
           mobile network usually does not support very large messages. GSM supports only up to
           160 characters.

               $smpp->submit_multi(
                              service_type => '',      # default ok
                              source_addr_ton => 0x00, # default ok
                              source_addr_npi => 0x00, # default ok
                              source_addr => '',       # default ok
                              dest_flag =>             # default ok
                                   [ MULTIDESTFLAG_SME_Address,
                                     MULTIDESTFLAG_dist_list, ... ],
                              dest_addr_ton =>         # default ok
                                   [ 0x00, 0x00, ... ],
                              dest_addr_npi =>         # default ok
                                   [ 0x00, 0x00, ... ],
                              destination_addr =>      # mandatory
                                   [ $t1, $t2, ... ],
                              esm_class => 0x00,       # default ok
                              protocol_id => 0x00,     # default ok on CDMA,TDMA
                                                       #   on GSM value needed
                              priority_flag => 0x00,   # default ok
                              schedule_delivery_time => '', # default ok
                              validity_period => '',        # default ok
                              registered_delivery => 0x00,  # default ok
                              replace_if_present_flag => 0x00, # default ok
                              data_coding => 0x00,     # default ok
                              sm_default_msg_id => 0x00,    # default ok
                              short_message => '',     # default ok, but
                                                       #   usually supplied
                              ) or die;

           For example

              $resp_pdu = $smpp->submit_multi(destination_addr =>
                                              [ '+447799658372', '+447799658373' ],
                                              short_message => 'test message')
                 or die;
              die "Response indicated error: " . $resp_pdu->explain_status()
                  if $resp_pdu->status;

           The destinations are specified as an array reference. dest_flag, dest_addr_ton, and
           dest_addr_npi must have same cardinality as destination_addr if they are present.
           Default for dest_flag is MULTIDESTFLAG_SME_Address, i.e. normal phone number.

       unbind() (4.2, p.56)
           Used by ESME to unregisters ESME from SMSC. Does not take any parameters.

               $smpp->unbind() or die;

RESPONSE PDU METHODS

       Response PDU methods are used to indicate outcome of requested commands. Typically these
       methods would be used by someone implementing a server (SMSC).

       Response PDUs do not have separate asynchronous behaviour pattern.

       bind_receiver_resp()
       bind_transmitter_resp()
       bind_transceiver_resp()
               $smpp->bind_transceiver_resp(
                                            system_id => '', # default ok
                                            ) or die;

       cancel_sm_resp() (4.9.2, p.100)
               $smpp->cancel_sm_resp() or die;

       data_sm_resp()
               $smpp->data_sm_resp(message_id => $msg_id) or die;

       deliver_sm_resp()
               $smpp->deliver_sm_resp(message_id => $msg_id) or die;

       enquire_link_resp() (4.11.2, p.106)
               $smpp->enquire_link_resp() or die;

       generic_nack() (4.3.1, p.57)
               $smpp->generic_nack() or die;

       query_sm_resp() (4.6.2, p.96)
               $smpp->query_sm_resp(
                                    message_id => $msg_id,   # mandatory
                                    final_date => '',        # default ok
                                    message_state => $state, # mandatory
                                    error_code => 0x00,      # default ok
                              ) or die;

       replace_sm_resp() (4.10.2, p.104)
               $smpp->replace_sm_resp() or die;

       submit_sm_resp() (4.4.2, p.67)
               $smpp->submit_sm_resp(message_id => $msg_id) or die;

       submit_multi_resp() (4.5.2, p.76)
               $smpp->submit_multi_resp(message_id => $msg_id
                                        dest_addr_ton => [], # default ok
                                        dest_addr_npi => [], # default ok
                                        destination_addr => [],  # mandatory
                                        error_status_code => [], # mandatory
                                        ) or die;

       unbind_resp() (4.2.2, p.56)
               $smpp->unbind_resp() or die;

MESSAGE ENCODING AND LENGTH

           Many SMS technologies have inherent message length limits. For example GSM specifies
           length to be 140 bytes. Using 7 bit encoding, this holds the 160 characters that
           people are familiar with. Net::SMPP does not enforce this limit in any way, i.e. if
           you create too long message, then it is your problem. You should at application layer
           make sure you stay within limits.

           Net::SMPP also does not automatically perform the encoding, not even if you set
           data_encoding parameter. Application layer is responsible for performing the encoding
           and setting the data_encoding parameter accordingly.

           To assist in performing the usual 7 bit encoding, following functions are provided
           (but you have to call them explicitly):

           pack_7bit()
           unpack_7bit()
               Example

                  $resp_pdu = $smpp->submit_sm(destination_addr => '+447799658372',
                                               data_encoding => 0x00,
                                               short_message => pack_7bit('test message'))
                     or die;

           The rationale for leaving encoding and length issues at application layer is two fold:
           1. often the data is just copied through to another message or protocol, thus we do
           not really care how it is encoded or how long it is. Presumably it was valid at
           origin. 2. This policy avoids underlying technology dependencies in the module. Often
           local deployments have all the manner of hacks that make this area very difficult to
           chart. So I leave it to local application developer to find out what is locally
           needed.

OTHER METHODS

       read_pdu()
           Reads a PDU from stream and analyzes it into Net::SMPP::PDU object (if PDU is of known
           type). Blocks until PDU is available.  If you do not want it to block, do select on
           the socket to make sure some data is available (unfortunately some data may be
           available, but not enough, so it can still block).

           read_pdu() is very useful for implementing main loop of SMSC where unknown PDUs must
           be received in random order and processed.

               $pdu = $smpp->read_pdu() or die;

       wait_pdu()
           Reads PDUs from stream and handles or discards them until matching PDU is found.
           Blocks until success. Typically wait_pdu() is used internally by request methods when
           operating in synchronous mode.  The PDUs to handle are specified by
           "${*$me}{handlers}-"{$command_id}>.  The handlers table is initially populated to
           handle enquire_link PDUs automatically, but this can be altered using "handlers"
           argument to constructor.

               $pdu = $smpp->wait_pdu($cmd_id_to_wait, $seq_to_wait) or die;

       set_version($vers)
           Sets the protocol version of the object either to 0x40 or 0x34. Its important to use
           this method instead of altering $smpp->{smpp_version} field directly because there are
           several other fields that have to be set in tandem.

EXAMPLES

       Typical client:

         use Net::SMPP;
         $smpp = Net::SMPP->new_transceiver('smsc.foo.net', port=>2552) or die;
         $resp_pdu = $smpp->submit_sm(destination_addr => '447799658372',
                                      data => 'test message') or die;
         ***

       Typical server, run from inetd:

         ***

       See test.pl for good templates with all official parameters, but beware that the actual
       parameter values are fictitious as is the flow of the dialog.

MULTIPART MESSAGE

       Reportedly (Zeus Panchenko) multipart messages can be gotten to work with

         while (length ($msgtext)) {
           if ($multimsg_maxparts) {
             @udh_ar = map { sprintf "%x", $_ } $origref, $multimsg_maxparts, $multimsg_curpart;
             $udh = pack("hhhhhh",0x05, 0x00, 0x03 , @udh_ar);
             $resp_pdu = $smpp->submit_sm(destination_addr => $phone,
                                  ...
                                  short_message => $udh . $msgtext,
                                );
             ...
           }
         }

       #4#cut =head1 VERSION 4.0 SUPPORT

       Net::SMPP was originally written for version 3.4 of SMPP protocol. I have since then
       gotten specifications for an earlier protocol, the version 4.0 (Logical, eh? (pun
       intended)). In my understanding the relevant differences are as follows (n.b. (ok) marks
       difference that has already been implemented):

       1. A reserved (always 0x00000000) field in message
          header (v4 p. 21) (ok)

       2. Connection can not be opened in transceiver mode (this
          module will not enforce this restriction) (ok)

       3. Command versioning. Version 0x01 == V4 (v4 p. 22) (ok)

       4. Support for extended facilities has to be requested
          during bind (ok)

       5. bind_* PDUs have facilities_mask field (v4 p. 25) (ok)

       6. bind_*_resp PDUs have facilities_mask field (v4 p. 27) (ok)

       7. outbind lacks system ID field (v4 p.30, v3.4 p. 54) (ok)

       8. submit_sm lacks service_type and adds
          message_class (v4 p. 34, v3.4 p. 59) (ok)

       9. submit_sm: telematic_interworking == protocol_id (ok)

       10. submit_sm: starting from number of destinations and
           destination address the message format is substantially
           different. Actually the message format is somewhat
           similar to v3.4 submit_multi. (ok)

       11. submit_sm: validity period encoded as an integer
           relative offset (was absolute time as C string) (ok)

       12. submit_sm: replace_if_present flag missing (ok)

       13. submit_sm: sm_length field is 2 octets (was one) (ok)

       14. submit_sm_resp is completely different, but actually
           equal to v3.4 submit_multi_resp (v4 p. 37,
           v3.4 pp. 67,75) (ok)

       15. submit_sm vs submit_multi: lacks service_type,
           adds message_class (ok)

       16. submit_sm vs submit_multi: number_of_dests increased
           from 1 byte to 4 (ok)

       17. submit_sm vs submit_multi: esm_class lacking, adds
           messaging_mode and msg_reference (ok)

       18. submit_sm vs submit_multi: telematic_interworking == protocol_id (ok)

       19. submit_sm vs submit_multi: replace_if_present missing (ok)

       20. submit_sm vs submit_multi: sm_length is 2 bytes (was one) (ok)

       21. submit_sm vs submit_multi: lacks dest_flag and distribution_list_name (ok)

       22. deliver_sm: lacks service_type (ok)

       23. deliver_sm: lacks esm_class, adds msg_reference and message_class (ok)

       24. deliver_sm: telematic_interworking == protocol_id (ok)

       25. deliver_sm: priority_level == priority_flag (ok)

       26. deliver_sm: submit_time_stamp == schedule_delivery_time (ok)

       27. deliver_sm: lacks validity_period, registered_delivery,
           and replace_if_present_flag (ok)

       28. deliver_sm: lacks sm_default_msg_id (ok)

       29. deliver_sm: sm_length is now 2 bytes (was one) (ok)

       30. deliver_sm_resp: lacks message_id (v3.4 has the field, but its unused) (ok)

       31. New command: delivery_receipt (ok)

       32. New response: delivery_receipt_resp (ok)

       33. query_sm: dest_addr_* fields added (v4 p. 46, v3.4 p. 95) (ok)

       34. query_sm_resp: error_code renamed to network_error_code
           and increased in size from one to 4 bytes (ok)

       35. cancel_sm: service_type renamed to message_class, also
           type changed (ok)

       36. replace_sm: added dest_addr_* fields (ok)

       37. replace_sm: data type of validity_period changed (ok)

       38. replace_sm: added data_coding field (ok)

       39. replace_sm: sm_length field increased from one to two bytes (ok)

       40. In v3.4 command code 0x0009 means bind_transceiver,
           in v4.0 this very same code means delivery_receipt (bummer) (ok)

       41. In v3.4 enquire_link is 0x0015 where as in v4 it is 0x000a (ok)

       To create version 4 connection, you must specify smpp_version => 0x40 and you should not
       bind as transceiver as that is not supported by the specification.

       As v3.4 specification seems more mature, I recommend that where attributes have been
       renamed between v4 and v3.4 you stick to using v3.4 names. I have tried to provide
       compatibility code whenever possible.

       #4#end

MISC. NOTES

       Unless you wrote your program to be multithreaded or multiprocess, everything will happen
       in one thread of execution.  Thus if you get unbind while doing something else (e.g.
       checking your spool directory), it stays in operating system level buffers until you
       actually call read_pdu(). Knowing about unbind or not is of little use. You can write your
       program to assume the network traffic arrives only exactly when you call read_pdu().

       Regarding the unbind, it is normally handled by a dispatch table automatically if you use
       wait_pdu() to receive your traffic. But if you created your own dispatch table, you will
       have to add it there yourself. If you are calling read_pdu() then you have to handle it
       yourslef. Even if you are using the supplied table, you may want to double check - there
       could be a bug.

       One more thing: if your problem is knowing whether wait_pdu() or read_pdu() would block,
       then you have two possible solutions:

               1. use select(2) systemcall to determine for the socket
                  is ready for reading
               2. structure your program as several processes (e.g. one
                  for sending and one for receiving) so that you
                  can afford to block

       The above two tricks are not specific to this module. Consult any standard text book on
       TCP/IP network programming.

ERRORS

       Please consult "status_code" table in the beginning of the source code or SMPP
       specification section 5.1.3, table 5-2, pp.112-114.

EXPORT

       None by default.

TESTS / WHAT IS KNOWN TO WORK

       Interoperates with itself.

TO DO AND BUGS

       read_pdu() can block even if socket selects for reading.
       The submit_multi command has not been implemented.

AUTHOR AND COPYRIGHT

       Sampo Kellomaki <sampo@symlabs.com>

       Net::SMPP is copyright (c) 2001-2010 by Sampo Kellomaki, All rights reserved.  Portions
       copyright (c) 2001-2005 by Symlabs, All rights reserved.  You may use and distribute
       Net::SMPP under same terms as perl itself.

       NET::SMPP COMES WITH ABSOLUTELY NO WARRANTY.

PLUG

       This work was sponsored by Symlabs, the LDAP and directory experts (www.symlabs.com).

SEE ALSO

       test.pl from this package
       Short Message Peer to Peer Protocol Specification v3.4, 12-Oct-1999, Issue 1.2
       www.etsi.fr
       GSM 03.40, v5.7.1
       www.wapforum.org
       Short Message Peer to Peer (SMPP) V4 Protocol Specification, 29-Apr-1997, Version 1.1
       (from Aldiscon/Logica)  #4
       http://www.hsl.uk.com/documents/advserv-sms-smpp.pdf
       http://www.mobilesms.com/developers.asp
       http://opensmpp.logica.com
       www.smpp.org (it appears as of July 2007 domain squatters have taken over the site and it
       is no longer useful)
       http://www.smsforum.net/  -- New place for info (as of 20081214). However, this page
       announces the death of itself as of July 27, 2007. Great. The SMS folks really do not want
       anyone to implement their protocols from specifications.
       "Short Message Peer to Peer Protocol Specification v5.0 19-February-2003",
       http://www.csoft.co.uk/documents/smppv50.pdf (good as of 20081214)
       http://freshmeat.net/projects/netsmpp/ (announcements about Net::SMPP)
       http://zxid.org/smpp/net-smpp.html (home page)
       http://cpan.org/modules/by-module/Net/Net-SMPP-1.12.tar.gz (download from CPAN)
       perl(1)