Msg_Mapi_Session.h File Reference

Detailed Description

Defines session handling and message sending and receiving related functions.

#include "Msg_Mapi_Message.h"
#include "Msg_Mapi_Message_Status.h"
#include "Msg_Mapi_Message_Request.h"
#include "Msg_Mapi_Types.h"
#include "Msg_Mapi_FilterRule.h"


Typedefs
typedef struct MessagingSession *	MSG_SESSION_HANDLE_T
	Defines a session handle.
typedef void(*	MsgOnMessageIncomingCallback )(MSG_MESSAGE_S pMsgInfo, MSG_MESSAGE_STATUS_S pMsgStatus, MSG_SESSION_HANDLE_T hSession)
	Prototype of the function that will be called when a new message received.
typedef void(*	MsgOnStatusChangedCallback )(MSG_MESSAGE_STATUS_S *pMsgStatus, MSG_SESSION_HANDLE_T hSession)
	Prototype of the function that will be called when status changed.
Functions
MSG_ERROR_T	MsgCreateSession (MSG_SESSION_HANDLE_T *hSession)
	Creates a session handle.
MSG_ERROR_T	MsgDestroySession (MSG_SESSION_HANDLE_T hSession)
	Destroys the session handle.
MSG_ERROR_T	MsgRegMessageCallback (MSG_SESSION_HANDLE_T hSession, MsgOnMessageIncomingCallback onMsgIncoming)
	Registers MsgOnMessageIncomingCallback function to the session handle.
MSG_ERROR_T	MsgRegStatusCallback (MSG_SESSION_HANDLE_T hSession, MsgOnStatusChangedCallback OnStatusChanged)
	Registers MsgOnStatusChangedCallback to the session handle.
MSG_ERROR_T	MsgConnectSession (MSG_SESSION_HANDLE_T hSession)
	Connects the session handle.
MSG_ERROR_T	MsgDisconnectSession (MSG_SESSION_HANDLE_T hSession)
	Disconnects the session handle.
MSG_ERROR_T	MsgSetPriority (MSG_SESSION_HANDLE_T hSession, MSG_SESSION_PRIORITY_T priority)
	Sets priority for the session handle.
MSG_ERROR_T	MsgSetFilterList (MSG_SESSION_HANDLE_T hSession, const MSG_FILTER_LIST_S *pFilterList)
	Sets filter list to the session handle.
MSG_ERROR_T	MsgSubmitReq (MSG_SESSION_HANDLE_T hSession, const MSG_MESSAGE_REQUEST_S pReq, MSG_REQUEST_ID_T pReqId)
	Submits a request.
MSG_ERROR_T	MsgCancelReq (MSG_SESSION_HANDLE_T hSession, MSG_REQUEST_ID_T reqId)
	Cancels a request by request id.
MSG_ERROR_T	MsgGetAllSupportedMsgType (MSG_MESSAGE_TYPE_LIST_S *pMsgTypeList)
	Gets all supported message types.
void	MsgReleaseMsgTypeList (MSG_MESSAGE_TYPE_LIST_S *pMsgTypeList)
	Releases the memory of message type List.
MSG_ERROR_T	MsgGetAllSupportedFilterId (MSG_FILTER_ID_LIST_S *pFilterIdList)
	Gets all supported filter id.
void	MsgReleaseFilterIdList (MSG_FILTER_ID_LIST_S *pFilterIdList)
	Releases the memory of filter Id List.
MSG_PLUGIN_ERROR_T	MsgGetSessionPluginError (MSG_SESSION_HANDLE_T hSession)
	Get session specific plugin error.

Typedef Documentation

typedef struct MessagingSession* MSG_SESSION_HANDLE_T

Defines a session handle.

For details of Session, please refer to Session

typedef void(* MsgOnMessageIncomingCallback)(MSG_MESSAGE_S *pMsgInfo, MSG_MESSAGE_STATUS_S *pMsgStatus, MSG_SESSION_HANDLE_T hSession)

Prototype of the function that will be called when a new message received.

Applications SHOULD implement this callback function and register it into a session handle. For how to register this callback function, please refer to MsgRegMessageCallback. This callback function will be called when a new message received and the message satisfies the filter list which is attached to the session handle. The callback function runs in application process, not in framework process. The memory for pMsgInfo and pMsgStatus are managed by MAPI, when the callback function is finished, the memory will be released by MAPI automatically.

