Isode Messaging APIs

Summary Section These examples programs show how to use X.400 C 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.

X.400 Gateway C API - Example Applications

Application Features

These examples do the following using the X.400 C API

  • x400_mtsend: Transfer X.400 messages into the Gateway from the MTA
  • x400_mtrcv: Transfer X.400 messages into the MTA from the Gateway

Full specification of the C 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:

  • ExternalMTA Application Context
  • x400mt channel Outbound Protocol
  • Routing Tree entry

causes messages in the Gateway O/R address space to be routed to the Gateway via the x400mt channel. (Note the other distinctive feature of the the x400mt channel is that it has no prog value.)

Configuring the Applications

A set of common utilities for the applications is in x400_common.c. The rest of this text describes how to configure the Session object using the set_defaults() function.

x400_common.c:void set_defaults(IFP intfunc, IFP strfunc, void* sp);

The applications call this function as follows:

set_defaults(X400msSetIntDefault,X400msSetStrDefault, (void*)sp);

You must call this after the Session object has been initialized using X400msOpen(). Note that you can use any way of configuring these value you wish - but you must set the values in the Session object after calling X400msOpen() using X400msSetIntDefault, X400msSetStrDefault).

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

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

The applications can be amended to suit the configuration you created with Mconsole. You should consider the following values and either modify the source code, or pass in command line arguments to override the default values

  • channel name
  • MTA name (optional)

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

  • The outbound protocol is MTA Gateway
  • The prog value is absent
  • The auth.qmgr table is configured to a user name with rights=channel for the channel name

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

When transferring messages into the MTA (e.g. using the x400_mtsend.c example), you need to specify the originator and recipient(s).

The originator is configured in the orig variable. The message is sent to 3 recipients:

  • recip
  • recip2
  • badrecip

Make sure that the O/R Address referred to in the orig, recip and recip2 variables exist and the MTA knows how to route a message to each of these. Use

ckadr -x "<O/R address>" 

to check the O/R address. The badrecip variable should contain the address of an unknown address so that routing fails and a non-delivery report is generated.

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 - in fact 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

Using the hard-coded values in the source

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.

Unix

submitting

  
[root@dhcp-164 c]# ./x400_mtsend
originator of msg is /CN=GatewayUser/OU=Sales/OU=dhcp-164/O=GatewayMTA/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
Adding single recip /CN=GatewayUser/OU=Sales/OU=dhcp-164/O=GatewayMTA/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
no binary file set - not sending X400_T_BINARY
Adding exempted recip /CN=exemptedrecip/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
Adding address list indicators
[root@dhcp-164 c]# ./x400_mtrcv 
Message waiting

Originator: /CN=GatewayUser/OU=Sales/OU=dhcp-164/O=GatewayMTA/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
MessageID: [/PRMD=TestPRMD/ADMD=TestADMD/C=GB/;dhcp-165.2810401]
Content Identifier: 030924.140212
Content Correlator: ABCDEFGH
Original EITs: ia5-text
Message Submission Time: 071121125704Z
Latest Delivery Time: 080218212245Z
Originator Return Address : /S=x400test-orig/OU=dhcp-165/O=GatewayMTA/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
Content type : P2
Content type : P2
Priority: 2
Disclosure of recips prohibited Yes
Implicit conversion prohibited No
 Alternate recipient allowed: Yes
 Content return request: Yes
envelope recipient 1: /CN=GatewayUser/OU=Sales/OU=dhcp-164/O=GatewayMTA/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
        Responsibility 1
        MTA report request 1
        Originator report request 0
        Originator requested AR   $ /S=x400test-orig-orar/OU=dhcp-165/O=TestOrg/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
