EMG and custom HTTP requests (inbound) Print
Tuesday, 31 March 2015

Overview

EMG uses its own format and parameter for inbound HTTP requests. For example:

http://emgserver:8080/bin/send?USERNAME=xxx&PASSWORD=yyy&DESTADDR=46123&MESSAGE=Hello+world

Sometimes EMG needs to be able to handle HTTP requests in other formats and in order to handle that we need a custom handler.

You can implement such a custom handler via a HTTP connector that uses URLHANDLER keyword.

Connector definition

Sample connector definition using URLHANDLER:

CONNECTOR http-custom-in1 <
PROTOCOL=HTTP
TYPE=INCOMING
ADDRESS=0.0.0.0:8080
URLHANDLER=/sendsms_form:sendsms.pl:handle_form
URLHANDLER=/sendsms_xml:sendsms.pl:handle_xml
INSTANCES=5
USERS=users
>

Here we define a HTTP connector that listens on port 8080. It maps two different uris ("/sendsms_form" and "/sendsms_xml") to two different functions ("handle_form" and "handle_xml") defined in a perl file, sendsms.pl (relative paths are relative to EMGDIR, directory where server.cfg is located).

Sample perl script that implements handle_form and handle_xml

Sample URL for above connector and script:

http://emgserver:8080/sendsms_form?u=xxx&p=xxx&r=46123&t=Hello+world

The handler function

The handler function will be called at least once but it would normally be called twice for an accepted message.

Function arguments

Sample function definition:

sub do_handle_form {
my ($ci, $arg) = @_;
# Extract connector name
my $cname = ${$ci}{'name'};
my $data = ${$arg}{'data'};
# Operation, 0 = Phase 1, 1 = Phase 2
my $op = ${$arg}{'operation'};
...
}

The handler receives two arguments, a connector information hash reference and an argument hash reference.

The connection information hash contains the information of the connector where the url handler is defined.

The argument hash contains two keys "operation" and "data".

The operation is set to "0" in phase1 and set to "1" in phase 2.

The data contains the data from the http request (GET = query parameters, POST = body) and should be parsed by the script to extract user and message information.

Returning data

You return data from the handler function by setting additional keys in the argument hash.

In phase 1 you would set "status", "messages" and optionally "data".

When setting a non-200 http status code, use the "data" option to set the status text (response body) returned to the http client.

When returning a response body through the use of "data" remember to format it in a way that the client expects (plain text, json, xml etc).

if($recipient eq '' || $text eq '') {
# Return fail
${$arg}{'status'} = 500;
${$arg}{'data'} = 'Parameters "r" and "t" are mandatory';
return;
}

Phase 1 - First pass

The first time it is called it is supposed to extract and set up autentication and message parameters.

If no message is returned from this phase no further processing will take place.

The HTTP status code must be set. For successful it should be set to 200 (or 202). If a mandatory parameter is missing status 500 should be set.

To set http status to 200 for a successful request:

${$arg}{'status'} = 200;

Phase 2 - Second pass

In phase 2 the function is called once for each message returned from phase 1.

Now EMG has assigned a message id to each message and the message options are available from "message" in the argument hash.

my $m = ${$arg}{'message'};
my $msgid = ${$m}{'id'};

In phase two you would build the content / body of the http response and return it in argument hash key "data".

To simply return the message id after accepting a message:

${$arg}{'data'} = ${$m}{'id'};