MAP

The Message Access Profile (MAP) defines the features and procedures that shall be used by devices that exchange message objects. More...

Macros
#define	bt_map_read_msg_listing(session, folder_name, folder_name_len)   bt_map_read_msg_listing_ex(session, folder_name, folder_name_len, 1024, 0)
	Read messages listing from a MSE. More...

Functions
bt_bool	bt_map_init (void)
	Initialize the MAP layer. More...
bt_map_session_t *	bt_map_allocate_session (void)
	Allocate MAP session. More...
void	bt_map_free_session (bt_map_session_t *psess)
	Release MAP session. More...
bt_bool	bt_map_connect (bt_map_session_t *session, bt_byte instance, bt_bdaddr_t *pbdaddr_remote, bt_map_session_callback_pf callback, void *param)
	Connect to a remote MSE. More...
bt_bool	bt_map_mns_listen (bt_map_session_t *session, bt_byte server_channel, bt_map_session_callback_pf callback, void *param)
	Listen for notifications from MSE. More...
bt_bool	bt_map_disconnect (bt_map_session_t *session)
	Disconnect from a remote device. More...
bt_bool	bt_map_read_folder (bt_map_session_t *session, bt_byte *folder_name, bt_uint folder_name_len)
	Read a folder from a remote device. More...
bt_bool	bt_map_register_notifications (bt_map_session_t *session, bt_bool on)
	Enable or disable notification from MSE. More...
bt_bool	bt_map_update_inbox (bt_map_session_t *session)
	Update a MSE inbox. More...
bt_bool	bt_map_read_msg_listing_ex (bt_map_session_t *session, bt_byte *folder_name, bt_uint folder_name_len, bt_uint max_list_count, bt_uint list_start_offset)
	Read messages listing from a MSE. More...
bt_bool	bt_map_setpath (bt_map_session_t *session, const bt_byte *folder_name, bt_uint folder_name_len)
	Set current folder in a MSE. More...
bt_bool	bt_map_read_msg (bt_map_session_t *session, bt_byte *handle, bt_byte transcode_utf8)
	Read a message from a MSE. More...
bt_bool	bt_map_set_msg_status (bt_map_session_t *mMapSession, bt_byte *handle, bt_byte map_status_type, bt_byte status)
	Set a message's status in a MSE. More...
bt_bool	bt_map_push_message (bt_map_session_t *session, bt_byte *folder_name, bt_uint folder_name_len, bt_byte transparent, bt_byte retry, bt_byte charset)
	Push a message to a MSE. More...
bt_bool	bt_map_abort (bt_map_session_t *session)
	Abort current operation. More...

Detailed Description

The Message Access Profile (MAP) defines the features and procedures that shall be used by devices that exchange message objects.

It is based on a Client-Server interaction model where the Client initiates the transactions.

Macro Definition Documentation

#define bt_map_read_msg_listing	(		session,
			folder_name,
			folder_name_len
	)		bt_map_read_msg_listing_ex(session, folder_name, folder_name_len, 1024, 0)

Read messages listing from a MSE.

This function retrieves messages listing from a MSE. This function reads maximum 1024 messages starting from the first message.

Parameters

session	MAP session.
folder_name	The name of the folder from which the messages listing is to be retrieved.
folder_name_len	The length of the folder's name.

Returns

• TRUE if the function succeeds.
• FALSE otherwise.

Function Documentation

bt_bool bt_map_abort

(

bt_map_session_t *

session

)

Abort current operation.

This function aborts current operation initiated from a MCE.

Parameters

session

MAP session.

Returns

• TRUE if the function succeeds.
• FALSE otherwise.

bt_map_session_t* bt_map_allocate_session

(

void

)

Allocate MAP session.

This function allocates new MAP session.

Returns

• A pointer to the new MAP session structure if the function succeeds.
• NULL otherwise.

bt_bool bt_map_connect	(	bt_map_session_t *	session,
		bt_byte	instance,
		bt_bdaddr_t *	pbdaddr_remote,
		bt_map_session_callback_pf	callback,
		void *	param
	)

Connect to a remote MSE.

This function establishes a MAP connection with a remote device which is running MAS server. Changes in the session state are reported through a callback function.

Parameters

session	MAP session.
instance	MAS instance.
remote_addr	Address of the remote device.
callback	The callback function that will be called when the MAP generates an event.
param	A pointer to arbitrary data to be passed to the callback function.

Returns

• TRUE if the function succeeds.
• FALSE otherwise. The callback function is not called in this case.

bt_bool bt_map_disconnect

(

bt_map_session_t *

session

)

Disconnect from a remote device.

This function closes a MAP connection with a remote device. Changes in the session state are reported through a callback function set in bt_map_connect call.

Parameters

session

MAP session.

Returns

• TRUE if the function succeeds.
• FALSE otherwise.

void bt_map_free_session

(

bt_map_session_t *

psess

)

Release MAP session.

This function deallocated the specified MAP session. This function does not disconnect the session. It just frees the memory used by the bt_map_session_t structure. The session has to be disconnected by a remote device or by calling bt_map_disconnect.

Parameters

session

The MAP session to be deallocated.

bt_bool bt_map_init

(

void

)

Initialize the MAP layer.

This function initializes the MAP layer of the stack. It must be called prior to any other MAP function is called.

