X400 MS (P3/P7) API

Typedefs

typedef void X400msConnEstablishedCb(struct X400msSession *session, int errorcode, int alert)
 A callback which will be invoked when a P7 bind completes asynchronously, whether the completion is successful or unsuccessful. More...
 
typedef void X400msConnDroppedCb(struct X400msSession *session, int reason_code, char *diagnostic)
 A callback which will be invoked when a P7 connection is lost. More...
 
typedef void X400msMsgSubmittedCb(struct X400msSession *session, struct X400msMessage *message, int errorcode)
 A callback which will be invoked when a P7 Submission operation completes asynchronously, whether the completion is successful or unsuccessful. More...
 
typedef void X400msMsgFetchedCb(struct X400msSession *session, struct X400msMessage *message, int type, int seqno, int errorcode)
 A callback which will be invoked when a P7 Fetch operation completes asynchronously, whether the completion is successful or unsuccessful. More...
 
typedef void X400msMsgDeletedCb(struct X400msSession *session, int seqno, int errorcode)
 A callback which will be invoked when a P7 Delete operation completes asynchronously, whether the completion is successful or unsuccessful. More...
 
typedef void X400msMsgWaitingCb(struct X400msSession *session, int num_messages_waiting, int errorcode)
 A callback which will be invoked when a P7 Summarize operation (invoked via X400msWait) completes asynchronously, whether the completion is successful or unsuccessful. More...
 
typedef void X400msListCb(struct X400msSession *session, struct X400msListResult *lrp, int errorcode)
 A callback which will be invoked when a P7 List operation completes asynchronously, whether the completion is successful or unsuccessful. More...
 
typedef void X400msRegisterCb(struct X400msSession *session, int errorcode)
 A callback which will be invoked when a P7 Register operation completes asynchronously, whether the completion is successful or unsuccessful. More...
 
typedef void X400msAlertCb(struct X400msSession *session)
 A callback which will be invoked when a P7 Alert invoke is received. More...
 
typedef int X400msManageCb(struct X400msSession *session, int fd, int event_mask)
 A callback which will be invoked when a particular file descriptor either needs to be monitored for a given set of event types, or no longer needs to be monitored for the specified event types. More...
 

Functions

const char * X400msError (int error)
 Obtain a string describing the meaning of the given error code. More...
 
int X400msOpenAsync (int type, const char *oraddr, const char *dirname, const char *credentials, const char *pa, const char *ret_psw, X400msConnEstablishedCb *conupcb, X400msConnDroppedCb *condowncb, X400msMsgSubmittedCb *msgsubcb, X400msMsgFetchedCb *msgfetchcb, X400msMsgDeletedCb *msgdelcb, X400msMsgWaitingCb *msgwaitcb, X400msListCb *listcb, X400msRegisterCb *registercb, X400msAlertCb *alertcb, X400msManageCb *managecb, X400msManageCb *unmanagecb, struct X400msSession **spp)
 Initiate an asynchronous opening of a session to a Message Store (P7) More...
 
int X400msOpenAsyncSession (struct X400msSession *sp, const char *addr, const char *dn, const char *credentials, const char *pa, const char *ret_psw, X400msConnEstablishedCb *conupcb, X400msConnDroppedCb *condowncb, X400msMsgSubmittedCb *msgsubcb, X400msMsgFetchedCb *msgfetchcb, X400msMsgDeletedCb *msgdelcb, X400msMsgWaitingCb *msgwaitcb, X400msListCb *listcb, X400msRegisterCb *registercb, X400msAlertCb *alertcb, X400msManageCb *managecb, X400msManageCb *unmanagecb)
 Initiate an asynchronous opening of a session to a Message Store (P7) using an existing session object. More...
 
struct X400msSession * X400msNewAsyncSession (int type)
 Create a new X400msSession object of the specified type. More...
 
int X400msGetHandle (struct X400msSession *session)
 Get a handle suitable for use in a call to select() More...
 
void X400msSetUserPointer (struct X400msSession *session, void *ptr)
 Set a user pointer value in a session object. More...
 
void * X400msGetUserPointer (struct X400msSession *session)
 Get a user pointer value from a session object. More...
 
int X400msGetGeneric (struct X400msMessage *mp, struct X400Message **genp)
 Generate an X400Message from an X400msMessage. More...
 
int X400msOpen (int type, const char *oraddr, const char *dirname, const char *credentials, const char *pa, int *messages, struct X400msSession **spp)
 Open a session to a Message Store (P7) or MTA (P3) in synchronous mode. More...
 
int X400msOpenCheck (int type, const char *oraddr, const char *dirname, const char *credentials, const char *pa, const char *ret_psw, int *messages, struct X400msSession **spp)
 Open a session to a Message Store (P7) or MTA (P3) in synchronous mode, checking the password which the Message Store or MTA returns. More...
 
void X400msSetConfigRequest (int val)
 Disable and enable configuration requests in MS Bind operations. More...
 
void X400msCancelWait (void)
 Signal any threads waiting in X400msWait() function calls to return. More...
 
void X400msEnableWait (void)
 Enable X400msWait() function to work normally again. More...
 
void X400msCancelWaitSession (struct X400msSession *sp)
 Signal the thread waiting in an X400msWait() function call for the specified MS Session to return. More...
 
void X400msEnableWaitSession (struct X400msSession *sp)
 Enable X400msWait() function to work normally again for an individual session. More...
 
int X400msClose (struct X400msSession *sp)
 Close a X400 Session. More...
 
int X400msList (struct X400msSession *sp, char *since_time, struct X400msListResult **lrp)
 List messages in the P7 Message Store. More...
 
int X400msListEx (struct X400msSession *sp, char *since_time, int entryclass, struct X400msListResult **lrp)
 List messages in the P7 Message Store, specifying entryclass. More...
 
int X400msListExAux (struct X400msSession *sp, char *since_time, int entryclass, int entrystatus, struct X400msListResult **lrp)
 List messages in the P7 Message Store, specifying entryclass and entrystatus. More...
 
int X400msListExAuxPri (struct X400msSession *sp, char *since_time, int entryclass, int entrystatus, int priority, struct X400msListResult **lrp)
 List messages in the P7 Message Store, specifying entryclass entrystatus and priority. More...
 
int X400msListExAuxPriBefore (struct X400msSession *sp, char *since_time, char *before_time, int entryclass, int entrystatus, int priority, struct X400msListResult **lrp)
 List messages in the P7 Message Store, specifying entryclass, entrystatus and priority, with before time. More...
 
int X400msListGetIntParam (struct X400msListResult *lr, int paramtype, int number, int *valp)
 Get an integer attribute value from an element of a ListResult. More...
 
int X400msListGetStrParam (struct X400msListResult *lr, int paramtype, int number, char *buffer, size_t buflen, size_t *paramlenp)
 Get a string attribute value from an element of a ListResult. More...
 
void X400msListFree (struct X400msListResult *lr)
 Free the memory occupied by a ListResult. More...
 
int X400msMsgNew (struct X400msSession *sp, int type, struct X400msMessage **mpp)
 Creates new message. More...
 
int X400msMsgCountRecip (struct X400msMessage *mp, int type, int *cp)
 Returns count of addresses of given type in message object. More...
 
int X400msMsgSend (struct X400msMessage *mp)
 Send message object. More...
 
int X400msMsgDelete (struct X400msMessage *mp, int retain)
 Delete message object. More...
 
int X400msMsgAddStrParam (struct X400msMessage *mp, int paramtype, const char *value, size_t length)
 Add string-valued parameter to the message. More...
 
int X400msMsgAddIntParam (struct X400msMessage *mp, int paramtype, int value)
 Add integer-valued parameter to the message. More...
 
int X400msMsgAddAttachment (struct X400msMessage *mp, int type, const char *string, size_t length)
 Add attachment to the message. More...
 
int X400msMsgAddBodypart (struct X400msMessage *mp, struct X400Bodypart *bp)
 
int X400msMsgAddMessageBodyWType (struct X400msMessage *mp, struct X400Message *mbp, int type)
 Add a message body part object to a message. More...
 
int X400msMsgAddMessageBody (struct X400msMessage *mp, struct X400Message *mbp)
 
int X400msRecipNew (struct X400msMessage *mp, int type, struct X400Recipient **rpp)
 Add new recipient to a message. More...
 
int X400msRecipAddStrParam (struct X400Recipient *rp, int paramtype, const char *value, size_t length)
 Add string-valued parameter to the message. More...
 
int X400msRecipAddIntParam (struct X400Recipient *rp, int paramtype, int value)
 Add integer-valued parameter to the message. More...
 
int X400msWait (struct X400msSession *sp, int seconds, int *count)
 Wait for messages to be ready to be read. More...
 
int X400msWaitNew (struct X400msSession *sp, int seconds, int *count)
 Wait for new messages to be ready to be read. More...
 