-----------------------------------------------------------
GDI entry 1 OR Address:/PRMD=wibble/ADMD=TestADMD/C=GB/
DSI arrival time 1  :071121125704Z
DSI routing action 1  :rerouted
DSI attempted domain 1  :/PRMD=atmpdom/ADMD=TestADMD/C=GB/
DSI AA 1  :071122125704Z
DSI AA 1  :ia5-text
DSI AA redirected 1  :1
DSI AA dl operation 1  :1
GDI entry 2 OR Address:/PRMD=fluffy/ADMD=TestADMD/C=GB/
DSI arrival time 2  :071121125704Z
DSI routing action 2  :relayed
Error in do_trace_info optional component: Value for parameter is not available
Error in do_trace_info optional component: Value for parameter is not available
Error in do_trace_info optional component: Value for parameter is not available
DSI AA redirected 2  :1
DSI AA dl operation 2  :1
GDI entry 3 OR Address:/PRMD=intprmd/ADMD=TestADMD/C=GB/
DSI arrival time 3  :081121125704Z
DSI routing action 3  :relayed
Error in do_trace_info optional component: Value for parameter is not available
DSI AA 3  :081121125714Z
DSI AA 3  :ia5-text
DSI AA redirected 3  :1
DSI AA dl operation 3  :1
GDI entry 4 OR Address:/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
DSI arrival time 4  :080216212245Z
DSI routing action 4  :relayed
Error in do_trace_info optional component: Value for parameter is not available
Error in do_trace_info optional component: Value for parameter is not available
DSI AA 4  :ia5-text
DSI AA redirected 4  :1
DSI AA dl operation 4  :1
error getting Trace Info
Error fetching trace info: No error

Content:
primary recipient 1: /CN=GatewayUser/OU=Sales/OU=dhcp-164/O=GatewayMTA/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
        Reply Request true
-----------------------------------------------------------
Exempted recipient OR address 1: /CN=exemptedrecip/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
Exempted recipient DN address 1: cn=exemprecip,c=gb
Exempted recipient free form name 1: Mr Exempted
Exempted recipient Tel number 1: 0123456789
Exempted recipient OR address 2: /CN=exemp2/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
Exempted recipient DN address 2: 
IPM IDentifier: 1064400656.24922*
Subject: A Test Message
Replied-to-identifier: 1064400656.24923*
Obsoleted IPMs: 1064400656.24924*
Related IPMs: 1064400656.24925*
Expiry Time: 050924120000
Reply Time: 050924120000
Importance: 2
Sensitivity: 3
number of attachments: 1
P772 Ext Auth Info Time: 050924120000
P772 Codress value: 0
P772 Message Type: 0
P772 Primary Precedence: 5
P772 Copy Precedence: 4
P772 ALI recipient OR address 1: /CN=ALI1/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
P772 ALI recipient DN address 1: cn=ali1,c=gb
P772 ALI recipient free form name 1: Mr Address List Indicator1
P772 ALI recipient Tel number 1: 0123456789
P772 ALI Type  0
P772 ALI Notification Request  0
P772 ALI Notification Request  1
P772 ALI recipient OR address 2: /CN=ALI2/PRMD=TestPRMD/ADMD=TestADMD/C=GB/
P772 ALI recipient DN address 2: cn=ali2,c=gb
P772 ALI Type  1
Read raw content into file 
Text:
First line
Second line

X400mtMsgFinish returned success 0
No messages ...
Error in X400mtMsgGet: No error
[root@dhcp-164 c]# 
  
[root@dhcp-164 c]# 

Using command line arguments

The application accepts values for the originator, recipient and other values for message (such as message priority). The following options are supported:

x400_mtsend 
usage: uG:O:r:g:G:c:l:R:y:C:iaqsAvf:X:S:
where:
-u : Don't prompt to override defaults 
-G : Originator 
-O : Originator Return Address 
-g : Recipient
-c : X.400 passive channel
-l : Logline
-R : Reports (0 - never, 1 - always, 2 - always NDR 
-y : Priority (0 - normal, 1 - non-urgent, 2 - urgent 
-C : Content Type (2/22/772/OID) 
-i : Implicit conversion prohibited = TRUE 
-a : Alternate Recipient Prohibited = TRUE 
-q : Content Return Request = TRUE 
-s : Disclosure of Recipient = FALSE 
-A : Recipient Reassignment Prohibited = FALSE 
-v : Conversion with Loss Prohibited = FALSE 
-f : Filename to transfer as binary bp
-X : Number of messages to send
-S : Size of binary attachment (requires -f)

x400_mtrcv
usage: uo:O:r:c:l:EQ:
where:
-u : Don't prompt to override defaults 
-o : Originator 
-O : Originator Return Address 
-r : Recipient
-c : X.400 passive channel
-l : Logline
-E : Stop after one attempt to transfer a msg

Windows

To aid in submitting and receiving messages the example programs have been pre-compiled by Isode. These example programs are located within $(BINDIR) typically C:\Program Files\Isode\bin These example programs work in the same way as their unix counterparts, and are compiled from the same code.