Isode Messaging APIs
Isode Messaging APIsSummary 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
- Messaging Configuration
- Configuring the Applications
- Transfer out of the Gateway (into the MTA)
- Transfer into the the Gateway (out of the MTA)
- Running the Applications
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
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.)
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:
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.
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:
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.
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.
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.
[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]#
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
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.