Managing Remote Contacts

Article
06/14/2014

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

The contact list provides the basis for virtually all other Unified Communications client communication related functionality. Although it is possible to initiate an audio call or IM session without picking a contact from a contact list, most users begin their audio/video or IM sessions by picking a target contact from a contact list. Contact lists are normally used to display the friendly name and presence status of remote users. The list allows the local user to tell at a glance which users are available for conversations. You can display the contact cards of the contacts in a contact list using the interfaces discussed in this topic.

The topics presented in this section explain how to implement these and other related tasks in a Unified Communications Client API application.

What You Should Already Know

To create a contact list and maintain it, you must be familiar with many of the interfaces provided by Unified Communications Client API. If you have not already done so, review the following:

Contact List Management Tasks

To add or remove users from a contact list, your custom client must first subscribe to the local user's "contacts" category. After getting contact list members as individual "contacts" category instances via asynchronous category context events, a custom client can add or remove individual contacts by publishing an updated contact list with the desired changes. Publishing a contact list persists the list on Office Communications Server so that the local client can later obtain it in an update to the contact subscription.

Creating a contact list in your application typically involves the following operations:

Add the contacts category to the local user's self-subscription and subscribe to the added category. Use the received contact list to fill the Presentities collection in the subscription object for remote user data. Looking at the programming pattern described in this topic, you see that the first steps in the pattern are creating a self-subscription****and adding the contactList category to that self-subscription. You do not subscribe to information belonging to other users until you start receiving the contact list. For more information, see Create Contact List Subscription.
Handle the OnCategoryInstanceAdded events. You receive these events when Office Communications Server begins sending the local user contact list. When your callback method is called to handle this event, you can add the single contact represented by each event to the Presentities property of the subscription object for other user information. For more information, see Receive Contact List.
The example code in this section instantiates a Contact class object for each received contact. This Contact object is responsible for monitoring contact presence information and raising its own events that the example application handles. For more information, see Sample Contact Presence Handling Class.

Normally, a Unified Communications Client API application enables a third subscription session to receive the self-published category instances and the containers category instances. This allows the application to receive the user's own presence information and the containers used to control who is allowed to receive published category instances.

Adding a contact to a contact list typically involves the following operations:

Supplying a contact URI and other inputs to Unified Communications Client API and creating a publishable instance of the "contacts" category.
Setting the publication operation as UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_ADD.
Publishing the category instance in a newly created publication object.

Removing a contact from a contact list typically involves the following operations:

Supplying a contact URI and other inputs to Unified Communications Client API and creating a publishable instance of the "contacts" category.
Setting the publication operation as UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_REMOVE.
Publishing the category instance in a newly created or an ongoing publication session.

Note

Publishing an updated contact list follows the same general programming pattern as publishing a local user's contact card except the contact list is only published to container UCC_SELF_CONTAINER_ID. To review contact card publishing, see Publishing Enhanced Presence