int X400msMsgGet (struct X400msSession *sp, int number, struct X400msMessage **mpp, int *typep, int *seqp)
 Get message object for transfer out from MS or MTA via P3. More...
 
int X400msMsgGetEx (struct X400msSession *sp, int number, int entryclass, struct X400msMessage **mpp, int *typep, int *seqp)
 Get message object for transfer out from MS or MTA via P3. More...
 
int X400msMsgGetStart (struct X400msSession *sp, int number, struct X400msMessage **mpp, int *typep, int *seqp)
 Get message object for transfer out from MS or MTA via P3. More...
 
int X400msMsgGetStartEx (struct X400msSession *sp, int number, int entryclass, struct X400msMessage **mpp, int *typep, int *seqp)
 Get message object for transfer out from MS or MTA via P3. More...
 
int X400msMsgGetFinish (struct X400msMessage *mp, int errnum, int problem)
 Generate delivery result or error for a message. More...
 
int X400msMsgGetStrParam (struct X400msMessage *mp, int paramtype, char *buffer, size_t buflen, size_t *paramlenp)
 Return a string-valued parameter from the message object. More...
 
int X400msMsgGetIntParam (struct X400msMessage *mp, int paramtype, int *valp)
 Return a integer-valued parameter from the message object. More...
 
int X400msMsgGetAttachment (struct X400msMessage *mp, int number, int *typep, char *buffer, size_t buflen, size_t *lengthp)
 Return the data of an attachment (=bodypart) from the message object. More...
 
int X400msMsgGetBodypart (struct X400msMessage *mp, int number, int *typep, struct X400Bodypart **bpp)
 Return a pointer to a body part object. More...
 
int X400msMsgGetMessageBody (struct X400msMessage *mp, int number, struct X400Message **mpp)
 Return a pointer to a message part object. More...
 
int X400msMsgGetCert (struct X400msMessage *mp, int certtype, struct X400Certificate **certp)
 Get certificate object from message This returns a certificate which was used to sign an object in the message. The attribute type indicates which object type. More...
 
int X400msMakeIPN (struct X400msMessage *mp, int non_receipt_reason, struct X400msMessage **mpp)
 Make an IPN based on the subject IPM. More...
 
int X400msRecipGet (struct X400msMessage *mp, int type, int number, struct X400Recipient **rpp)
 Get recipient object from message. More...
 
int X400msRecipGetStrParam (struct X400Recipient *rp, int paramtype, char *buffer, size_t buflen, size_t *paramlenp)
 Return a string-valued parameter from the recipient object. More...
 
int X400msRecipGetIntParam (struct X400Recipient *rp, int paramtype, int *valp)
 Return a integer-valued parameter from the recipient object. More...
 
int X400msSetIntDefault (struct X400msSession *sp, int paramtype, int value)
 Set a default integer parameter value in a session. More...
 
int X400msSetStrDefault (struct X400msSession *sp, int paramtype, const char *value, size_t length)
 Set a default string parameter value in a session. More...
 
int X400msTestSecurityEnv (struct X400msSession *sp)
 Test the default Security Environment. More...
 
int X400msRegisterAutoAction (struct X400msSession *sp, int type, int id, struct X400msAutoActionParameter *aa_param)
 Register an autoaction with the Message Store. More...
 
int X400msDeregisterAutoAction (struct X400msSession *sp, int type, int id)
 Deregister an autoaction from the Message Store. More...
 
struct X400msAutoActionParameter * X400msNewAutoActionParameter (void)
 Create a new (empty) autoaction parameter structure. More...
 
void X400msFreeAutoActionParameter (struct X400msAutoActionParameter *aa_param)
 Free an autoaction parameter. More...
 
int X400msAutoActionParameterAddRecip (struct X400msAutoActionParameter *aap, int reciptype, struct X400Recipient *recip)
 Add a receipient to the autoaction parameter. More...
 
int X400msAutoActionParameterAddIntParam (struct X400msAutoActionParameter *aap, int paramtype, int value)
 Add integer-valued parameter to the autoaction parameter. More...
 
int X400msAutoActionParameterAddStrParam (struct X400msAutoActionParameter *aap, int paramtype, const char *value, size_t length)
 Add string-valued parameter to the autoaction parameter. More...
 
int X400msCheckConnection (struct X400msSession *sp)
 Check that a connection is still active. More...
 
int X400msDLExpHistGet (struct X400msMessage *mp, int entry, struct X400DLExpHist **hist)
 Create a new DL Expansion History object from the message object. More...
 
int X400msDLExpHistNew (struct X400msMessage *mp, struct X400DLExpHist **histp)
 Create a new DL Expansion History object, and associate it with the existing message. More...
 
int X400msALINew (struct X400msMessage *mp, struct X400ALI **ali)
 Create a new Address List Indicator Object, and associate it with the existing message. More...
 
int X400msALIGet (struct X400msMessage *mp, int entry, struct X400ALI **info)
 Get a Address List Indicator Object for a message object. More...
 
int X400msPSSNew (struct X400msMessage *mp, struct X400PSS **pss, int type)
 Create a new Printable String Syntax Object, and associate it with the existing message. More...
 
int X400msPSSGet (struct X400msMessage *mp, int type, int entry, struct X400PSS **pss)
 Get a Printable String Syntax Object for a message object. More...
 
int X400msDistFieldNew (struct X400msMessage *mp, struct X400DistField **pss)
 Create a new P772 Distribution Field object for a message object. More...
 
int X400msDistFieldGet (struct X400msMessage *mp, int entry, struct X400DistField **pss)
 Get a new P772 Distribution Field object for a message object. More...
 
int X400msOtherRecipNew (struct X400msMessage *mp, struct X400OtherRecip **otherrecip)
 Create a new P772 Other Recipient object for a message object. More...
 
int X400msOtherRecipGet (struct X400msMessage *mp, int entry, struct X400OtherRecip **otherrecip)
 Get a new P772 Other Recipient object for a message object. More...
 
int X400msRediHistGetEnv (struct X400msMessage *msg, int entry, struct X400RediHist **hist)
 Get the Redirection History object from a message envelope this is represented by 8.3.1.2.1.5 in X.411. More...
 
int X400msTraceInfoGet (struct X400msMessage *mp, int entry, struct X400TraceInfo **info, int type)
 Get a Trace Info object for a message object. More...
 
int X400msInternalTraceInfoGet (struct X400msMessage *mp, int entry, struct X400InternalTraceInfo **info)
 Get an Internal Trace Info object for a message object. More...
 
int X400msORandDLGet (struct X400msMessage *msg, int entry, struct X400ORandDL **or_and_dl)
 Get Originator and DL expansion history object. More...
 
int X400msGetContentOctets (struct X400msMessage *mp, char *buf, size_t buflen, size_t *lenp)
 Obtains the bytes containing the ASN.1 encoding of the Content of a message. The Content is obtained by building an IPM from the attributes of the message and then encoding it. More...
 
int X400msSetContentOctets (struct X400msMessage *mp, char *buf, size_t len)
 Takes a byte stream containing the ASN.1 encoding of a P22 (or P772) content, decodes it and sets it into a message, so that attributes can be extracted from it. More...
 
int X400msACP127RespGet (struct X400msMessage *mp, struct X400ACP127Resp **respp)
 Get the ACP127 Notification Response object from a message. More...
 
int X400msACP127RespNew (struct X400msMessage *mp, struct X400ACP127Resp **respp)
 Create an ACP127 Notification Response object. More...
 
struct X400ACP127Resp * X400msACP127RespDeepCopy (struct X400msMessage *mp, struct X400ACP127Resp *orig)
 Copy an ACP127 Notification Response object. More...
 
int X400msMsgGetRaw (struct X400msSession *sp, struct X400msMessage *mp, char *buffer, size_t buflen, size_t *buflenp)
 Get a binary representation of a message which can be subsequently be used to reconstruct the message. More...
 
int X400msMsgFromRaw (struct X400msSession *sp, char *buffer, size_t buflen, struct X400msMessage **mpp, int *typep)
 Reconstruct a message from a binary representation. More...
 

Detailed Description

The function calls which make up the P3 or P7 (X.400 UA) interface.

Typedef Documentation

◆ X400msConnEstablishedCb

typedef void X400msConnEstablishedCb(struct X400msSession *session, int errorcode, int alert)

A callback which will be invoked when a P7 bind completes asynchronously, whether the completion is successful or unsuccessful.

Parameters
session[in] Session to which callback applies
errorcode[in] Indicates success or failure of connection attempt
alert[in] Set for alert indication

Definition at line 371 of file x400_msapi.h.

◆ X400msConnDroppedCb

typedef void X400msConnDroppedCb(struct X400msSession *session, int reason_code, char *diagnostic)

A callback which will be invoked when a P7 connection is lost.