Parameters:

`[in]`	pMsgInfo	is a pointer to the received message.
`[in]`	pMsgStatus	is a pointer to the status.
`[in]`	hSession	is a session handle. It indicates which session is invoked.

Returns:: void

Please refer to Callback Functions

Since:: 1.0

typedef void(* MsgOnStatusChangedCallback)(MSG_MESSAGE_STATUS_S *pMsgStatus, MSG_SESSION_HANDLE_T hSession)

Prototype of the function that will be called when status changed.

Applications SHOULD to implement this callback function and register it into a session handle. For how to register this callback function, please refer to MsgRegStatusCallback. For instance, if application sends a message, this callback function will be called to report sending status. Application can get the request id from pMsgStatus to know which request the status is bound. The callback function runs in user application process, not in framework process. The memory of pMsgStatus is managed by MAPI, when the callback function is finished, the memory will be released by MAPI automatically.

Parameters:

`[in]`	pMsgStatus	is a pointer to the status.
`[in]`	hSession	is a session handle. It indicates which session is invoked.

Returns:: void

Note:: Please refer to Callback Functions

Since:: 1.0

Function Documentation

MSG_ERROR_T MsgCancelReq	(	MSG_SESSION_HANDLE_T	hSession,
		MSG_REQUEST_ID_T	reqId
	)

Cancels a request by request id.

If cancel successfully, status "MSG_STATUS_REQ_CANCELLED" will be sent back. If cancel failed, no special status will be sent back.
If reqId is invalid, MSG_ERR_INVALID_REQUEST_ID will be returned.

: This is an asynchronous function.

Parameters:

`[in]`	hSession	is a pointer to an established session handle.
`[in]`	reqId	is the request id of the request to be cancelled.

Returns:: MSG_ERROR_T

Return values:

	MSG_SUCCESS	submits the "cancel request" request to framework successfully.
	MSG_ERR_INVALID_SESSION_HANDLE	the session handle is invalid.
	MSG_ERR_SESSION_NOT_CONNECTED	session is not connected.
	MSG_ERR_COMMUNICATION_ERROR	communication between client and server is error.
	MSG_ERR_MEMORY_ERROR	memory is error.
	MSG_ERR_INVALID_REQUEST_ID	request id is error.
	MSG_ERR_PLUGIN	the generic error code for plugin. Call MsgGetSessionPluginError() to get detail error code.

Note:: The result information will be sent back by using callback function MsgOnStatusChangedCallback

Since:: 1.0

MSG_ERROR_T MsgConnectSession ( MSG_SESSION_HANDLE_T hSession )

Connects the session handle.

This function MUST be called after session handle is created.
It is the precondition to call functions MsgSubmitReq, MsgSetPriority, MsgSetFilterList, MsgCancelReq and MsgGetAllSupportedFilterId

Parameters:

[in] hSession is a pointer to an session handle.

Returns:: MSG_ERROR_T

Return values:

	MSG_SUCCESS	connects the session handle successfully.
	MSG_ERR_INVALID_SESSION_HANDLE	the session handle is invalid.
	MSG_ERR_COMMUNICATION_ERROR	communication between client and server is error.
	MSG_ERR_MEMORY_ERROR	memory is error.

Since:: 1.0

MSG_ERROR_T MsgCreateSession ( MSG_SESSION_HANDLE_T * hSession )

Creates a session handle.

This function creates a session handle. Each application can call this function multiple times to create more than one session handles. All session handles are independent. For details of session, please refer to Session.

Parameters:

[out] hSession is a pointer to a session handle. When this function returns MSG_SUCCESS, *hSession will be valid session handle. Otherwise, it will be NULL.

Returns:: MSG_ERROR_T

Return values:

	MSG_SUCCESS	creates session handle successfully.
	MSG_ERR_NULL_POINTER	the input parameter is NULL.
	MSG_ERR_MEMORY_ERROR	memory is error.

Since:: 1.0

MSG_ERROR_T MsgDestroySession ( MSG_SESSION_HANDLE_T hSession )

Destroys the session handle.

