MAP

The Message Access Profile 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. In general MAP will be used to combine the messaging capabilities of a messaging server device and the user interface capabilities of a client device for notifying, browsing, reading, deleting, generation and sending of messages. This manual describes API definition and provides the capabilities of a client device for MAP.

Terminology and Concepts

MAP Profile Stack

The Baseband, LMP and L2CAP are the physical and data link layers of the Bluetooth Protocols. RFCOMM is the Bluetooth serial port emulation entity. SDP is the Bluetooth Service Discovery Protocol.

MAP Roles

  • MSE - This is the device that provides the message repository engine, i.e., has the ability to provide a client unit with messages that are stored in this device and notifications of changes in its message repository.

  • MCE - This is the device that uses the message repository engine of the MSE for browsing and displaying existing messages and to upload messages created on the MCE to the MSE.

MAP Services

  • MAS - Allows the MCE to browse messages on the MSE and to retrieve individual messages from the MSE.

  • MNS - Allows the MSE to send event reports to the MCE (e.g., message arrival notifications).

MAP Folder

Figure below shows the MAP virtual folder structure.

  • telecom\msg\inbox - This folder shall contain all the messages that have been received by the MSE.

  • telecom\msg\outbox - This folder shall contain all the messages that are queued for transmission by the MSE.

  • telecom\msg\sent - This folder shall contain messages that were successfully sent to the network by the MSE.

  • telecom\msg\draft - This folder is the repository for messages that have not been sent and may require further editing.

  • telecom\msg\deleted - This folder shall contain the messages that have been deleted on the MSE.

MAP SDP Record

There shall be one service record for MCE device.

#define RFC_MAP_MNS_CHANN_NUM           20        //user defined
#define L2CAP_MAP_MNS_PSM               0x1001    //user defined

const uint8_t map_mce_sdp_record[] =
{
    SDP_DATA_ELEM_SEQ_HDR,
    0x49,
    //attribute SDP_ATTR_SRV_CLASS_ID_LIST
    SDP_UNSIGNED_TWO_BYTE,
    (uint8_t)(SDP_ATTR_SRV_CLASS_ID_LIST >> 8),
    (uint8_t)SDP_ATTR_SRV_CLASS_ID_LIST,
    SDP_DATA_ELEM_SEQ_HDR,
    0x03,
    SDP_UUID16_HDR,
    (uint8_t)(UUID_MSG_NOTIFICATION_SERVER >> 8),
    (uint8_t)(UUID_MSG_NOTIFICATION_SERVER),

    //attribute SDP_ATTR_PROTO_DESC_LIST
    SDP_UNSIGNED_TWO_BYTE,
    (uint8_t)(SDP_ATTR_PROTO_DESC_LIST >> 8),
    (uint8_t)SDP_ATTR_PROTO_DESC_LIST,
    SDP_DATA_ELEM_SEQ_HDR,
    0x11,
    SDP_DATA_ELEM_SEQ_HDR,
    0x03,
    SDP_UUID16_HDR,
    (uint8_t)(UUID_L2CAP >> 8),
    (uint8_t)(UUID_L2CAP),
    SDP_DATA_ELEM_SEQ_HDR,
    0x05,
    SDP_UUID16_HDR,
    (uint8_t)(UUID_RFCOMM >> 8),
    (uint8_t)(UUID_RFCOMM),
    SDP_UNSIGNED_ONE_BYTE,
    RFC_MAP_MNS_CHANN_NUM,  //channel number
    SDP_DATA_ELEM_SEQ_HDR,
    0x03,
    SDP_UUID16_HDR,
    (uint8_t)(UUID_OBEX >> 8),
    (uint8_t)(UUID_OBEX),

    //Attribute SDP_ATTR_SRV_NAME
    SDP_UNSIGNED_TWO_BYTE,
    (uint8_t)((SDP_ATTR_SRV_NAME + SDP_BASE_LANG_OFFSET) >> 8),
    (uint8_t)(SDP_ATTR_SRV_NAME + SDP_BASE_LANG_OFFSET),
    SDP_STRING_HDR,
    0x0B,
    'R', 'e', 'a', 'l', 't', 'e', 'k', '-', 'M', 'N', 'S',

    //attribute SDP_ATTR_PROFILE_DESC_LIST
    SDP_UNSIGNED_TWO_BYTE,
    (uint8_t)(SDP_ATTR_PROFILE_DESC_LIST >> 8),
    (uint8_t)SDP_ATTR_PROFILE_DESC_LIST,
    SDP_DATA_ELEM_SEQ_HDR,
    0x08,
    SDP_DATA_ELEM_SEQ_HDR,
    0x06,
    SDP_UUID16_HDR,
    (uint8_t)(UUID_MSG_ACCESS_PROFILE >> 8),
    (uint8_t)UUID_MSG_ACCESS_PROFILE,
    SDP_UNSIGNED_TWO_BYTE,
    0x01,
    0x04,   //version 1.4

    //attribute SDP_ATTR_L2C_PSM
    SDP_UNSIGNED_TWO_BYTE,
    (uint8_t)((SDP_ATTR_L2C_PSM) >> 8),
    (uint8_t)(SDP_ATTR_L2C_PSM),
    SDP_UNSIGNED_TWO_BYTE,
    (uint8_t)(L2CAP_MAP_MNS_PSM >> 8),
    (uint8_t)(L2CAP_MAP_MNS_PSM),

    //attribute SDP_ATTR_MAP_SUPPORTED_FEATS
    SDP_UNSIGNED_TWO_BYTE,
    (uint8_t)((SDP_ATTR_MAP_SUPPORTED_FEATS) >> 8),
    (uint8_t)(SDP_ATTR_MAP_SUPPORTED_FEATS),
    SDP_UNSIGNED_FOUR_BYTE,
    (uint8_t)(0x0000024F >> 24),
    (uint8_t)(0x0000024F >> 16),
    (uint8_t)(0x0000024F >> 8),
    (uint8_t)(0x0000024F)
};