Parameters
session[in] Session to which callback applies
reason_code[in] Reason for connection loss
diagnostic[in] Diagnostic text

Definition at line 381 of file x400_msapi.h.

◆ X400msMsgSubmittedCb

typedef void X400msMsgSubmittedCb(struct X400msSession *session, struct X400msMessage *message, int errorcode)

A callback which will be invoked when a P7 Submission operation completes asynchronously, whether the completion is successful or unsuccessful.

Parameters
session[in] Session to which callback applies
message[in] On success, gives message submission result attributes
errorcode[in] Indicates success or failure of submission

Definition at line 393 of file x400_msapi.h.

◆ X400msMsgFetchedCb

typedef void X400msMsgFetchedCb(struct X400msSession *session, struct X400msMessage *message, int type, int seqno, int errorcode)

A callback which will be invoked when a P7 Fetch operation completes asynchronously, whether the completion is successful or unsuccessful.

Parameters
session[in] Session to which callback applies
message[in] On success, message which has been fetched
type[in] On success, message type
seqno[in] On success, message sequence number
errorcode[in] Indicates success or failure of fetch operation

Definition at line 407 of file x400_msapi.h.

◆ X400msMsgDeletedCb

typedef void X400msMsgDeletedCb(struct X400msSession *session, int seqno, int errorcode)

A callback which will be invoked when a P7 Delete operation completes asynchronously, whether the completion is successful or unsuccessful.

Parameters
session[in] Session to which callback applies
seqno[in] Sequence number of deleted message
errorcode[in] Indicates success or failure of delete operation

Definition at line 421 of file x400_msapi.h.

◆ X400msMsgWaitingCb

typedef void X400msMsgWaitingCb(struct X400msSession *session, int num_messages_waiting, int errorcode)

A callback which will be invoked when a P7 Summarize operation (invoked via X400msWait) completes asynchronously, whether the completion is successful or unsuccessful.

Parameters
session[in] Session to which callback applies
num_messages_waiting[in] Number of messages waiting
errorcode[in] Indicates success or failure of summarize operation

Definition at line 433 of file x400_msapi.h.

◆ X400msListCb

typedef void X400msListCb(struct X400msSession *session, struct X400msListResult *lrp, int errorcode)

A callback which will be invoked when a P7 List operation completes asynchronously, whether the completion is successful or unsuccessful.

Parameters
session[in] Session to which callback applies
lrp[in] List result pointer on success
errorcode[in] Indicates success or failure of list operation

Definition at line 445 of file x400_msapi.h.

◆ X400msRegisterCb

typedef void X400msRegisterCb(struct X400msSession *session, int errorcode)

A callback which will be invoked when a P7 Register operation completes asynchronously, whether the completion is successful or unsuccessful.

Parameters
session[in] Session to which callback applies
errorcode[in] Indicates success or failure of register operation

Definition at line 456 of file x400_msapi.h.

◆ X400msAlertCb

typedef void X400msAlertCb(struct X400msSession *session)

A callback which will be invoked when a P7 Alert invoke is received.

Parameters
session[in] Session to which callback applies

Definition at line 464 of file x400_msapi.h.

◆ X400msManageCb

typedef int X400msManageCb(struct X400msSession *session, int fd, int event_mask)

A callback which will be invoked when a particular file descriptor either needs to be monitored for a given set of event types, or no longer needs to be monitored for the specified event types.

Parameters
session[in] Session to which callback applies
fd[in] File descriptor to which the callback applies
event_mask[in] The set of events which need to be managed or can now be ignored.

Definition at line 475 of file x400_msapi.h.

Function Documentation

◆ X400msError()

const char* X400msError ( int  error)

Obtain a string describing the meaning of the given error code.

Parameters
error[in] error code
Returns
Pointer to NUL terminated string for error
Examples:
examples/x400_mslist.c, examples/x400_msraa.c, examples/x400_msrcv.c, examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, examples/x400_mssend_sign.c, and x400_msasync.c.

◆ X400msOpenAsync()

int X400msOpenAsync ( int  type,
const char *  oraddr,
const char *  dirname,
const char *  credentials,
const char *  pa,
const char *  ret_psw,
X400msConnEstablishedCb conupcb,
X400msConnDroppedCb condowncb,
X400msMsgSubmittedCb msgsubcb,
X400msMsgFetchedCb msgfetchcb,
X400msMsgDeletedCb msgdelcb,
X400msMsgWaitingCb msgwaitcb,
X400msListCb listcb,
X400msRegisterCb registercb,
X400msAlertCb alertcb,
X400msManageCb managecb,
X400msManageCb unmanagecb,
struct X400msSession **  spp 
)

Initiate an asynchronous opening of a session to a Message Store (P7)

Parameters
type[in] Connection type: X400_TYPE_MS, X400_TYPE_MTA_SUBMIT or X400_TYPE_MTA_BOTH
oraddr[in] String encoding of OR-Address to use when binding
dirname[in] String encoding of Directory name to use when binding
credentials[in] String giving the credentials for the session
pa[in] String encoding (as per RFC1278) of MS or MTA Presentation Address to contact. A Calling Presentation Address may be appended with a semicolon separator, allowing Calling Selectors to be specified. When this is done, a Network Address of "0.0.0.0" should be specified, unless an attempt to use a specific local interface is required.
ret_psw[in] String giving the expected password from the MS or MTA
conupcb[in] Function to be called when connection is open
condowncb[in] Function to be called when connection is lost
msgsubcb[in] Function to be called when submission completes
msgfetchcb[in] Function to be called when fetch completes
msgdelcb[in] Function to be called when delete completes
msgwaitcb[in] Function to be called when wait completes
listcb[in] Function to be called when list completes
registercb[in] Function to be called when register completes
alertcb[in] Function to be called when alert occurs
managecb[in] Function to be called when an event type needs to be handled
unmanagecb[in] Function to be called when an event type does not need to be handled
spp[out] Pointer to receive pointer to opaque session data
Returns
zero on success or non-zero error code

Both the credentials and ret_psw strings are passwords, for simple authentication. The ret_psw value (if non-NULL) specifies the password we expect to get back from the MS or MTA to which we are binding. The API will perform a check that the returned password matches the expected value and will return an error if they do not match.

The function will return X400_E_WAIT_WRITE, indicating that the client application need to wait for the file descriptor associated with the X400msSession object to become writeable. At this point, X400msProcessEvent needs to be called to handle the 'write' event (which actually indicates that the network-level connection has been established). X400msProcessEvent will then return X400_E_WAIT_READ, to indicate that the application needs to wait for the file descriptor to become readable before calling X400msProcessEvent again. The application will need to call X400msProcessEvent multiple times before the association becomes open - at this point the "X400msConnEstablishedCb" callback will be invoked.

Examples:
x400_msasync.c.

◆ X400msOpenAsyncSession()

int X400msOpenAsyncSession ( struct X400msSession *  sp,
const char *  addr,
const char *  dn,
const char *  credentials,
const char *  pa,
const char *  ret_psw,
X400msConnEstablishedCb conupcb,
X400msConnDroppedCb condowncb,
X400msMsgSubmittedCb msgsubcb,
X400msMsgFetchedCb msgfetchcb,
X400msMsgDeletedCb msgdelcb,
X400msMsgWaitingCb msgwaitcb,
X400msListCb listcb,
X400msRegisterCb registercb,
X400msAlertCb alertcb,
X400msManageCb managecb,
X400msManageCb unmanagecb 
)

Initiate an asynchronous opening of a session to a Message Store (P7) using an existing session object.

Parameters
sp[in] Session to connect
addr[in] String encoding of OR-Address to use when binding
dn[in] String encoding of Directory name to use when binding
credentials[in] String giving the credentials for the session
pa[in] String encoding (as per RFC1278) of MS or MTA Presentation Address to contact. A Calling Presentation Address may be appended with a semicolon separator, allowing Calling Selectors to be specified. When this is done, a Network Address of "0.0.0.0" should be specified, unless an attempt to use a specific local interface is required.
ret_psw[in] String giving the expected password from the MS or MTA
conupcb[in] Function to be called when connection is open
condowncb[in] Function to be called when connection is lost
msgsubcb[in] Function to be called when submission completes
msgfetchcb[in] Function to be called when fetch completes
msgdelcb[in] Function to be called when delete completes
msgwaitcb[in] Function to be called when wait completes
listcb[in] Function to be called when list completes
registercb[in] Function to be called when register completes
alertcb[in] Function to be called when alert occurs
managecb[in] Function to be called when an event type needs to be handled
unmanagecb[in] Function to be called when an event type does not need to be handled
Returns
zero on success or non-zero error code

Both the credentials and ret_psw strings are passwords, for simple authentication. The ret_psw value (if non-NULL) specifies the password we expect to get back from the MS or MTA to which we are binding. The API will perform a check that the returned password matches the expected value and will return an error if they do not match.