This function destroys a session handle. This function releases resources and disconnects session if it's connected. Once a session handle is destroyed, it can't be used any more. For each created session, applications MUST destroy it, when it's not used any more. If the input parameter is NULL, this function does nothing and returns MSG_ERR_INVALID_SESSION_HANDLE.

Parameters:

[in] hSession is a pointer to an session handle to be destroyed.

Returns:: MSG_ERROR_T

Return values:

	MSG_SUCCESS	destroyes the handle successfully.
	MSG_ERR_INVALID_SESSION_HANDLE	the session handle is invalid.
	MSG_ERR_COMMUNICATION_ERROR	communication between client and server is error.

Since:: 1.0

MSG_ERROR_T MsgDisconnectSession ( MSG_SESSION_HANDLE_T hSession )

Disconnects the session handle.

If the session is NULL, this function does nothing and returns MSG_ERR_INVALID_SESSION_HANDLE.

Parameters:

[in] hSession is a pointer to an session handle.

Returns:: MSG_ERROR_T

Return values:

	MSG_SUCCESS	disconnects the session handle successfully.
	MSG_ERR_INVALID_SESSION_HANDLE	the session handle is invalid.
	MSG_ERR_SESSION_NOT_CONNECTED	the session handle is not connected.
	MSG_ERR_COMMUNICATION_ERROR	communication between client and server is error.
	MSG_ERR_MEMORY_ERROR	memory is error.

Since:: 1.0

MSG_ERROR_T MsgGetAllSupportedFilterId ( MSG_FILTER_ID_LIST_S * pFilterIdList )

Gets all supported filter id.

Parameters:

[out] pFilterIdList is a pointer to a filter id list.

Returns:: MSG_ERROR_T

Return values:

	MSG_SUCCESS	gets all supported filter id successfully.
	MSG_ERR_NULL_POINTER	pFilterIdList is NULL.
	MSG_ERR_MEMORY_ERROR	memory is error.
	MSG_ERR_COMMUNICATION_ERROR	communication between client and server is error

MSG_ERROR_T MsgGetAllSupportedMsgType ( MSG_MESSAGE_TYPE_LIST_S * pMsgTypeList )

Gets all supported message types.

Parameters:

[out] pMsgTypeList is a pointer to a message type list.

Returns:: MSG_ERROR_T

Return values:

	MSG_SUCCESS	gets all supported message types successfully.
	MSG_ERR_NULL_POINTER	pMsgTypeList is NULL.
	MSG_ERR_MEMORY_ERROR	memory is error.
	MSG_ERR_COMMUNICATION_ERROR	communication between client and server is error

MSG_PLUGIN_ERROR_T MsgGetSessionPluginError ( MSG_SESSION_HANDLE_T hSession )

Get session specific plugin error.

This function is to get the specific plugin error. In case that some functions return MSG_ERR_PLUGIN, applications can call this function immediately to get specific error code of the plugins. If hSession is invalid, this function will return 0.

Parameters:

[in] hSession is a pointer to an established session handle.

Returns:: MSG_PLUGIN_ERROR_T

MSG_ERROR_T MsgRegMessageCallback	(	MSG_SESSION_HANDLE_T	hSession,
		MsgOnMessageIncomingCallback	onMsgIncoming
	)

Registers MsgOnMessageIncomingCallback function to the session handle.

Applications SHOULD implement the function MsgOnMessageIncomingCallback. For details, please refer to MsgOnMessageIncomingCallback

Applications MAY deregister the callback function MsgOnMessageIncomingCallback by invoking this function like MsgRegMessageCallback(hSession, NULL).

This function MUST be called after session handle is created. It makes no difference to call this function before or after session connected. This function can be called more times and the last inovking will be effective.

Parameters:

`[in]`	hSession	is a pointer to an session handle.
`[in]`	onMsgIncoming	is a function pointer to an implemenation function.

Returns:: MSG_ERROR_T

Return values:

	MSG_SUCCESS	registers the call back function successfully
	MSG_ERR_INVALID_SESSION_HANDLE	the session handle is invalid.
	MSG_ERR_MEMORY_ERROR	memory is error.

Since:: 1.0

MSG_ERROR_T MsgRegStatusCallback	(	MSG_SESSION_HANDLE_T	hSession,
		MsgOnStatusChangedCallback	OnStatusChanged
	)

