C open smpp-3.4 Library

Raśl Tremsal <rtremsal@movilgate.com>

Revision History
Revision 1.02006-06-03Revised by: Raúl Tremsal
Initial version.
Revision 1.12006-06-12Revised by: Marcela Carbajo
Some corrections in english version.
Revision 1.22006-06-28Revised by: Raúl Tremsal
Some corrections in english version.
Revision 1.32006-10-28Revised by: Raúl Tremsal
Version 1.8, pending solved.

This work is directed to C programmers with basic knowledge in SMPP protocol, at least in the specification and handling of sessions. Extending a little the development of the library, the scope of the same might involve a development methodology of protocols on TCP/IP.


Table of Contents
1. Introduction
1.1. The main objective
1.2. API definition
2. Packaging function of data structures
2.1. An example
3. Unpackaging function of data structures
3.1. An example
4. Data structures dump function
4.1. An example
5. Buffer dump function
5.1. An example
6. Optional parameters
6.1. An example
7. Handling of destination address lists in SUBMIT_MULTI and SUBMIT_MULTI_RESP PDUs
8. Examples included in library release.
8.1. PDU samples.
8.2. An ESME basic.
9. Conclusions and future works.

1. Introduction

The library main focus is to work in packaging and unpackaging of data structures. Independently that this implementation is about SMPP-3.4, the aim is to generate a simple way to implement any proprietary protocol on TCP.

1.1. The main objective

Any developer that attempts to enter in SMPP world, must go through Kannel software (http://www.kannel.org/). However, Kannel project is so big that it discourages anybody willing to develop a simple SMPP application.

So the library focus is to provide an implementation of SMPP-3.4 protocol but just for PDUs handling, taking as independent the managing of TCP connection and SMPP session. As we see, the library is directed to solve just the protocol issue, left to programmers the handling of the other levels in the communication

1.2. API definition

The API is defined in four functions:

  • Packed function: In this function the first and last parameters are identifying the data structure that we want to pack. The first parameter indetifies the data structure through an integer and the last one refers to data object.

    int smpp34_pack( uint32_t type,    /* in  */
                     uint8_t *ptrBuf,  /* out */
                     int      ptrSize, /* out */
                     int     *ptrLen,  /* out */
                     void    *tt       /* in  */  )
        

  • Unpacked function: In this function a pointer to the buffer and its lenght is passed as parameters. The function returns a pointer to a data structure defined by a type field.

    int smpp34_unpack( uint32_t type,   /* in  */
                       void    *tt,     /* out */
                       uint8_t *ptrBuf, /* in  */
                       int     ptrLen,  /* in  */ )
        

  • Structure dump function: The utility of this function is to provide with a tool for to see the parameters and values of a PDU (data structure). The in parameters refers to data object and the out parameters is a string buffer where the new representation is done.

    int smpp34_dumpPdu( uint32_t type,      /* in  */
                        uint8_t *dest,      /* out */
                        int      size_dest, /* in  */
                        void    *tt         /* in  */ )
        

  • Buffer dump function: In this function, the in parameters refers to a buffer and the its lenght. This function prints in a external buffer a hexa representation of the binary source.

    int smpp34_dumpBuf( uint8_t *dest,  /* out */
                        int      destL, /* in  */
                        uint8_t *src,   /* in  */
                        int      srcL   /* in  */ )
        

In addition to this function, the global variables that complete the API for developing are defined.

int smpp34_errno;
char smpp34_strerror[2048];

Besides, all the data structure proprietary of th SMPP protocol are defined. There is a data structure for each PDU definition. For more information about SMPP please refer to SMPP protocol specification.

typedef struct tlv_t tlv_t;
typedef struct dad_t dad_t;              /* used in SUBMIT_MULTI PDU      */
typedef struct udad_t udad_t;            /* used in SUBMIT_MULTI_RESP PDU */
typedef struct bind_transmitter_t bind_transmitter_t;
typedef struct bind_transmitter_resp_t bind_transmitter_resp_t;
typedef struct bind_receiver_t bind_receiver_t;
typedef struct bind_receiver_resp_t bind_receiver_resp_t;
typedef struct bind_transceiver_t bind_transceiver_t;
typedef struct bind_transceiver_resp_t bind_transceiver_resp_t;
typedef struct outbind_t outbind_t;
typedef struct unbind_t unbind_t;
typedef struct unbind_resp_t unbind_resp_t;
typedef struct generic_nack_t generic_nack_t;
typedef struct submit_sm_t submit_sm_t;
typedef struct submit_sm_resp_t submit_sm_resp_t;
typedef struct submit_multi_t submit_multi_t; 
typedef struct submit_multi_resp_t submit_multi_resp_t; 
typedef struct deliver_sm_t deliver_sm_t;
typedef struct deliver_sm_resp_t deliver_sm_resp_t;
typedef struct data_sm_t data_sm_t;
typedef struct data_sm_resp_t data_sm_resp_t;
typedef struct query_sm_t query_sm_t;
typedef struct query_sm_resp_t query_sm_resp_t;
typedef struct cancel_sm_t cancel_sm_t;
typedef struct cancel_sm_resp_t cancel_sm_resp_t;
typedef struct replace_sm_t replace_sm_t;
typedef struct replace_sm_resp_t replace_sm_resp_t;
typedef struct enquire_link_t enquire_link_t;
typedef struct alert_notification_t alert_notification_t;
The description of each data structure is detailed in SMPP-3.4 document (Short Message Peer to Peer Protocol Specification v3.4). As another settled goal, the implementation of each structure doesn't differ at all from the protocol specification (with exception of the optional parameters, where a list of dynamic data are used).

So if you want to handle optional parameters in SMPP-3.4 protocol, you must use two functions:

int build_tlv( tlv_t **dest, tlv_t *source );
int destroy_tlv( tlv_t *sourceList );
If you want to handle destination address dinamic list in SUBMIT_MULTI and SUBMIT_MULTI_RESP PDUs, you must use two functions:
int build_dad( dad_t **dest, dad_t *source );
int destroy_dad( dad_t *sourceList );
int build_udad( udad_t **dest, udad_t *source );
int destroy_udad( udad_t *sourceList );
    
Please check the SMPP-3.4 specification and the examples added to handle this PDUs.

We'll see each function in detail. The library gives you an example of each PDU handled.