Summary: These examples programs show how to use X.400 C OpenGroup Gateway API to transfer messages in and out of a gateway. Typically this API is used for transferring messages to a protocol other than X.400.

Content

Isode X.400 OpenGroup X.400 Gateway API - Example Applications

API Specification

The OpenGroup APIs can be seen here. For an overview of the Isode X.400 Gateway APIs, click here.

Note that this implementation of the OpenGroup API does not work over protocol, ie the API is procedural, and must therefore be colocated with the MTA.

Isode Extensions

Although this is an Open Standard, Isode have added some proprietary extensions which are documented here [TBS].

Application Features

These examples do the following using the Isode implementation of the OpenGroup X.400 Gateway API

  • transfer X.400 messages into the Gateway from the MTA
  • transfer X.400 messages into the MTA from the Gateway

Full specification of the API is here.

Messaging Configuration

Create an MTA using Mconsole and the wizards. You will need to create an External MTA to act as the Gateway, and a Gateway channel which you application will use as which to Bind to the MTA.

You will need to register the O/R address space of message recipients to be transfered into the Gateway using a Routing Tree node which points at the External Gateway.

The External MTA is an MTA Gateway, ie it has an MTA Gateway as its Application Context. The local MTA has an x400mt channel which has an Outbound Protocol of MTA Gateway. The combination of:

ex_trout will then be able to connect to the Gateway channel. Submit a message, which will then be routed to the Gateway MTA. The message will then wait on the Gateway channel until the ex_trin program picks it up

Configuring the Applications

Each if the two example applications has a file exmain.c, which hold config details

ex_trin

The following values need to be changed depending the way the application is to connect to the MTA.

char EX_SERVICE_NAME[]      = "",
     EX_COUNTRY_NAME[]      = "GB",
     EX_ADMD_NAME[]         = "TestADMD",
     EX_PRMD_IDENTIFIER[]   = "TestPRMD",
     EX_ORGANIZATION_NAME[] = "attlee",
     EX_ORG_UNIT_NAME_1[]   = "lppt",
     EX_ORG_UNIT_NAME_2[]   = "",
     EX_ORG_UNIT_NAME_3[]   = "",
     EX_ORG_UNIT_NAME_4[]   = "",
     EX_COMMON_NAME[]       = "lppt1",
     EX_SURNAME[]           = "",
     EX_INITIALS[]          = "",
     EX_USER_PASSWORD[]     = "",
     EX_SERVICE_PASSWORD[]  = "",
/* NB the first part must be configured as a gateway channel in EMMA, 
 *  * second can be anything (the value is used as the progname when logging) */
     EX_CLIENT_NAME[]       = "xmt",
     EX_CLIENT_INSTANCE[]   = "";

ex_trout

The following values need to be changed depending the way the application is to connect to the MTA and transfer messages out of the Gateway.


char EX_SERVICE_NAME[]      = "machine!x400srv",
EX_COUNTRY_NAME[]      = "XX",
EX_ADMD_NAME[]         = "ICAO",
EX_PRMD_IDENTIFIER[]   = "AVID",
EX_ORGANIZATION_NAME[] = "BODENSEE",
EX_ORG_UNIT_NAME_1[]   = "OU1",
EX_ORG_UNIT_NAME_2[]   = "OU2",
EX_ORG_UNIT_NAME_3[]   = "OU3",
EX_ORG_UNIT_NAME_4[]   = "gateway",
EX_SURNAME[]           = "USER",
EX_RECIP_SURNAME[]           = "USER",
EX_BAD_SURNAME[]           = "USER",
EX_OTHER_BAD_SURNAME[]           = "BADUSER",
EX_INITIALS[]          = "MT",
EX_INITIALS_TTX[]          = "M_T",
EX_COMMON_NAME[]        = "COMMONNAME",
EX_USER_PASSWORD[]     = "PASSWD",
EX_SERVICE_PASSWORD[]  = "WORDPASS",
EX_CLIENT_NAME[]       = "xmt",
EX_CLIENT_INSTANCE[]   = "Instance Name",
EX_MTA_NAME[]      = "local-mta",
...

