Avaya Client Services API Reference (OS X)
|
Interface for all conversation related tasks and properties. More...
#import <CSMessagingConversation.h>
Inherits NSObject.
Inherited by CSMessagingSearchConversation.
Instance Methods | |
(BOOL) | - isParticipantActive: |
Returns YES if a specified participant is active in this conversation. More... | |
(CSMessage *) | - createMessage |
Creates a new message in this conversation. More... | |
(void) | - removeMessage:completionHandler: |
Removes a CSMessage (only draft messages can be removed). More... | |
(void) | - startWithCompletionHandler: |
Invokes a start request for this conversation. More... | |
(void) | - addParticipantWithContact:completionHandler: |
Invokes an add participant request for this conversation for provided contact object. More... | |
(void) | - addParticipantAddresses:completionHandler: |
Invokes an add participant request for this conversation for each of the provided addresses. More... | |
(void) | - removeParticipantAddresses:completionHandler: |
Invokes a remove participant request for this conversation for each of the provided addresses. More... | |
(void) | - removeParticipant:completionHandler: |
Invokes a remove participant request for this conversation. More... | |
(void) | - addParticipants:completionHandler: |
Adds participants. More... | |
(void) | - retrieveMessagesWithWatcher: |
Starts the retrieval of messages associated with this conversation. More... | |
(void) | - retrieveMessagesAfterMessage:maxCount: |
Retrieves a list of the conversation messages after the specified message. More... | |
(void) | - retrieveMessagesBeforeMessage:maxCount: |
Retrieves a list of the conversation messages before the specified message. More... | |
(void) | - updateLastAccessTimeWithCompletionHandler: |
Invokes a set last access time request for this conversation. More... | |
(void) | - setSubject:completionHandler: |
Sets the subject for this conversation. More... | |
(void) | - setSensitivity:completionHandler: |
Set conversation sensitivity level. More... | |
(void) | - setType:completionHandler: |
Sets the conversation type. More... | |
(void) | - leaveWithCompletionHandler: |
Invokes a leave request for this conversation. More... | |
(void) | - clearLocalAttachmentDataWithCompletionHandler: |
Clear conversation local attachment data. More... | |
(void) | - markAllContentAsReadWithCompletionHandler: |
Marks all content in this conversation as read. More... | |
Properties | |
id< CSMessagingConversationDelegate > | delegate |
The delegate responsible for handling conversation events. More... | |
id< CSMessagingComposingParticipantsWatcherDelegate > | composingParticipantsWatcherDelegate |
The delegate responsible for handling messages signalling a change in the list of composing participants. More... | |
NSString * | conversationId |
The unique conversation identifier. More... | |
NSString * | providerConversationId |
This is the conversation ID from the underlying provider (e.g., the AMM server) as-is. More... | |
CSMessagingSensitivityLevel | sensitivity |
The sensitivity of the conversation. More... | |
BOOL | active |
A Boolean value indicating whether the conversation is active. More... | |
BOOL | closed |
A Boolean value indicating whether the conversation is closed. More... | |
BOOL | multiParty |
The multi-party status of the conversation. More... | |
BOOL | privateConversation |
The conversation is private when the sensitivity of the conversation is set to CSMessagingSensitivityLevelPrivate. More... | |
BOOL | hasUnreadMessagesSinceLastAccess |
A Boolean value indicating whether the conversation has unread messages since the time the conversation was last accessed. More... | |
BOOL | hasUnreadMessages |
A Boolean value indicating whether the conversation has any unread messages. More... | |
BOOL | hasUnreadAttachments |
A Boolean value indicating whether the conversation has any unread attachments. More... | |
BOOL | hasAttachments |
A Boolean value indicating whether the conversation has any attachments on any of its messages. More... | |
NSDate * | lastAccessDate |
The date the conversation was last accessed. More... | |
NSDate * | lastUpdatedDate |
The date the conversation was last updated. More... | |
NSDate * | latestEntryDate |
The last entry timestamp of the conversation. More... | |
NSArray * | composingParticipants |
An array of composing participants contained in this conversation. More... | |
NSArray * | allParticipants |
A list of participants contained in this conversation. More... | |
NSArray * | activeParticipants |
A list of active participants contained in this conversation. More... | |
CSMessagingConversationType | type |
The conversation type. More... | |
NSString * | previewText |
The preview text of the conversation. More... | |
NSUInteger | totalMessageCount |
The total number of messages in the conversation. More... | |
NSUInteger | attachmentCount |
The total number of attachments in all messages of the conversation. More... | |
NSUInteger | unreadAttachmentCount |
The total number of unread attachments in all messages of the conversation. More... | |
NSUInteger | unreadMessageCount |
The number of unread messages in the conversation. More... | |
NSString * | subject |
The subject of the conversation if one is provided by the server. More... | |
CSMessagingParticipant * | lastUpdatedByParticipant |
The last CSMessagingParticipant that updated this conversation. More... | |
CSMessagingConversationStatus | status |
The server reconciled status of the conversation. More... | |
CSCapability * | updateSubjectCapability |
A CSCapability object that indicates if the subject property of the conversation can be updated. More... | |
CSCapability * | updateLastAccessedTimeCapability |
A CSCapability object that indicates if the type of the conversation can be updated. More... | |
CSCapability * | updateSensitivityCapability |
A CSCapability object that indicates if the sensitivity of the conversation can be updated. More... | |
CSCapability * | updateTypeCapability |
A CSCapability object that indicates if the type of the conversation can be updated. More... | |
CSCapability * | olderContentCapability |
A CSCapability object that indicates whether the user can "scroll to get more
messages", i.e. More... | |
CSCapability * | addParticipantsCapability |
A CSCapability object that indicates if new participants can be added to the conversation. More... | |
CSCapability * | removeParticipantsCapability |
A CSCapability object that indicates if participants can be removed from the conversation. More... | |
CSCapability * | removeParticipantCapability |
A CSCapability object that indicates if a participant can be removed from the conversation. More... | |
CSCapability * | createMessageCapability |
A CSCapability object that indicates if a new message can be created in the conversation. More... | |
CSCapability * | markAllContentAsReadCapability |
A CSCapability object that indicates if all messages in the conversation can be marked as read. More... | |
CSCapability * | leaveCapability |
A CSCapability object that indicates if the conversation can be left. More... | |
CSCapability * | startCapability |
A CSCapability object that indicates if the conversation can be started. More... | |
CSCapability * | removeCapability |
A CSCapability object that indicates if the conversation can be removed. More... | |
CSCapability * | isTypingCapability |
A CSCapability object that indicates if typing status reporting is avaliable. More... | |
CSCapability * | messageReadStateCapability |
Returns a capability indicating whether this conversation is capable of reporting read state updates for sent messages. More... | |
CSCapability * | messageDeliveryStateCapability |
Returns a capability indicating whether this conversation is capable of reporting delivery state updates for sent messages. More... | |
CSMessagingProviderType | providerType |
A CSMessagingProviderType object that contains information about source of the conversation. More... | |
Interface for all conversation related tasks and properties.
A conversation is managing a list of messages which are sent between its participants.
Beside messages, a conversation also contains a lot of its own parameters. Almost all of them can be set only before it is published. After that, one can only send a message, add a new participant, change subject, etc.
It is important to understand that all conversation participants have the same privileges. Once the first user starts a conversation it cannot be closed by that user; every user can leave only by themselves, and add new participants as desired.
After creating new conversation object call addParticipantAddresses:completionHandler: (CSMessagingConversation) method for adding new participants. Before sending first message set all other required parameters, like Subject and call startWithCompletionHandler: (CSMessagingConversation) method.
- (void) addParticipantAddresses: | (NSArray *) | addressesToAdd | |
completionHandler: | (CSMessagingParticipantsChangedCompletionHandler) | handler | |
Invokes an add participant request for this conversation for each of the provided addresses.
addressesToAdd | - NSArray of NSStrings representing the participant addresses to add |
handler | CSMessagingParticipantsChangedCompletionHandler for this operation. |
- (void) addParticipants: | (NSArray *) | participantsToAdd | |
completionHandler: | (CSMessagingParticipantsChangedCompletionHandler) | handler | |
Adds participants.
participantsToAdd | NSArray of CSMessagingParticipant(s) to add |
handler | The completion handler associated with this operation |
- (void) addParticipantWithContact: | (CSContact *) | contact | |
completionHandler: | (CSMessagingParticipantsChangedCompletionHandler) | handler | |
Invokes an add participant request for this conversation for provided contact object.
contact | - Contact representing the participant to add |
handler | CSMessagingParticipantsChangedCompletionHandler for this operation. |
- (void) clearLocalAttachmentDataWithCompletionHandler: | (CSMessagingCompletionHandler) | handler |
Clear conversation local attachment data.
This method clears only application data and it is not applicable to any content downloaded to a user’s device.
handler | CSMessagingCompletionHandler for this operation. |
- (CSMessage *) createMessage |
Creates a new message in this conversation.
- (BOOL) isParticipantActive: | (CSMessagingParticipant *) | messagingParticipant |
Returns YES if a specified participant is active in this conversation.
messagingParticipant | the participant to query for |
- (void) leaveWithCompletionHandler: | (CSMessagingCompletionHandler) | handler |
Invokes a leave request for this conversation.
After leaving, participant can no longer contribute to the conversation unless he is added once again.
When last participant is leaving the conversation it will become closed after a while.
handler | CSMessagingCompletionHandler for this operation. |
- (void) markAllContentAsReadWithCompletionHandler: | (CSMessagingCompletionHandler) | handler |
Marks all content in this conversation as read.
handler | CSMessagingCompletionHandler for this operation. |
- (void) removeMessage: | (CSMessage *) | messageToRemove | |
completionHandler: | (CSMessagingCompletionHandler) | handler | |
Removes a CSMessage (only draft messages can be removed).
messageToRemove | The CSMessage to be removed. |
handler | CSMessagingCompletionHandler for this operation. |
- (void) removeParticipant: | (CSMessagingParticipant *) | messagingParticipant | |
completionHandler: | (CSMessagingParticipantsChangedCompletionHandler) | handler | |
Invokes a remove participant request for this conversation.
messagingParticipant | the participant to remove from this conversation. |
handler | CSMessagingParticipantsChangedCompletionHandler for this operation. |
- (void) removeParticipantAddresses: | (NSArray *) | addressesToRemove | |
completionHandler: | (CSMessagingParticipantsChangedCompletionHandler) | handler | |
Invokes a remove participant request for this conversation for each of the provided addresses.
addressesToRemove | - NSArray of NSStrings representing the participant addresses to remove |
handler | CSMessagingParticipantsChangedCompletionHandler for this operation. |
- (void) retrieveMessagesAfterMessage: | (CSMessage *) | message | |
maxCount: | (NSUInteger) | maxMessagesToRetrieve | |
Retrieves a list of the conversation messages after the specified message.
This list represents a list of contiguous messages which have been, or are being, downloaded.
This method is used in conjunction with the retrieveMessagesWithWatcher: method to retrieve older message content associated with the conversation. Please refer to the description of that method for detailed usage information.
To determine when it is appropriate to call the retrieveMessagesAfter method, the client application should query the olderContentCapability method.
maxMessagesToRetrieve | the maximum number of messages to retrieve. The actual number retrieved may be less than this if the maximum number of messages allowed per retrieval request, as configured on the server, is less than the specified value, or if the end of the message list is reached. |
message | the starting point in the retrieval. Messages immediately after this one will be retrieved. |
- (void) retrieveMessagesBeforeMessage: | (CSMessage *) | message | |
maxCount: | (NSUInteger) | maxMessagesToRetrieve | |
Retrieves a list of the conversation messages before the specified message.
This list represents a list of contiguous messages which have been, or are being, downloaded.
This method is used in conjunction with the retrieveMessagesWithWatcher: method to retrieve older message content associated with the conversation. Please refer to the description of that method for detailed usage information.
To determine when it is appropriate to call the retrieveMessagesBefore method, the client application should query the olderContentCapability method.
maxMessagesToRetrieve | The maximum number of messages to retrieve. The actual number retrieved may be less than this if the maximum number of messages allowed per retrieval request, as configured on the server is less than the specified value, or if the start of the message list is reached. |
message | the starting point in the retrieval. Messages immediately before this one will be retrieved. |
- (void) retrieveMessagesWithWatcher: | (CSDataRetrievalWatcher *) | watcher |
Starts the retrieval of messages associated with this conversation.
This initial retrieval represents the most recent messages in the conversation and is limited to a maximum number that is specified by the messaging server. This is not necessarily the entire historical message content of the conversation.
This method begins the retrieval of the dynamically-updated collection of messages associated with this conversation. Normally the client application will only need to call this method once to install a watcher object to monitor the initial download of messages and then continue to watch for updates to the collection.
If older messages are required to be downloaded, the retrieveMessagesBeforeMessage:maxCount: and/or retrieveMessagesAfterMessage:maxCount:] methods can be used to retrieve additional message history. Note, however, that retrieveMessagesWithWatcher: must be called first to install the CSDataRetrievalWatcher object that will monitor the retrieval, since these other methods work on a shared collection managed internally by the CSMessagingConversation object. The application should use the dataRetrievalWatcher:contentsDidChange:changedItems: (CSDataRetrievalWatcherDelegate-p) callback to build up and maintain a local collection of messages associated with this conversation.
When using these message retrieval methods, it is important to note that there can only be a single retrieval operation in progress at any given time. If there is a retrieval operation in progress when once of these three message retrieval methods are called, the currently running retrieval will be cancelled before starting the next operation.
If the client application calls this method additional times, no actual download of messages from the server occurs, but the watcher listener callbacks that report progress will fire (i.e. "progress" and "done" callbacks). However, no additions to the message collection will occur as a result of the subsequent calls. If a different watcher object is supplied in a subsequent call, the previous watcher object is "unlinked" from the underlying message object collection and will never receive any additional updates.
watcher | CSDataRetrievalWatcher object, created by the application, to track the progress of the requested operation. |
- (void) setSensitivity: | (CSMessagingSensitivityLevel) | sensitivity | |
completionHandler: | (CSMessagingCompletionHandler) | handler | |
Set conversation sensitivity level.
sensitivity | CSMessagingSensitivityLevel the new conversation sensitivity. |
handler | CSMessagingCompletionHandler for this operation. |
- (void) setSubject: | (NSString *) | subject | |
completionHandler: | (CSMessagingCompletionHandler) | handler | |
Sets the subject for this conversation.
subject | the new subject of this conversation. |
handler | The Application/client context associated with this operation |
- (void) setType: | (CSMessagingConversationType) | type | |
completionHandler: | (CSMessagingCompletionHandler) | handler | |
Sets the conversation type.
type | CSMessagingConversationType the new conversation type. |
handler | CSMessagingCompletionHandler for this operation. |
- (void) startWithCompletionHandler: | (CSMessagingCompletionHandler) | handler |
Invokes a start request for this conversation.
handler | CSMessagingCompletionHandler for this operation. |
- (void) updateLastAccessTimeWithCompletionHandler: | (CSMessagingCompletionHandler) | handler |
Invokes a set last access time request for this conversation.
handler | CSMessagingCompletionHandler for this operation. |
|
readnonatomicassign |
A Boolean value indicating whether the conversation is active.
An active conversation is one that allows new contributions from any of the current participants and has the local user as an active participant (i.e. the local user has not left the conversation).
|
readnonatomicassign |
A list of active participants contained in this conversation.
|
readnonatomicassign |
A CSCapability object that indicates if new participants can be added to the conversation.
This capability is Allowed when all of the following conditions are true:
|
readnonatomicassign |
A list of participants contained in this conversation.
|
readnonatomicassign |
The total number of attachments in all messages of the conversation.
|
readnonatomicassign |
A Boolean value indicating whether the conversation is closed.
A closed conversation prohibits new contributions (or activity of any kind) from any participants. Such conversations are candidates for being deleted (after backup) as part of storage management activities.
|
readnonatomicassign |
An array of composing participants contained in this conversation.
|
readwritenonatomicweak |
The delegate responsible for handling messages signalling a change in the list of composing participants.
The application should set a delegate only when needed, to reduce the network traffic associated with updating the composing participants list. When no longer interested in this information (i.e. the user has left the conversation window), the application should set this delegate to nil to remove the installed delegate.
When there is no delegate set, the composingParticipants property will always return an empty array, since the lack of an installed delegate indicates that the application is not interested in this information.
|
readnonatomicassign |
The unique conversation identifier.
|
readnonatomicassign |
A CSCapability object that indicates if a new message can be created in the conversation.
This capability is Allowed when all of the following conditions are true:
|
readwritenonatomicweak |
The delegate responsible for handling conversation events.
|
readnonatomicassign |
A Boolean value indicating whether the conversation has any attachments on any of its messages.
|
readnonatomicassign |
A Boolean value indicating whether the conversation has any unread attachments.
|
readnonatomicassign |
A Boolean value indicating whether the conversation has any unread messages.
|
readnonatomicassign |
A Boolean value indicating whether the conversation has unread messages since the time the conversation was last accessed.
|
readnonatomicassign |
A CSCapability object that indicates if typing status reporting is avaliable.
|
readnonatomicassign |
The date the conversation was last accessed.
|
readnonatomicassign |
The last CSMessagingParticipant that updated this conversation.
|
readnonatomicassign |
The date the conversation was last updated.
|
readnonatomicassign |
The last entry timestamp of the conversation.
This is the timestamp of the most recent message in the conversation.
|
readnonatomicassign |
A CSCapability object that indicates if the conversation can be left.
This capability is Allowed when all of the following conditions are true:
|
readnonatomicassign |
A CSCapability object that indicates if all messages in the conversation can be marked as read.
This capability is Allowed when all of the following conditions are true:
|
readnonatomicassign |
Returns a capability indicating whether this conversation is capable of reporting delivery state updates for sent messages.
|
readnonatomicassign |
Returns a capability indicating whether this conversation is capable of reporting read state updates for sent messages.
|
readnonatomicassign |
The multi-party status of the conversation.
A conversation is considered to be a multi-party conversation if there are more than two active participants in the conversation.
|
readnonatomicassign |
A CSCapability object that indicates whether the user can "scroll to get more messages", i.e.
there are additional messages not yet downloaded from the server.
This capability is Allowed when all of the following conditions are true:
|
readnonatomicassign |
The preview text of the conversation.
Preview text is a body of the latest message in the conversation.
|
readnonatomicassign |
The conversation is private when the sensitivity of the conversation is set to CSMessagingSensitivityLevelPrivate.
|
readnonatomicassign |
This is the conversation ID from the underlying provider (e.g., the AMM server) as-is.
It will be consistent across clients and application launches, but is only guaranteed to be unique for conversations of that provider type. It will be empty for draft conversation.
|
readnonatomicassign |
A CSMessagingProviderType object that contains information about source of the conversation.
|
readnonatomicassign |
A CSCapability object that indicates if the conversation can be removed.
This capability is Allowed when the conversation is in draft state.
|
readnonatomicassign |
A CSCapability object that indicates if a participant can be removed from the conversation.
This capability is Allowed when one of the following conditions are true:
|
readnonatomicassign |
A CSCapability object that indicates if participants can be removed from the conversation.
This capability is Allowed when the conversation is in draft state and is not transitioning to the published state.
|
readwritenonatomicassign |
The sensitivity of the conversation.
|
readnonatomicassign |
A CSCapability object that indicates if the conversation can be started.
This capability is Allowed when the conversation is in draft state and has not yet been started.
|
readnonatomicassign |
The server reconciled status of the conversation.
|
readnonatomicassign |
The subject of the conversation if one is provided by the server.
|
readnonatomicassign |
The total number of messages in the conversation.
|
readwritenonatomicassign |
The conversation type.
|
readnonatomicassign |
The total number of unread attachments in all messages of the conversation.
|
readnonatomicassign |
The number of unread messages in the conversation.
|
readnonatomicassign |
A CSCapability object that indicates if the type of the conversation can be updated.
This capability is currently always disabled because the messaging server only supports conversations of type "thread".
This capability is Allowed when all of the following conditions are true:
|
readnonatomicassign |
A CSCapability object that indicates if the sensitivity of the conversation can be updated.
This capability is Allowed when the conversation is in the draft state.
|
readnonatomicassign |
A CSCapability object that indicates if the subject property of the conversation can be updated.
This capability is Allowed when all of the following conditions are true:
|
readnonatomicassign |
A CSCapability object that indicates if the type of the conversation can be updated.
This capability is currently always disabled because the messaging server only supports conversations of type "thread".