MessageService

Since: BlackBerry 10.0.0

#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 the signals in this class to listen for several types of messages. You can listen for emails from supported account types (including POP, IMAP, and so on), SMS messages, and MMS messages. However, you can't use these signals to listen for other message types, such as BBM messages, WhatsApp messages, or messages from other non-PIM apps. There are no APIs available to listen for messages from non-PIM apps.

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 also:

Message

Permissions:

To use the messaging service, you must set the access_pimdomain_messages permission to access email and PIN messages and the access_sms_mms permission to access text messages. These permissions are set in the bar-descriptor.xml file of your project.


Overview

Public Functions Index

MessageService (QObject *parent=0)
MessageService (bb::pim::account::AccountKey accountId, QObject *parent=0)
~MessageService ()
voidaddMessageFolder (bb::pim::account::AccountKey accountId, MessageFolderKey folderId, const QString &name)
QList< FileAttachment >attachments (bb::pim::account::AccountKey accountId, ConversationKey conversationId, const AttachmentFilter &filter) const
voidbulkOperationOnConversations (const QMap< bb::pim::account::AccountKey, QList< ConversationKey > > &data, MessageUpdateFilter::UpdateOperation operationType)
voidbulkOperationOnMessages (const QMap< bb::pim::account::AccountKey, QList< MessageKey > > &data, MessageUpdateFilter::UpdateOperation operationType)
boolclearTransactions (bb::pim::account::AccountKey accountId, TransactionKey id) const
Conversationconversation (bb::pim::account::AccountKey accountId, ConversationKey conversationId) const
intconversationCount (bb::pim::account::AccountKey accountId) 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
intcountTransactions (bb::pim::account::AccountKey accountId) const
voiddeleteMessageFolder (bb::pim::account::AccountKey accountId, MessageFolderKey folderId)
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)
voiddownloadAttachment (bb::pim::account::AccountKey accountId, MessageKey messageId, AttachmentKey attachmentId)
voiddownloadMessage (bb::pim::account::AccountKey accountId, MessageKey messageId)
voiddownloadMessage (bb::pim::account::AccountKey accountId, MessageKey messageId, bool partial)
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)
MessageFolderfolder (bb::pim::account::AccountKey accountId, MessageFolderKey folderId) const
QList< MessageFolder >folders (bb::pim::account::AccountKey accountId) const
MessageFolderKeyfolderSuggestion (bb::pim::account::AccountKey accountId, MessageKey messageId) const
QList< MessageFolder >foldersWithSuggestion (bb::pim::account::AccountKey accountId, MessageKey messageId, MessageFolderKey *suggestedFolderId) const
voidhide (bb::pim::account::AccountKey accountId, MessageKey messageId)
voidhide (bb::pim::account::AccountKey accountId, ConversationKey conversationId)
voidhidePrior (QList< bb::pim::account::AccountKey > accountIds, const MessageUpdateFilter &filter)
boolisFeatureSupported (bb::pim::account::AccountKey accountId, MessageServiceFeature::Type feature)
voidmarkOrDeletePrior (QList< bb::pim::account::AccountKey > accountIds, const MarkOrDeletePriorFilter &filter, const MarkOrDeletePriorOp::Type &operationType)
voidmarkOrDeletePriorForSearch (QList< bb::pim::account::AccountKey > accountIds, const MessageSearchFilter &filter, const QDateTime &dateTime, const QDateTime &srchExecDateTime, const MarkOrDeletePriorOp::Type &operationType)
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)
voidmarkRead (bb::pim::account::AccountKey accountId, MessageKey messageId)
voidmarkRead (bb::pim::account::AccountKey accountId, ConversationKey conversationId)
voidmarkUnread (bb::pim::account::AccountKey accountId, MessageKey messageId)
voidmarkUnread (bb::pim::account::AccountKey accountId, ConversationKey conversationId)
Messagemessage (bb::pim::account::AccountKey accountId, MessageKey messageId) const
intmessageCount (bb::pim::account::AccountKey accountId, const MessageFilter &filter) const
QList< MessageKey >messageKeys (bb::pim::account::AccountKey accountId, const MessageFilter &filter) const
voidmessagePreFetch (bb::pim::account::AccountKey accountId, MessageKey messageId) const
QList< Message >messages (bb::pim::account::AccountKey accountId, const MessageFilter &filter) const
QList< Message >messagesInConversation (bb::pim::account::AccountKey accountId, ConversationKey conversationId, const MessageFilter &filter) const
QList< Message >messagesInFolder (bb::pim::account::AccountKey accountId, MessageFolderKey folderId, const MessageFilter &filter) const
QList< MessageTransaction >messageTransactions (bb::pim::account::AccountKey accountId) const
QList< MessageTransaction >messageTransactions (bb::pim::account::AccountKey accountId, unsigned int limit) const
OutOfOfficeSettingsoutOfOffice (bb::pim::account::AccountKey accountId) const
voidremove (bb::pim::account::AccountKey accountId, MessageKey messageId)
voidremove (bb::pim::account::AccountKey accountId, ConversationKey conversationId)
voidrenameMessageFolder (bb::pim::account::AccountKey accountId, MessageFolderKey folderId, const QString &name)
voidresetFollowupFlag (bb::pim::account::AccountKey accountId, MessageKey messageId)
MessageKeysave (bb::pim::account::AccountKey accountId, const Message &message)
ConversationKeysave (bb::pim::account::AccountKey accountId, const Conversation &conversation)
QList< Message >searchLocal (bb::pim::account::AccountKey accountId, const MessageSearchFilter &filter)
QList< Message >searchRemote (bb::pim::account::AccountKey accountId, const MessageSearchFilter &filter) BB_DEPRECATED
QList< Message >searchRemote (bb::pim::account::AccountKey accountId, const MessageSearchFilter &filter, quint32 *totalItemsOnServer)
MessageKeysend (bb::pim::account::AccountKey accountId, const Message &message)
boolsetFolderSyncConfig (bb::pim::account::AccountKey accountId, MessageFolderKey folderId, bool syncConfig)
voidsetFollowupFlag (bb::pim::account::AccountKey accountId, MessageKey messageId, const MessageFlag &followupFlag)
voidsetOutOfOffice (bb::pim::account::AccountKey accountId, const OutOfOfficeSettings &outOfOffice)
voidsetPriority (bb::pim::account::AccountKey accountId, MessageKey messageId, MessagePriority::Type priority)
voidsetStatus (bb::pim::account::AccountKey accountId, MessageKey messageId, MessageStatus::Types status)
voidsetStatus (bb::pim::account::AccountKey accountId, ConversationKey conversationId, ConversationStatus::Types status)
voidsetTransmissionStatus (bb::pim::account::AccountKey accountId, MessageKey messageId, MessageTransmissionStatus::Type transmissionStatus)
voidsetTypingStatus (bb::pim::account::AccountKey accountId, ConversationKey conversationId, bool typing)
MessageKeysmartForward (bb::pim::account::AccountKey accountId, const Message &message, bool isOrignalMsgEdited)
MessageKeysmartReply (bb::pim::account::AccountKey accountId, const Message &message, bool isOrignalMsgEdited)
voidsyncAccounts (const QList< bb::pim::account::AccountKey > &accountIds)
voidsyncFolder (bb::pim::account::AccountKey accountId, MessageFolderKey folderId) const
voidunHide (bb::pim::account::AccountKey accountId, MessageKey messageId)
voidunHide (bb::pim::account::AccountKey accountId, ConversationKey conversationId)
voidunHidePrior (QList< bb::pim::account::AccountKey > accountIds, const MessageUpdateFilter &filter)