Compiling the Applications

To build the applications an example Makefile is supplied. On Linux run the command

# cd /opt/isode/share/examples/xmt
# make

For Solaris or other Unix platforms you will need to edit the Makefile depending on the compiler you are using.

Isode Specific Features of XMT

Although the API is a formally specified API, there are some Isode specific features, which are decribed here.

Arguments to mt_open()

The arguments to mt_open() that are of particular interest to XAPI are:

  • client_name which takes the format: channel/mta_name/password

mta_name and password are optional.

However, if you wish to use a password, you must also specify the associated mta_name, or the queue manager will not know to which MTA the password applies.

If an mta_name is not specified, all messages arriving on the channel are listed for delivery. If an mta_name is specified, only messages specifically addressed to that MTA will be delivered. The definition of legal values for these fields is made in the $(TBLDIR)/auth.qmgr file.

  • client_instance_name,which is ignored.

Queue Manager Interaction

  • If you read messages but decide not to accept delivery of them at that time, they will become unavailable for a time period determined by the queue manager:
  • If you read five messages or more and do not take delivery of them, subsequent messages already queued for delivery will also become unavailable for a period of time. This is because the queue manager is attempting to ensure integrity.

Isode Extensions

The example applications provide two useful extensions.

This function prints the object to the file handle specified. The object can be a public or private object.

void ex_print_obj (FILE *out, OM_object obj, int indent);

This function places the information supplied in its parameters in the descriptor indicated.

void add_descriptor (OM_descriptor *desc, OM_type type,OM_syntax syntax, void *value);

Configuring the Applications

Similarly to the Isode Gateway API, the OpenGroup Gateway API requires a passive channel to be configured. See Connection to the MTA below.

Messages are put in the x400mt channel when recipients for the Gateway O/R address space are routed. Message are transferred from the x400mt of the MTA by a Gateway client binding as a passive channel. Message are transferred from the Gateway to the MTA similarly.

All configuration for each application is in a set of strings at the top of examin.c. Some arguments configure the connection to the MTA (clientname and mtaname), and the rest configure the values used in O/R Addresses of the originator and recipients. O/R address attributes which are configured as zero length strings, will not be added to the O/R address.

Transfer out of the Gateway into the MTA

Connection to the MTA

Gateway applications use a procedural, non-protocol interface to the MTA. This means that the client and MTA must be colocated. The only connection arguments required are

  • channel name
  • MTA name (optional)

The channel name must be the name of a valid Gateway channel (eg x400mt). Ie it requires that

  • the outbound protocol is MTA Gateway
  • the prog value is absent
  • the auth.qmgr table is configured with rights=channel for the channel name (eg x400mt). Optionally a password can also be specified. See Connection to MTA above.

The MTA name acts as a filter so that only messages queued on the Gateway channel for the specified MTA are returned.

Transfer into the Gateway out of the MTA

Connection to the MTA

Gateway applications work in the same way whether they are transferring in or out of the Gateway - an application can do both in the same session. Connecting to the MTA for transfer into the Gateway is identical to that of transferring out (see above).

No configuration of program variables isrequired in order to run the example application which transfers message into the Gateway.

Running the Applications

To run the applications you simply run the executable from the command line. No arguments are required.

Not that the transfer in program transfers in both the message as transfered into the Gateway, and the non-delivery report generated by the MTA.

# cd /opt/isode/share/examples/xmt/trout/
# ./ex_trout
Isode OpenGroup Gateway API Example Application - Transfer Out

Attempting to open session
Session opened successfully

arrival_time is 080229145736+0000
trace built in ex is : 
==================================================
type    = om_class
syntax  = object_identifier_string
value   = MH_C_EXTERNAL_TRACE_ENTRY
<deliberately cut short>

# cd ../trin
# ./ex_trin 

Isode OpenGroup Gateway API Example Application - Transfer In

Attempting to open session
Count is 2
Session opened successfully

available = 1
Attempting transfer in of item  0
==================================================
type    = om_class
syntax  = object_identifier_string|om_s_service_generated
value   = MH_C_REPORT
<deliberately cut short>