The function will return X400_E_WAIT_WRITE, indicating that the client application need to wait for the file descriptor associated with the X400msSession object to become writeable. At this point, X400msProcessEvent needs to be called to handle the 'write' event (which actually indicates that the network-level connection has been established). X400msProcessEvent will then return X400_E_WAIT_READ, to indicate that the application needs to wait for the file descriptor to become readable before calling X400msProcessEvent again. The application will need to call X400msProcessEvent multiple times before the association becomes open - at this point the "X400msConnEstablishedCb" callback will be invoked.

◆ X400msNewAsyncSession()

struct X400msSession* X400msNewAsyncSession ( int  type)

Create a new X400msSession object of the specified type.

Parameters
type[in] Connection type: X400_TYPE_MS, X400_TYPE_MTA_SUBMIT or X400_TYPE_MTA_BOTH
Returns
Valid session pointer on success or NULL on error

◆ X400msGetHandle()

int X400msGetHandle ( struct X400msSession *  session)

Get a handle suitable for use in a call to select()

Parameters
session[in] Session to get handle for
Returns
Valid fd on success or -1 on error
Examples:
x400_msasync.c.

◆ X400msSetUserPointer()

void X400msSetUserPointer ( struct X400msSession *  session,
void *  ptr 
)

Set a user pointer value in a session object.

Parameters
session[in] Session to set pointer in
ptr[in] Pointer value to set
Returns
None

◆ X400msGetUserPointer()

void* X400msGetUserPointer ( struct X400msSession *  session)

Get a user pointer value from a session object.

Parameters
session[in] Session to get pointer from
Returns
Pointer value

◆ X400msGetGeneric()

int X400msGetGeneric ( struct X400msMessage *  mp,
struct X400Message **  genp 
)

Generate an X400Message from an X400msMessage.

Parameters
mp[in] X400msMessage source object
genp[out] pointer to X400Message object to get new message object generated from input object
Returns
zero on success or non-zero error code

◆ X400msOpen()

int X400msOpen ( int  type,
const char *  oraddr,
const char *  dirname,
const char *  credentials,
const char *  pa,
int *  messages,
struct X400msSession **  spp 
)

Open a session to a Message Store (P7) or MTA (P3) in synchronous mode.

Parameters
type[in] Connection type: X400_TYPE_MS, X400_TYPE_MTA_SUBMIT or X400_TYPE_MTA_BOTH
oraddr[in] String encoding of OR-Address to use when binding
dirname[in] String encoding of Directory name to use when binding
credentials[in] String giving the credentials for the session
pa[in] String encoding (as per RFC1278) of MS or MTA Presentation Address to contact. A Calling Presentation Address may be appended with a semicolon separator, allowing Calling Selectors to be specified. When this is done, a Network Address of "0.0.0.0" should be specified, unless an attempt to use a specific local interface is required.
messages[out] Pointer to integer to get number of messages, or NULL if the result of the Summarize is not required
spp[out] Pointer to receive pointer to opaque session data
Returns
zero on success or non-zero error code

The credentials string is a password, for simple authentication.

Bear in mind that if you are binding only to submit a message, and don't need to know how many messages there are in the inbox, it's better to pass NULL to the messages paremeter, as that will prevent an expensive SUMMARIZE operation.

Examples:
examples/x400_mslist.c, examples/x400_msraa.c, examples/x400_msrcv.c, examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, and examples/x400_mssend_sign.c.

◆ X400msOpenCheck()

int X400msOpenCheck ( int  type,
const char *  oraddr,
const char *  dirname,
const char *  credentials,
const char *  pa,
const char *  ret_psw,
int *  messages,
struct X400msSession **  spp 
)

Open a session to a Message Store (P7) or MTA (P3) in synchronous mode, checking the password which the Message Store or MTA returns.

Parameters
type[in] Connection type: X400_TYPE_MS, X400_TYPE_MTA_SUBMIT or X400_TYPE_MTA_BOTH
oraddr[in] String encoding of OR-Address to use when binding
dirname[in] String encoding of Directory name to use when binding
credentials[in] String giving the credentials for the session
pa[in] String encoding (as per RFC1278) of MS or MTA Presentation Address to contact. A Calling Presentation Address may be appended with a semicolon separator, allowing Calling Selectors to be specified. When this is done, a Network Address of "0.0.0.0" should be specified, unless an attempt to use a specific local interface is required.
ret_psw[in] String for the expected password from the MS or MTA
messages[out] Pointer to integer to get number of messages, or NULL if the result of the Summarize is not required
spp[out] Pointer to receive pointer to opaque session data
Returns
zero on success or non-zero error code

The Directory Name parameter is optional, specify it as NULL to omit.

Both the credentials and ret_psw strings are passwords, for simple authentication. The ret_psw value (if non-NULL) specifies the password we expect to get back from the MS or MTA to which we are binding. The API will perform a check that the returned password matches the expected value and will return an error if they do not match.

Bear in mind that if you are binding only to submit a message, and don't need to know how many messages there are in the inbox, it's better to pass NULL to the messages paremeter, as that will prevent an expensive SUMMARIZE operation.

◆ X400msSetConfigRequest()

void X400msSetConfigRequest ( int  val)

Disable and enable configuration requests in MS Bind operations.

Parameters
val[in] Boolean to turn on or off configuration requests
Returns
None

Disables and enables configuration requests in MS Bind operations. Default setting is TRUE.

Examples:
examples/x400_mslist.c, examples/x400_msrcv.c, examples/x400_mssend.c, and x400_msasync.c.

◆ X400msCancelWait()

void X400msCancelWait ( void  )

Signal any threads waiting in X400msWait() function calls to return.

Returns
None

Signal any threads waiting in X400msWait() function calls to return immediately (with an error code of X400_E_NOMESSAGE).

◆ X400msEnableWait()

void X400msEnableWait ( void  )

Enable X400msWait() function to work normally again.

Returns
None

This function can be used to allow X400msWait() to work normally again after X400msCancelWait has been used.

◆ X400msCancelWaitSession()

void X400msCancelWaitSession ( struct X400msSession *  sp)

Signal the thread waiting in an X400msWait() function call for the specified MS Session to return.

Parameters
sp[in] Pointer to session data
Returns
None

Signal the thread waiting in an X400msWait() function call for the indicated MS Session to return immediately (with an error code of X400_E_NOMESSAGE).

◆ X400msEnableWaitSession()

void X400msEnableWaitSession ( struct X400msSession *  sp)

Enable X400msWait() function to work normally again for an individual session.

Parameters
sp[in] Pointer to session data
Returns
None

This function can be used to allow X400msWait() to work normally again after X400msCancelWait has been used. It applies only to the supplied MS Session

◆ X400msClose()

int X400msClose ( struct X400msSession *  sp)

Close a X400 Session.

Parameters
sp[in] Pointer to session data
Returns
Zero on success or non-zero error code

Closes a session and deletes all resources associated with the session.

Examples:
examples/x400_mslist.c, examples/x400_msraa.c, examples/x400_msrcv.c, examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, examples/x400_mssend_sign.c, and x400_msasync.c.

◆ X400msList()

int X400msList ( struct X400msSession *  sp,
char *  since_time,
struct X400msListResult **  lrp 
)

List messages in the P7 Message Store.

Parameters
sp[in] Pointer to session data
since_time[in] Optional UTC time string
lrp[out] Pointer to receive pointer to opaque list result
Returns
zero on success or non-zero error code

The "since" parameter is optional, specify it as NULL to omit. If specified, it should be a UTC time string, and is used to select only messages which were delivered after that time & date.

Examples:
x400_msasync.c.

◆ X400msListEx()

int X400msListEx ( struct X400msSession *  sp,
char *  since_time,
int  entryclass,
struct X400msListResult **  lrp 
)

List messages in the P7 Message Store, specifying entryclass.

Parameters
sp[in] Pointer to session data
since_time[in] Optional UTC time string
entryclass[in] Entry class to list within
lrp[out] Pointer to receive pointer to opaque list result
Returns
zero on success or non-zero error code

The "since" parameter is optional, specify it as NULL to omit. If specified, it should be a UTC time string, and is used to select only messages which were delivered after that time & date.

◆ X400msListExAux()

int X400msListExAux ( struct X400msSession *  sp,
char *  since_time,
int  entryclass,
int  entrystatus,
struct X400msListResult **  lrp 
)

List messages in the P7 Message Store, specifying entryclass and entrystatus.

Parameters
sp[in] Pointer to session data
since_time[in] Optional UTC time string
entryclass[in] Entry class to list within
entrystatus[in] Entry status of messages to list
lrp[out] Pointer to receive pointer to opaque list result
Returns
zero on success or non-zero error code