Signals Index

voidaccountAdded (bb::pim::account::AccountKey accountId)
voidaccountConnected (bb::pim::account::AccountKey accountId)
voidaccountDefaultChanged (bb::pim::account::AccountKey accountId)
voidaccountInvalidated (bb::pim::account::AccountKey accountId)
voidaccountRemoved (bb::pim::account::AccountKey accountId)
voidaccountUpdated (bb::pim::account::AccountKey accountId)
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)
voidattachmentDownloadStatusChanged (bb::pim::account::AccountKey accountId, bb::pim::message::MessageKey messageId, bb::pim::message::AttachmentKey attachmentId, int percentDownloaded)
voidbodyDownloaded (bb::pim::account::AccountKey accountId, bb::pim::message::MessageKey messageId)
voidconversationAdded (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId)
voidconversationRemoved (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId)
voidconversationRemoved (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId, const QList< bb::pim::message::MessageKey > &messageIds)
voidconversationUpdated (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId, bb::pim::message::ConversationUpdate data)
voiddatalockedMessageAdded (bb::pim::account::AccountKey accountId, const QString &mimeType, int count)
voidfolderAdded (bb::pim::account::AccountKey accountId, bb::pim::message::MessageFolderKey folderId)
voidfolderEmptied (bb::pim::account::AccountKey accountId, bb::pim::message::MessageFolderKey folderId)
voidfolderHierarchySynced (bb::pim::account::AccountKey accountId)
voidfolderRemoved (bb::pim::account::AccountKey accountId, bb::pim::message::MessageFolderKey folderId)
voidfolderSyncCompleted (bb::pim::account::AccountKey accountId, bb::pim::message::MessageFolderKey folderId)
voidfolderSyncStarted (bb::pim::account::AccountKey accountId, bb::pim::message::MessageFolderKey folderId, int count)
voidfolderUpdated (bb::pim::account::AccountKey accountId, bb::pim::message::MessageFolderKey folderId)
voidmessageAdded (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId, bb::pim::message::MessageKey messageId)
voidmessageDownloadStatusChanged (bb::pim::account::AccountKey accountId, bb::pim::message::MessageKey messageId, int percentDownloaded)
voidmessageRemoved (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId, bb::pim::message::MessageKey messageId, QString sourceId)
voidmessagesAdded (bb::pim::account::AccountKey accountId, QList< bb::pim::message::ConversationKey > conversationIds, QList< bb::pim::message::MessageKey > messageIds)
voidmessageSyncCompleted (bb::pim::account::AccountKey accountId)
voidmessageUpdated (bb::pim::account::AccountKey accountId, bb::pim::message::ConversationKey conversationId, bb::pim::message::MessageKey messageId, bb::pim::message::MessageUpdate data)
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 (
  • bb::pim::account::AccountKeyaccountId,
  • QObject *parent )

