MessageBuilder

Since: BlackBerry 10.0.0

#include <bb/pim/message/MessageBuilder>

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

The MessageBuilder class lets you create, and specify properties for, a new Message or edit an existing Message.

You can use this class to set properties, such as status, subject, and body, for a Message. This class uses the builder pattern to create a Message and set its properties. Each of the setter functions returns a self reference to the builder, allowing you to chain function calls together. For example, here's how to create a Message using the builder pattern:

Message createMessage()
{
    MessageBuilder *builder = MessageBuilder::create(1);
    QString subject = "Test Subject ";
    MessageContact rto = MessageContact(-1 ,MessageContact::To,
                                        "Test Act1",
                                        "TestAct1@gmail.com");
    MessageContact rtoCC = MessageContact(-1, MessageContact::Cc,
                                          "Test Act2",
                                          "TestAct2@yahoo.com");
    MessageContact rtoBCC  = MessageContact(-1, MessageContact::Bcc,
                                            "Test Act3",
                                            "TestAct3@hotmail.com");
    QByteArray bodyData = "Testing email body";
    builder->subject(subject);
    bool added;
    builder->addRecipient(rto,&added);
    builder->addRecipient(rtoCC,&added);
    builder->addRecipient(rtoBCC,&added);
    builder->body(MessageBody::Html,bodyData);
    Attachment attachment(attachmentType, attachmentName,
                          QUrl::fromLocalFile(attachmentPath));
    builder->addAttachment(attachment);
    Message message = *builder;
    delete builder;
    return message;

}

Any changes that you make to a Message using this builder are temporary until the changes are saved using the MessageService.


Overview

Public Functions Index

~MessageBuilder ()
MessageBuilder &addAttachment (const Attachment &attachment, bool *ok=0)
MessageBuilder &addRecipient (const MessageContact &recipient, bool *ok=0)
AttachmentattachmentAt (int index) const
intattachmentCount () const
QList< Attachment >attachments () const
MessageBodybody () const
MessageBuilder &body (MessageBody::Type type, const QByteArray &data)
ConversationKeyconversationId () const
MessageBuilder &conversationId (ConversationKey conversationId)
QDateTimedeviceTimestamp () const
MessageBuilder &deviceTimestamp (QDateTime deviceTimestamp)
MessageFolderKeyfolderId () const
MessageBuilder &folderId (MessageFolderKey folderId)
MessageFlagfollowupFlag () const
MessageBuilder &followupFlag (const MessageFlag &followupFlag)
boolhasContent () const
boolhasRecipients () const
MessageKeyid () const
MessageBuilder &id (MessageKey id)
MessageBuilder &inbound (bool inbound)
boolisInbound () const
operator Message ()
MessageBuilder &origMessageId (MessageKey origMessageId)
MessagePriority::Typepriority () const
MessageBuilder &priority (MessagePriority::Type priority)
MessageContactrecipientAt (int index) const
intrecipientCount () const
QList< MessageContact >recipients () const
MessageBuilder &referencesSyncId (QString referencesSyncId)
MessageBuilder &removeAllAttachments ()
MessageBuilder &removeAllRecipients ()
MessageBuilder &removeAttachment (const Attachment &attachment, bool *ok=0)
MessageBuilder &removeRecipient (const MessageContact &recipient, bool *ok=0)
MessageBuilder &replaceAllRecipients (const QList< MessageContact > &recipients)
MessageContactsender () const
MessageBuilder &sender (const MessageContact &sender)
QDateTimeserverTimestamp () const
MessageBuilder &serverTimestamp (QDateTime serverTimestamp)
intsize () const
MessageStatus::Typesstatus () const
MessageBuilder &status (MessageStatus::Types status)
QStringsubject () const
MessageBuilder &subject (const QString &subject)
longtransmissionStatus () const
MessageBuilder &transmissionStatus (long transmissionStatus)
QStringtype () const

Static Public Functions Index

MessageBuilder *create (bb::pim::account::AccountKey accountId)
MessageBuilder *create (bb::pim::account::AccountKey accountId, const Message &message)

Public Functions

~MessageBuilder ()

Destructor.

Since:

BlackBerry 10.0.0