The MAP supported features used in SDP of MCE is defined below. The associated bit shall be set to 1 if supported, 0 if not. Reserved bits shall be set to 0, and ignored by the MSE as future versions might use them.

Bit

Description

0

Notification Registration Feature

1

Notification Feature

2

Browsing Feature

3

Uploading Feature

4

Delete Feature

5

Instance Information Feature

6

Extended Event Report 1.1

7

Event Report Version 1.2

8

Message Format Version 1.1

9

Messages-Listing Format Version 1.1

10

Persistent Message Handles

11

Database Identifier

12

Folder Version Counter

13

Conversation Version Counters

14

Participant Presence Change Notification

15

Participant Chat State Change Notification

16

PBAP Contact Cross Reference

17

Notification Filtering

18

UTC Offset Timestamp Format

19

MapSupportedFeatures in Connect Request

20

Conversation Listing

21

Owner Status

22

Message Forwarding

23-31

RFA

Feature Set

The functions provided by MAP APIs are as below:

  1. Connecting and Disconnecting: Including functions to connect/disconnect MAP.

  2. Getting message: Including functions to retrieve a specific message from the MSE.

  3. Pushing message: Including functions to push message to the MSE.

Provided APIs

This figure shows the relationship between Applications and MAP and Bluetooth Protocol Stack. Above the horizon line is developed by the Applications. Below the horizon line is developed by Realtek.

The table below shows a simple description of MAP APIs. MAP related APIs are provided in the sdk\inc\framework\bt\bt_map.h.

Header File

Description

API Reference

bt_map.h

Connect MAP, get and push message etc.

Bluetooth MAP Profile

Functions

MAP Initialization

Main function is invoked when the application is powered on or the chip is reset.

int main(void)
{
    board_init();

    ......

    bt_map_init(3, RFC_MAP_MNS_CHANN_NUM, L2CAP_MAP_MNS_PSM, 0x0000024F);

    ......
    os_task_create(&app_task_handle, "app_task", app_task, NULL, 1024 * 4, 1);
    ......

    os_sched_start();
    return 0;
}

MAP Connect

OBEX connection of MAP must always be initiated by the device of OBEX client. When establishing Message Access Service, the MCE device as OBEX client must initiate OBEX connection. The establishment of a MNS connection is done with the MCE as OBEX server and the MSE as OBEX client. The establishment of a Message Notification connection requires the previous establishment of a Message Access Service connection.

Note

When the device is MCE, it must initiate the OBEX connection to establish Message Access Service.

bt_map_mas_msg_notification_set() is used to register for being notified of the arrival of new messages. After this API is called, the MSE device will establish OBEX connection for Message Notification Service.

bt_map_mns_connect_cfm() is used to accept or reject the incoming MNS connection.

MAP Get Message

bt_map_mas_folder_set() is used to navigate the folders of the MSE.

Note

The default folder will be set to telecom/msg by framework when the MAS connection is established.

bt_map_mas_folder_listing_get() is used to retrieve the Folder-Listing object from the current folder of the MSE. The Folder-Listing object is an XML object and shall be encoded in UTF-8. In the context of the MAP profile, the Folder-Listing object shall not contain message entries. It shall only contain folder entries located in the current folder level.

bt_map_mas_msg_listing_get() is used to retrieve Messages-Listing objects from the MSE. The Messages-Listing object is an XML object and shall be encoded in UTF-8. The message listing retrieve procedure is shown below.

bt_map_mas_msg_get() is used to retrieve a specific message from the MSE.

MAP Push Message

bt_map_mas_msg_push() is used to push a message to a folder of the MSE. In the case of sending messages through the MSE, the messages shall be uploaded into the ‘Outbox’ folder of the MSE. In the case of uploading messages to the MSE, the messages shall not be uploaded into the ‘Outbox’ folder of the MSE, but any other folder is permitted. In the case of sending messages through the MSE, the MCE shall get a notification when the messages have been sent to the network and thus have been shifted by the MSE from the ‘Outbox’ to the ‘Sent’ folder.

Note

The MSE may implement policies that disable the sending of messages to the remote network, making sending messages through the MSE impossible to realize. Framework will not keep a record of the message data, for the purpose of reducing use of RAM.

MAP Disconnect

bt_map_mas_disconnect_req()

Request to disconnect Message Access Service.

Sample Projects

SDK provides a corresponding demo application for developers’ reference in development. The BR/EDR MAP gives a simple example on how to use MAP as MCE role.