The "since" parameter is optional, specify it as NULL to omit. If specified, it should be a UTC time string, and is used to select only messages which were delivered after that time & date.

◆ X400msListExAuxPri()

int X400msListExAuxPri ( struct X400msSession *  sp,
char *  since_time,
int  entryclass,
int  entrystatus,
int  priority,
struct X400msListResult **  lrp 
)

List messages in the P7 Message Store, specifying entryclass entrystatus and priority.

Parameters
sp[in] Pointer to session data
since_time[in] Optional UTC time string
entryclass[in] Entry class to list within
entrystatus[in] Entry status of messages to list
priority[in] Priority value of messages to list
lrp[out] Pointer to receive pointer to opaque list result
Returns
zero on success or non-zero error code

The "since" parameter is optional, specify it as NULL to omit. If specified, it should be a UTC time string, and is used to select only messages which were delivered after that time & date.

◆ X400msListExAuxPriBefore()

int X400msListExAuxPriBefore ( struct X400msSession *  sp,
char *  since_time,
char *  before_time,
int  entryclass,
int  entrystatus,
int  priority,
struct X400msListResult **  lrp 
)

List messages in the P7 Message Store, specifying entryclass, entrystatus and priority, with before time.

Parameters
sp[in] Pointer to session data
since_time[in] Optional UTC time string to select messages created after this time
before_time[in] Optional UTC time string to select messages created before this time
entryclass[in] Entry class to list within
entrystatus[in] Entry status of messages to list
priority[in] Priority value of messages to list
lrp[out] Pointer to receive pointer to opaque list result
Returns
zero on success or non-zero error code

The "since" and "before" parameters are optional (specify as NULL to omit). If specified, they should be a UTC time string (e.g 130520101535Z).

Examples:
examples/x400_mslist.c.

◆ X400msListGetIntParam()

int X400msListGetIntParam ( struct X400msListResult *  lr,
int  paramtype,
int  number,
int *  valp 
)

Get an integer attribute value from an element of a ListResult.

Parameters
lr[in] List result to access
paramtype[in] Type of parameter to get
number[in] Index of element in ListResult to access
valp[out] Pointer to receive attribute value
Returns
zero on success or non-zero error code

Retrieve an integer parameter value from an element of a ListResult. Index starts at 1 for the first element of the ListResult. The error code X400_E_NO_MORE_RESULTS is returned when the specified element does not exist. Error code X400_E_NO_VALUES is returned when a particular parameter type is not present in the element.

Examples:
examples/x400_mslist.c, and x400_msasync.c.

◆ X400msListGetStrParam()

int X400msListGetStrParam ( struct X400msListResult *  lr,
int  paramtype,
int  number,
char *  buffer,
size_t  buflen,
size_t *  paramlenp 
)

Get a string attribute value from an element of a ListResult.

Parameters
lr[in] List result to access
paramtype[in] Type of parameter to get
number[in] Index of element in ListResult to access
buffer[out] Buffer receive attribute value
buflen[in] Length of buffer
paramlenp[out] Pointer to receive length of value
Returns
zero on success or non-zero error code

Retrieve an string parameter value from an element of a ListResult. Index starts at 1 for the first element of the ListResult. The error code X400_E_NO_MORE_RESULTS is returned when the specified element does not exist. Error code X400_E_NO_VALUES is returned when a particular parameter type is not present in the element.

Examples:
examples/x400_mslist.c, and x400_msasync.c.

◆ X400msListFree()

void X400msListFree ( struct X400msListResult *  lr)

Free the memory occupied by a ListResult.

Parameters
lr[in] List result to free
Returns
none

Free the memory occupied by the given ListResult.

Examples:
examples/x400_mslist.c, and x400_msasync.c.

◆ X400msMsgNew()

int X400msMsgNew ( struct X400msSession *  sp,
int  type,
struct X400msMessage **  mpp 
)

Creates new message.

Parameters
sp[in] X400 session pointer
type[in] Type of message object
mpp[out] pointer to receive pointer to message object
Returns
zero on success or non-zero error code

Message types are

  • X400_MSG_MESSAGE A Message object
  • X400_MSG_REPORT A Report object
  • X400_MSG_PROBE A Probe object
Examples:
examples/x400_msrcv_msg_tok_sign.c, examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, examples/x400_mssend_sign.c, and x400_msasync.c.

◆ X400msMsgCountRecip()

int X400msMsgCountRecip ( struct X400msMessage *  mp,
int  type,
int *  cp 
)

Returns count of addresses of given type in message object.

Parameters
mp[in] X400 MS message
type[in] Type of address to count
cp[out] pointer integer to receive count of addresses
Returns
zero on success or non-zero error code

◆ X400msMsgSend()

int X400msMsgSend ( struct X400msMessage *  mp)

Send message object.

Parameters
mp[in] Message pointer
Returns
Zero on success or non-zero error code
Examples:
examples/x400_msrcv_msg_tok_sign.c, examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, examples/x400_mssend_sign.c, and x400_msasync.c.

◆ X400msMsgDelete()

int X400msMsgDelete ( struct X400msMessage *  mp,
int  retain 
)

Delete message object.

Parameters
mp[in] Message pointer
retain[in] If true, message is not deleted from Message Store
Returns
Zero on success or non-zero error code

This is called after submitting a message object or to abandon submission. Also called when a message which has been read has been finished with. By default, for a P7 connection, the message is deleted from the message store at the same time. However, if the retain flag is set, then the message is not deleted from the Store. This flag has no effect for a P3 connection.

Examples:
examples/x400_mslist.c, examples/x400_msrcv.c, examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, examples/x400_mssend_sign.c, and x400_msasync.c.

◆ X400msMsgAddStrParam()

int X400msMsgAddStrParam ( struct X400msMessage *  mp,
int  paramtype,
const char *  value,
size_t  length 
)

Add string-valued parameter to the message.

Parameters
mp[in] Message pointer
paramtype[in] Type of parameter
value[in] Value of parameter
length[in] Length of parameter, -1 if NUL terminated
Returns
Zero on success or non-zero error code
Examples:
examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, examples/x400_mssend_sign.c, and x400_msasync.c.

◆ X400msMsgAddIntParam()

int X400msMsgAddIntParam ( struct X400msMessage *  mp,
int  paramtype,
int  value 
)

Add integer-valued parameter to the message.

Parameters
mp[in] Message pointer
paramtype[in] Type of parameter
value[in] Value of parameter
Returns
Zero on success or non-zero error code
Examples:
examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, and examples/x400_mssend_sign.c.

◆ X400msMsgAddAttachment()

int X400msMsgAddAttachment ( struct X400msMessage *  mp,
int  type,
const char *  string,
size_t  length 
)

Add attachment to the message.

Parameters
mp[in] Message pointer
type[in] Type of attachment
string[in] String value for attachment
length[in] Length of string
Returns
Zero on success or non-zero error code
Examples:
examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, examples/x400_mssend_sign.c, and x400_msasync.c.

◆ X400msMsgAddBodypart()

int X400msMsgAddBodypart ( struct X400msMessage *  mp,
struct X400Bodypart *  bp 
)
Deprecated:
Use X400msMsgAddMessageBodyWtype instead.

◆ X400msMsgAddMessageBodyWType()

int X400msMsgAddMessageBodyWType ( struct X400msMessage *  mp,
struct X400Message *  mbp,
int  type 
)

Add a message body part object to a message.

Parameters
mp[in] Message pointer
mbp[in] Message body part pointer
type[in] BodyPart type (E.G X400_T_MESSAGE)
Returns
Zero on success or non-zero error code

The message body part must be a message delivery object for forwarded-message body part.

If the message object being created has an IPN content, then any envelope information is ignored.

◆ X400msMsgAddMessageBody()

int X400msMsgAddMessageBody ( struct X400msMessage *  mp,
struct X400Message *  mbp 
)
Deprecated:
Use X400msMsgAddMessageBodyWType instead.
Examples:
examples/x400_mssend.c.

◆ X400msRecipNew()

int X400msRecipNew ( struct X400msMessage *  mp,
int  type,
struct X400Recipient **  rpp 
)

Add new recipient to a message.

Parameters
mp[in] Message pointer
type[in] type of recipient
rpp[out] Pointer to place for pointer to recipient information
Returns
Zero on success or non-zero error code

Creates a recipient object associated with the message. There are several different types for recipient object. Normal recipients can be specified separately for the envelope (i.e. controlling where the message actually goes) and the header which is part of the content. They can also be specified together. A separate type of recipient is the reported recipient which appears in a report content.

  • X400_RECIP_PRIMARY Primary recipient in header
  • X400_RECIP_CC Carbon copy recipient in header
  • X400_RECIP_BCC Blind copy recipient in header
  • X400_RECIP_REPLY Reply-recipient in header
  • X400_RECIP_ENVELOPE Actual recipient in envelope
  • X400_RECIP_REPORT Reported recipient in report content
  • X400_RECIP_INTENDED Originally intended recipient in report content
  • X400_ORIGINATOR Originator address in IPM header
  • X400_AUTH_ORIG Authorizing originator address in IPM header

