Summary: Isode provides a number of APIs which allow integrators and product developers to build components that access the Isode Messaging server products or other products supporting the same protocols.
Session Management

Data Structures

struct  SOMSession
 Opaque session data. More...
 

Macros

#define SOM_FACILITY_MULTITHREADED   (32)
 Create a Session object. More...
 

Typedefs

typedef void SOMSessionCallback(struct SOMSession *session, void *ophandle, void *clientdata, int status, const char *opdata, size_t opdatalen)
 Prototype for callback for session operation completion. More...
 

Functions

const char * SOMError (int error)
 Return string for error code. More...
 
void SOMSetService (struct SOMSession *session, const char *service)
 Set the service name - defaults to "som". More...
 
int SOMSessionAuthenticated (struct SOMSession *session)
 Return TRUE if session authenticated, FALSE otherwise. More...
 
int SOMInit (int version)
 Return string for error code. More...
 
int SOMSessionCreate (int facilities, void *clientdata, struct SOMSession **session)
 
int SOMEventPoll (int dispatch, int timeout)
 Poll for asynchronous events on all open sessions. More...
 
int SOMEventPollSingle (struct SOMSession *sp, int dispatch, int timeout)
 Poll for asynchronous events on a single Session. More...
 
int SOMSessionSetTLS (struct SOMSession *session, const char *identity, const char *passphrase)
 Enable use of TLS/SSL for the session. More...
 
int SOMSessionSetSessionCallback (struct SOMSession *session, SOMSessionCallback *callback, SOMSessionCallback **oldvalue)
 Set the session callback function for this session. More...
 
int SOMSessionOpen (struct SOMSession *session, const char *host, int port, const char *username, const char *password, void *ophandle, int async)
 Open a session to the MTA. More...
 
int SOMSessionOpenMech (struct SOMSession *session, const char *host, int port, const char *username, const char *passwd, void *ophandle, int async, const char *mech)
 Open a session to the MTA, specifying the SASL mechanism to be used. More...
 
int SOMSessionClose (struct SOMSession *sp)
 Close a X400 Session. More...
 
int SOMSessionDelete (struct SOMSession *session)
 Delete a session. More...
 
int SOMSessionClear (struct SOMSession *session, int facilities)
 Clear all subordinate objects. More...
 

Detailed Description

Description of the function calls for general Session Management.

Macro Definition Documentation

#define SOM_FACILITY_MULTITHREADED   (32)

Create a Session object.

Parameters
clientdata[in] Client data associated with session object
facilities[in] Facilities to be used
session[out] Pointer to location for address of session object
Returns
zero on success; non-zero on error

The facilities field is the bitwise OR for the different facilities which the session will be using. The core library uses this to initialize the related libraries. The facility values are defined by SOM_FACILITY_* values in the header files relating to the API for each facility.

You must specify at least one facility.

Definition at line 116 of file session.h.

Typedef Documentation

typedef void SOMSessionCallback(struct SOMSession *session, void *ophandle, void *clientdata, int status, const char *opdata, size_t opdatalen)

Prototype for callback for session operation completion.

Parameters
session[in] Pointer to address of session object
ophandle[in] Data associated with operation
clientdata[in] Data associated with session
status[in] Status for the operation
opdata[in] Data returned by operation
opdatalen[in] Length of data returned by operation
Returns
no return value

The structure of the data returned depends upon the operation. Session operations do not normally return data. However, if the status is an error status, the data, if set, contains a string which is error data.

Definition at line 56 of file session.h.

Function Documentation

const char* SOMError ( int  error)

Return string for error code.

Parameters
error[in] error code
Returns
Pointer to NUL terminated string for error
void SOMSetService ( struct SOMSession session,
const char *  service 
)

Set the service name - defaults to "som".

Parameters
session[in] session to set
service[in] the service name
int SOMSessionAuthenticated ( struct SOMSession session)

Return TRUE if session authenticated, FALSE otherwise.

Parameters
session[in] session to query
Returns
TRUE / FALSE
int SOMInit ( int  version)

Return string for error code.

Parameters
version[in] Library version number expected
Returns
zero on success or non-zero error code

The library version is an opaque integer which is passed in. The value SOM_LIBRARY_VERSION should be used. This is used to check that the client is using a compatible library version.

int SOMEventPoll ( int  dispatch,
int  timeout 
)

Poll for asynchronous events on all open sessions.

Parameters
dispatch[in] Processing of events is performed if true
timeout[in] Wait this long (in milliseconds) before giving up.
Returns
zero if events to process or processed, SOM_ERROR_TIMEOUT if no events within timeout, or other error.

