Messages

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).

The Message class represents a message. 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, and sent. 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.

The Conversation class represents a conversation. 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.

Prerequisites

To use the Messages API in your app, you need to link against the correct library by adding the following line to your project's .pro file:

LIBS += -lbbpim

Your app must also have the Email and PIN Messages permission ( access_pimdomain_messages) to access email and PIN messages, or the Text Messages permission ( access_sms_mms) to access text messages. You specify these permissions in the bar-descriptor.xml file for your app.

Manipulating messages

To create a new message and send it using the message service, you create a MessageBuilder object for the message that you want to create. This object lets you add the attributes for the message. For example, you can create recipients (each of which is represented by a MessageContact object) and add these recipients to the message by calling MessageBuilder::addRecipient().

After you add attributes to the message, you can call MessageService::send() to send the message. You can also use MessageService::save() to save the message as a draft to the message database without sending it.

Not applicable

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.

#include <bb/pim/message/MessageService>
#include <bb/pim/message/MessageContact>
#include <bb/pim/message/MessageBuilder>
#include <bb/pim/message/Message>

using namespace bb::pim::message;
// Create the message service object
    MessageService service;

    // Create the recipients for the first message
    MessageContact firstRecipient = MessageContact(1,
            MessageContact::To,
            "Wes Barichak", "wes.barichak@example.com");
    MessageContact secondRecipient = MessageContact(2,
                                 MessageContact::To,
                                 "Karla Tetzel",
                                 "karla.tetzel@example.com");
    MessageContact thirdRecipient = MessageContact(3,
            MessageContact::Cc,
            "Mike Chepesky", "mike.chepesky@example.com");

    // Create the first message
    MessageBuilder *msg1Builder = MessageBuilder::create(1);
    msg1Builder->subject("Lunch");
    msg1Builder->body(MessageBody::PlainText,
        QByteArray("Got lunch plans? Let me know and we'll go somewhere!"));
    msg1Builder->addRecipient(firstRecipient);
    msg1Builder->addRecipient(secondRecipient);
    msg1Builder->addRecipient(thirdRecipient);

    Message firstMessage = *msg1Builder;

    // Send the first message using the message service object
    service.send(1, firstMessage);

    // Create the second message
    MessageBuilder *msg2Builder = MessageBuilder::create(1);
    msg2Builder->subject("Meeting minutes");
    msg2Builder->body(MessageBody::PlainText,
        QByteArray("Here are the minutes from today's meeting."));

    Message secondMessage = *msg2Builder;

    // Save the second message using the message service object
    service.save(1, secondMessage);

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. 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).

To search for messages, 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.

Not applicable

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).

#include <bb/pim/message/MessageService>
#include <bb/pim/message/MessageSearchFilter>
#include <bb/pim/message/Message>

using namespace bb::pim::message;
// 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: 2014-11-17



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus