Description of the function calls for general Session Management. More...

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	SOMSessionOpenRole (struct SOMSession session, const char host, int port, const char username, const char password, const char role, 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	SOMSessionOpenMechRole (struct SOMSession session, const char host, int port, const char username, const char passwd, const char role, 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

◆ SOM_FACILITY_MULTITHREADED

#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

◆ SOMSessionCallback

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

◆ SOMError()

const char* SOMError ( int error )

Return string for error code.

Parameters

error [in] error code

Returns: Pointer to NUL terminated string for error

◆ SOMSetService()

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

◆ SOMSessionAuthenticated()

int SOMSessionAuthenticated ( struct SOMSession * session )

Return TRUE if session authenticated, FALSE otherwise.

Parameters

session [in] session to query

Returns: TRUE / FALSE

◆ SOMInit()

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.

◆ SOMEventPoll()

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.

◆ SOMEventPollSingle()

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.

◆ SOMSessionSetTLS()

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.

◆ SOMSessionSetSessionCallback()

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

◆ SOMSessionOpen()

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.

◆ SOMSessionOpenRole()

int SOMSessionOpenRole	(	struct SOMSession *	session,
		const char *	host,
		int	port,
		const char *	username,
		const char *	password,
		const char *	role,
		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
role	[in] SASL id for Role
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. The Role ID should identify an MMRole entry which the user is to assume, or NULL if the username value is to be used.

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.

◆ SOMSessionOpenMech()

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.

◆ SOMSessionOpenMechRole()

int SOMSessionOpenMechRole	(	struct SOMSession *	session,
		const char *	host,
		int	port,
		const char *	username,
		const char *	passwd,
		const char *	role,
		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
role	[in] SASL id for Role
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. The Role ID should identify an MMRole entry which the user is to assume, or NULL if the username value is to be used.

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.

◆ SOMSessionClose()

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.

◆ SOMSessionDelete()

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.

◆ SOMSessionClear()

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.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ SOM_FACILITY_MULTITHREADED

Typedef Documentation

◆ SOMSessionCallback

Function Documentation

◆ SOMError()

◆ SOMSetService()

◆ SOMSessionAuthenticated()

◆ SOMInit()

◆ SOMEventPoll()

◆ SOMEventPollSingle()

◆ SOMSessionSetTLS()

◆ SOMSessionSetSessionCallback()

◆ SOMSessionOpen()

◆ SOMSessionOpenRole()

◆ SOMSessionOpenMech()

◆ SOMSessionOpenMechRole()

◆ SOMSessionClose()

◆ SOMSessionDelete()

◆ SOMSessionClear()