MessageService

#include <bb/pim/message/MessageService>

To link against this class, add the following line to your .pro file: LIBS += -lbbpim

The MessageService class provides access (read, write, and update) to PIM message data.

This class is an interface to the messaging service. The messaging service manages a database and controls a set of synchronization services. Functions in this class affect this database. The signals in this class are emitted by changes in the messaging database, such as adding or removing messages, or updating existing messages.

You can use this class to perform different operations on messages, such as sending, saving, updating, removing, and retrieving. You can create an instance of this class and use it to manage all of the messaging-related operations in your app. For example, here's how to perform some common operations using the MessageService:

MessageService messageService;
AccountService accountService;

// Use MessageBuilder to build a message msg, and the required accountId from
// AccountService

// Send it using an account
messageService.send(accountId , msg ) ;

// Save using an account
messageService.save(accountId , msg ) ;

// Remove a message
messageService.remove(accountId , msg.id() ) ;

Folders are containers for messages. The MessageService class implements retrieval and update operations on folders. Here's how you might use folders in your app:

QList<MessageFolder> folders = messageService.folders(accountId);
MessageFolder firstFolder = folders.at(0);
messageService.renameMessageFolder( accountId , firstFolder.id(), name )

You can also use the MessageService to retrieve a list of messages and conversations, as follows:

MessageFilter filter;
filter.insert(MessageFilter::Quantity ,QVariant("20") );
QList<Message> messageList = messageService.messages(accountId, filter);
QList<Conversation> conversationList = messageService.conversations(accountId,
                                        filter);
See:

Message

Since:

BlackBerry 10.0.0

Public Functions Index

MessageService (QObject *parent=0)
~MessageService ()
QList< MessageKey >messageKeys (bb::pim::account::AccountKey accountId, const MessageFilter &filter) const
QList< Message >messages (bb::pim::account::AccountKey accountId, const MessageFilter &filter) const
voiddownloadMessage (bb::pim::account::AccountKey accountId, MessageKey messageId)
Messagemessage (bb::pim::account::AccountKey accountId, MessageKey messageId) const
intmessageCount (bb::pim::account::AccountKey accountId, const MessageFilter &filter) const
QList< ConversationKey >conversationKeys (bb::pim::account::AccountKey accountId, const MessageFilter &filter) const
QList< Conversation >conversations (bb::pim::account::AccountKey accountId, const MessageFilter &filter) const
Conversationconversation (bb::pim::account::AccountKey accountId, ConversationKey conversationId) const
intconversationCount (bb::pim::account::AccountKey accountId) const
QList< Message >messagesInConversation (bb::pim::account::AccountKey accountId, ConversationKey conversationId, const MessageFilter &filter) const
QList< MessageFolder >folders (bb::pim::account::AccountKey accountId) const
QList< MessageFolder >foldersWithSuggestion (bb::pim::account::AccountKey accountId, MessageKey messageId, MessageFolderKey *suggestedFolderId) const
MessageFolderKeyfolderSuggestion (bb::pim::account::AccountKey accountId, MessageKey messageId) const
MessageFolderfolder (bb::pim::account::AccountKey accountId, MessageFolderKey folderId) const
QList< Message >messagesInFolder (bb::pim::account::AccountKey accountId, MessageFolderKey folderId, const MessageFilter &filter) const
voidmarkRead (bb::pim::account::AccountKey accountId, MessageKey messageId)
voidmarkUnread (bb::pim::account::AccountKey accountId, MessageKey messageId)
voidmarkRead (bb::pim::account::AccountKey accountId, ConversationKey conversationId)
voidmarkUnread (bb::pim::account::AccountKey accountId, ConversationKey conversationId)
MessageKeysend (bb::pim::account::AccountKey accountId, const Message &message)
MessageKeysmartReply (bb::pim::account::AccountKey accountId, const Message &message, bool isOrignalMsgEdited)
MessageKeysmartForward (bb::pim::account::AccountKey accountId, const Message &message, bool isOrignalMsgEdited)
MessageKeysave (bb::pim::account::AccountKey accountId, const Message &message)
ConversationKeysave (bb::pim::account::AccountKey accountId, const Conversation &conversation)
voidremove (bb::pim::account::AccountKey accountId, MessageKey messageId)
voidremove (bb::pim::account::AccountKey accountId, ConversationKey conversationId)
voidfile (bb::pim::account::AccountKey accountId, MessageKey messageId, MessageFolderKey folderId)
voidfile (bb::pim::account::AccountKey accountId, QList< MessageKey > messageIds, MessageFolderKey folderId)
voidfile (bb::pim::account::AccountKey accountId, ConversationKey conversationId, MessageFolderKey folderId)
voidsetFollowupFlag (bb::pim::account::AccountKey accountId, MessageKey messageId, const MessageFlag &followupFlag)
voidresetFollowupFlag (bb::pim::account::AccountKey accountId, MessageKey messageId)
voidsetPriority (bb::pim::account::AccountKey accountId, MessageKey messageId, MessagePriority::Type priority)
voidsetStatus (bb::pim::account::AccountKey accountId, MessageKey messageId, MessageStatus::Types status)
voidsetTransmissionStatus (bb::pim::account::AccountKey accountId, MessageKey messageId, MessageTransmissionStatus::Type transmissionStatus)
voidsetStatus (bb::pim::account::AccountKey accountId, ConversationKey conversationId, ConversationStatus::Types status)
voiddownloadAttachment (bb::pim::account::AccountKey accountId, MessageKey messageId, AttachmentKey attachmentId)
QList< Message >searchLocal (bb::pim::account::AccountKey accountId, const MessageSearchFilter &filter)
QList< Message >searchRemote (bb::pim::account::AccountKey accountId, const MessageSearchFilter &filter)
voidsetTypingStatus (bb::pim::account::AccountKey accountId, ConversationKey conversationId, bool typing)
voidrenameMessageFolder (bb::pim::account::AccountKey accountId, MessageFolderKey folderId, const QString &name)
voidaddMessageFolder (bb::pim::account::AccountKey accountId, MessageFolderKey folderId, const QString &name)
voiddeleteMessageFolder (bb::pim::account::AccountKey accountId, MessageFolderKey folderId)
boolsetFolderSyncConfig (bb::pim::account::AccountKey accountId, MessageFolderKey folderId, bool syncConfig)
boolisFeatureSupported (bb::pim::account::AccountKey accountId, MessageServiceFeature::Type feature)
voiddeletePrior (QList< bb::pim::account::AccountKey > accountIds, const QString &dateTime)
voiddeletePriorSearchResults (QList< bb::pim::account::AccountKey > accountIds, const MessageSearchFilter &filter, const QString &dateTime, const QString &srchExecDateTime)
voidmarkPrior (QList< bb::pim::account::AccountKey > accountIds, const QString &dateTime, bool markRead)
voidmarkPriorSearchResults (QList< bb::pim::account::AccountKey > accountIds, const MessageSearchFilter &filter, const QString &dateTime, const QString &srchExecDateTime, bool markRead)
voidsetOutOfOffice (bb::pim::account::AccountKey accountId, const OutOfOfficeSettings &outOfOffice)
OutOfOfficeSettingsoutOfOffice (bb::pim::account::AccountKey accountId) const
voidsyncAccounts (const QList< bb::pim::account::AccountKey > &accountIds)
voidsyncFolder (bb::pim::account::AccountKey accountId, MessageFolderKey folderId) const
voidmessagePreFetch (bb::pim::account::AccountKey accountId, MessageKey messageId) const
QList< MessageTransaction >messageTransactions (bb::pim::account::AccountKey accountId) const
boolclearTransactions (bb::pim::account::AccountKey accountId, TransactionKey id) const

