Isode R15.2v7 Messaging APIs

Overview

How to read this document

Isode provides a number of APIs which allow integrators and product developers to build components that access the Isode server products or other products supporting the same protocols. This document describes

The APIs that are available
The features available in the APIs
How to install and use these features
Examples clients written by Isode, and delivered as part of the products

The following APIs are provided:

Isode X.400 Client API described here that provides client access using the X.400 P3 and P7 protocols
Isode X.400 Gateway API described here that enables building of gateways to X.400.
The Open Group X.400 API specified here that enables building gateways to X.400.
Isode Switch Operation and Management (SOM) API that provides access to the Isode M-Switch operational management features, described here.

Style of API

The Isode specified APIs use an object-oriented style, and rely on arguments which are

integers (either explicitly or as manifest constants)
strings (whose length is passed as an integer)
opaque objects (on which the API functions perform operations)

This approach facilitates support in multiple languages. The Isode APIs share common definitions where appropriate.

Programming Language Support

Support for programming languages are as follows:

'C': All APIs are provided in C. The underlying implementations are in C.
Tcl: Some of the APIs have Tcl bindings to help provides scripting interfaces and test tools.
Java: Some of the APIs have Java bindings, built using JNI over the C API.

Language support is as follows:

API	C	JAVA	TCL
X.400 Client API	X	X	X
Isode X.400 Gateway API	X	X	X
Open Group X.400 Gateway API	X
SOM API	X		X

A Java implementation of the SOM API may be provided in a future release.

API Documentation

Descriptions on overall use is provided for all APIs. The Isode 'C' and Java APIs have detailed API documentation that is auto-generated from the API implementation. The Open Group X.400 Gateway API is externally specified. Isode documents how to use this API and Isode's extensions to the standard API.

There are examples of using all of the APIs in each language (except SOM/Tcl). Because the API functionality is broadly language independent, the examples in other languages may be helpful.

Isode also makes available (for a small fee) the Java source code to XUXA the demonstration X.400 User Agent, that uses the X.400 Client API. This provides a complete application and also an example of building a higher level Java API on the base API.

The rest of this page gives some more information on the APIs, and pointers to the documentation on APIs and example code. Quick links to the Isode API detailed specifications are provided below.

X.400 Client API	'C'	Java	Java Highlevel
X.400 Gateway API	'C'	Java
SOM API	'C'

X.400 Messaging APIs

Description

The X.400 APIs allow client programs to connect to the Isode MTA. They are divided into two categories

APIs for X.400 Client API messaging user agents (UAs)
APIs for gateway applications
- AMHS Gateway API
- The Open Group X.400 Gateway API

Installation

The most straightforward starting point for the X.400 APIs is to use the Mconsole to install, initialize and configure a system to use all of the X.400 APIs.

Using the P3/P7 APIs

Having created your messaging configuration you will be able to use the P3 and P7 APIs using C, Tcl and Java language bindings.

Difference between P3 and P7

It's important to understand the difference between these two X.400 protocols. The MTA needs to be configured differently, and the applications need to be written differently. This is despite the use of the same set of functions as interfaces by the applications.

P3 and P7 client applications bind as a User Agent (to the MTA and Message Store respectively). Submission work in a similar way. However P7 is a retrieval protocol, whereas P3 is a delivery protocol.

P7 applications bind as a Message Store user to the Message Store. The P7 application can retrieve messages, which can be deleted from this user's mailbox. Only messages for the bound user can be retrieved, deleted etc. When submitting messages, the originator of the message must be the bound user.

P3 applications bind to the P3 channel of the MTA. They bind to a P3 passive channel (ie a channel which has no prog value in its configuration). The MTA creation wizard creates a p3server channel which is suitable for a P3 client.

Although the P3 client authenticates as a Message Store user (using the user's MTS password), this means that all messages which are routed for delivery to the P3 passive channel are delivered when a P3 client binds to the P3 server of the MTA. P3 clients are responsible for reliable storage of the messages. P3 clients can only unbind after an msWait() operation has returned indicating that there are no further messages for delivery by the MTA - ie all queued messages must be delivered.

Mconsole configures the MTA so that both P7 and P3 clients can retrieve/submit messages.

C Bindings

The example code is in:

Unix: /opt/isode/share/x400sdk/example/c
Windows: C:\Isode\share\x400sdk\example\c

See here for details.

Tcl Bindings

The example code is in:

Unix: /opt/isode/share/x400sdk/example/tcl
Windows: C:\Isode\share\x400sdk\example\tcl

See here for details

Java Bindings

The example code is in

Unix: /opt/isode/share/x400sdk/example/java
Windows: C:\Isode\share\x400sdk\example\java

See here for details

Using the Gateway APIs

Isode X.400 Gateway API

You need to install and configure the Isode messaging products using Mconsole in order to be able to use the Gateway APIs using C, Jave and Tcl language bindings described here.

C Bindings

The example code is in

Unix: /opt/isode/share/x400sdk/example/c
Windows: C:\Isode\share\x400sdk\example\c

See here for details.

Tcl Bindings

The example code is in

Unix: /opt/isode/share/example/xmt
Windows: C:\Isode\share\example\xmt

See here for details

Java Bindings

The example code is in

Unix: /opt/isode/share/example/java
Windows: C:\Isode\share\example\java

See here for details

Open Group Gateway API

Having created a messaging configuration for your MTA using Mconsole, you will be able to use The Open Group's X.400 Gateway API using C language bindings. For

C Bindings

The example code is in

Unix: /opt/isode/share/example
Windows: C:\Isode\share\example

See here for details.

SOM API

SOM servers available are

Switch Queue Manager
M-Store

The main components of the SOM API for M-Switch Queue Manager are:

EventViewing: an API allowing the viewing of events logged by M-Switch of its operations
Queue Viewing: an API providing access to information about the MTA's queues
Queue Manager Operations: an API allowing operations such as restarting the qmgr,or clearing delays.
Message Resubmission: an API allowing messages in quarantine or archive to be resubmitted.
Message Viewing: an API allowing messages in an M-Switch repository to be vewied. Available repositories are : the live queue; the archive; the quarantine.
X.400 P1 ping: an API which causes the x400p1 channel on the MTA to check P1 connectivity with another MTA

The main components of the SOM API for M-Store are:

Messages: an API for examining messages in M-Store
Connections: an API for examining connections in M-Store
Mailboxes: an API for examining mailboxes in M-Store

The SOM API is described at http://www.isode.com/Documentation/switch-doc/somc-api/index.html.

Using the SOM APIs

Having installed the Isode M-Switch product, you can use the SOM APIs using C and Tcl language bindings.

C Bindings

The example code is in

Unix: /opt/isode/share/soma/example/c
Windows: C:\Isode\share\soma\example\c

See here for details.

Tcl Bindings

There are no example SOM Tcl applications.