< Back to Package Overview
Adding support for multimedia messages
The messaging service API provides instant messaging functionality to the client application. It deals with retrieving data from the server, managing and performing business logic on this data and finally, presenting it to the UI layer. This API attempts to use closures where possible.
- Network connectivity
- Query messaging capabilities (from the AMM server)
- Query/start conversations
- Send messages (with attachments)
- Mark messages as read
- Query/invite conversation participants
- Leave conversations
- IM address validation
Most of the API calls allow a listener to pass in to handle success or fail.
MessagingService Capabilities
MessagingService supports different features based on its type. To recognize whether the feature is available or not, you need to check the appropriate capability. UI elements should be enabled, disabled or hidden depending on these capabilities. Such capabilities exist at the MessagingService level:
| Capability |
Conditions Required |
Property to check Capability |
| Create Conversation |
The Client is connected to the messaging server. |
CreateConversationCapability |
| Remove Conversation |
The Conversation is in the draft state. |
RemoveConversationCapability |
| Retrieve Conversation |
The Client is connected to the messaging server. The messaging server supports Retrieve. |
RetrieveConversationCapability |
| Search Conversation |
The Client is connected to the messaging server. The messaging server supports Search. |
SearchConversationCapability |
| Update Refresh Mode |
The Client is connected to the messaging server. The messaging server supports changing the refresh mode. |
UpdateRefreshModeCapability |
| Validate Participant Addresses |
The Client is connected to the messaging server. The messaging server supports validation of participant addresses. |
ValidateParticipantAddressesCapability |
| Automatically Update Last Access Time |
The Client is connected to the messaging server. The messaging server supports automatic update of conversation last access timestamps. |
AutomaticallyUpdateLastAccessTimeCapability |
Initializing and Configuring the MessagingService
The MessagingService object is obtained from the Client SDK User object. The UserConfiguration object is used to define the services that are available to the end users of your application. Each service is configured individually. Its configuration is stored in a dedicated object referenced from the UserConfiguration object.
Note: More information on service configuration can be found in the article Configuring the SDK.
Start by obtaining any existing service configuration:
AMMConfiguration ammConfiguration = userConfiguration.AmmConfiguration;
Enable the service and configure the AMM parameters supplied by your administrator:
ammConfiguration.Enabled = true;
ammConfiguration.ServerInfo = new ServerInfo("",
"",
TLS); // True if connection to the server is required to be secure;
//the poll refresh interval in minutes
ammConfiguration.PollIntervalInMinutes = ((uint)(0));
Valid username and password are required to successfully register to the AMM server. The password required for the AMM service is not defined as a part of the service configuration. Passwords are requested by and communicated to the Client SDK using the ICredentialProvider interface:
ammConfiguration.CredentialProvider =
new UserNamePasswordCredentialProvider("","","");
And finally, save your configuration back to your UserConfiguration object.
userConfiguration.AmmConfiguration = ammConfiguration;
Note: More information on how to manage passwords using ICredentialProvider can be found in the article Working with Credentials.
After you instantiate and set up required configuration objects, now you are ready to create User and then call the Start() method of your User to start all services. Then you can get MessagingService for its further usage:
MessagingService messagingService = mUser.MessagingService;
Conversation Capabilities
These capabilities exist on the Client SDK Conversation object:
| Capability |
Conditions Required |
Property to check Capability |
| Create Message |
The Client is connected to the messaging server. The Conversation is in the draft state and has been started, or the Conversation is in the published state. |
CreateMessageCapability |
| MarkAllContentAsRead |
The Client is connected to the messaging server. The messaging server supports marking all content in the conversation as read. The Conversation is published. |
MarkAllContentAsReadCapability |
| Update Subject |
The Client is connected to the messaging server. The messaging server supports changing the subject of the Conversation. The Conversation is active. The Conversation is either draft or published. |
UpdateSubjectCapability |
| Update Last Access Time Capability |
The Client is connected to the messaging server. The messaging server supports changing the LastAccessTime of the Conversation. The Conversation is published. |
UpdateLastAccessTimeCapability |
| Leave |
The Client is connected to the messaging server. The Conversation is in the published state. |
LeaveCapability |
| Add Participants |
The Client is connected to the messaging server. The Conversation is active. The Conversation is either draft or published. |
AddParticipantsCapability |
| Remove Participants |
The Conversation is in the draft state. |
RemoveParticipantsCapability |
| Update Sensitivity |
The Conversation is in the draft state. |
UpdateSensitivityCapability |
| Older Content |
The Client is connected to the messaging server. The Conversation is published. |
OlderContentCapability |
| Start |
The Conversation is in the draft state and has not yet been started. |
StartCapability |
| Remove |
The Conversation is in the draft state. |
RemoveCapability |
Retrieval of active conversations
The RetrieveActiveConversations() method retrieves the dynamically updated collection of conversations that are associated with the currently logged in user. Normally, the client application will only need to call this method once to install a watcher object to monitor the initial download of conversations and then continue to watch for updates to the collection.
ConversationRetrievalWatcher watcher = new ConversationRetrievalWatcher();
watcher.DataRetrievalProgress += ConversationDataRetrievalProgress;
watcher.DataRetrievalDone += ConversationDataRetrievalDone;
watcher.DataRetrievalCollectionChanged +=
ConversationDataRetrievalCollectionChanged;
messagingService.RetrieveActiveConversations(watcher);
Creating a conversation
First, create new Conversation and then call the Start() method of your Conversation object. Then you can add a participant to Conversation by specifying a valid extension and domain.
Conversation newConversation = messagingService.CreateConversation();
newConversation.Start((error) =>
{
if (error == null)
{
// Update UI elements: Start conversation succeeded
}
else
{
// Update UI elements: Start conversation failed
}
});
newConversation.AddParticipantAddresses(addresses, (newConversation,
participants, error) =>
{
if (error == null)
{
// Update UI elements: Add participant succeeded
}
else
{
// Update UI elements: Add participant failed
}
});
Message Capabilities
These capabilities exist on the Client SDK Message object:
| Capability |
Conditions Required |
Property to check Capability |
| Update Body |
The Message is in the draft or error state. |
UpdateBodyCapability |
| Update InReplyTo |
The Message is in the draft or error state. |
UpdateInReplyToCapability |
| Update DoNotForward |
The Message is in the draft or error state. |
UpdateDoNotForwardCapability |
| Update Importance |
The Message is in the draft or error state. |
UpdateImportanceCapability |
| Create Attachment |
The Message is in the draft or error state. |
CreateAttachmentCapability |
| Send |
The Client is connected to the messaging server. The Message is in the draft or error state. |
SendCapability |
| MarkAsRead |
The Client is connected to the messaging server. The messaging server supports marking messages as read. The Message is published. |
MarkAsReadCapability |
| Remove |
The Message is in the draft or error state. |
RemoveCapability |
Creating a message
Once Conversation has been created successfully, new Message can be created and sent in the scope of Conversation.
Message message = newConversation.createMessage();
message.SetBodyAndReportTyping(messageBody, (arg) =>
{
if (arg == null)
{
CreatedMessage.Send((sendArg) =>
{
if (sendArg == null)
{
// Update UI elements: Send message succeeded
}
else
{
// Update UI elements: Send message failed
}
});
}
else
{
// Update UI elements: Failed to set message text
}
});
Receive messages
If new Message has been received in the scope of existing Conversation your application will be notified via DataCollectionChangedEventArgs. The content of received message should be added to active conversation.
private void CPCoreManager_MessagesDataSetChanged(object sender,
DataCollectionChangedEventArgs e)
{
if (e.ChangeType == DataCollectionChangeType.ItemsAdded)
{
ProcessNewMessages(e.ChangedItems);
}
else if (e.ChangeType == DataCollectionChangeType.ItemsUpdated)
{
ProcessUpdatedMessages(e.ChangedItems);
}
}
Marking as read
To mark selected Message as read use the MarkAsRead() method of the Message object.
if (message.MarkAsReadCapability.Allowed)
{
message.MarkAsRead();
}
You can also mark all content in Conversation as read using the MarkAllContentAsRead() method.
if (conversation.MarkAllContentAsReadCapability.Allowed)
{
conversation.MarkAllContentAsRead((error) =>
{
if (error == null)
{
// Update UI elements: Mark content as read succeeded
}
else
{
// Update UI elements: Mark content as read failed
}
});
}
Attachment Capabilities
These capabilities exist on the Client SDK Attachment object:
| Capability |
Conditions Required |
Property to check Capability |
| Update Name |
The Attachment is in the draft or error state |
UpdateNameCapability |
| Update IsThumbnail |
The Attachment is in the draft or error state |
UpdateIsThumbnailCapability |
| Update IsGeneratedContent |
The Attachment is in the draft or error state |
UpdateIsGeneratedContentCapability |
| Update Location |
The Attachment is in the draft or error state |
UpdateLocationCapability |
| Update MIME Type |
The Attachment is in the draft or error state |
UpdateMimeTypeCapability |
| Download |
The Client is connected to the messaging server. The Attachment is in the "ready to download" state. |
DownloadCapability |
| Consume |
The Attachment is in the "downloaded" or "consumed" state |
ConsumeCapability |
| Remove |
The Attachment is in the draft or error state |
RemoveCapability |
Creating a message with an attachment
Message is a crucial part of Conversation. An important part of Message is also represented as attachments. In order to create new Attachment in the Message object, use the CreateAttachment() method. You can attach Audio (".m4a"), Video (".mp4") and Pictures (".jpg") to your Message. First, create new Attachment in the Message object via the CreateAttachment() method and then set desired values (location, name, MIME types, etc.) for this attachment object.
Attachment attachment = draftMessage.CreateAttachment();
attachment.SetLocation(attachmentPath, (attachment, error) =>
{
if (error == null)
{
// Update UI elements: Attachment Location set successfully
}
else
{
// Update UI elements: Set Location failed for attachment
}
});
attachment.SetMimeType(mimeType, (attachment, error) =>
{
if (error == null)
{
// Update UI elements: Attachment MIME type set successfully
}
else
{
// Update UI elements: Set MIME type failed for attachment
}
});
attachment.SetName(name, (attachment, error) =>
{
if (error == null)
{
// Update UI elements: Attachment Name set successfully
}
else
{
// Update UI elements: Set Name failed for attachment
}
});
attachment.SetIsThumbnail(IsThumbnail, (attachment, error) =>
{
if (error == null)
{
// Update UI elements: Attachment IsThumbnail set successfully
}
else
{
// Update UI elements: Set IsThumbnail failed for attachment
}
});
attachment.SetIsGeneratedContent(IsGeneratedContent, (attachment, error) =>
{
if (error == null)
{
// Update UI elements: Attachment IsGeneratedContent
set successfully
}
else
{
// Update UI elements: Set IsGeneratedContent failed
for attachment
}
});
To remove Attachment from Message, use the RemoveAttachment() method. Operation success or failure is reported through the completion handler.
foreach (Attachment attachment in the draftMessage.Attachments)
{
draftMessage.RemoveAttachment(attachment, (error) =>
{
if (error == null)
{
// Update UI elements: Attachment removed successfully
}
else
{
// Update UI elements: Remove attachment failed
}
});
}
Now you are ready to send your draft Message using the methods described above in the article.
Downloading an attachment
You can download Attachment from Message by specifying the path to write the file to. To start downloading Attachment asynchronously you can use the Download() method.
if (message.HasAttachment)
{
foreach (Attachment attachment in message.Attachments)
{
if (!attachment.IsThumbnail)
{
inProgressDownload = attachment.Download(attachPath, (attachment,
error) =>
{
if (error == null)
{
// Update UI elements: Downloaded successfully
}
else
{
// Update UI elements: Download attachment failed
}
// Attachment was saved to + attachment.Consume()
});
}
}
}
The Consume() from the example above returns the location of Attachment (or empty string if the location is not available) so that it can be opened by the application. This method has additional effect of changing the status of Attachment to Opened.
You can cancel downloading Attachment as follows:
if (inProgressDownload != null)
{
inProgressDownload.Cancel();
// Update UI elements: Cancelled download attachment
}
else
{
// Update UI elements: No download in progress
}
Please note that the location of attachments is not stored across user session. Therefore, after logout/login there are no local storage paths and the client needs to download attachments again.