bt_bool bt_map_mns_listen	(	bt_map_session_t *	session,
		bt_byte	server_channel,
		bt_map_session_callback_pf	callback,
		void *	param
	)

Listen for notifications from MSE.

This function starts listening for OBEX requests from a MCE.

• Connect
• Disconnect
• Put
• Get
• Abort
• SetPath

Parameters

session	MAP session.
server_channel	RFCOMM channel to listent on.
callback	The callback function that will be called when the MAP generates an event.
param	A pointer to arbitrary data to be passed to the callback function.

Returns

• TRUE if the function succeeds.
• FALSE otherwise. The callback function is not called in this case.

bt_bool bt_map_push_message	(	bt_map_session_t *	session,
		bt_byte *	folder_name,
		bt_uint	folder_name_len,
		bt_byte	transparent,
		bt_byte	retry,
		bt_byte	charset
	)

Push a message to a MSE.

This function sends a message to a MSE. The app should supply the body of the message through the session callback. When this function is called it will send a MAP_SESSION_GET_MSG_FRAGMENT event to the app. The parameter to this event is of type bt_map_get_msg_fragment_t. The len field indicates the buffer size. The app should fill the buffer and set the len to the actual number of bytes copied. Once th fragment was sent to the MSE new MAP_SESSION_GET_MSG_FRAGMENT is sent to the app. This process repeats until the app has copied the entire message and set the len to 0. After that a MAP_SESSION_PUT_MSG_COMPLETED event is sent to the app.

Parameters

session	MAP session.
folder_name	The name of the folder to send a message to.
folder_name_len	The length of the folder's name.
transparent	This parameter is used to indicate to the MSE that no copy of the message shall be kept in the 'Sent' folder after the message was sent. 0 - Save the copy of the message in the the 'Sent' folder. 1 - Do not save the copy of the message in the the 'Sent' folder.
retry	This parameter is used to indicate whether successive attempts at sending the message shall be carried out in case the cellular network is not accessible when the message is sent from the MCE to the outbox of the MSE. 0 - Do not retry sending the message if network is not available. 1 - Retry sending the message if network is not available.

Returns

• TRUE if the function succeeds.
• FALSE otherwise.

bt_bool bt_map_read_folder	(	bt_map_session_t *	session,
		bt_byte *	folder_name,
		bt_uint	folder_name_len
	)

Read a folder from a remote device.

This function reads content of a folder from a MSE.

Parameters

session	MAP session.
folder_name	The name of the folder.
folder_name_len	The length of the folder's name.

Returns

• TRUE if the function succeeds.
• FALSE otherwise.

bt_bool bt_map_read_msg	(	bt_map_session_t *	session,
		bt_byte *	handle,
		bt_byte	transcode_utf8
	)

Read a message from a MSE.

This function is used to read a message a MSE. If the message is long it will be split in several fragments. The received fragments are reported to the app via session calback with MAP_SESSION_GET_MSG_FRAGMENT event. When complete message is received MAP_SESSION_GET_MSG_COMPLETED event is sent to the app.

Parameters

session	MAP session.
handle	The message handle.
transcode_utf8	Indicates if message should be delivered in native charset or transcoded to UTF-8.

Returns

• TRUE if the function succeeds.
• FALSE otherwise.

bt_bool bt_map_read_msg_listing_ex	(	bt_map_session_t *	session,
		bt_byte *	folder_name,
		bt_uint	folder_name_len,
		bt_uint	max_list_count,
		bt_uint	list_start_offset
	)

Read messages listing from a MSE.

This function retrieves messages listing from a MSE.

Parameters

session	MAP session.
folder_name	The name folder from which the messages listing is to be retrieved.
folder_name_len	The length of the folder's name.
max_list_count	The maximum number of messages to return.
list_start_offset	The first message to return.

Returns

• TRUE if the function succeeds.
• FALSE otherwise.

bt_bool bt_map_register_notifications	(	bt_map_session_t *	session,
		bt_bool	on
	)

Enable or disable notification from MSE.

This function enables or disables notifications in a MCE from a MSE about the arrival of new messages.

Parameters

session	MAP session.
folder_name	The name of the folder.
folder_name_len	The length of the folder's name.

Returns

• TRUE if the function succeeds.
• FALSE otherwise.

bt_bool bt_map_set_msg_status	(	bt_map_session_t *	mMapSession,
		bt_byte *	handle,
		bt_byte	map_status_type,
		bt_byte	status
	)

Set a message's status in a MSE.

This function is used to set the status of a message in a MSE.

Parameters

session	MAP session.
handle	The message handle.
map_status_type	The type of status to set. 0 - read 1 - deleted
status	The value of the status 0 - read 1 - deleted

Returns

• TRUE if the function succeeds.
• FALSE otherwise.

bt_bool bt_map_setpath	(	bt_map_session_t *	session,
		const bt_byte *	folder_name,
		bt_uint	folder_name_len
	)

Set current folder in a MSE.

This function is used to navigate the folder of a MSE.

Parameters

session	MAP session.
folder_name	The name folder.
folder_name_len	The length of the folder's name.

Returns

• TRUE if the function succeeds.
• FALSE otherwise.

bt_bool bt_map_update_inbox

(

bt_map_session_t *

session

)

Update a MSE inbox.

This function intitates an update of a MSE's inbox.

Parameters

session

MAP session.

Returns

• TRUE if the function succeeds.
• FALSE otherwise.