Receive Contact List
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.
To receive a local user's contact list in a subscription, create a subscription to the "contacts" category. For information about creating a contact list subscription, see Create Contact List Subscription.
After the subscription to the contact list is requested, the application begins to receive individual entries in the contact list through a chain of events initiated by OnCategoryContextAdded. This callback function must be used to advise for category context events. Doing so allows OnCategoryInstanceAdded events to be raised. These events originate from the contact list's presentity object (that is, selfPresentity in the following code) representing the user herself. The application must handle these events to receive the contact list entries and monitor the presence of individual contacts. This also implies that an application must register for _IUccPresentityEvents, _IUccCategoryContextEvents, and _IUccCategoryInstanceEvents in addition to _IUccContactEvents and/or _IUccGroupEvents.
Examples
The following examples handle subscription events, presentity events, and category events raised after a request to subscribe to a local user's contact list. When Office Communications Server has completed the request for a contact list, the example creates a batch subscription for individual contact list member's presence.
Presentity Event Handler
this example class implements presentity event callback methods to handle the local user's presentity events. An instance of this class begins to receive events on the local user presentity when Office Communications Server returns the subscribed "contacts" category.
partial class ContactManager : _IUccPresentityEvents
{
// Subscription used to subscribe for availability/contact card of all contacts.
private UccSubscription m_ContactsSubscription;
private UccSubscription m_SelfSubscription;
#region _IUccPresentityEvents Members
void _IUccPresentityEvents.OnCategoryContextAdded(
IUccPresentity pPresentity,
IUccCategoryContextEvent pCategoryCtxt)
{
IUccCategoryContext cx = pCategoryCtxt.CategoryContext;
// Advise for _IUccCategoryContextEvents on category context so
// we get category instances of this category context.
// Subscribe to "categories" category, to get OnCategoryContextAdded
// event for categories published by this user.
UCC_Advise<_IUccCategoryContextEvents>( cx, this);
}
void _IUccPresentityEvents.OnCategoryContextRemoved(
IUccPresentity pPresentity,
IUccCategoryContextEvent pCategoryCtxt)
{
IUccCategoryContext cx = pCategoryCtxt.CategoryContext;
// Un advise for this category context.
UCC_Unadvise<_IUccCategoryContextEvents>(
pCategoryCtxt.CategoryContext,
this);
}
#endregion
}
Category Context Event Handler
This example is a class that implements the category context events raised when a category context, in this case "contacts" has been received. The category context is the source of category instance events. For this reason, a client application advises for category instance events.
Note: The type UCCPContact in this example is an application class found in the sampleUCCPClient solution included with this software development kit.
partial class ContactManager : _IUccCategoryContextEvents
{
private List<UCCPContact> contacts = null;
#region _IUccCategoryContextEvents
void _IUccCategoryContextEvents.OnCategoryInstanceAdded(
IUccCategoryContext pCategoryCtxt,
IUccCategoryInstanceEvent pCategory)
{
IUccCategoryInstance ci = pCategory.CategoryInstance;
try
{
StringComparer strComparer = StringComparer.Create(System.Globalization.CultureInfo.CurrentCulture, true);
if (strComparer.Compare(pCategoryCtxt.Name, "contacts") == 0)
{
// A category instance with category context name "contacts" represents
// a contact. Cast the category instance to IUccContact to get the
// IUccContact object.
IUccContact addedContact = ci as IUccContact;
// Create a presentity for this contact.
IUccPresentity presentity = this.m_ContactsSubscription.CreatePresentity(addedContact.Uri, null);
// New application class responsible for handling
// events raised by the presentity representing the remote
// user represented by this new presentity.
UCCPContact contact = new UCCPContact(presentity);
contacts.Add(contact);
// Add the contact to the contact list.
contactList.Add(addedContact.Uri.Value);
// Add the presentity of the remote user to a subscription
// to contact enhanced presence. This subscription holds
// a collection of contact presentities at the completion of
// the request to subscribe to the local users contact list.
//
// A batch subscription request is made with this subscription
// in the OnSubscribe event raised when Office Communications Server
// has filled the contact list subscription.
this.m_ContactsSubscription.AddPresentity(presentity);
}
else
{
// Advise for _IUccCategoryInstanceEvents to get events when this instance is modified.
UCC_Advise<_IUccCategoryInstanceEvents>(ci, this);
}
}
catch (COMException ex)
{
Utilities.ReportError(ex.ToString());
}
}
void _IUccCategoryContextEvents.OnCategoryInstanceRemoved(
IUccCategoryContext pCategoryCtxt,
IUccCategoryInstanceEvent pCategory)
{
IUccCategoryInstance ci = pCategory.CategoryInstance;
UCC_Unadvise<_IuccCategoryInstanceEvents>(ci, this);
if (pCategoryCtxt.Name == "contacts" && hasShutDownStarted == false)
{
// A category instance with category context name "contacts" represents
// a contact. Cast the category instance to IUccContact to get the
// IUccContact object.
IUccContact contactToBeRemoved = ci as IUccContact;
// Unsubscribe for this contact.
this.m_contactsSubscription.RemovePresentity(pCategoryCtxt.Presentity);
}
}
#endregion
}
Category Instance Event Handler
The following example handles the event raised when specific instances of the contacts category are received on the client. The OnCategoryInstanceValueModified event exposes properties giving the client access to the actual contact list category data.
partial class ContactManager : _IUccCategoryInstanceEvents
{
#region _IUccCategoryInstanceEvents Members
void _IUccCategoryInstanceEvents.OnCategoryInstanceValueModified(
IUccCategoryInstance pCategory,
object pEventData)
{
try{
StringComparer strComparer = StringComparer.Create(System.Globalization.CultureInfo.CurrentCulture, true);
if (strComparer.Compare(pCategory.CategoryContext.Name,"contactCard")== 0)
{
// Cast the category instance to an IUccPresenceContactCardInstance.
IUccPresenceContactCardInstance card = pCategory as IUccPresenceContactCardInstance;
// Get display name from the contact card instance.
if (card.Identity != null)
{
this.selfDisplayName = card.Identity.DisplayName;
}
}
else if (strComparer.Compare(pCategory.CategoryContext.Name,"state") == 0)
{
// Cast the category instance to IUccPresenceStateInstance to obtain
// availability.
IUccPresenceStateInstance state = pCategory as IUccPresenceStateInstance;
}
}
catch (COMException ex)
{
Utilities.ReportError(ex.ToString());
}
}
#endregion
}
Subscription Event Handler
This example handles the OnSubscribe event raised when a request for subscription has been completed by Office Communications Server. The example issues a batch subscription to the enhanced presence categories of the remote users on the local user's contact list.
partial class ContactManager : _IUccSubscriptionEvents
{
#region _IUccSubscriptionEvent Members
/// <summary>
/// Handles event raised when Office Communications Server has completed a
/// subscription request
/// </summary>
/// <param name="pSubscription">UccSubscription Original subscription request</param>
/// <param name="pEventInfo">UccSubscriptionEvent subscription status</param>
void _IUccSubscriptionEvents.OnSubscribe(
UccSubscription pSubscription,
UccSubscriptionEvent pEventInfo)
{
if (Object.ReferenceEquals(pSubscription, this.m_SelfSubscription))
{
IUccOperationProgressEvent opEvent = pEventInfo.GetOperationInfo(m_SelfPresentity);
if (opEvent.IsComplete)
{
if (opEvent.StatusCode == Utilities.S_OK)
{
// Raise an event to indicate sign in completed successfully.
// Issue batch subscribe request for the new contacts
this.m_ContactsSubscription.Subscribe(null);
}
}
}
}
#endregion
}
See Also
Concepts
Create Contact List Subscription
Add a Contact to the Contact List
Remove a Contact from the Contact List
Receive User's Presence States
Presence Availability State
Sample Contact Presence Handling Class
Manage ACL Container Membership
Contact Group Management