MS X.400 API

Isode X.400 MS Client API Overview

Version 16.3
Copyright (c) 2005-2017, Isode Limited, London, England

Introduction

This document is a specification of the Isode X.400 MS Client Library API. This API allows client programs to connect to the Isode X.400 Message Store, using the P7 protocol, or directly to the Isode X.400 MTA, using the P3 protocol. The API is suitable for building the functionality of a User Agent or an Access Unit.

A summary of this product, which sets out its general function and intended application is given in http://www.isode.com/products/x400-client-api.html

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 "program" 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 should only unbind after an X400msWait() operation has returned indicating that there are no further messages for delivery by the MTA; ie all queued messages must be delivered. If this is not done, the MTA will conclude that the p3channel has failed, and will impose a delay before the delivery of the remaining messages on the channel can be attempted.

How to Read this API

If you wish to "Jump right in" then the best thing to do is:

  1. Look at the x400_mstutorial.c example program. It is a very simple streamlined program that demonstrates the basic approach of manipulating API objects. To keep things simple this program demonstrates how to create and send a message using the P7 protocol.
  2. Look at the x400_mssend.c and x400_msrcv.c example programs. These programs give a more detailed example of how the API should be used.
  3. Other examples are also provided:
  1. Look at the reference table which matches attributes described within the standards to the objects / attributes used within the API.
  2. Have a good read of the API manual.

Standards.

It is highly recommended you are familiar with the following standards:

  • X.402
  • X.411
  • X.413
  • X.420
  • STANAG 4406 Annex A
  • ISO/IEC 10021
  • ISO/IEC 10022
  • ISO/IEC 10024
  • ISO/IEC 10025
  • ISO/IEC 10027

Language Bindings

The X.400 MS API is available in C, Tcl and Java bindings.

Relationship of MS and Pure X.400 Interfaces

Top-level message objects are built, submitted, retrieved and examined using the X400 MS Client API. In particular, functions specific to X.400 MS message objects are used to get and set attribute values within messages. For example, X400msMsgAddStrParam() would be used to set a string parameter value in such a message.

There is one specific situation where protocol-independent functions need to be used to manipulate messages: this is when dealing with forwarded messages (i.e. messages which have been included as bodyparts of "top-level" X.400 MS messages). In this case, the equivalent "pure X.400" functions must be used - X400MsgAddStrParam() in the equivalent case to the one described above.

C Bindings

The example code is in:

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

The details of the C bindings are here:

Tcl Bindings

The example code is in

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

Java Bindings

The example code is in

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

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)

Feedback

Please send any comments on the API to support@isode.com.