To set a given recipient in both envelope and header, add together the values, e.g. X400_RECIP_PRIMARY + X400_RECIP_ENVELOPE. The value X400_RECIP_STANDARD is a shorthand for this combination.

Examples:
examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, examples/x400_mssend_sign.c, and x400_msasync.c.

◆ X400msRecipAddStrParam()

int X400msRecipAddStrParam ( struct X400Recipient *  rp,
int  paramtype,
const char *  value,
size_t  length 
)

Add string-valued parameter to the message.

Parameters
rp[in] Recipient pointer
paramtype[in] Type of parameter
value[in] Value of parameter
length[in] Length of parameter, -1 if NUL terminated
Returns
Zero on success or non-zero error code
Examples:
examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, examples/x400_mssend_sign.c, and x400_msasync.c.

◆ X400msRecipAddIntParam()

int X400msRecipAddIntParam ( struct X400Recipient *  rp,
int  paramtype,
int  value 
)

Add integer-valued parameter to the message.

Parameters
rp[in] Message pointer
paramtype[in] Type of parameter
value[in] Value of parameter
Returns
Zero on success or non-zero error code
Examples:
examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, and examples/x400_mssend_sign.c.

◆ X400msWait()

int X400msWait ( struct X400msSession *  sp,
int  seconds,
int *  count 
)

Wait for messages to be ready to be read.

Parameters
sp[in] Session pointer
seconds[in] Seconds to wait
count[out] pointer to receive number of messages
Returns
Zero on success, non-zero on failure, including timeout.
If seconds is zero, then there is no delay. If seconds is negative,
then the delay is indefinite.
Examples:
examples/x400_msrcv.c, examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, examples/x400_mssend_rcv_sign.c, and x400_msasync.c.

◆ X400msWaitNew()

int X400msWaitNew ( struct X400msSession *  sp,
int  seconds,
int *  count 
)

Wait for new messages to be ready to be read.

Parameters
sp[in] Session pointer
seconds[in] Seconds to wait
count[out] pointer to receive number of messages
Returns
Zero on success, non-zero on failure, including timeout.
If seconds is zero, then there is no delay. If seconds is negative,
then the delay is indefinite.

◆ X400msMsgGet()

int X400msMsgGet ( struct X400msSession *  sp,
int  number,
struct X400msMessage **  mpp,
int *  typep,
int *  seqp 
)

Get message object for transfer out from MS or MTA via P3.

Parameters
sp[in] Session pointer
number[in] Sequence number of message to retrieve
mpp[out] Pointer to receive message object pointer
typep[out] Pointer to receive message object type.
seqp[out] Pointer to receive sequence number
Returns
Zero on success, non-zero on failure or message verification failure

Note that this function is deprecated for P3, and should be replaced by X400msMsgGetStart() and X400msMsgGetFinish() in order to provide transactional security.

The number argument can be zero, which means fetch the next message object. For a P7 connection, it can specify the sequence number of the object to retrieve. It is ignored for P3.

The seqp argument, if not NULL, points to an integer which receives the sequence number for a message object, when the connection is P7.

Examples:
examples/x400_mslist.c, examples/x400_msrcv.c, examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, examples/x400_mssend_rcv_sign.c, and x400_msasync.c.

◆ X400msMsgGetEx()

int X400msMsgGetEx ( struct X400msSession *  sp,
int  number,
int  entryclass,
struct X400msMessage **  mpp,
int *  typep,
int *  seqp 
)

Get message object for transfer out from MS or MTA via P3.

Parameters
sp[in] Session pointer
number[in] Sequence number of message to retrieve
entryclass[in] Entry class of message to retrieve
mpp[out] Pointer to receive message object pointer
typep[out] Pointer to receive message object type.
seqp[out] Pointer to receive sequence number
Returns
Zero on success, non-zero on failure or message verification failure

Note that this function is deprecated for P3, and should be replaced by X400msMsgGetStart() and X400msMsgGetFinish() in order to provide transactional security.

The number argument can be zero, which means fetch the next message object. For a P7 connection, it can specify the sequence number of the object to retrieve. It is ignored for P3.

The seqp argument, if not NULL, points to an integer which receives the sequence number for a message object, when the connection is P7.

◆ X400msMsgGetStart()

int X400msMsgGetStart ( struct X400msSession *  sp,
int  number,
struct X400msMessage **  mpp,
int *  typep,
int *  seqp 
)

Get message object for transfer out from MS or MTA via P3.

Parameters
sp[in] Session pointer
number[in] Sequence number of message to retrieve
mpp[out] Pointer to receive message object pointer
typep[out] Pointer to receive message object type.
seqp[out] Pointer to receive sequence number
Returns
Zero on success, non-zero on failure or message verification failure

The number argument can be zero, which means fetch the next message object. For a P7 connection, it can specify the sequence number of the object to retrieve. It is ignored for P3.

The seqp argument, if not NULL, points to an integer which receives the sequence number for a message object, when the connection is P7.

When used in P3 mode, this function does not acknowledge recipt of the message it returns: this should be done by calling X400msMsgGetFinish() once the message has been successfully processed.

◆ X400msMsgGetStartEx()

int X400msMsgGetStartEx ( struct X400msSession *  sp,
int  number,
int  entryclass,
struct X400msMessage **  mpp,
int *  typep,
int *  seqp 
)

Get message object for transfer out from MS or MTA via P3.

Parameters
sp[in] Session pointer
number[in] Sequence number of message to retrieve
entryclass[in] Entry class of message to retrieve
mpp[out] Pointer to receive message object pointer
typep[out] Pointer to receive message object type.
seqp[out] Pointer to receive sequence number
Returns
Zero on success, non-zero on failure or message verification failure

The number argument can be zero, which means fetch the next message object. For a P7 connection, it can specify the sequence number of the object to retrieve. It is ignored for P3.

The seqp argument, if not NULL, points to an integer which receives the sequence number for a message object, when the connection is P7.

When used in P3 mode, this function does not acknowledge recipt of the message it returns: this should be done by calling X400msMsgGetFinish() once the message has been successfully processed.

◆ X400msMsgGetFinish()

int X400msMsgGetFinish ( struct X400msMessage *  mp,
int  errnum,
int  problem 
)

Generate delivery result or error for a message.

Parameters
mp[in] Message object for which to signal success/failure
errnum[in] Error code for non-delivery reason
problem[in] Problem code for non-delivery (see X.411 for values)

This function is a no-op for P7. For P3 mode, this function signals successful delivery of a message back to the MTA.

Examples:
x400_msasync.c.

◆ X400msMsgGetStrParam()

int X400msMsgGetStrParam ( struct X400msMessage *  mp,
int  paramtype,
char *  buffer,
size_t  buflen,
size_t *  paramlenp 
)

Return a string-valued parameter from the message object.

Parameters
mp[in] message object pointer
paramtype[in] type of parameter
buffer[in/out] address for result
buflen[in] length of buffer provided
paramlenp[out] Pointer to receive actual length
Returns
Zero on success or non-zero error code
Examples:
examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, and x400_msasync.c.

◆ X400msMsgGetIntParam()

int X400msMsgGetIntParam ( struct X400msMessage *  mp,
int  paramtype,
int *  valp 
)

Return a integer-valued parameter from the message object.

Parameters
mp[in] message object pointer
paramtype[in] type of parameter
valp[out] Pointer to receive value
Returns
Zero on success or non-zero error code
Examples:
examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, and examples/x400_mssend_rcv_sign.c.

◆ X400msMsgGetAttachment()

int X400msMsgGetAttachment ( struct X400msMessage *  mp,
int  number,
int *  typep,
char *  buffer,
size_t  buflen,
size_t *  lengthp 
)

Return the data of an attachment (=bodypart) from the message object.

Parameters
mp[in] message object pointer
number[in] Attachment number
typep[out] Pointer to receive attachment type
buffer[in] Buffer to receive data
buflen[in] Length of buffer
lengthp[out] Length of string
Returns
Zero on success or non-zero error code

This is different from X400msMsgGetBodypart() in that only the data and not the bodypart itself is returned.

◆ X400msMsgGetBodypart()

int X400msMsgGetBodypart ( struct X400msMessage *  mp,
int  number,
int *  typep,
struct X400Bodypart **  bpp 
)

Return a pointer to a body part object.

Parameters
mp[in] message object pointer
number[in] Bodypart number
typep[out] Pointer to receive attachment type
bpp[out] Pointer to pointer to object
Returns
Zero on success or non-zero error code

◆ X400msMsgGetMessageBody()

int X400msMsgGetMessageBody ( struct X400msMessage *  mp,
int  number,
struct X400Message **  mpp 
)

Return a pointer to a message part object.

Parameters
mp[in] message object pointer
number[in] Bodypart number
mpp[out] Pointer to pointer to object
Returns
Zero on success or non-zero error code

◆ X400msMsgGetCert()

int X400msMsgGetCert ( struct X400msMessage *  mp,
int  certtype,
struct X400Certificate **  certp 
)

Get certificate object from message This returns a certificate which was used to sign an object in the message. The attribute type indicates which object type.

Parameters
mp[in] Message object pointer
certtype[in] Attribute type for certificate
certp[out] Pointer to receive certificate object pointer
Returns
Zero on success, non-zero on failure
Examples:
examples/x400_msrcv_sign.c, and examples/x400_mssend_rcv_sign.c.

◆ X400msMakeIPN()

int X400msMakeIPN ( struct X400msMessage *  mp,
int  non_receipt_reason,
struct X400msMessage **  mpp 
)

Make an IPN based on the subject IPM.

Parameters
mp[in] Message object pointer
non_receipt_reason[in] Non-receipt reason (-1 for receipt)
mpp[out] Pointer to receive message object pointer
Returns
Zero on success, non-zero on failure

Generate a new message object ready for submission as a Inter-Personal Notification based on the received message object. It is associated with the same session as the subject message.

If the non-receipt reason is specified as -1, then the IPN is a receipt notification. The receipt time is set to the current date and time.

For a non-receipt notification, the original IPM is returned if the requested by the sender.

If a notification of the type indicated has not been requested by the sender, then the function returns X400_E_NO_VALUE.

Examples:
examples/x400_msrcv_msg_tok_sign.c.

◆ X400msRecipGet()

int X400msRecipGet ( struct X400msMessage *  mp,
int  type,
int  number,
struct X400Recipient **  rpp 
)

Get recipient object from message.

Parameters
mp[in] Message object pointer
type[in] Type of recipient
number[in] Ordinal number of recipient
rpp[out] Pointer to receive recipient object pointer
Returns
Zero on success, non-zero on failure
Examples:
examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, examples/x400_mssend.c, and examples/x400_mssend_rcv_sign.c.

◆ X400msRecipGetStrParam()

int X400msRecipGetStrParam ( struct X400Recipient *  rp,
int  paramtype,
char *  buffer,
size_t  buflen,
size_t *  paramlenp 
)

Return a string-valued parameter from the recipient object.

Parameters
rp[in] recipient object pointer
paramtype[in] type of parameter
buffer[in/out] address for result
buflen[in] length of buffer provided
paramlenp[out] Pointer to receive actual length
Returns
Zero on success or non-zero error code
Examples:
examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, examples/x400_mssend.c, and examples/x400_mssend_rcv_sign.c.

◆ X400msRecipGetIntParam()

int X400msRecipGetIntParam ( struct X400Recipient *  rp,
int  paramtype,
int *  valp 
)

Return a integer-valued parameter from the recipient object.

Parameters
rp[in] recipient object pointer
paramtype[in] type of parameter
valp[out] Pointer to receive value
Returns
Zero on success or non-zero error code
Examples:
examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, and examples/x400_mssend_rcv_sign.c.

◆ X400msSetIntDefault()

int X400msSetIntDefault ( struct X400msSession *  sp,
int  paramtype,
int  value 
)

Set a default integer parameter value in a session.

Parameters
sp[in] Session handle returned from an X400msOpen call
paramtype[in] Parameter type to set
value[in] Parameter value to set
Returns
zero on success or non-zero error code

Sets a default integer parameter value in a session object. If this parameter has previously been set in the session, the existing value is replaced. When a message is sent, any attribute which is not present in the message being sent will be taken from the session's default set.

Examples:
examples/x400_mslist.c, examples/x400_msraa.c, examples/x400_msrcv.c, examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, and x400_msasync.c.

◆ X400msSetStrDefault()

int X400msSetStrDefault ( struct X400msSession *  sp,
int  paramtype,
const char *  value,
size_t  length 
)

Set a default string parameter value in a session.

Parameters
sp[in] Session handle returned from an X400msOpen call
paramtype[in] Parameter type to set
value[in] Parameter value to set
length[in] Length of parameter value to set
Returns
zero on success or non-zero error code

Sets a default string parameter value in a session object. If this parameter has previously been set in the session, the existing value is replaced. When a message is sent, any attribute which is not present in the message being sent will be taken from the session's default set.

Examples:
examples/x400_mslist.c, examples/x400_msraa.c, examples/x400_msrcv.c, examples/x400_msrcv_msg_tok_sign.c, examples/x400_msrcv_sign.c, examples/x400_mssend.c, examples/x400_mssend_rcv_sign.c, examples/x400_mssend_sign.c, and x400_msasync.c.

◆ X400msTestSecurityEnv()

int X400msTestSecurityEnv ( struct X400msSession *  sp)

Test the default Security Environment.

Parameters
sp[in] Session handle returned from an X400msOpen call
Returns
zero on success or non-zero error code

Test the default Security Environment set up in earlier calls to X400msSetStrDefault. This can be called prior to a call to X400msSend() with signing request set to ensure that the enviroment is correct so that helpful errors can be returned to the API client.

Examples:
examples/x400_mssend_rcv_sign.c, and examples/x400_mssend_sign.c.

◆ X400msRegisterAutoAction()

int X400msRegisterAutoAction ( struct X400msSession *  sp,
int  type,
int  id,
struct X400msAutoActionParameter *  aa_param 
)

Register an autoaction with the Message Store.

Parameters
sp[in] Session handle returned from an X400msOpen call
type[in] Autoaction type to register
id[in] Identifier for autoaction
aa_param[in] Parameter for new autoaction
Returns
zero on success or non-zero error code

Registers an autoaction with the Store. Any existing autoaction with the same id will be overwritten. Available values for autoaction type are X400_AUTO_ALERT and X400_AUTO_FORWARD.

Examples:
examples/x400_msraa.c, examples/x400_msrcv.c, examples/x400_msrcv_sign.c, and x400_msasync.c.

◆ X400msDeregisterAutoAction()

int X400msDeregisterAutoAction ( struct X400msSession *  sp,
int  type,
int  id 
)

Deregister an autoaction from the Message Store.

Parameters
sp[in] Session handle returned from an X400msOpen call
type[in] Autoaction type to deregister
id[in] Identifier of autoaction to deregister
Returns
zero on success or non-zero error code

Deregisters an autoaction with the Store. Available values for autoaction type are X400_AUTO_ALERT and X400_AUTO_FORWARD.

Examples:
examples/x400_msraa.c, examples/x400_msrcv.c, examples/x400_msrcv_sign.c, and x400_msasync.c.

◆ X400msNewAutoActionParameter()

struct X400msAutoActionParameter* X400msNewAutoActionParameter ( void  )

Create a new (empty) autoaction parameter structure.

Returns
New autoaction handle
Examples:
examples/x400_msraa.c, examples/x400_msrcv.c, and examples/x400_msrcv_sign.c.

◆ X400msFreeAutoActionParameter()

void X400msFreeAutoActionParameter ( struct X400msAutoActionParameter *  aa_param)

Free an autoaction parameter.

Parameters
aa_param[in] Handle to autoaction parameter to be freed
Returns
None
Examples:
examples/x400_msraa.c, examples/x400_msrcv.c, and examples/x400_msrcv_sign.c.

◆ X400msAutoActionParameterAddRecip()

int X400msAutoActionParameterAddRecip ( struct X400msAutoActionParameter *  aap,
int  reciptype,
struct X400Recipient *  recip 
)

Add a receipient to the autoaction parameter.

Parameters
aap[in] Autoaction parameter
reciptype[in] Type of recipient parameter
recip[in] Recipient structure
Returns
Zero on success or non-zero error code
Examples:
examples/x400_msraa.c, examples/x400_msrcv.c, and examples/x400_msrcv_sign.c.

◆ X400msAutoActionParameterAddIntParam()

int X400msAutoActionParameterAddIntParam ( struct X400msAutoActionParameter *  aap,
int  paramtype,
int  value 
)

Add integer-valued parameter to the autoaction parameter.

Parameters
aap[in] Autoaction parameter
paramtype[in] Parameter type
value[in] Value of parameter
Returns
Zero on success or non-zero error code
Examples:
examples/x400_msraa.c, examples/x400_msrcv.c, and examples/x400_msrcv_sign.c.

◆ X400msAutoActionParameterAddStrParam()

int X400msAutoActionParameterAddStrParam ( struct X400msAutoActionParameter *  aap,
int  paramtype,
const char *  value,
size_t  length 
)

Add string-valued parameter to the autoaction parameter.

