Isode Messaging APIs
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
- Application Features
- Messaging Configuration
- Configuring the Applications
- Compiling the Applications
- Isode Specific Features of XMT
- Configuring the Applications
- Transfer out of the Gateway into the MTA
- Transfer into the the Gateway out of the MTA)
- Running the 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>