EMG Plugin API Print
Tuesday, 07 August 2007

This document explains how to use the EMG Plugin API available in EMG 3 and later.

Overview

It is possible to “hook in” to EMG 3 using an external shared library in order to perform special tasks before and after messages are sent and received by EMG. This makes it possible to implement special billing procedures, advanced routing etc.

The shared library is usually implemented in the C programming language.

Sample connector using the Plugin API:

PLUGIN myplugin <
CONFIG=/etc/emg/plugins/myplugin.cfg
INSTANCES=1
LIBRARY=/etc/emg/plugins/myplugin.so
>

CONNECTOR smpp-out <
TYPE=OUTGOING
ADDRESS=10.0.0.1:5000
PROTOCOL=SMPP
INSTANCES=1
PLUGIN=myplugin:my-optional-string-argument
>

API functions

The library should export the following functions. All functions are optional, so leave unused functions out instead of having empty stubs.

void* create_config(char* pluginname, char* configname)

Load the configuration given in 'configname', and return a pointer to it. This pointer will be used as the first argument to all other functions.

void destroy_config(void* configuration)

Free all resources used by the given configuration.

The following four functions are called at different times in the lifetime of a message:

int before_receive(void* configuration, pluginrequest_t* request, pluginresponse_t* response)

Called before a message is accepted into EMG.

If it is ok to proceed it should return 0.

int before_send(void* configuration, pluginrequest_t* request, pluginresponse_t* response)

Called before a message is sent from EMG.

If it is ok to proceed it should return 0.

int after_send(void* configuration, pluginrequest_t* request, pluginresponse_t* response)

Called after a message is sent from EMG.

The status is available in the 'request' struct, in the 'result' field.

int after_dlr(void* configuration, pluginrequest_t* request, pluginresponse_t* response)

Called after a delivery report is received to EMG.

The status is available in the 'request' struct, in the 'result' field.

Utility functions

In order to take full advantage of the Plugin API a limited number of utility functions in order to access data structures used by EMG internally. The most important of these is the message (or queue entry) represented as “qe” below. The message entity holds a list of key-value pairs for all message attributes such as source address, destination address and message data.

As an example in order to retrieve the source address of a message the following function call can be used:

char *msg = qe_option_get(qe, MGP_OPTION_SOURCEADDR);

or to change the route option of a message forcing it to be routed through a specific connector (named “smsc1” in this example):

qe_option_replace(qe, MGP_OPTION_ROUTE, “smsc1”);

Also string within EMG are stored as variable buffers (called vbuf’s) in order to eliminate the risk for buffer overflows.

Message functions (qe)

char* qe_option_get(void* qe, int option)

Get the string representation of the specified option from message entry.

int qe_option_getint(void* qe, int option, int defaultvalue)

Get the integer representation of the specified option from message entry. If key is missing the defaultvalue is returned instead.

char* qe_option_get2(void* qe, int option, int* len)

Get the string representation of the specified option from message entry. The length of the string returned is stored in the integer pointed to by len.

void qe_option_replace(void* qe, int option, char* value)

Replace the value of the specified option with the given value. The value is a pointer to a null-terminated string.

void qe_option_replace2(void* qe, int option, char* value, int len)

Replace the value of the specified option with the given value. The value is a pointer to a string and the length must be provided in the len parameter.

void qe_foreach_option(void* qe, qe_func_foreach_t func, void* arg)

Loop over message options calling the supplied function for every option. The user-supplied function must use the signature defined by the following typedef:

typedef void (*qe_func_foreach_t)(int key, char* value, int len, void* arg)

Variable buffer functions (vbuf)

int vbuf_length(vbuf_t *)

Return the length of the string contained in the specified vbuf.

char *vbuf_tostring(vbuf_t *)

Returns a pointer to the string contained in the specified vbuf.

More information

EMG Plugin API - Manual

For more information about the Plugin API, header files and code samples please contact Infoflex Connect EMG support, This e-mail address is being protected from spambots. You need JavaScript enabled to view it .