Implementing a Perl plugin - Nordic Messaging

Contents

This document describes how to implement a EMG plugin in Perl. First, setup a separate Perl installation according to description here:
https://nordicmessaging.se/emg-5-2-6-and-perl-plugins/

Adding a Perl plugin to EMG configuration

Plugins are defined in a PLUGIN section in server.cfg. The defined plugin can then be used for one or more connectors using the PLUGIN keyword in the connector section. A sample configuration is shown below.

PLUGIN perl-reject <
LIBRARY=/etc/emg/plugins/reject.pl
CONFIG=config parameter
INSTANCES=1
>

CONNECTOR smpp-in1 <
...
PLUGIN=perl-reject
>

When referencing the plugin in connector section the plugin name can optionally be followed by “:” and a string which can be retrieved from request object in function calls. This is useful when using the same plugin on different connectors.

CONNECTOR smpp-in1 <
...
PLUGIN=perl-reject:smpp
>

CONNECTOR ucp-in1 <
...
PLUGIN=perl-reject:ucp
>

Plugin lifecycle

When emgd is started one perl interpretator is created for each plugin instance and the “create_config” hook, if present, is executed for each instance.

Since a separate perl interpretator is created for each instance different instances cannot share data easily. It requires using shared memory or networking.

All plugins are loaded on emgd startup, with all instances being started in sequence. It is therefore critical that this operation is fast, and does not load lots of data.

Any changes to the plugin source code requires an emgd restart to take effect.

Plugin hooks

There are several hooks defined in EMG. For each hook the corresponding function in the plugin will be called, if present.

The plugin hooks are:

# Executed on emgd start when plugins are loaded
sub create_config
{
  my ($plugin_name, $config) = @_;
  my $myconfig = "dummy";
  return $myconfig;
}

# Executed when a message has been received, but before response is sent back
sub before_receive
{
  my ($request, $response) = @_;
  my $myconfig = $request->{'config'};
  # Accept message
  my $status = 0;
  return $status;
}

# Executed before routing logic is applied
sub route
{
  my ($request, $response) = @_;
  $response->{'route'} = 'smpp-out2';
  # Use 'route'
  return 0;
}

# Executed before message send operation
sub before_send
{
  my ($request, $response) = @_;
  return 0;
}

# Executed after message send operation
sub after_send
{
  my ($request, $response) = @_;
  my $status = $request->{'result'};
}

# Executed after a delivery report (DLR) has been received
sub after_dlr
{
 my ($request, $response) = @_;
}

It is possible to modify message options in all plugin hooks.

Plugin hooks sequence diagram

About the route hook

If route returns 0 and $response->route is set to a string with length > 0, then that string is used as the route target connector and no other routing logic is applied.

For other cases, normal routing logic will be applied.

Plugin objects

The following objects (perl hashes) are used in the EMG Perl Plugin API:

Object $request

config	Object returned in create_config.
connector	A connector object.
ccarg	The string optionally specified when referencing plugin in connector config.
name	Plugin name.
qe	Message object.
result	Set to 0 if send operation was successful, otherwise set to non-zero (after_send only).

Object $response

errorcode	Numeric error code (used by “before_*” hooks when return value is non-zero).
errormessage	Error text (used by “before_*” hooks when return value is non-zero).
route	Target connector (only used by “route” hook).

Object connector

name	Connector name.
instance	Connector instance number (starting at 0).
loglevel	Connector log level.
username	Username (outgoing connectors only).
password	Password (outgoing connectors only).

Object message (qe)

All message options as key-value pairs with MGP names as key. The message options can be modified from any plugin hook and will take effect regardless of return value.

Sample code:

sub before_receive
{
  my ($request, $response) = @_;
  my $qe = ${$request}{'qe'};
  $qe->{'SOURCEADDR'} = 'sender';
  return 0;
}

Sample plugins

Some sample plugins can be found here:
https://nordicmessaging.se/sample-perl-plugins/