Signals Index

voidaccountAdded (bb::pim::account::AccountKey accountId)
voidaccountRemoved (bb::pim::account::AccountKey accountId)
voidaccountUpdated (bb::pim::account::AccountKey accountId)
voidaccountConnected (bb::pim::account::AccountKey accountId)
voidaccountInvalidated (bb::pim::account::AccountKey accountId)
voidaccountDefaultChanged (bb::pim::account::AccountKey accountId)
voidmessagesAdded (bb::pim::account::AccountKey accountId, QList< bb::pim::message::ConversationKey > conversationIds, QList< bb::pim::message::MessageKey > messageIds)
voidmessageAdded (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId, bb::pim::message::MessageKey messageId)
voidmessageUpdated (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId, bb::pim::message::MessageKey messageId, bb::pim::message::MessageUpdate data)
voidmessageRemoved (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId, bb::pim::message::MessageKey messageId, QString sourceId)
voidmessageSyncCompleted (bb::pim::account::AccountKey accountId)
voidconversationAdded (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId)
voidconversationUpdated (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId, bb::pim::message::ConversationUpdate data)
voidconversationRemoved (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId)
voidfolderAdded (bb::pim::account::AccountKey accountId, bb::pim::message::MessageFolderKey folderId)
voidfolderSyncStarted (bb::pim::account::AccountKey accountId, bb::pim::message::MessageFolderKey folderId, int count)
voidfolderSyncCompleted (bb::pim::account::AccountKey accountId, bb::pim::message::MessageFolderKey folderId)
voidfolderUpdated (bb::pim::account::AccountKey accountId, bb::pim::message::MessageFolderKey folderId)
voidfolderRemoved (bb::pim::account::AccountKey accountId, bb::pim::message::MessageFolderKey folderId)
voidfolderEmptied (bb::pim::account::AccountKey accountId, bb::pim::message::MessageFolderKey folderId)
voidattachmentDownloadStatusChanged (bb::pim::account::AccountKey accountId, bb::pim::message::MessageKey messageId, bb::pim::message::AttachmentKey attachmentId, int percentDownloaded)
voidattachmentDownloaded (bb::pim::account::AccountKey accountId, bb::pim::message::MessageKey messageId, bb::pim::message::AttachmentKey attachmentId)
voidattachmentDownloadFailed (bb::pim::account::AccountKey accountId, bb::pim::message::MessageKey messageId, bb::pim::message::AttachmentKey attachmentId, bb::pim::message::AttachmentDownloadStatus::Type attachmentStatus)
voidmessageDownloadStatusChanged (bb::pim::account::AccountKey accountId, bb::pim::message::MessageKey messageId, int percentDownloaded)
voidbodyDownloaded (bb::pim::account::AccountKey accountId, bb::pim::message::MessageKey messageId)
voidtypingStatusChanged (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId, bool typing)

Public Functions