Parameters
aap[in] Autoaction parameter
paramtype[in] Type of parameter
value[in] Value of parameter
length[in] Length of parameter, -1 if NUL terminated
Returns
Zero on success or non-zero error code
Examples:
examples/x400_msraa.c, examples/x400_msrcv.c, and examples/x400_msrcv_sign.c.

◆ X400msCheckConnection()

int X400msCheckConnection ( struct X400msSession *  sp)

Check that a connection is still active.

Parameters
sp[in] Session pointer
Returns
Zero on success or non-zero error code

◆ X400msDLExpHistGet()

int X400msDLExpHistGet ( struct X400msMessage *  mp,
int  entry,
struct X400DLExpHist **  hist 
)

Create a new DL Expansion History object from the message object.

Parameters
mp[in] message object pointer
entry[in] DL expansion history element to fetch
hist[out] pointer to receive new DL Expansion History object
Returns
Zero on success, or non-zero error code

◆ X400msDLExpHistNew()

int X400msDLExpHistNew ( struct X400msMessage *  mp,
struct X400DLExpHist **  histp 
)

Create a new DL Expansion History object, and associate it with the existing message.

Parameters
mp[in] message pointer
histp[out] pointer to receive new DL Expansion History object
Returns
Zero on success, or non-zero error code

◆ X400msALINew()

int X400msALINew ( struct X400msMessage *  mp,
struct X400ALI **  ali 
)

Create a new Address List Indicator Object, and associate it with the existing message.

Parameters
mp[in] message pointer
ali[out] pointer to receive new ALI object
Returns
Zero on success, or non-zero error code

◆ X400msALIGet()

int X400msALIGet ( struct X400msMessage *  mp,
int  entry,
struct X400ALI **  info 
)

Get a Address List Indicator Object for a message object.

Parameters
mp[in] message pointer
entry[in] ALI object being used.
info[out] pointer to receive new ALI object
Returns
Zero on success, or non-zero error code

◆ X400msPSSNew()

int X400msPSSNew ( struct X400msMessage *  mp,
struct X400PSS **  pss,
int  type 
)

Create a new Printable String Syntax Object, and associate it with the existing message.

Parameters
mp[in] message pointer
pss[out] pointer to receive new PSS object
type[in] type of PSS object
Returns
Zero on success, or non-zero error code

◆ X400msPSSGet()

int X400msPSSGet ( struct X400msMessage *  mp,
int  type,
int  entry,
struct X400PSS **  pss 
)

Get a Printable String Syntax Object for a message object.

Parameters
mp[in] message pointer
type[in] type of PSS being used.
entry[in] PSS object being used.
pss[out] pointer to receive new pss object
Returns
Zero on success, or non-zero error code

◆ X400msDistFieldNew()

int X400msDistFieldNew ( struct X400msMessage *  mp,
struct X400DistField **  pss 
)

Create a new P772 Distribution Field object for a message object.

Parameters
mp[in] message pointer
pss[out] pointer to receive distfield object
Returns
Zero on success, or non-zero error code

◆ X400msDistFieldGet()

int X400msDistFieldGet ( struct X400msMessage *  mp,
int  entry,
struct X400DistField **  pss 
)

Get a new P772 Distribution Field object for a message object.

Parameters
mp[in] message pointer
entry[in] distfield object being used.
pss[out] pointer to receive new PSS object
Returns
Zero on success, or non-zero error code

◆ X400msOtherRecipNew()

int X400msOtherRecipNew ( struct X400msMessage *  mp,
struct X400OtherRecip **  otherrecip 
)

Create a new P772 Other Recipient object for a message object.

Parameters
mp[in] message pointer
otherrecip[out] pointer to receive other recipient object
Returns
Zero on success, or non-zero error code

◆ X400msOtherRecipGet()

int X400msOtherRecipGet ( struct X400msMessage *  mp,
int  entry,
struct X400OtherRecip **  otherrecip 
)

Get a new P772 Other Recipient object for a message object.

Parameters
mp[in] message pointer
entry[in] Other Recip object being used.
otherrecip[out] pointer to receive new other recipient object
Returns
Zero on success, or non-zero error code

◆ X400msRediHistGetEnv()

int X400msRediHistGetEnv ( struct X400msMessage *  msg,
int  entry,
struct X400RediHist **  hist 
)

Get the Redirection History object from a message envelope this is represented by 8.3.1.2.1.5 in X.411.

Parameters
msg[in] X.400 Message
entry[in] Redirection history object to use
hist[out] Pointer to redirection history object
Returns
Zero on success or non-zero error code

◆ X400msTraceInfoGet()

int X400msTraceInfoGet ( struct X400msMessage *  mp,
int  entry,
struct X400TraceInfo **  info,
int  type 
)

Get a Trace Info object for a message object.

Parameters
mp[in] message pointer
entry[in] Trace Info object to use
info[out] pointer to receive new trace infomation object
type[in] type of trace info object to get
Returns
Zero on success, or non-zero error code

◆ X400msInternalTraceInfoGet()

int X400msInternalTraceInfoGet ( struct X400msMessage *  mp,
int  entry,
struct X400InternalTraceInfo **  info 
)

Get an Internal Trace Info object for a message object.

Parameters
mp[in] message pointer
entry[in] Trace Info object to use
info[out] pointer to receive new trace infomation object
Returns
Zero on success, or non-zero error code

◆ X400msORandDLGet()

int X400msORandDLGet ( struct X400msMessage *  msg,
int  entry,
struct X400ORandDL **  or_and_dl 
)

Get Originator and DL expansion history object.

Parameters
msg[in] X.400 Message
entry[in] The orginator and dl expansion history object to use
or_and_dl[out] Pointer to orig ans dl expan history object
Returns
Zero on success or non-zero error code

◆ X400msGetContentOctets()

int X400msGetContentOctets ( struct X400msMessage *  mp,
char *  buf,
size_t  buflen,
size_t *  lenp 
)

Obtains the bytes containing the ASN.1 encoding of the Content of a message. The Content is obtained by building an IPM from the attributes of the message and then encoding it.

Parameters
mp[in] Message from which to get Content encoding
buf[in] Buffer for return of content
buflen[in] Length of buffer
lenp[out] Length of data returned
Returns
Zero on success or non-zero error code

◆ X400msSetContentOctets()

int X400msSetContentOctets ( struct X400msMessage *  mp,
char *  buf,
size_t  len 
)

Takes a byte stream containing the ASN.1 encoding of a P22 (or P772) content, decodes it and sets it into a message, so that attributes can be extracted from it.

Parameters
mp[in] Message into which to put the Content
buf[in] Buffer containing encoding of content
buflen[in] Length of buffer
Returns
Zero on success or non-zero error code

◆ X400msACP127RespGet()

int X400msACP127RespGet ( struct X400msMessage *  mp,
struct X400ACP127Resp **  respp 
)

Get the ACP127 Notification Response object from a message.

Parameters
mp[in] X.400 Message Recipient pointer
resp[out] Pointer to ACP127 Notification Response object
Returns
Zero on success or non-zero error code

◆ X400msACP127RespNew()

int X400msACP127RespNew ( struct X400msMessage *  mp,
struct X400ACP127Resp **  respp 
)

Create an ACP127 Notification Response object.

Parameters
mp[in] X400 message pointer
resp[out] Pointer X400ACP127Resp object
Returns
Zero on success or non-zero error code

◆ X400msACP127RespDeepCopy()

struct X400ACP127Resp* X400msACP127RespDeepCopy ( struct X400msMessage *  mp,
struct X400ACP127Resp *  orig 
)

Copy an ACP127 Notification Response object.

Parameters
mp[in] message pointer for copy
original[in] object to copy
Returns
Copy of object or NULL on error

◆ X400msMsgGetRaw()

int X400msMsgGetRaw ( struct X400msSession *  sp,
struct X400msMessage *  mp,
char *  buffer,
size_t  buflen,
size_t *  buflenp 
)

Get a binary representation of a message which can be subsequently be used to reconstruct the message.

Parameters
sp[in] session pointer
mp[in] message
buffer[in] buffer into which to write binary representation of message
buflen[in] length of buffer
buflenp[out] number of bytes written to buffer or required
Returns
Zero on success or non-zero error code
Examples:
examples/x400_mslist.c, examples/x400_msrcv.c, and examples/x400_mssend.c.

◆ X400msMsgFromRaw()

int X400msMsgFromRaw ( struct X400msSession *  sp,
char *  buffer,
size_t  buflen,
struct X400msMessage **  mpp,
int *  typep 
)

Reconstruct a message from a binary representation.

Parameters
sp[in] session pointer
buffer[in] buffer containing binary representation of message
buflen[in] length of buffer
mpp[out] new message
typep[out] message type
Returns
Zero on success or non-zero error code
Examples:
examples/x400_mslist.c, examples/x400_msrcv.c, and examples/x400_mssend.c.