Biblioteca C-open-smpp-3.4

Raúl Tremsal <rtremsal@movilgate.com>

Historial de revisiones
Revisión 1.02006-06-03Revisado por: Raúl Tremsal
Versión inicial
Revisión 1.12006-10-28Revisado por: Raúl Tremsal
Version 1.8 de la librería, resolución de pendientes.

Este trabajo está dirigido a programadores C con conocimientos básicos del protocolo SMPP, al menos en la especificación y manejo de sesiones. Extendiendo un poco el desarrollo de la biblioteca, el alcance de la misma podría involucrar un metodo de desarrollo de protocolos sobre TCP/IP.


Tabla de contenidos
1. Introducción
1.1. El objetivo planteado
1.2. Definición de la API
2. Función de empaquetamiento de estructuras
2.1. Ejemplo de uso
3. Función de desempaquetamiento de estructuras
3.1. Ejemplo de uso
4. Función de volcado de estructuras (DUMP)
4.1. Ejemplo de uso
5. Función de volcado de buffer (DUMP)
5.1. Ejemplo de uso
6. Manejo de parámetros opcionales
6.1. Ejemplo de uso
7. Manejo de listas de destinos en los PDUs SUBMIT_MULTI y SUBMIT_MULTI_RESP
8. Ejemplos incluidos en la librería.
8.1. Ejemplos para cada PDU.
8.2. Un ESME de ejemplo.
9. Conclusiones y futuras actualizaciones.

1. Introducción

El principal enfoque de la biblioteca, es trabajar en el empaquetado y desempaquetado de estructuras de dato. Así independientemente de que esta implementación sea del protocolo SMPP-3.4, el potencial de la misma es generar de manera simple cualquier protocolo propietario sobre TCP.

1.1. El objetivo planteado

Todo desarrollador que intente entrar en el mundo SMPP, invariablemente pasa por el kannel (http://www.kannel.org/). Sin embargo, el proyecto kannel es lo suficientemente grande como para desanimar a quien quiere implementar alguna solución que involucre solamente el SMPP.

La actual biblioteca, se basa en algunos trucos del código fuente del kannel, generando una forma para manipular estructuras de datos en base al precompilador de C. El resultado es una serie de funciones que empacan y desempacan estructuras de datos hacia o desde un buffer.

La intención de la misma, es proveer de una implementación de protocolo SMPP-3.4 solo en la parte de manejo de PDUs. Independizando de la misma el manejo de la conexión TCP y de la sesión SMPP. Como se vé, la biblioteca apunta a solucionar solamente el tema del protocolo, dejando a criterio del desarrollador el manejo de los otros niveles en la comunicación.

La actual versión de librería 1.8, incorpora los dos PDUs pendientes en la versión 1.7 completando la totalidad de los PDUs del SMPP-3.4. Los nuevos PDUs son SUBMIT_MULTI y SUBMIT_MULTI_RESP. Dichos PDUs son especiales ya que incorporan listas dinámicas de destinos. La implementación de las mismas fueron hechas siguiendo las primitivas de los parámetros opcionales.

1.2. Definición de la API

La API está definida en 4 funciones:

  • Función de empaquetado: En esta función, el primer y último parámetro son representativos de la estructura de datos que se quiere empacar, el primero indentifica dicha estructura y el último es un puntero al objeto de dato.

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

  • Función de desempacado: En esta función, se le pasa un puntero al buffer y la longitud del mismo, y la función devuelve un puntero a una estructura definida por el campo type.

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

  • Función de volcado de estructura (DUMP): En esta función, los parámetros de entrada corresponden a la dirección de un objeto de dato, y la función parsea los valores de dicha estructura, dejando dicho texto en otro puntero de salida.

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

  • Función de volcado de buffer (DUMP): En esta función, los parámetros de entrada corresponden a la dirección de un buffer, la función imprime en un buffer de salida en formato imprimible el contenido del buffer.

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

Además de las funciones, se definen las variables globales que completan la API de desarrollo.

int smpp34_errno;
char smpp34_strerror[2048];
    

Se definen además todas las estructuras de datos propias del protocolo que se quiere implementar. En este caso hay una estructura de dato por cada PDU del SMPP-3.4.

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;
    
La descripción de cada una de estas estructura esta detallada en la especificación misma del protocolo. Como otro de los objetivos planteados, la implementación de cada estructura no difiere en nada de la especificación del protolo (salvo en el tema de parámetros opcionales, donde se usa una lista de datos dinámicos).

Para manejar parámetros opcionales dentro del protocolo SMPP-3.4 se han agregado 2 funciones que manejan listas dinamicas de TLVs.

int build_tlv( tlv_t **dest, tlv_t *source );
int destroy_tlv( tlv_t *sourceList );
    
Para manejar las listas dinámicas de los destinos en los PDUs de SUBMIT_MULTI y SUBMIT_MULTI_RESP se agregan las funciones.
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 );
    
Consulte la especificación del protocolo SMPP-3.4 así como los ejemplos provistos, para manipular dichos PDUs.

A continuación, se verá en más detalle cada una de estas funciones. La biblioteca cuenta con ejemplos para todos los PDUs del protocolo SMPP-3.4.