Registers MsgOnStatusChangedCallback to the session handle.

Applications SHOULD implement the function MsgOnStatusChangedCallback. For details, please refer to MsgOnStatusChangedCallback

Applications MAY deregister the callback function MsgOnStatusChangedCallback by invoking this function like MsgRegStatusCallback(hSession, NULL).

Parameters:

`[in]`	hSession	is a pointer to an session handle.
`[in]`	OnStatusChanged	is a function pointer to an implemenation function.

Returns:: MSG_ERROR_T

Return values:

	MSG_SUCCESS	registers the call back function successfully.
	MSG_ERR_INVALID_SESSION_HANDLE	the session handle is invalid.
	MSG_ERR_MEMORY_ERROR	memory is error.

Since:: 1.0

void MsgReleaseFilterIdList ( MSG_FILTER_ID_LIST_S * pFilterIdList )

Releases the memory of filter Id List.

This function releases the memory of filterIds in MSG_FILTER_ID_LIST_S structure.

If pFilterIdList or pFilterIdList->filterIds is NULL, nothing happens. If pFilterIdList or pFilterIdList->filterIds is invalid, undefined behavior.

Note:: This function only frees the list pointer member inside the structure. It doesn't free the structure itself.

Parameters:

[in] pFilterIdList is a pointer to an MSG_FILTER_ID_LIST_S structure.

Since:: 1.0

void MsgReleaseMsgTypeList ( MSG_MESSAGE_TYPE_LIST_S * pMsgTypeList )

Releases the memory of message type List.

This function releases the memory of pMsgTypes in MSG_MESSAGE_TYPE_LIST_S structure. If pMsgTypeList or pMsgTypeList->pMsgTypes is NULL, nothing happens. If pMsgTypeList or pMsgTypeList->pMsgTypes is invalid, undefined behavior.

Note:: This function only frees the list pointer member inside the structure. It doesn't free the structure itself.

Parameters:

[in] pMsgTypeList is a pointer to a MSG_MESSAGE_TYPE_LIST_S structure.

Since:: 1.0

MSG_ERROR_T MsgSetFilterList	(	MSG_SESSION_HANDLE_T	hSession,
		const MSG_FILTER_LIST_S *	pFilterList
	)

Sets filter list to the session handle.

This function sets the filter list to a session handle. It impacts the callback functions. Only the received messages satisfying one filter in the filter list can be passed up to the callback function. Otherwise, the callback function will not be called. For details of filter list, please refer to MSG_FILTER_LIST_S

This function MUST be called after session is created and connected. This function can be called more times and the last one will be effective. If no filter list is set to the session or pFilterList is NULL, all the messages will be received by the session.

Parameters:

`[in]`	hSession	is a pointer to an established session handle.
`[in]`	pFilterList	is a pointer to the filter list for the session handle.

Returns:: MSG_ERROR_T

Return values:

	MSG_SUCCESS	sets the filter list successfully.
	MSG_ERR_INVALID_SESSION_HANDLE	the session handle is invalid.
	MSG_ERR_SESSION_NOT_CONNECTED	the session handle is not connected.
	MSG_ERR_INVALID_FILTER_ID	the filter id in pFilterList is invalid.
	MSG_ERR_COMMUNICATION_ERROR	communication between client and server is error.
	MSG_ERR_MEMORY_ERROR	memory is error.

Since:: 1.0

MSG_ERROR_T MsgSetPriority	(	MSG_SESSION_HANDLE_T	hSession,
		MSG_SESSION_PRIORITY_T	priority
	)

Sets priority for the session handle.

This function sets the priority for a session handle. The following use case shows the usage of priority:
When a messaging is received, if this message satisfies the filter rule of this session and intercept of the satisfied filter rule is set true, this message will be passed to this session callback function and will not be passed to lower priority session callback functions.

All the sessions will receive the messages if they have same priority.

For details of intercept, please refer to Intercept.

This function MUST be called after session is created and connected. This function can be called more times and the last invoking will be effective.

If this function is not called, the default priority is MSG_SESSION_PRIORITY_NORMAL.

Parameters:

`[in]`	hSession	is a pointer to a session handle.
`[in]`	priority	is for the session handle.

Returns:: MSG_ERROR_T

Return values:

	MSG_SUCCESS	sets the priority successfully.
	MSG_ERR_INVALID_SESSION_HANDLE	the session handle is invalid.
	MSG_ERR_SESSION_NOT_CONNECTED	the session handle is not connected.
	MSG_ERR_INVALID_SESSION_PRIORITY	the priority is invalid.
	MSG_ERR_COMMUNICATION_ERROR	communication between client and server is error.
	MSG_ERR_MEMORY_ERROR	memory is error.

Since:: 1.0

MSG_ERROR_T MsgSubmitReq	(	MSG_SESSION_HANDLE_T	hSession,
		const MSG_MESSAGE_REQUEST_S *	pReq,
		MSG_REQUEST_ID_T *	pReqId
	)

Submits a request.

To submit a request, applications need to specify the reqType in request structure: For example, to send a message, applications need to set reqType with value MSG_REQUEST_TYPE_SEND.

reqId will be filled by this function automatically and return to application.

Following is the sample code to send a message:

    MSG_SESSION_HANDLE_T session;
    MSG_MESSAGE_REQUEST_S req;
    MSG_MESSAGE_S msg;
    //.... init session and msg.
    //Set request type
    req.reqType = MSG_REQUEST_TYPE_SEND;
    //Set msg
    req.mpMsg = &msg;
    //Submit request.
    MsgSubmitReq(session, &req);

Message plugins can extend the request types to provide more functions. Please refer to enum MSG_REQUEST_TYPE_T to define the extended request types. When applications submit these requests, the framework will pass the requests to the underlaying plugins.

If pReq->reqType is invalid, an asynchronous status with error "MSG_ERR_INVALID_REQUEST" will be sent back.

For request type "MSG_REQUEST_TYPE_SEND" and "MSG_REQUEST_TYPE_SENDSAVE":
Applications MUST fill valid message type for field pReq->msgType, otherwise, MSG_ERR_INVALID_REQUEST will be returned immediately.

If pReq->pMsg->accountId is MSG_DEFAULT_ACCOUNT_ID, then the default account is used.
If pReq->pMsg->accountId is not valid, the function returns "MSG_ERR_INVALID_REQUEST".

For request type "MSG_REQUEST_TYPE_SEND", following fields will be ignored:
pReq->pMsg->msgId, pReq->pMsg->parentId, pReq->pMsg->storageId.

For request type "MSG_REQUEST_TYPE_SENDSAVE", if valid pReq->pMsg->parentId and pReq->pMsg->storageId are given, they override the default values in account information. If pReq->pMsg->parentId is MSG_DEFAULT_FOLDER_ID, the message will be added to the outbox in its associated account. If pReq->pMsg->storageId is MSG_STORAGE_DEFAULT, the message will be added to the defaultMsgStorageId in its associated account.

: This is an asynchronous function.

Parameters:

`[in]`	hSession	is a pointer to an established session handle.
`[in]`	pReq	is the request to be submitted.
`[out]`	pReqId	is the id of this request. This id is assigned by framework automatically. Applications can keep this id and use MsgCancelReq to cancel the request.

Returns:: MSG_ERROR_T.

Return values:

	MSG_SUCCESS	submits the request to framework successfully.
	MSG_ERR_NULL_POINTER	pReq is NULL or pReqId is NULL.
	MSG_ERR_INVALID_SESSION_HANDLE	the session handle is invalid.
	MSG_ERR_SESSION_NOT_CONNECTED	session is not connected.
	MSG_ERR_INVALID_REQUEST	the message type in request is invalid. For request type "MSG_REQUEST_TYPE_SENDSAVE", some mandatory fields are invalid.
	MSG_ERR_COMMUNICATION_ERROR	communication between client and server is error.
	MSG_ERR_MEMORY_ERROR	memory is error.
	MSG_ERR_PLUGIN	the generic error code for plugin. Call MsgGetSessionPluginError() to get detail error code.

Note:: The result information will be sent back by using callback function MsgOnStatusChangedCallback.

Since:: 1.0

Generated on Mon Mar 31 01:01:00 2008 by

1.5.4

LiMo Foundation

Msg_Mapi_Session.h File Reference

Detailed Description

Typedefs

Functions

Typedef Documentation

Function Documentation