~MessageService ()

Destructor.

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

QList< FileAttachment > attachments (

Retrieves a list of attachments that fit the provided criteria.

You can use this function to retrieve the Attachment objects from a specific account, or all accounts, that fit a set of criteria (represented by a AttachmentFilter), and then use this to display the attachments in your UI (for example, in a list view). Attachments for all accounts are retrieved if the accountId is equal to bb::pim::account::InvalidKey. If a valid accountId is specified along with an empty conversationId, then all attachments are retrieved for that account only. Specifying a valid conversationId along with its corresponding accountId retrieves the attachments that are contained within that single conversation.

Parameters
accountId

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

conversationId

The ID of a pre-existing conversation.

filter

The criteria to use to retrieve the attachments.

Return:

A QList of attachments that fit the provided criteria.

Since:

BlackBerry 10.2.0

void bulkOperationOnConversations (

Performs a bulk operation on a list of conversations.

This operation supports the following operations: mark conversations read, mark conversations unread, delete conversations and hide conversations. Conversations must be supplied in batches of 100 or less per account. Exceeding 100 conversations per account will cause the operation to fail and no conversation will be processed.
Parameters
data

A map containing account IDs and corresponding list of conversations to be updated.

operationType

Specifies the type of operation to perform (mark read/unread, hide or delete).

Since:

BlackBerry 10.3.1

void bulkOperationOnMessages (

Performs a bulk operation on a list of messages.

This function supports the following operations: mark messages read, mark messages unread, delete messages and hide messages. Messages must be supplied in batches of 100 or less per account. Exceeding 100 messages per account will cause the operation to fail and no message will be processed.
Parameters
data

A map containing account IDs and corresponding list of messages to be updated.

operationType

Specifies the type of operation to perform (mark read/unread, hide, or delete).

Since:

BlackBerry 10.3.1

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

Clears the transaction logs up to the specified transaction key for an account.

Parameters
accountId

The account ID of the account to clear the transaction logs for.

id

The transaction key of the transaction up to which to clear the logs.

Return:

true if the logs were cleared successfully, false otherwise.

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

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

Returns the total count of transaction logs entries for an account.

Parameters
accountId

The account ID of the account to count transaction entries.

Return:

a positive int value matching the total transaction entries, 0 if none exist.

Since:

BlackBerry 10.3.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

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 that meet the given search filter criteria.

Parameters
accountIds

A list of account IDs to delete messages from.

filter

The criteria to use for the search.

dateTime

The date and time representing the 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).

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

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

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

Downloads partial or full contents of a single message from the messaging service.

This function is an asynchronous call to retrieve the remaining message from the messaging service, based on the provided account ID and message ID. You can use this function to download the partial or 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.

partial

If true and the underlying protocol supports partial bodies, then the partial message contents are requested from the server; if the underlying protocol does not support partial bodies, then the full message is requested. If false, the full message is downloaded. Note that partial bodies are not supported by all email protocols.

Since:

BlackBerry 10.3.1

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

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

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

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

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

Mark a message as hidden.

You can use this function to mark a message with a specific account ID and message ID as hidden. 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.3.0

void hide (

Marks a conversation as hidden.

You can use this function to mark a conversation with a specific account ID and conversation ID as hidden. 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.3.0

void hidePrior (

Marks messages as hidden prior to the specified date.

Parameters
accountIds

A list of account IDs for which to mark messages as read or unread, or to delete messages from.

filter

The MessageupdateFilter used for specifying options, such as date prior, folder ID, and so on.

Since:

BlackBerry 10.3.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 markOrDeletePrior (

Marks messages as read or unread, or deletes all messages prior to the provided date and time and that meet the given MarkOrDeletePriorFilter criteria.

Parameters
accountIds

A list of account IDs for which to mark messages as read or unread, or to delete messages from.

filter

The MarkOrDeletePriorFilter used for specifying options, such as date prior, folder ID, and so on.

operationType

Specifies the type of operation to perform, for example: MarkOrDeletePriorOp::MarkPriorRead, MarkOrDeletePriorOp::MarkPriorUnread, or MarkOrDeletePriorOp::DeletePrior.

Since:

BlackBerry 10.1.0

void markOrDeletePriorForSearch (

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

Parameters
accountIds

A list of account IDs for which to mark messages as read or unread, or to delete messages from.

filter

The criteria to use for the search.

dateTime

The date and time representing the 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).

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

operationType

Specifies the type of operation to perform, for example: MarkOrDeletePriorOp::MarkPriorRead, MarkOrDeletePriorOp::MarkPriorUnread, or MarkOrDeletePriorOp::DeletePrior.

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 and time as read or unread.

Parameters
accountIds

A list of account IDs for which to mark messages as read or unread.

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 and time and that meet the given search filter criteria, as read or unread.

Parameters
accountIds

A list of account IDs for which to mark messages as read or unread.

filter

The criteria to use for the search.

dateTime

The date and time representing the 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).

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 the messages are marked as read, if false the messages are marked as unread.

Since:

BlackBerry 10.1.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 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 (
  • 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 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

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

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

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

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

Retrieves a list of message transactions for an account.

You can use this function to sync any messaging changes from the message service.

Parameters
accountId

The account ID of the account to retrieve message transactions from.

Since:

BlackBerry 10.0.0

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

Retrieves a list of message transactions for an account.

You can use this function to sync any messaging changes from the message service.

Parameters
accountId

The account ID of the account to retrieve message transactions from.

limit

The max number of transactions to get, if 0 defaults to 100.

Since:

BlackBerry 10.3.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 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 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 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

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

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.

This method is deprecated. Use searchRemote that takes additional parameter totalItemsOnServer.
Since:

BlackBerry 10.0.0

QList< Message > searchRemote (
  • bb::pim::account::AccountKeyaccountId,
  • const MessageSearchFilter &filter,
  • quint32 *totalItemsOnServer )

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.

totalItemsOnServer

The number of items in the result set returned by the server. A valid pointer should be passed in to get the number of items in a result set back.

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

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

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

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 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 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 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 not used for SMS or MMS accounts.

Parameters
accountId

The 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

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

Forwards a message if the 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(), you provide either the delta of changes in the body of the message or the entire contents of the body, depending on whether isOrignalMsgEdited is set. 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

True if the provider should treat the contents of message as the delta of changes, false if the entire message is provided.

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 the 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(), you provide either the delta of changes in the body of the message or the entire contents of the body, depending on whether isOrignalMsgEdited is set. 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

True if the provider should treat the contents of message as the delta of changes, false if the entire message is provided.

Return:

The message ID of the sent message.

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 unHide (
  • bb::pim::account::AccountKeyaccountId,
  • MessageKeymessageId )

Mark a message as unhidden.

You can use this function to mark a message with a specific account ID and message ID as unhidden. 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.3.0

void unHide (

Marks a conversation as unhidden.

You can use this function to mark a conversation with a specific account ID and conversation ID as unhidden. 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.3.0

void unHidePrior (

Marks messages as un-hidden prior to the specified date.

Parameters
accountIds

A list of account IDs for which to mark messages as read or unread, or to delete messages from.

filter

The MessageupdateFilter used for specifying options, such as date prior, folder ID, and so on.

Since:

BlackBerry 10.3.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 accountConnected (
  • bb::pim::account::AccountKeyaccountId)

Emitted when an account is connected.

Parameters
accountId

The account ID of the account that is connected.

Since:

BlackBerry 10.2.0

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

Since:

BlackBerry 10.2.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 attachmentDownloaded (
  • bb::pim::account::AccountKeyaccountId,
  • bb::pim::message::MessageKeymessageId,
  • bb::pim::message::AttachmentKeyattachmentId )

Emitted when an attachment has finished downloading.

Parameters
accountId

The account ID of the account that contains the message.

messageId

The messageId of the message.

attachmentId

The attachment ID of the attachment.

Since:

BlackBerry 10.0.0

void attachmentDownloadFailed (

Emitted when an attachment isn't downloaded successfully.

Parameters
accountId

The account ID of the account that contains the message.

messageId

The message ID of the message.

attachmentId

The attachment ID of the attachment.

attachmentStatus

The status code of the attachment, which indicates why the attachment wasn't downloaded successfully.

Since:

BlackBerry 10.0.0

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

Emitted when the download status of an attachment changes.

For example, this signal is emitted when an attachment is being downloaded incrementally.

Parameters
accountId

The account ID of the account that contains the message.

messageId

The message ID of the message.

attachmentId

The attachment ID of the attachment.

percentDownloaded

The percentage of the attachment that's finished downloading.

Since:

BlackBerry 10.0.0

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

Emitted when the body of a message is downloaded.

Parameters
accountId

The account ID of the account that contains the message.

messageId

The message ID of the message.

Since:

BlackBerry 10.0.0

void conversationAdded (

Emitted when a conversation is added to the message service.

You can respond to this signal by updating your conversation list in your app. This signal is used only for SMS accounts.

Parameters
accountId

The account ID of the conversation that was added.

conversationId

The conversation ID of the new conversation.

Since:

BlackBerry 10.0.0

void conversationRemoved (

Emitted when a conversation is removed from the message service.

You can respond to this signal by updating your conversation list in your app.

Parameters
accountId

The account ID of the conversation that was removed.

conversationId

The conversation ID of the conversation that was removed.

Since:

BlackBerry 10.0.0

void conversationRemoved (

Emitted when a conversation is removed from the message service.

You can respond to this signal by updating your conversation list in your app.

Parameters
accountId

The account ID of the conversation that was removed.

conversationId

The conversation ID of the conversation that was removed.

messageIds

The list message IDs in the conversation that was removed.

Since:

BlackBerry 10.3.1

void conversationUpdated (

Emitted when a conversation is updated in the message service.

You can respond to this signal by updating your conversation list in your app. This signal is used only for SMS accounts.

Parameters
accountId

The account ID of the conversation that was updated.

conversationId

The conversation ID of the conversation that was updated.

data

The data regarding the update, as a ConstConversationUpdateSharedPtr. You can apply this update to the corresponding Conversation in your app.

Since:

BlackBerry 10.0.0

void datalockedMessageAdded (
  • bb::pim::account::AccountKeyaccountId,
  • const QString &mimeType,
  • intcount )

Emitted when a new message is available during a data locked state when Advanced Data at Rest Protection is enabled.

This signal indicates that a new email is available while the device Advanced Data at Rest Protection enabled and the device is in a data locked state. The user will need to unlock the device before the message can be retrieved. This signal is only an indication that a new email is available, after unlock the messageAdded signal will occur as normal.
See also:

messageAdded()

Parameters
accountID

the account ID of the account that contains the message.

mimeType

the mime type of the available message.

count

how many messages are available

Since:

BlackBerry 10.3.0

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

Emitted when a folder is added to the message service.

You can respond to this signal by updating your folder list in your app.

Parameters
accountId

The account ID of the folder that was added.

folderId

The folder ID of the folder that was added.

Since:

BlackBerry 10.0.0

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

Emitted when a folder becomes out of sync and is updated by the service.

This signal is emitted in rare cases where the folder becomes out of sync with the server and the service re-synchronizes the folder. This signal is not emitted when all of the messages in a folder are deleted manually.

Parameters
accountId

The account ID of the folder that was re-synchronized.

folderId

The folder ID of the folder that was re-synchronized.

Since:

BlackBerry 10.0.0

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

Emitted when the folder hierarchy (for example, folder names and structure) for an account is synced.

This signal is emitted every time the folder hierarchy for an account is synced. For example, the folder hierarchy might be synced when all of the folders for the account have been added but the folder content and messages are not synced yet.

This signal is emitted for all types of email providers (ActiveSync, IMAP, and POP). Note that this signal is emitted only for email accounts. For non-email accounts, such as LinkedIn, Facebook, and so on, this signal is not emitted.

Parameters
accountId

The account ID of the account that is being synced.

Since:

BlackBerry 10.3.0

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

Emitted when a folder is removed from the message service.

Parameters
accountId

The account ID of the folder that was removed.

folderId

The folder ID of the folder that was removed.

Since:

BlackBerry 10.0.0

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

Emitted when a folder synchronization finishes.

Parameters
accountId

The account ID of the folder that finished synchronizing.

folderId

The folder ID of the folder that finished synchronizing.

Since:

BlackBerry 10.0.0

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

Emitted when a folder synchronization starts.

You can respond to this signal by updating your folder list view and any new messages in the specified folder in your app.

Parameters
accountId

The account ID of the folder that started synchronizing.

folderId

The folder ID of the folder that started synchronizing.

count

The number of messages being updated in the folder.

Since:

BlackBerry 10.0.0

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

Emitted when a folder is updated in the message service.

For example, this signal is emitted when the name of a folder is changed.

Parameters
accountId

The account ID of the folder that was updated.

folderId

The folder ID of the folder that was updated.

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 messageDownloadStatusChanged (
  • bb::pim::account::AccountKeyaccountId,
  • bb::pim::message::MessageKeymessageId,
  • intpercentDownloaded )

Emitted when the download status of a message changes.

For example, this signal is emitted when a message (such as an MMS message) is being downloaded incrementally.

Parameters
accountId

The account ID of the account that contains the message.

messageId

The message ID of the message.

percentDownloaded

The percentage of the message that's finished downloading.

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 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 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 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 typingStatusChanged (

Emitted when the typing status in a conversation changes.

This signal indicates that a participant in a conversation has either started typing or stopped typing. This signal is used only for accounts that support the idea of presence, and it is not used for SMS or MMS accounts.

Parameters
accountId

The account ID of the account that contains the message.

conversationId

The conversation ID of the conversation.

typing

If true the participant has started typing, if false the participant has stopped typing.

Since:

BlackBerry 10.0.0

Last modified: 2014-11-17



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

comments powered by Disqus