BlackBerry Spark Communications Services for iOS  1.11.0
BBMChatMessage Class Reference
Inheritance diagram for BBMChatMessage:
BBMElement BBMElementBase

Class Methods

(BBMChatMessageFileState+ valueForFileStateString:
 
(NSString *) + stringForFileStateValue:
 
(BBMChatMessageRecall+ valueForRecallString:
 
(NSString *) + stringForRecallValue:
 
(BBMChatMessageState+ valueForStateString:
 
(NSString *) + stringForStateValue:
 
(BOOL) + tagIsDefined:
 
- Class Methods inherited from BBMElementBase
(NSString *) + identifierOfElement:
 

Properties

NSString * chatId
 
NSString * content
 
BBMChatMessage_Datadata
 
NSDictionary * rawData
 
NSString * externalId
 
NSString * file
 
NSNumber * fileSize
 
BBMChatMessageFileState fileState
 
NSString * flags
 
BOOL isControlFlagSet
 
BOOL isDeletedFlagSet
 
BOOL isIncomingFlagSet
 
BOOL isNeverCountUnreadFlagSet
 
BOOL isUnverifiedFlagSet
 
NSDictionary * localData
 
unsigned long long messageId
 
BBMChatMessageRecall recall
 
NSArray * ref
 
NSArray * refBy
 
NSString * senderUri
 
BBMChatMessageState state
 
BOOL stateIsPartial
 
NSString * tag
 
NSString * thumb
 
unsigned long long timestamp
 
BBMChatresolvedChatId
 
BBMUserresolvedSenderUri
 
- Properties inherited from BBMElement
BBMElementState bbmState
 
NSString * primaryKey
 
- Properties inherited from BBMElementBase
BBMContainerparentContainer
 The container (BBMLiveList or BBMLiveMap) holding this element. More...
 

Additional Inherited Members

- Instance Methods inherited from BBMElementBase
(BBMDSModel *) - masterModel
 
(id) - objectForKeyedSubscript:
 

Detailed Description

Each element in this list is a message in a chat. The primary key for each element is the 'chatId' and 'messageId'.

The range of valid message ids for a given chat can be found in the chat list as ['lastMessage'

  • 'numMessages', 'lastMessage'].

When a new message is added to a chat, bbmcore will first 'listAdd' the message entry, and then will 'listChange' the chat to update the 'lastMessage' and 'numMessages' fields.

Note that 'listRemove' is not supported for this list. The message counters maintained in the chat list indicate when messages have been removed from this list.

Since
R2

Method Documentation

◆ tagIsDefined:()

+ (BOOL) tagIsDefined: (NSString *)  DEPRECATED_ATTRIBUTE

Returns YES iff the given tag is one defined in the BBMDS specification.

Since
R3
Deprecated:
R4

Property Documentation

◆ chatId

- (NSString*) chatId
readnonatomicstrong

The unique identifier of the chat to which this message belongs.

Since
R2

◆ content

- (NSString*) content
readnonatomicstrong

Holds the text content of the message, when the 'tag' has such a concept; otherwise omitted.

Since
R2

◆ data

- (BBMChatMessage_Data*) data
readnonatomicstrong

This field contains opaque data managed by your application that is sent with the message. Unless specifically noted, bbmcore does not examine or modify this JSON object.This can contain a single JSON object, or it can not exist at all. It cannot contain any other JSON type.Many 'tag' values have a corresponding object defined as a child of the 'data' object with a key equal to the 'tag'. All 'tags' with such a corresponding child of 'data' require that child to be present. Other tags have no such requirement.The 'data' object can also contain other key-value pairs independently from the 'tag'.

Since
R2

◆ externalId

- (NSString*) externalId
readnonatomicstrong

The identifier used externally to uniquely identify this chat message.This field is present iff this chat message has such an identifier when this BBMDS message was emitted. Bbmcore does not emit 'listChange' or 'listElement' messages when this identifier becomes known for a message that previously lacked one.

Since
R13

◆ file

- (NSString*) file
readnonatomicstrong

A path to a large file that is not carried in the message. This file is uploaded or download by bbmcore automatically. For downloads, this will only be set once 'fileState' progresses to 'Done'.A maximum file size limit of 128 MB is imposed by bbmcore. The size limit may change in future versions. Clients that encounter files that are larger than their maximums will not download them.

Since
R2

◆ fileSize

- (NSNumber*) fileSize
readnonatomicstrong

The advertised size of the file, in bytes, as indicated by the sender. This field is only meaningful when this message has a file attachment. The actual file size can differ from this advertised size.When the sender did not indicate a size, this field will not be present. Otherwise, this value is available in all 'fileState' states, even before any attempt is made to download a received attachment. Your application can use this value to decide whether or not to download the attachment.In versions after this field was introduced, bbmcore automatically includes this size value when attaching a file to an outgoing message.

Since
R7

◆ fileState

- (BBMChatMessageFileState) fileState
readnonatomicassign

Indicates the state of file upload or download.Generally, whether the transfer is an upload or download is not exposed to your application. However, some states imply that the transfer is a download that can be started or restarted by the 'chatMessageFileDownload' message. The 'incoming' 'flag' on this 'chatMessage' does not indicate whether the transfer is an upload or download.Bbmcore automatically handles temporary errors during uploads and downloads. Such errors and the retries that occur are not exposed to your application. Eventually, bbmcore will give up and place a transfer into either the 'Failed' or 'FailedAvailable' state.

Since
R2

◆ flags

- (NSString*) flags
readnonatomicstrong

Compact read-only flags about the message. Each flag that is 'true' has its corresponding letter present in the string. Each flag that is 'false' has its corresponding letter not present in the string. The letters will always be provided in alphabetical order.

Since
R2

◆ isControlFlagSet

- (BOOL) isControlFlagSet
readnonatomicassign

This message was flagged by the sending application as being for control purposes versus for display purposes. This flag is useful for introducing new custom message types (typically with a new 'tag' value) that older endpoints do not understand.Some applications, such as Instant Messaging applications, will want to inform the user that some message was received even when that type of message is unknown to the endpoint. For example, an Instant Messaging application might show "This item is not supported." when an unknown type of message is received in a chat. This lets users know they received something, but their client can't display it.This flag is meant to allow a sender to prevent the display of such placeholders for messages that the receiver doesn't understand. When an endpoint receives a message that it does not understand and the message has this flag set, it should ignore the message and not even attempt to display a placeholder. The flag indicates that the receiving endpoint is safe to assume that the message was never meant to be displayed in any versions of the application. In this way, any older endpoint that knows about this flag and behaves accordingly can be told which messages are worth displaying placeholders for and which messages are "control" messages that it can completely ignore even when those messages (and their 'tag' values) were not yet invented when the older endpoint was made.There is a subtle distinction between understanding and supporting a message. Receivers that do understand a received message should ignore this flag and decide how to handle it based on what they do and don't want to support. Changes should be designed so that receivers that partially understand a received message, and, for example, know its 'tag' and how to display its 'content' but which don't know all of the 'data' fields should be able to use what they can from the message and still behave properly. It is only receivers that do not even understand the message that should consider this flag.When sending a newly introduced message type, consider whether receivers that are completely ignorant of the message should display a placeholder or not. If and only if they never should, then set this flag.If your application has no concept of placeholders, this flag is irrelevant. Bbmcore does not set or act upon this flag.

Since
R9

◆ isDeletedFlagSet

- (BOOL) isDeletedFlagSet
readnonatomicassign

The message has been deleted.

Since
R2

◆ isIncomingFlagSet

- (BOOL) isIncomingFlagSet
readnonatomicassign

The 'senderUri' is not the local user, and the message may be considered to be incoming from the local user's perspective. This is a convenience alias for inspecting the 'senderUri' field. The absence of this flag reflects the fact that the 'senderUri' is the local user.

Since
R2

◆ isNeverCountUnreadFlagSet

- (BOOL) isNeverCountUnreadFlagSet
readnonatomicassign

This message never contributes to the 'chat' 'numUnread' count and never sets the 'chat' 'lastActivity' timestamp.Your application can set this on messages it sends that are not displayed by other endpoints. Doing so helps the 'chat' 'numUnread' count reflect the number of messages that the user has not read. This flag has no effect on the 'state' of a chat message or the behaviour of 'chatMessageRead'. For example, messages with this flag will be 'Delivered' when received and can be marked as 'Read'.

Since
R9

◆ isUnverifiedFlagSet

- (BOOL) isUnverifiedFlagSet
readnonatomicassign

The message's signature was not verified as being from the claimed sender. Despite this, the content of the message is made available to be processed or ignored as your application sees fit.

Since
R2

◆ localData

- (NSDictionary*) localData
readnonatomicstrong

This field contains opaque local-only data managed by your application that is associated to the message. This field will be omitted until your application sets it via 'requestListChange'. When present, it will always be a valid JSON object.

Since
R5

◆ messageId

- (unsigned long long) messageId
readnonatomicassign

The unique identifier for this message. These are consecutive integers, ordered by arrival time. The range of valid integers for a given chat is stored in 'listChat's 'lastMessage' and 'numMessages' values.

Since
R2

◆ rawData

- (NSDictionary*) rawData
readnonatomicstrong

If the tag associated with this message is defined in the BBMDS specification, this property will be nil. If the tag is unrecognized, this property will hold a dictionary representing the JSON string sent by bbmcore in the 'data' property. The set of recognized tags can be obtained from the recognizedTags property.

Since
R3

◆ recall

- (BBMChatMessageRecall) recall
readnonatomicassign

This field indicates the recall state of the message.

Since
R2

◆ ref

- (NSArray*) ref
readnonatomicstrong

A 'chatMessage' can reference other messages or be referenced by other messages.All references are directional and known to both messages involved. If message A references message B, then A has an entry in its 'ref' array with the 'messageId' of B, and B has an entry in its 'refBy' array that counts the reference from A.Each reference in the 'ref' array has an application-specified 'tag' that indicates what kind of reference it is. A single message can only have one 'ref' for each tag string. Your application uses 'tag' strings to allow multiple different kinds of references between messages. For example, a message could both 'Quote' one message and 'Edit' another.Each reference in the 'refBy' array has the same application-specified tag. A single message can have multiple references to it with the same 'tag'. To find all messages that refer to a given message, use 'requestListMatching' with the 'tag' and the 'messageId' of the referred-to message. Because the number of incoming references to a message can be large, only the most recent referring message is identified by 'newestRef' in 'refBy', along with a count of the total number of referring messages.When there are no references to any other messages, the 'ref' field is omitted.

Since
R5

◆ refBy

- (NSArray*) refBy
readnonatomicstrong

See 'ref' for an explanation of 'ref' and 'refBy'.This field will be omitted entirely if there are no references from other messages.

Since
R5

◆ senderUri

- (NSString*) senderUri
readnonatomicstrong

Holds the user URI of the sender of this message. See the URIs section for information on the URI format.

Since
R2

◆ state

- (BBMChatMessageState) state
readnonatomicassign

This field indicates the overall delivery state of the message.

Since
R2

◆ stateIsPartial

- (BOOL) stateIsPartial
readnonatomicassign

This indicates whether or not the state applies to some (true) or all (false) recipients.

Since
R2

◆ tag

- (NSString*) tag
readnonatomicstrong

Indicates the type of content this message represents. Admin - The message contains an admin change. This tag contains no content. The 'data' must contain 'Admin'.

Gap - The message history contains a gap at this position where messages have been permanently lost. The 'senderUri' will be that of the local user, the 'state' will be 'Sent', and the 'timestamp' will be the time the gap was detected. This tag has no 'content'

Join - The sender has joined the chat. This tag has no 'content'.

Leave - The sender has left the chat. This tag has no 'content'. The 'data', if present, must contain 'Leave'.

Remove - This message indicates that the sending user has removed another user from the chat. This tag contains no content. The 'data' must contain 'Remove' and will indicate which user has been removed.

Shred - The sender has requested that all previously sent messages be recalled. This tag has no 'content''.

Subject - The sender has changed the chat's 'subject'. The content contains the new subject.

Text - The message contains plain text content. This tag requires 'content'.

Since
R2

◆ thumb

- (NSString*) thumb
readnonatomicstrong

A path to a small file that is carried in the message.

Since
R2

◆ timestamp

- (unsigned long long) timestamp
readnonatomicassign

The time at which this message was posted to the BlackBerry Infrastructure, in seconds since 1970.

Since
R2