Receiving Contacts and Groups

Once the ContactGroupServices object is initialized and the desired event handlers are registered with it, an application can start to receive the self-published contact list by submitting a SUBSCRIBE request containing contacts and groups category names in the message body. In Microsoft Unified Communications Managed API (UCMA) 3.0, the operation is asynchronous and the SUBSCRIBE request corresponds to the call to BeginSubscribe/EndSubscribe on the ContactGroupServices object. The results are returned in the NotificationReceived events raised by the ContactGroupServices object.

Start to Receive Contacts and Groups

The following code example shows how to start to receive a published contact list using UCMA.

        /// <summary>
        /// Start to receive the contacts and groups category instances. The results 
        /// are returned in ContactAdded or GroupAdded events.
        /// </summary>
        public void StartToReceiveContactsAndGroups()
        {
            if (_cgServices.CurrentState != CollaborationSubscriptionState.Subscribed)
            {
                _cgServices.BeginSubscribe(CallbackOnBeginSubscribe, _cgServices);
            }
        }

        void CallbackOnBeginSubscribe(IAsyncResult result)
        {
            try
            {
                _cgServices.EndSubscribe(result);
            }
            catch (Exception ex)
            {
                MessageBox.Show(ex.Message, "UcmaContactManager.CallbackOnBeginSubscribe");
            }
        }

The results of this operation will be returned in the NotificationReceived events raised by ContactGroupServices. When the request succeeds, the subscription state changes from Idle to Subscribed. The changes are returned in the SubscriptionStateChanged events raised by the ContactGroupServices object as well. Example of these event handlers are discussed in Preparing to Receive the Contact List. The last published contacts and groups are returned as the initial results. Subsequent updates to the contact list, i.e., addition or removal of a contact or a group, will be returned as incremental changes.

Stop Receiving Contacts and Groups

The following code example shows how to stop an active subscription to receive the contact list.

        /// <summary>
        /// Stop receiving contacts and groups category instances
        /// </summary>
        public void StopToReceiveContactsAndGroups()
        {
            if (_cgServices.CurrentState == CollaborationSubscriptionState.Subscribed)
            {
                _cgServices.BeginUnsubscribe(CallbackOnBeginUnsubscribe, _cgServices);
            }           
        }

        void CallbackOnBeginUnsubscribe(IAsyncResult result)
        {
            try
            {
                _cgServices.EndUnsubscribe(result);

                this.UnsubscribeToContactsPresence();
            }
            catch (Exception ex)
            {
                MessageBox.Show(ex.Message, "UcmaContactManager.CallbackOnBeginUnsubscribe");
            }
        }

As a result, the final subscription state will Terminated.

Refresh the Contact List

Refreshing the contact list amounts to issuing a SUBSCRIBE request on the ContactGroupServices object when the contact list is already subscribed to.

        /// <summary>
        /// Refresh the contact list (obtained via the ContactGroupServices instance)
        /// </summary>
        public void RefreshContactsAndGroups()
        {
            _cgServices.BeginRefresh(CallbackOnBeginRefresh, _cgServices);

        }

        void CallbackOnBeginRefresh(IAsyncResult result)
        {
            try
            {
                if (_cgServices == result.AsyncState as ContactGroupServices)
                {
                    if (result.IsCompleted)
                    {
                        // Complete the contact list refresh request.
                        _cgServices.EndRefresh(result);

                        // Refresh contacts presence
                        this.RefreshContactsPresence();
                    }
                }

            }
            catch (Exception ex)
            {
                MessageBox.Show(ex.Message, "UcmaContactManager.CallbackOnBeginRefresh");
            }
        }