The Messages API lets you create and send messages directly from your apps. You can build different types of messages, such as email messages or text messages, and send them to a list of recipients that you specify. Each message can include basic information like a subject, body, and priority, as well as more detailed information (for example, MIME type, follow-up flag status, and attachments). You can also create conversations, which are chat-like interactions that you can choose to display in a special way in your apps (say, by using a chat interface that's similar to BBM).
A message is represented by a Message object. This class contains all of the information about a specific message. The Messages API also includes supporting classes that represent other information that's relevant to a message. For example, the MessageStatus class represents the status of a message, such as read, draft, filed, sent, and so on. The Attachment class includes information about a specific attachment to the message, such as MIME type, file path to the attachment in the file system, and attachment data.
A conversation is represented by a Conversation object. Each conversation consists of a series of messages, and you can obtain these messages by calling MessageService::messagesInConversation(). You can also retrieve general information about the conversation, such as the number of messages and the participants.
Several classes in the Messages API use the builder design pattern, which makes it easy to create instances of these classes and specify values for their properties. For example, the Message class has a builder class called MessageBuilder. Many of the functions in MessageBuilder returns a self reference to the builder, allowing you to chain function calls together.
To use the Messages API in your apps, you need to import the correct library by adding the following line to your project's .pro file:
LIBS += -lbbpim
Your app must also have the access_pimdomain_messages permission, which you specify in the bar-descriptor.xml file for your app. To learn more about the bar-descriptor.xml file, see Using the bar-descriptor.xml file.
Here's how to create two messages using the Messages API. Both messages are created by using the MessageBuilder class. The first message is sent to a list of three recipients (two are listed in the To field and one is listed in the Cc field), and the second message is saved as a draft. To save your messages to the database and send them, you need to create and use a MessageService object.
// Create the message service object MessageService service; // Create the recipients for the first message MessageContact firstRecipient = MessageContact(1, MessageContact::To, "Wes Barichak", "email@example.com"); MessageContact secondRecipient = MessageContact(2, MessageContact::To, "Karla Tetzel", "firstname.lastname@example.org"); MessageContact thirdRecipient = MessageContact(3, MessageContact::Cc, "Mike Chepesky", "email@example.com"); // Create the first message MessageBuilder msg1Builder; Message firstMessage = msg1Builder.subject("Lunch") .body(MessageBody::PlainText, QByteArray("Got lunch plans? Let me know and we'll go somewhere!")) .addRecipient(firstRecipient) .addRecipient(secondRecipient) .addRecipient(thirdRecipient); // Send the first message using the message service object service.send(1, firstMessage); // Create the second message MessageBuilder msg2Builder; Message secondMessage = msg2Builder.subject("Meeting minutes") .body(MessageBody::PlainText, QByteArray("Here are the minutes from today's meeting.")); // Save the second message using the message service object service.save(1, secondMessage);
Using the Messages API
The following sections outline some important concepts about messages. You may find these concepts useful as you work with messages and conversations in your apps.
Searching for messages
You can use the MessageService to search for messages that fit various criteria. For example, you might want to search for messages that contain the text "Cascades" in the subject line. Or, you might want to retrieve a list of all unread messages in a particular account. You can use the MessageSearchFilter class to specify the search criteria that you're interested in, and you can also set search parameters such as offset (the number of messages after the first message to start the search) and limit (the maximum number of search results to return).
There are two supporting classes that you can use to specify search criteria. The SearchFilterCriteria class contains an enumeration of the fields in a message that you can search (for example, SearchFilterCriteria::FromAddress, SearchFilterCriteria::Subject, and so on). The SearchStatusCriteria class contains an enumeration of the message statuses that you can search for (for example, SearchStatusCriteria::Unread, SearchStatusCriteria::Flagged, and so on).
Here's how to search for messages that include the text "stakeholder" in the subject or body of the message, and are marked as unread (up to a maximum of 20 results). There are two different search functions in MessageService that you can use. The searchLocal() function searches for messages that are present on the device, and the searchRemote() function searches for messages on the messaging server. The results from these two functions might be different, so it's important to choose the one that makes the most sense in your apps.
// Create the message service object MessageService service; // Create the search criteria MessageSearchFilter filter; filter.addSearchCriteria(SearchFilterCriteria::Subject, "stakeholder"); filter.addSearchCriteria(SearchFilterCriteria::Body, "stakeholder"); filter.addStatusCriteria(SearchStatusCriteria::Unread); filter.setLimit(20); // Perform a local search using the filter criteria QList<Message> localMessageResults = service.searchLocal(1, filter); // Perform a remote search using the filter criteria QList<Message> remoteMessageResults = service.searchRemote(1, filter);
Last modified: 2013-09-26