MessageBuilder & addAttachment (

Adds an attachment to the message.

Parameters
attachment

The attachment to add.

ok

Indicates whether the operation was successful. If true the attachment was added successfully, if false the attachment was not added successfully.

Return:

A MessageBuilder with the provided attachment added.

Since:

BlackBerry 10.0.0

MessageBuilder & addRecipient (

Adds a recipient to the message.

Parameters
recipient

The recipient to add.

ok

Indicates whether the operation was successful. If true the recipient was added successfully, if false the recipient was not added successfully.

Return:

A MessageBuilder with the provided recipient added.

Since:

BlackBerry 10.0.0

Attachment attachmentAt (
  • intindex)

Retrieves the attachment at the provided index of the Message that this MessageBuilder represents.

Parameters
index

The index of the attachment to retrieve.

Return:

The attachment at the provided index.

Since:

BlackBerry 10.0.0

int attachmentCount ()

Retrieves the number of attachments for the Message that this MessageBuilder represents.

Return:

The number of attachments.

Since:

BlackBerry 10.0.0

QList< Attachment > attachments ()

Retrieves the list of attachments for the Message that this MessageBuilder represents.

Return:

The list of attachments.

Since:

BlackBerry 10.0.0

MessageBody body ()

Retrieves the body of the Message that this MessageBuilder represents.

Return:

The message's body.

Since:

BlackBerry 10.0.0

MessageBuilder & body (

Sets the body of the message.

Parameters
type

The type of body to set (plain text or HTML).

data

The body data to set.

Return:

A MessageBuilder with the provided body type and body data.

Since:

BlackBerry 10.0.0

ConversationKey conversationId ()

Retrieves the coversation ID of the Message that this MessageBuilder represents.

Return:

The conversation's ID.

Since:

BlackBerry 10.0.0

MessageBuilder & conversationId (

Sets the conversation ID of the message.

Parameters
conversationId

The message's conversation ID.

Return:

A MessageBuilder with the provided conversation ID.

Since:

BlackBerry 10.0.0

QDateTime deviceTimestamp ()

Retrieves the device timestamp of the Message that this MessageBuilder represents.

The device timestamp represents the time that the message data was created on the device.

Return:

The device timestamp.

Since:

BlackBerry 10.0.0

MessageBuilder & deviceTimestamp (

Sets the device timestamp for the message.

Parameters
deviceTimestamp

The device timestamp.

Return:

A MessageBuilder with the provided device timestamp.

Since:

BlackBerry 10.0.0

MessageFolderKey folderId ()

Retrieves the folder ID of the Message that this MessageBuilder represents.

Return:

The message's folder ID.

Since:

BlackBerry 10.0.0

MessageBuilder & folderId (
  • MessageFolderKeyfolderId)

Sets the folder ID of the message.

Parameters
folderId

The message's folder ID.

Return:

A MessageBuilder with the provided folder ID.

Since:

BlackBerry 10.0.0

MessageFlag followupFlag ()

Retrieves the follow-up flag for the Message that this MessageBuilder represents.

Return:

The message's follow-up flag.

Since:

BlackBerry 10.0.0

MessageBuilder & followupFlag (

Sets the follow-up flag of the message.

Parameters
followupFlag

The message's follow-up flag.

Return:

A MessageBuilder with the provided follow-up flag.

Since:

BlackBerry 10.0.0

bool hasContent ()

Indicates whether the Message that this MessageBuilder represents has any content (such as recipients, subject, body, or attachments).

Return:

true if the message has content, false otherwise.

Since:

BlackBerry 10.0.0

bool hasRecipients ()

Indicates whether the Message that this MessageBuilder represents has any recipients.

Return:

true if the message has recipients, false otherwise.

Since:

BlackBerry 10.0.0

MessageKey id ()

Retrieves the ID of the Message that this MessageBuilder represents.

Return:

The message's ID.

Since:

BlackBerry 10.0.0

MessageBuilder & id (
  • MessageKeyid)

Sets the ID of the message.

Parameters
id

The message's ID.

Return:

A MessageBuilder with the provided message ID.

Since:

BlackBerry 10.0.0

MessageBuilder & inbound (
  • boolinbound)

Sets whether the message is an inbound message.

Parameters
If

true the message is an inbound message, if false the message is not an inbound message.

Return:

A MessageBuilder with the provided indication of whether the message is an inbound message.

Since:

BlackBerry 10.0.0

bool isInbound ()

Indicates whether the Message that this MessageBuilder represents is an inbound message.

Return:

true if the message is an inbound message, false otherwise.

Since:

BlackBerry 10.0.0

operator Message ()

Cast operator.

This operator casts an object to the Message type.

Since:

BlackBerry 10.0.0

MessageBuilder & origMessageId (
  • MessageKeyorigMessageId)

Sets the original message ID for this Message.

You can use this ID to to refer to the message that's being replied to.

Parameters
origMessageId

The original message ID as a MessageKey.

Return:

A MessageBuilder with the provided original message ID.

Since:

BlackBerry 10.0.0

MessagePriority::Type priority ()

Retrieves the priority of the Message that this MessageBuilder represents.

Return:

The message's priority.

Since:

BlackBerry 10.0.0

MessageBuilder & priority (

Sets the priority of the message.

Parameters
priority

The message's priority.

Return:

A MessageBuilder with the provided priority.

Since:

BlackBerry 10.0.0

MessageContact recipientAt (
  • intindex)

Retrieves the recipient at the provided index of the Message that this MessageBuilder represents.

Parameters
index

The index of the recipient to remove.

Return:

The recipient at the provided index.

Since:

BlackBerry 10.0.0

int recipientCount ()

Retrieves the number of recipients for the Message that this MessageBuilder represents.

Return:

The number of recipients.

Since:

BlackBerry 10.0.0

QList< MessageContact > recipients ()

Retrieves the list of recipients for the Message that this MessageBuilder represents.

Return:

The list of recipients.

Since:

BlackBerry 10.0.0

MessageBuilder & referencesSyncId (

Sets the references sync ID for the Message that this MessageBuilder represents.

The references sync ID is used for smart replies.

Parameters
referencesSyncId

The references sync ID to set.

Return:

A MessageBuilder with the provided references sync ID.

Since:

BlackBerry 10.0.0

MessageBuilder & removeAllAttachments ()

Removes all attachments from the message.

Return:

A MessageBuilder with all attachments removed.

Since:

BlackBerry 10.0.0

MessageBuilder & removeAllRecipients ()

Removes all recipients from the message.

Return:

A MessageBuilder with all recipients removed.

Since:

BlackBerry 10.0.0

MessageBuilder & removeAttachment (

Removes a previously added attachment from the message.

Parameters
attachment

The attachment to remove.

ok

Indicates whether the operation was successful. If true the attachment was removed successfully, if false the attachment was not removed successfully.

Return:

A MessageBuilder with the provided attachment removed.

Since:

BlackBerry 10.0.0

MessageBuilder & removeRecipient (

Removes a previously added recipient from the message.

Parameters
recipient

The recipient to remove.

ok

Indicates whether the operation was successful. If true the recipient was removed successfully, if false the recipient was not removed successfully.

Return:

A MessageBuilder with the provided recipient removed.

Since:

BlackBerry 10.0.0

MessageBuilder & replaceAllRecipients (

Replaces all recipients of the message with the provided list of recipients.

Parameters
recipients

The list of recipients to replace the current recipients with.

Return:

A MessageBuilder with the provided recipients list.

Since:

BlackBerry 10.0.0

MessageContact sender ()

Retrieves the sender of the Message that this MessageBuilder represents.

Return:

The message's sender.

Since:

BlackBerry 10.0.0

MessageBuilder & sender (

Sets the sender of the message.

Parameters
sender

The message's sender.

Return:

A MessageBuilder with the provided sender.

Since:

BlackBerry 10.0.0

QDateTime serverTimestamp ()

Retrieves the server timestamp of the Message that this MessageBuilder represents.

The server timestamp represents the time the message data was sent to the server. This value is not valid for outbound messages.

Return:

The server timestamp.

Since:

BlackBerry 10.0.0

MessageBuilder & serverTimestamp (

Sets the server timestamp for the message.

Parameters
serverTimestamp

The server timestamp.

Return:

A MessageBuilder with the provided server timestamp.

Since:

BlackBerry 10.0.0

int size ()

Retrieves the size (in bytes) of the Message that this MessageBuilder represents.

Return:

The message's size (in bytes).

Since:

BlackBerry 10.0.0

MessageStatus::Types status ()

Retrieves the status of the Message that this MessageBuilder represents.

Return:

The message's status.

Since:

BlackBerry 10.0.0

MessageBuilder & status (
  • MessageStatus::Typesstatus)

Sets the status of the message.

Parameters
status

The message's status.

Return:

A MessageBuilder with the provided status.

Since:

BlackBerry 10.0.0

QString subject ()

Retrieves the subject of the Message that this MessageBuilder represents.

Return:

The message's subject.

Since:

BlackBerry 10.0.0

MessageBuilder & subject (

Sets the subject of the message.

Parameters
subject

The message's subject.

Return:

A MessageBuilder with the provided subject.

Since:

BlackBerry 10.0.0

long transmissionStatus ()

Retrieves the transmission status of the Message that this MessageBuilder represents.

Return:

The message's transmission status.

Since:

BlackBerry 10.0.0

MessageBuilder & transmissionStatus (
  • longtransmissionStatus)

Sets the status of the message.

Parameters
transmissionStatus

The message's status.

Return:

A MessageBuilder with the provided status.

Since:

BlackBerry 10.0.0

QString type ()

Retrieves the type of the Message that this MessageBuilder represents.

For protocols such as text messaging, this value may change based on the contents of the builder.

Return:

The message's type.

Since:

BlackBerry 10.0.0

Static Public Functions

MessageBuilder * create (
  • bb::pim::account::AccountKeyaccountId)

Creates a new MessageBuilder for the provided account ID.

Parameters
accountId

The account ID to create the message for (for example, an SMS or email account ID).

Return:

A MessageBuilder object.

Since:

BlackBerry 10.0.0

MessageBuilder * create (
  • bb::pim::account::AccountKeyaccountId,
  • const Message &message )

Creates a new MessageBuilder for the provided account ID and message.

Based on the account ID and message that are provided (for example, corresponding to a chat or messaging message), the appropriate type of MessageBuilder is returned. You can use this function to create a copy MessageBuilder based on an existing message, and then use other functions in this class to edit that message.

Parameters
accountId

The account ID to create the message for (for example, an SMS or email account ID).

message

The message to be copied and edited.

Return:

A MessageBuilder object.

Since:

BlackBerry 10.0.0

Last modified: 2014-06-24



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

comments powered by Disqus