Messaging and Directory Server software used around the world in the Government, Military, Aviation and Commercial sectors.
Isode R14.3v0 X.400 Message API documentation
August 2008
Copyright © 2008 Isode Limited, London, U.K
Isode R14.3v0 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 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 folliows:
| API | C | JAVA | TCL |
| X.400 Client API | X | X | X |
| Isode X.400 Gateway API | 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'): | HTML | |
| X.400 Client Java API ('Java'): | HTML | |
| X.400 Gateway API: | HTML | |
| SOM API: | HTML |
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
Installation
The most straightforward starting point for the X.400 APIs is to use the quickconfig program. This provides a quick and easy way to install, initialize and configure a system to use all of the X.400 APIs. The Quick Start Guide includes an explanation of how to submit messages using the quickconfig GUI (which uses the X.400 API)
Using the P3/P7 APIs
Having run the quickconfig program 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). 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.
The quickconfig program 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
Having run the quickconfig program you will be able to use the Gateway APIs using C and Tcl language bindings.
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/examples/xmt
- Windows: c:\Isode\share\examples\xmt
See here for details
Open Group Gateway API
Having run the quickconfig program 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/messaging-api/somc-api/index.htm
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.