If dispatch is false, the function only checks to see if there may be data to process. If true, then operation results are processed, which may create, update or delete objects, and callbacks, if set, are called.

The timeout can be zero, for a true poll, a negative number which indicates no timeout, or a positive number of milliseconds to wait.

int SOMEventPollSingle ( struct SOMSession sp,
int  dispatch,
int  timeout 
)

Poll for asynchronous events on a single Session.

Parameters
session[in] Session to poll on
dispatch[in] Processing of events is performed if true
timeout[in] Wait this long (in milliseconds) before giving up.
Returns
zero if events to process or processed, SOM_ERROR_TIMEOUT if no events within timeout, or other error.

If dispatch is false, the function only checks to see if there may be data to process. If true, then operation results are processed, which may create, update or delete objects, and callbacks, if set, are called.

The timeout can be zero, for a true poll, a negative number which indicates no timeout, or a positive number of milliseconds to wait.

int SOMSessionSetTLS ( struct SOMSession session,
const char *  identity,
const char *  passphrase 
)

Enable use of TLS/SSL for the session.

Parameters
session[in] Pointer to address of session object
identity[in] Security environment
passphrase[in] Passphrase for Identity
Returns
zero on success; non-zero on error

This must be called before the session is opened.

If the security environment is NULL, then the client will not verify itself against the server, and the server will not be verified. The environment can contain trusted CA information, in which case the server will be verified. If the environment contains an identity, then the passphrase may be needed to use it. If it can be accessed, then the client will verify itself against the server.

At this point the security environment is the name of a directory which can contain a PEM file called ca.pem which contains trusted CA certificates. The identity should be a PKCS#12 file called id.p12. This can also contain trusted CA certs.

int SOMSessionSetSessionCallback ( struct SOMSession session,
SOMSessionCallback callback,
SOMSessionCallback **  oldvalue 
)

Set the session callback function for this session.

Parameters
session[in] Pointer to address of session object
callback[in] Address of callback function
oldvalue[out] Pointer to location for previous value of callback function
Returns
zero on success; non-zero on error

callback may be NULL to clear the callback function oldvalue may be NULL, in which case the previous value is not returned

int SOMSessionOpen ( struct SOMSession session,
const char *  host,
int  port,
const char *  username,
const char *  password,
void *  ophandle,
int  async 
)

Open a session to the MTA.

Parameters
session[in] Pointer to session
host[in] Hostname of Switch system
port[in] Port to use for connection
username[in] Username for credentials
password[in] Password
ophandle[in] Client data for this operation
async[in] Operation is async if TRUE
Returns
zero on success or non-zero error code

Opens a session for transfer in and transfer out.

The username and password can be omitted if an anonymous bind is permitted by the server. This may restrict the operations which can be carried out.

If async is TRUE, a session callback MUST have been setup.

If the session is already open, it may be closed and reopened with the new credentials.

int SOMSessionOpenMech ( struct SOMSession session,
const char *  host,
int  port,
const char *  username,
const char *  passwd,
void *  ophandle,
int  async,
const char *  mech 
)

Open a session to the MTA, specifying the SASL mechanism to be used.

Parameters
session[in] Pointer to session
host[in] Hostname of Switch system
port[in] Port to use for connection
username[in] Username for credentials
password[in] Password
ophandle[in] Client data for this operation
async[in] Operation is async if TRUE
mech[in] SASL mechanism to use
Returns
zero on success or non-zero error code

Opens a session for transfer in and transfer out.

The username and password can be omitted if an anonymous bind is permitted by the server. This may restrict the operations which can be carried out.

If async is TRUE, a session callback MUST have been setup.

If the mechanism specified is not in the list of supported mechanisms returned by the server, an error will be returned.

If the session is already open, it may be closed and reopened with the new credentials.

int SOMSessionClose ( struct SOMSession 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.

int SOMSessionDelete ( struct SOMSession session)

Delete a session.

Parameters
session[in] Pointer to address of session object
Returns
zero on success; non-zero on error

There is an implicit Close in this operation, if the session is not already closed.

There is an implicit Clear in this operation.

int SOMSessionClear ( struct SOMSession session,
int  facilities 
)

Clear all subordinate objects.

Parameters
session[in] Pointer to address of session object
facilities[in] Bitwise OR of facilities to be cleared
Returns
zero on success; non-zero on error

Issues a delete for all objects related to this session. This clears all objects connected to the session related to the facilities specified. Specify -1 to clear all data.