MessageService (

Constructs a new MessageService.

Parameters
parent

The parent object. This parameter is optional.
Since:

BlackBerry 10.0.0

~MessageService ()

Destructor.

Since:

BlackBerry 10.0.0

QList< MessageKey > messageKeys (
  • bb::pim::account::AccountKeyaccountId,
  • const MessageFilter &filter )

Retrieves a list of message IDs that fit the provided criteria.

You can use this function to retrieve the IDs of messages from a specific account that fit a set of criteria (represented by a MessageFilter), and then use this to display the messages in your UI (for example, in a list view).

Parameters
accountId

The account ID to retrieve the message IDs from (for example, the unique ID of an existing email account).

filter

The criteria to use to retrieve the message IDs.
Return:

A QList of message IDs that fit the provided criteria.

Since:

BlackBerry 10.0.0

QList< Message > messages (
  • bb::pim::account::AccountKeyaccountId,
  • const MessageFilter &filter )

Retrieves a list of messages that fit the provided criteria.

You can use this function to retrieve the Message objects from a specific account that fit a set of criteria (represented by a MessageFilter), and then use this to display the messages in your UI (for example, in a list view).

Parameters
accountId

The account ID to retrieve the messages from (for example, the unique ID of an existing email account or SMS account).

filter

The criteria to use to retrieve the messages.
Return:

A QList of messages that fit the provided criteria.

Since:

BlackBerry 10.0.0

void downloadMessage (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId )

Downloads a single message from the messaging service.

This function is an asynchronous call to retrieve a message from the messaging service, based on the provided account ID and message ID. You can use this function to download the full message body when your app needs it.

At the end of this operation, the MessageService emits the bodyDownloaded() signal. You can use this signal to get the updated message by calling MessageService::message().

Parameters
accountId

The account ID to download the message from (for example, the unique ID of an existing email account).

messageId

The unique ID of the message to download.
Since:

BlackBerry 10.0.0

Message message (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId )

Retrieves a message with the provided account ID and message ID.

You can use this function to access the full contents of a message (for example, to display the message on a viewer screen in your app).

Parameters
accountId

The account ID to retrieve the message from (for example, the unique ID of an existing email account).

messageId

The unique ID of the message to retrieve.
Return:

The message with the provided account ID and message ID.

Since:

BlackBerry 10.0.0

int messageCount (
  • bb::pim::account::AccountKeyaccountId,
  • const MessageFilter &filter )

Retrieves the number of messages with the provided account ID and that fit the provided filter criteria.

You can use this function to determine the size of the message data before constructing a list of messages in the UI of your app.

Parameters
accountId

The account ID to retrieve the number of messages from (for example, the unique ID of an existing email account)

filter

The criteria to use to retrieve the number of messages (for example, limiting the results based on conversation ID, and so on).
Return:

The number of messages with the provided account ID and that fit the provided filter criteria.

Since:

BlackBerry 10.0.0

QList< ConversationKey > conversationKeys (
  • bb::pim::account::AccountKeyaccountId,
  • const MessageFilter &filter )

Retrieves a list of conversation IDs that fit the provided criteria.

You can use this function to retrieve a list of conversation IDs from a specific account that fit a certain set of criteria (represented by a MessageFilter), and then use this to display the conversations in your UI (for example, in a conversation view).

Obtaining the list of keys allows you to maintain a mapping of UI list index to conversation IDs in your UI.

Parameters
accountId

The account ID to retrieve the conversation IDs from (for example, the unique ID of an existing email account).

filter

The criteria to use to retrieve the conversation IDs.
Return:

A QList of conversation IDs that fit the provided criteria.

Since:

BlackBerry 10.0.0

QList< Conversation > conversations (
  • bb::pim::account::AccountKeyaccountId,
  • const MessageFilter &filter )

Retrieves a list of conversations that fit the provided criteria.

You can use this function to retrieve the Conversation objects from a specific account that fit a set of criteria (represented by a MessageFilter), and then use this to display the conversations in your UI (for example, in a conversation view).

Parameters
accountId

The account ID to retrieve the conversations from (for example, the unique ID of an existing email account or SMS account).

filter

The criteria to use to retrieve the conversations.
Return:

A QList of conversations that fit the provided criteria.

Since:

BlackBerry 10.0.0

Conversation conversation (

Retrieves a conversation with the provided account ID and conversation ID.

You can use this function to access the full contents of a conversation (for example, to display the conversation on a viewer screen in your app).

Parameters
accountId

The account ID to retrieve the conversation from (for example, the unique ID of an existing email account).

messageId

The unique ID of the conversation to retrieve.
Return:

The conversation with the provided account ID and conversation ID.

Since:

BlackBerry 10.0.0

int conversationCount (
  • bb::pim::account::AccountKeyaccountId)

Retrieves the number of conversations with the provided account ID.

You can use this function to determine the size of the conversation data before constructing a list of conversations in the UI of your app.

Parameters
accountId

The account ID to retrieve the number of conversations from (for example, the unique ID of an existing email account)
Return:

The number of conversations with the provided account ID.

Since:

BlackBerry 10.0.0

QList< Message > messagesInConversation (

Retrieves a list of messages in a conversation that fit the provided criteria.

Parameters
accountId

The account ID to retrieve the messages from (for example, the unique ID of an existing email account).

conversationId

The ID of a pre-existing conversation.

filter

The filter criteria to use to retrieve the messages.
Return:

A QList of messages with the provided conversation ID and that fit the provided criteria.

Since:

BlackBerry 10.0.0

QList< MessageFolder > folders (
  • bb::pim::account::AccountKeyaccountId)

Retrieves a list of folders in the provided account.

You can use this function to display a folder view in the UI of your app.

Parameters
accountId

The account ID to retrieve the folders from (for example, the unique ID of an existing email account).
Return:

A QList of folders in the provided account.

Since:

BlackBerry 10.0.0

QList< MessageFolder > foldersWithSuggestion (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId,
  • MessageFolderKey *suggestedFolderId )

Retrieves a list of folders and a suggested folder for the provided message.

You can use this function to display a folder view in the UI of your app, as well as suggest a folder in which to file the provided message.

Parameters
accountId

The account ID to retrieve the folders from (for example, the unique ID of an existing email account).

messageId

The message ID of a message in the account that you want a suggested folder for.

suggestedFolderId

This function returns a folder ID in this parameter, which represents a suggested folder to file the provided message in. This value is invalid if an invalid account ID or message ID is provided.
Return:

A QList of folders, or an empty list if an invalid account ID or message ID is provided.

Since:

BlackBerry 10.0.0

MessageFolderKey folderSuggestion (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId )

Suggests a possible folder for filing a given message.

Parameters
accountId

The account ID of an account (for example, the account ID of an existing email account).

messageId

The message ID of a message (for example, the message ID of an existing email message).
Return:

The suggested folder ID for filing a message, or UndefinedKey in the case of an invalid account ID or message ID.

Since:

BlackBerry 10.0.0

MessageFolder folder (
  • bb::pim::account::AccountKeyaccountId,
  • MessageFolderKeyfolderId )

Retrieves a folder with the provided account ID and folder ID.

Parameters
accountId

The account ID to retrieve the folder from (for example, the unique ID of an existing email account).

folderId

A unique folder ID.
Return:

The folder with the provided account ID and folder ID.

Since:

BlackBerry 10.0.0

QList< Message > messagesInFolder (
  • bb::pim::account::AccountKeyaccountId,
  • MessageFolderKeyfolderId,
  • const MessageFilter &filter )

Retrieves a list of messages in the provided folder that fit the provided criteria.

You can use this function to view messages in a specific folder that fit a set of criteria

Parameters
accountId

The account ID to retrieve the messages from (for example, the unique ID of an existing email account).

folderId

The ID of the folder to retrieve the messages from.

filter

The set of criteria to use to retrieve the messages.
Return:

A QList of messages in the provided folder that fit the provided criteria.

Since:

BlackBerry 10.0.0

void markRead (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId )

Marks a message as read.

You can use this function to mark a message with a specific account ID and message ID as read. After the status is changed, the messageUpdated() signal is emitted. You can listen for this signal and update the list of messages in your UI accordingly.

Parameters
accountId

The account ID of the message to update (for example, the unique ID of an existing email account).

messageId

The message ID of the message to update.
Since:

BlackBerry 10.0.0

void markUnread (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId )

Marks a message as unread.

You can use this function to mark a message with a specific account ID and message ID as unread. After the status is changed, the messageUpdated() signal is emitted. You can listen for this signal and update the list of messages in your UI accordingly.

Parameters
accountId

The account ID of the message to update (for example, the unique ID of an existing email account).

messageId

The message ID of the message to update.
Since:

BlackBerry 10.0.0

void markRead (

Marks a conversation as read.

You can use this function to mark a conversation with a specific account ID and conversation ID as read. This function is used only for SMS accounts.

Parameters
accountId

The account ID of the conversation to update.

conversationId

The conversation ID of the conversation to update.
Since:

BlackBerry 10.0.0

void markUnread (

Marks a conversation as unread.

You can use this function to mark a conversation with a specific account ID and conversation ID as unread. This function is used only for SMS accounts.

Parameters
accountId

The account ID of the conversation to update.

conversationId

The conversation ID of the conversation to update.
Since:

BlackBerry 10.0.0

MessageKey send (
  • bb::pim::account::AccountKeyaccountId,
  • const Message &message )

Sends a message.

You can use a MessageBuilder to create a message, and then call this function to send the message. To reply to a message, you can call MessageBuilder::create() and provide the account ID and existing message to create a reply.

Parameters
accountId

The account ID of the message to send (for example, the unique ID of an existing email account).

message

The message to send, created using a MessageBuilder.
Return:

The message ID of the sent message.

Since:

BlackBerry 10.0.0

MessageKey smartReply (
  • bb::pim::account::AccountKeyaccountId,
  • const Message &message,
  • boolisOrignalMsgEdited )

Sends a reply to a message if underlying provider supports SmartReply.

You can use a MessageBuilder to create a message, and then call this function to send the message. To reply to a message, you can call MessageBuilder::create() and provide the account ID and existing message to create a reply. In order to use smartReply(), provide either the delta of changes in the body of the message or entire body contents depending on whether isOrignalMsgEdited. Also, a valid originalMessageId needs to be set on the message using MessageBuilder::origMessageId(). This is usually the unique ID of the message which is being replied to.

Parameters
accountId

The account ID of the message to send (for example, the unique ID of an existing email account).

message

The message to send, created using a MessageBuilder.

isOrignalMsgEdited

Hint to the provider whether it needs to treat contents of message as the delta or entire message.
Return:

The message ID of the sent message.

Since:

BlackBerry 10.0.0

MessageKey smartForward (
  • bb::pim::account::AccountKeyaccountId,
  • const Message &message,
  • boolisOrignalMsgEdited )

Forwards a message if underlying provider supports SmartForward.

You can use a MessageBuilder to create a message, and then call this function to send the message. To forward a message, you can call MessageBuilder::create() and provide the account ID and existing message to create a forward. In order to use smartForward(), provide either the delta of changes in the body of the message or entire body contents depending on whether isOrignalMsgEdited. Also, a valid originalMessageId needs to be set on the message using MessageBuilder::origMessageId().This is usually the unique ID of the message which is being forwarded.

Parameters
accountId

The account ID of the message to send (for example, the unique ID of an existing email account).

message

The message to send, created using a MessageBuilder.

isOrignalMsgEdited

Hint to the provider whether it needs to treat contents of message as the delta or entire message.
Return:

The message ID of the sent message.

Since:

BlackBerry 10.0.0

MessageKey save (
  • bb::pim::account::AccountKeyaccountId,
  • const Message &message )

Saves a draft message.

You can use a MessageBuilder to create a message, and then call this function to save the message as a draft.

Parameters
accountId

The account ID of the message to save (for example, the unique ID of an existing email account).

message

The message to save, created using a MessageBuilder.
Return:

The message ID of the saved message.

Since:

BlackBerry 10.0.0

ConversationKey save (
  • bb::pim::account::AccountKeyaccountId,
  • const Conversation &conversation )

Saves a conversation.

You can use a ConversationBuilder to create a conversation, and then call this function to save the conversation. This function is used only for SMS accounts.

Parameters
accountId

The account ID of the conversation to save.

conversation

The conversation to save, created using a ConversationBuilder.
Return:

The conversation ID of the saved conversation.

Since:

BlackBerry 10.0.0

void remove (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId )

Removes a message from an account.

You can use this function to delete a message from an account.

Parameters
accountId

The account ID of the message to remove (for example, the unique ID of an existing email account).

messageId

The message ID of the message to delete.
Since:

BlackBerry 10.0.0

void remove (

Removes a conversation from an account.

You can use this function to delete a conversation from an account.

Parameters
accountId

The account ID of the conversation to remove.

conversationId

The conversation ID of the conversation to delete.
Since:

BlackBerry 10.0.0

void file (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId,
  • MessageFolderKeyfolderId )

Files a message in a folder.

Parameters
accountId

The account ID of the message to file (for example, the unique ID of an existing email account).

messageId

The message ID of the message to file.

folderId

The folder ID of the folder to file the message in.
Since:

BlackBerry 10.0.0

void file (
  • bb::pim::account::AccountKeyaccountId,
  • QList< MessageKey >messageIds,
  • MessageFolderKeyfolderId )

Files multiple messages from the same account in a folder.

Parameters
accountId

The account ID of the messages to file (for example, the unique ID of an existing email account).

messageIds

The list of message IDs of the messages to file.

folderId

The folder ID of the folder to file the messages in.
Since:

BlackBerry 10.1.0

void file (
  • bb::pim::account::AccountKeyaccountId,
  • ConversationKeyconversationId,
  • MessageFolderKeyfolderId )

Files a conversation in a folder.

Parameters
accountId

The account ID of the conversation to file (for example, the unique ID of an existing email account).

conversationId

The conversation ID of the conversation to file.

folderId

The folder ID of the folder to file the conversation in.
Since:

BlackBerry 10.0.0

void setFollowupFlag (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId,
  • const MessageFlag &followupFlag )

Sets the follow-up flag of a message.

After the follow-up flag is set, the messageUpdated() signal is emitted so you can update the message in the UI of your app.

Parameters
accountId

The account ID of the message to flag (for example, the unique ID of an existing email account).

messageId

The message ID of the message to flag.

followupFlag

The follow-up flag to set.
Since:

BlackBerry 10.0.0

void resetFollowupFlag (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId )

Resets the follow-up flag of a message.

After the follow-up flag is reset, the messageUpdated() signal is emitted so you can update the message in the UI of your app.

Parameters
accountId

The account ID of the message to flag (for example, the unique ID of an existing email account).

messageId

The message ID of the message to flag.
Since:

BlackBerry 10.0.0

void setPriority (

Sets the priority of a message.

Parameters
accountId

The account ID of the message to set the priority of (for example, the unique ID of an existing email account).

messageId

The message ID of the message to set the priority of.

priority

The priority to set.
Since:

BlackBerry 10.0.0

void setStatus (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId,
  • MessageStatus::Typesstatus )

Sets the status of a message.

This function is used only for SMS accounts.

Parameters
accountId

The account ID of the message to set the status of.

messageId

The message ID of the message to set the status of.

status

The status to set.
Since:

BlackBerry 10.0.0

void setTransmissionStatus (

Sets the transmission status of a message.

This function is used only for SMS accounts.

Parameters
accountId

The account ID of the message to set the transmission status of.

messageId

The message ID of the message to set the transmission status of.

transmissionStatus

The transmission status to set.
Since:

BlackBerry 10.0.0

void setStatus (
  • bb::pim::account::AccountKeyaccountId,
  • ConversationKeyconversationId,
  • ConversationStatus::Typesstatus )

Sets the status of a conversation.

This function is used only for SMS accounts.

Parameters
accountId

The account ID of the conversation to set the status of.

conversationId

The conversation ID of the conversation to set the status of.

status

The status to set.
Since:

BlackBerry 10.0.0

void downloadAttachment (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId,
  • AttachmentKeyattachmentId )

Downloads the attachment of a message.

Parameters
accountId

The account ID of the message to retrieve the attachment of (for example, the unique ID of an existing email account).

messageId

The ID of the message to retrieve the attachment of.

attachmentId

The ID of the attachment to retrieve.
Since:

BlackBerry 10.0.0

QList< Message > searchLocal (

Performs a local search for messages that fit the provided criteria.

Parameters
accountId

The account ID to search (for example, the unique ID of an existing email account). If you pass bb::pim::message::UndefinedKey, then the search will be across all accounts.

filter

The criteria to use for the search.
Return:

A QList of messages that fit the provided criteria.

Since:

BlackBerry 10.0.0

QList< Message > searchRemote (

Performs a remote search on the messaging server for messages that fit the provided criteria.

Parameters
accountId

The account ID to search (for example, the unique ID of an existing email account). The account ID must not be bb::pim::message::UndefinedKey. Unlike searchLocal(), the searchRemote() function does not support search in all accounts simultaneously.

filter

The criteria to use for the search.
Return:

A QList of messages that fit the provided criteria, or an empty QList if the account ID was specified as bb::pim::message::UndefinedKey.

Since:

BlackBerry 10.0.0

void setTypingStatus (
  • bb::pim::account::AccountKeyaccountId,
  • ConversationKeyconversationId,
  • booltyping )

Sets the "is typing" status for a conversation.

This function sets the "is typing" status for conversations in accounts where the underlying protocol supports the idea of presence. This function is used only for SMS accounts.

Parameters
accountId

The SMS account ID.

conversationId

The conversation ID.

typing

If true the user is typing, if false the user is not typing.
Since:

BlackBerry 10.0.0

void renameMessageFolder (
  • bb::pim::account::AccountKeyaccountId,
  • MessageFolderKeyfolderId,
  • const QString &name )

Renames a message folder.

After the folder is renamed, the folderUpdated() signal is emitted, and you can listen for this signal and update the UI of your app accordingly.

Parameters
accountId

The account ID of the folder to rename (for example, the unique ID of an existing email account).

folderId

The ID of the folder to rename.

name

The new name of the folder.
Since:

BlackBerry 10.0.0

void addMessageFolder (
  • bb::pim::account::AccountKeyaccountId,
  • MessageFolderKeyfolderId,
  • const QString &name )

Adds a message folder.

After the folder is added, the folderAdded() signal is emitted, and you can listen for this signal and update the UI of your app accordingly.

Parameters
accountId

The account ID of the folder to add (for example, the unique ID of an existing email account).

folderId

The ID of the folder to add.

name

The name of the folder.
Since:

BlackBerry 10.0.0

void deleteMessageFolder (
  • bb::pim::account::AccountKeyaccountId,
  • MessageFolderKeyfolderId )

Deletes a message folder.

After the folder is deleted, the folderRemoved() signal is emitted, and you can listen for this signal and update the UI of your app accordingly.

Parameters
accountId

The account ID of the folder to delete (for example, the unique ID of an existing email account).

folderId

The ID of the folder to delete.
Since:

BlackBerry 10.0.0

bool setFolderSyncConfig (
  • bb::pim::account::AccountKeyaccountId,
  • MessageFolderKeyfolderId,
  • boolsyncConfig )

Enables synchronization for a message folder.

Parameters
accountId

The account ID of an account (for example, the account ID of an existing email account).

folderId

The message folder ID.

syncConfig

If true synchronization is enabled for the message folder, if false synchronization is disabled for the message folder.
Return:

true if synchronization configuration was set successfully, false otherwise.

Since:

BlackBerry 10.0.0

bool isFeatureSupported (

Indicates whether the provided feature is supported by an account.

You can use this function to determine if a specific feature is supported by an account, such as folder management.

Parameters
accountId

The account ID to query (for example, the unique ID of an existing email account).

feature

The feature to query.
Return:

true if the feature is supported by the account, false otherwise.

Since:

BlackBerry 10.0.0

void deletePrior (
  • QList< bb::pim::account::AccountKey >accountIds,
  • const QString &dateTime )

Deletes all messages prior to the provided date and time.

Parameters
accountIds

A list of account IDs to delete messages from.

dateTime

The date and time, expressed in yyyy-MM-dd hh:mm:ss.zzzzzz format (for example, 2012-07-25 23:59:59.999999).
Since:

BlackBerry 10.0.0

void deletePriorSearchResults (

Deletes all messages prior to the provided date and time and meeting given search filter crieria.

Parameters
accountIds

A list of account IDs to delete messages from.

dateTime

The date and time representing upperbound time limit on the bulk delete action, expressed in yyyy-MM-dd hh:mm:ss.zzzzzz format (for example, 2012-07-25 23:59:59.999999).

filter

The criteria to use for the search.

srchExecDateTime

The date and time when the search was executed, expressed in yyyy-MM-dd hh:mm:ss.zzzzzz format (for example, 2012-07-25 23:59:59.999999).
Since:

BlackBerry 10.1.0

void markPrior (
  • QList< bb::pim::account::AccountKey >accountIds,
  • const QString &dateTime,
  • boolmarkRead )

Marks all messages prior to the provided date & time and given search filter as read or unread.

Parameters
accountIds

A list of account IDs to mark messages from.

dateTime

The date and time, expressed in yyyy-MM-dd hh:mm:ss.zzzzzz format (for example, 2012-07-25 23:59:59.999999).

markRead

If true the messages are marked as read, if false the messages are marked as unread.
Since:

BlackBerry 10.0.0

void markPriorSearchResults (

Marks all messages prior to the provided date & time and meeting given search filter criteria, as read or unread.

Parameters
accountIds

A list of account IDs to delete messages from.

dateTime

The date and time representing upperbound time limit on the bulk mark prior action, expressed in yyyy-MM-dd hh:mm:ss.zzzzzz format (for example, 2012-07-25 23:59:59.999999).

filter

The criteria to use for the search.

srchExecDateTime

The date and time when the search was executed, expressed in yyyy-MM-dd hh:mm:ss.zzzzzz format (for example, 2012-07-25 23:59:59.999999).

markRead

If true marks all items prior to dateTime as read.
Since:

BlackBerry 10.1.0

void setOutOfOffice (

Sets the out-of-office option for an account.

Parameters
accountId

The account ID to set the out-of-office option for (for example, the unique ID of an existing email account).

outOfOffice

The out-of-office option to set.
Since:

BlackBerry 10.0.0

OutOfOfficeSettings outOfOffice (
  • bb::pim::account::AccountKeyaccountId)

Retrieves the out-of-office option for an account.

Parameters
accountId

The account ID to retrieve the out-of-office option for (for example, the unique ID of an existing email account).
Return:

The out-of-office option for the provided account.

Since:

BlackBerry 10.0.0

void syncAccounts (
  • const QList< bb::pim::account::AccountKey > &accountIds)

Synchronizes all messages in a set of accounts.

Parameters
accountIds

The list of account IDs to synchronize (for example, the unique IDs of existing email accounts).
Since:

BlackBerry 10.0.0

void syncFolder (
  • bb::pim::account::AccountKeyaccountId,
  • MessageFolderKeyfolderId )

Synchronizes a folder in an account.

Parameters
accountId

The account ID of the folder to synchronize (for example, the unique ID of an existing email account).

folderId

The folder ID of the folder to synchronize.
Since:

BlackBerry 10.0.0

void messagePreFetch (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId )

Pre-fetch a message from the messaging service.

This function indicates to the messaging service that the provided message should be pre-fetched for faster retrieval. You can use this function to indicate that a message is about to be viewed, which would then improve the retrieval time of a subsequent call to MessageService::message().

Parameters
accountId

The account ID of the message to pre-fetch id of the account (for example, the unique ID of an existing email account).

messageId

The message ID of the message to pre-fetch.
Since:

BlackBerry 10.0.0

QList< MessageTransaction > messageTransactions (
  • bb::pim::account::AccountKeyaccountId)

brief Retrieve a list of Message changes MessageTransactions for an account

You can use this function to sync any messaging changes from service layer

Parameters
accountId

of an Messaging account
Since:

BlackBerry 10.0.0

bool clearTransactions (
  • bb::pim::account::AccountKeyaccountId,
  • TransactionKeyid )

Clear the transaction logs from the specified TransactionKey for an account.

Parameters
accountId

of an Messaging account

id

as TranscationKey as a marker up to the point at which to clear the transactions.

Return:

as true/false if the clear was successfull

Since:

BlackBerry 10.0.0

Signals

void accountAdded (
  • bb::pim::account::AccountKeyaccountId)

Emitted when an account is added to the message service.

Parameters
accountId

The account ID of the account that was added (for example, if a new email account was added).
Since:

BlackBerry 10.0.0

void accountRemoved (
  • bb::pim::account::AccountKeyaccountId)

Emitted when an account is removed from the message service.

Parameters
accountId

The account ID of the account that was removed (for example, if an existing email account was removed).
Since:

BlackBerry 10.0.0

void accountUpdated (
  • bb::pim::account::AccountKeyaccountId)

Emitted when an account is updated in the message service.

Parameters
accountId

The account ID of the account that was updated (for example, if an existing email account was updated with a name change).
Since:

BlackBerry 10.0.0

void accountConnected (
  • bb::pim::account::AccountKeyaccountId)

Emitted when an account is connected.

Parameters
accountId

The account ID of the account that is connected.

void accountInvalidated (
  • bb::pim::account::AccountKeyaccountId)

Emitted when an account is marked invalid.

Parameters
accountId

The account ID of the account that is invalid (for example, if a user password changed).

void accountDefaultChanged (
  • bb::pim::account::AccountKeyaccountId)

Emitted when the default account in the message service is changed.

Parameters
accountId

The account ID of the new default account.
Since:

BlackBerry 10.0.0

void messagesAdded (

Emitted when messages are added to the message service.

This signal is usually emitted on initial sync or if the server has been out of sync for some time.

Parameters
accountId

The account ID that the messages were added to.

conversationIds

The list of conversation IDs that were added.

messageIds

The list of message IDs that were added.
Since:

BlackBerry 10.0.0

void messageAdded (

Emitted when a single message is added to the message service.

Parameters
accountId

The account ID of the message that was added.

conversationId

The conversation ID that was added.

messageId

The message ID that was added.
Since:

BlackBerry 10.0.0

void messageUpdated (

Emitted when a message is updated in the message service.

The MessageUpdate parameter includes the details of the update, which you can use to update the local copy of the message in your app.

Parameters
accountId

The account ID of the message that was updated.

conversationId

The conversation ID that was updated.

messageId

The message ID that was updated.

data

The data regarding the update.
Since:

BlackBerry 10.0.0

void messageRemoved (

Emitted when a single message is removed from the message service.

Parameters
accountId

The account ID of the message that was removed.

conversationId

The conversation ID that was removed.

messageId

The message ID that was removed.

sourceId

The ID of the source.
Since:

BlackBerry 10.0.0

void messageSyncCompleted (
  • bb::pim::account::AccountKeyaccountId)

Emitted when an account's messages are synchronized.

Parameters
accountId

The account ID of the messages that were synchronized.
Since:

BlackBerry 10.0.0

void conversationAdded (

Signal emitted by the service on a conversation add , that can be used by client to update its conversation list.

Used only for sms accounts

Parameters
accountId

Account id of an account

conversationId

of the new message
Since:

BlackBerry 10.0.0

void conversationUpdated (

Signal emitted by the service on a conversation update , that can be used by client to update its conversation list.

Used only for sms accounts

Parameters
accountId

Account id of an account

conversationId

of the new message

data

as ConstConversationUpdateSharedPtr , this would be applied to the corresponding Conversation in the client
Since:

BlackBerry 10.0.0

void conversationRemoved (

Signal emitted by the service on a conversation removed , that can be used by client to update its message list.

Parameters
accountId

conversationId

of the deleted conversation
Since:

BlackBerry 10.0.0

void folderAdded (
  • bb::pim::account::AccountKeyaccountId,
  • bb::pim::message::MessageFolderKeyfolderId )

Signal emitted by the service on a new folder addition, that can be used by client to update its folder list.

Parameters
accountId

Folder

id of the folder
Since:

BlackBerry 10.0.0

void folderSyncStarted (
  • bb::pim::account::AccountKeyaccountId,
  • bb::pim::message::MessageFolderKeyfolderId,
  • intcount )

Signal emitted by the service on a folder sync start , that can be used by client to update its folder list view to update and new messages in the specified folder.

Parameters
accountId

Folder

id of the folder

count

gives the number of messages being updated in that folder
Since:

BlackBerry 10.0.0

void folderSyncCompleted (
  • bb::pim::account::AccountKeyaccountId,
  • bb::pim::message::MessageFolderKeyfolderId )

Signal emitted by the service on a folder sync complete.

Parameters
accountId

Folder

id of the folder
Since:

BlackBerry 10.0.0

void folderUpdated (
  • bb::pim::account::AccountKeyaccountId,
  • bb::pim::message::MessageFolderKeyfolderId )

Signal emitted by the service if a folder is updated , example name of the folder is changed.

Parameters
accountId

Folder

id of the folder
Since:

BlackBerry 10.0.0

void folderRemoved (
  • bb::pim::account::AccountKeyaccountId,
  • bb::pim::message::MessageFolderKeyfolderId )

Signal emitted by the service if a folder is removed.

Parameters
accountId

Folder

id of the folder
Since:

BlackBerry 10.0.0

void folderEmptied (
  • bb::pim::account::AccountKeyaccountId,
  • bb::pim::message::MessageFolderKeyfolderId )

Signal emitted by the service if a folder is goes out of synch and is updated by the service.

Triggerd in rare cases where the folder gets out of synch with the server and the service layer resynch's the folder not used when all the messages in a folder are deleted manually

Parameters
accountId

Folder

id of the folder
Since:

BlackBerry 10.0.0

void attachmentDownloadStatusChanged (
  • bb::pim::account::AccountKeyaccountId,
  • bb::pim::message::MessageKeymessageId,
  • bb::pim::message::AttachmentKeyattachmentId,
  • intpercentDownloaded )

Signal emitted by the service when an attachment status change occurs (incremental download)

Parameters
Account

id of the account containing the message

Message

id of the message

Attachment

id of the attachment

Percent

of download completed
Since:

BlackBerry 10.0.0

void attachmentDownloaded (
  • bb::pim::account::AccountKeyaccountId,
  • bb::pim::message::MessageKeymessageId,
  • bb::pim::message::AttachmentKeyattachmentId )

Signal emitted by the service when an attachment download is complete.

Parameters
Account

id of the account containing the message

Message

id of the message

Attachment

id of the attachment
Since:

BlackBerry 10.0.0

void attachmentDownloadFailed (

Signal emitted by the service when an attachment download fails.

Parameters
Account

id of the account containing the message

Message

id of the message

Attachment

id of the attachment

Attachment

status code
Since:

BlackBerry 10.0.0

void messageDownloadStatusChanged (
  • bb::pim::account::AccountKeyaccountId,
  • bb::pim::message::MessageKeymessageId,
  • intpercentDownloaded )

...updates the Downloaded percent of a message eg:MMS

Since:

BlackBerry 10.0.0

void bodyDownloaded (
  • bb::pim::account::AccountKeyaccountId,
  • bb::pim::message::MessageKeymessageId )

Signal emitted by the service when body is downloaded.

Parameters
Account

id of the account containing the message

Message

id of the message
Since:

BlackBerry 10.0.0

void typingStatusChanged (

used only for sms accounts

Since:

BlackBerry 10.0.0