Overview of the LiMo Messaging API

The following sections describe the Common structures and MAPI Functions the LiMo Messaging API provides to the application. In addition, the concepts of a Session and Request are discussed.

Common structures

In MAPI, there are few main concepts of data:

Message

In LiMo messaging, a message represents data for a SMS, MMS, e-mail or i-mode message. A message is not specific to any one service, but supports the extension of this structure. For service-specific messages, please refer to Extendability.

Each message has a unique messageId in the entire messaging framework. The message information can be retrieved from the storage by its messageId.

For each message, there is one account attached to it. The concept is embodied on there is accountId field in _MSG_MESSAGE_S. If storageId field is not set, then the defaultStorageId in attached account would be used. For more information on account, please refer to Account

This concept is defined in Msg_Mapi_Message.h

Folder

A folder represents a container of messages or other folders. It should have only one parent folder, and zero or more children.

Each folder has a unique folderId in the entire messaging framework. The folder information can be retrieved from the storage by its folderId.

A folder can specify where it is stored. The storage where a folder is stored can be different from the storage where its containing messages are stored.

One of special folders is called "root folder", which is top-level folder and contains five predefined folders, which are:

  • INBOX,
  • OUTBOX,
  • DRAFTS,
  • SENT, and
  • DELETED
The predefined folders cannot be created or deleted individually, instead they can be created and deleted during the corrsponding operations on its root folder.

This concept is defined in Msg_Mapi_Folder.h

Account

An account represents the personal setting information for a message type. For example, an e-mail account can include such information as e-mail address, and SMS can include message center number.

Each account has a unique accountId in the entire messaging framework. The account information can be retrieved from the storage by its accountId. The account id is the reference being used by other types of structure, such as message and folder.

A message type can be associated with more than one accounts, and has one default account. However, one message has only one account. If application has not selected any account, then the default account takes effect. An account has an attribute called rootFolder, which defines the root folder having association with that account. As name suggested, rootFolder field needs to be set with root folder only, other folder cannot be set. A folder could be shared among different accounts.

This concept is defined in Msg_Mapi_Account.h

Session, Request and Filter Rules

Session

Session is the connection between application and MAPI for message reception and transmission.

When an application wants to send or receive a message, it must create and connect a session first. A session can be assigned with following information:

  • Register MsgOnMessageIncomingCallback function.
  • Register MsgOnStatusChangedCallback function.
  • Set priority. For details please refer to MsgSetPriority
  • Set filter rule.
One application can create and connect more than one sessions, different sessions can be assigned with different priorities and filter rules.

To know how to use asynchronous callback for communication between application and framework, please refer to Callback Functions

Request

A request contains the information that is used to command framework for services, such as sending a message. A request is sent to Messaging Framework via a session, and Messaging Framework chooses proper plugin to handle the request.

A common usage for the request is to send a message. And the request type is predefined as MSG_REQUEST_TYPE_SEND.

This concept is defined in Msg_Mapi_Message_Request.h

Callback Functions

Callback is used by application to detect incoming message and underlayer status change. Two callback functions prototype are provided:

  • one is MsgOnMessageIncomingCallback, which is to listen incoming message,
  • the other is MsgOnStatusChangedCallback, which is to listen underlayer status change.
Both callback functions are implemented by applications and should be bound to a session.

Filter and Filter List

When an application is only interested in some kinds of messages, filter list is used to filter these specific messages and return them to the application.

Noted that filter is for filtering incoming messages, not a storage concept. For storage, the filter concept is called Query.

Filter is the basic unit to set the rules, it tells the filter service how to filter the message. Filter list is composed of various filters. They are defined in Msg_Mapi_FilterRule.h .

Application can set a filter list for a session to get the interesting message. Please refer to _MSG_FILTER_S and _MSG_FILTER_LIST_S for details.

MAPI does NOT define any filters. Application developers should refer to the specific implementation of filter service to get the supported filters.

Storage

Connection

A connection is a logical concept between client application and LiMo Messaing framework. It does NOT represent the physical storage connection underneath the MAPI. A connection is required by the storage functions, such as adding message, as their first parameter.

There are found status in connection's life-cycle:

  • created(but-not-yet-connected),
  • connected,
  • disconnected and
  • destroyed.
The following functions are responsible to change life-cycle status:

For more information, please refer to Msg_Mapi_Storage_Manager.h

Storage

Storage is a collection of messages and related information that are stored on one storage media. Storage media is the physical data storage device, such as SD card and Flash. One storage media can have more than one storages.

For example, on flash storage media, there are two storages which are located at two different folders: /flash/Folder1/ and /flash/Folder2/ respectively. Since storage media can be removable, the storages on the media can be detached and attached dynamically. For instance, user plugs out SD card from UE 1 and plugs in this card into UE 2, all the messages stored in this card will be hidden from UE 1 and be visible to UE 2.

For details information, please refer to _MSG_STORAGE_REGISTRY_S

Application can query supported storages by MAPI method MsgListStorageRegistry and MsgGetStorageRegistry.

For sample code, please refer to Storage General: Initializing Storage

Query

LiMo Messaging supports query on message retrieval from storage.

Query rule, represented by _MSG_QUERY_S, is a rule to specify a single search criteria for messages. Query rule list, represented by _MSG_QUERY_LIST_S, is composed of a number of query rules. If one message satisfies one of query rule in the list, it satisfies the query rule list.

For more information on how to use Query, please refer to MsgQueryMessage .

Sort

LiMo Messaging supports sort on message retrieval from storage.

Sort rule, represented by _MSG_SORT_RULE_S, defines which field in message structure is sorted on, and how this field is sorted.

Sort type, represented by _MSG_SORT_TYPE_T, defines which field can be sorted on.

For more information on how to use Sort, please refer to MsgQueryMessage .

Extendability

There are several structures in LiMo Messageing designed to be extended. They are:

In these structures, there are two fields for data extension, which are :

  • pExtData
  • extDataSize
pExtData, of type void *, can hold a pointer to any structure. Noted that the pointed structure cannot contain any pointer as its field, since the extended data will be treated as a memory block to pass around between applications and plugins, any inside pointer would not be handled properly.

extDataSize, of type size_t, indicates the length of the pExtData block.

MAPI Functions

This section describes the functions that MAPI provides.

Message Sending and Receiving

The Message sending and receiving module provides the unique interfaces to send and receive messages. The Session structure is the primary structure to hold the connection information. Applications use Session to send and receive messages.
The major functionality that the message sending and reception module provides are:

The following is the file for this module:

For more information, please see the sample code:

Storage Functionality

Storage Management

The Storage management module provides the management functionality for storage such as storage registry operations, storage data initialization etc. The major functions that the Storage Management module provides are: For more information, please see the sample code:

Message Storage

The major functions that the message storage module provides are:

The functionality is defined in:

For more information, please see the sample code:

Folder Storage

The major functionality that folder storage module provides:

The functionality is defined in: For more information, please see the sample code:

Account Storage

The major functionality that the Account storage module provides:

The functionality is defined in:

For more information, please see the sample code:
Generated on Mon Mar 31 01:01:00 2008 by  doxygen 1.5.4