Walkthrough: Add and Remove Contacts in a Group (Lync 2010 SDK)

This topic demonstrates how to add contacts to, and remove contacts from groups. To display on a client’s contact list, a contact must be contained in at least one group. When a contact is obtained, your application users can add the contact to any group. They can later add this contact to additional groups or move this contact to a different group. Contacts can also be removed from a group or be removed completely from the contact list.

Although a DistributionGroup is inherited from the base Group class, you cannot add or remove contacts from the distribution group. Distribution group features are limited to group expansion and query for contact members. However, you can get a Contact from a distribution group contact collection and add it to any other group. For more information about working with distribution groups, see Walkthrough: Expand a Distribution Group (Lync 2010 SDK).

Prerequisites

Get the LyncClient instance. Verify that the client is signed in to the server. For information about signing in to Microsoft Lync Server 2010, see Walkthrough: Sign In to Lync (Lync 2010 SDK).

Add a Contact to a Group

To add a contact to a group, you call the BeginAddContact method on the target Group. If the contact is added to the group, you receive the ContactAdded state change event on the Group instance. BeginAddContact is an asynchronous operation and requires that you call EndAddContact to block your thread until the operation completes.

1. Register for the ContactAdded event on the custom group you are adding the contact to.

2. Get an instance of Contact. The Contact instance you add to a custom group can be a member of another group but cannot be added to the target group if it is already a member of the target group.

   Tip

   You can get this contact from a collection of search results or by calling into either BeginLookup or GetContactByUri. For a contact search walkthrough, see Walkthrough: Search For a Contact (Lync 2010 SDK)

3. Call BeginAddContact on the target instance of Group, passing the contact to add. An instance of System.IAsyncResult is returned.

4. Call EndAddContact, passing the return value from the previous step in the argument.

   Tip

   If you want to avoid blocking execution of your UI thread until the operation completes, you call EndAddContact from within the callback method you passed in the previous step.

5. Catch the ContactAdded event raised by Group.

   Tip

   This event is also raised when the local user adds a contact to a group using the Lync 2010 UI.

Remove a Contact from a Group

To remove a contact from a specific group, you call the BeginRemoveContactmethod on a Group to which the contact belongs, supplying the contact you want to remove. If the contact is removed from the group, you receive the ContactRemoved state changed event on the group. Like the add contact operation, BeginRemoveContact requires the corresponding EndRemoveContact operation.

1. Register for the ContactRemoved event on the custom group you are removing the contact from.

2. Call [M:System.Collections.Generic.ICollection<T>.Contains(T)] on the Group. Pass the Contact to be removed as the argument. If the group contains the Contact, true is returned.

   Tip

   The CustomGroups property is a collection of all custom groups to which the contact belongs. You can call TryGetGroup. If the Contact is a member of the group in question, the out parameter is returned with the Group in question.

3. Call the BeginRemoveContact method on the group that contains the contact to be removed. Pass the contact to be removed as the first argument.

4. Call EndRemoveContact to complete the operation started in the previous step.

   Tip

   If you want to avoid blocking execution of your UI thread until the operation completes, you call EndRemoveContact from within the callback method you passed in the previous step.

5. Catch the ContactRemoved event raised by the group from which the contact was removed.

Move an Existing Contact to a Different Group

Since a contact can be a member of multiple groups, adding the contact to a new group does not remove it from the original group. To move a contact from one group to another, you must first add the contact to the new target group and then remove the contact from the original group.

Remove a Contact from All Groups

To remove a contact from all groups, you call the BeginRemoveContactFromAllGroups method on the ContactManager, supplying the contact you want to remove.

1. Register for events on the ContactManager returned when you read the ContactManager property.

2. Call the BeginRemoveContactFromAllGroups method, passing the contact to be removed. You must cache the System.IAsyncResult instance returned from the called method.

3. Call EndRemoveContactFromAllGroups, passing the value returned from the method called in the previous step.

Examples

The following examples demonstrate the group actions described previously.

Add a Contact

The following example adds a contact to a group if the group is not a distribution group and the group’s collection of contacts does not contain the contact to add.

        /// Add a new contact to contact list.
        /// Add contact to selected custom group.
        /// <param name="contactToAdd">Contact</param>
        /// <param name="groupAdd">Group to add contact to</param>
        public void AddContact(Contact contactToAdd, Group groupAdd)
        {
            if (groupAdd.Type == GroupType.DistributionGroup)
            {
                return;
            }
            if (groupAdd.Contains(contactToAdd) == false)
            {
                groupAdd.ContactAdded += group_ContactAdded;
                IAsyncResult ar = groupAdd.BeginAddContact(contactToAdd, null, null);

                //UI thread execution blocked until operation completes.
                groupAdd.EndAddContact(ar);
            }
        }

In the next example, this registration is included in the previous example. The following example handles the ContactAdded event raised on Group by displaying a message dialog and registering for contact events.

        void group_ContactAdded(Object source, GroupMemberChangedEventArgs data)
        {
            ((Group)Source).ContactAdded -= group_ContactAdded;
            // Update application UI with event notification.
            System.Windows.Forms.MessageBox.Show(
                "New Contact in Group: " 
                + ((Group)source).Name 
                + " : " 
                + data.Contact.GetContactInformation(ContactInformationType.DisplayName).ToString());

                // Listen for contact events.
                data.Contact.ContactPropertyChanged += c_ContactPropertyChanged;
                data.Contact.PresenceItemsChanged += c_PresenceItemsChanged;
                data.Contact.UriChanged += c_UriChanged;
        }

Remove a Contact

The following example verifies that the group which the example is removing the contact from is not a distribution group. It verifies that the contact is actually a member of the specified group, registers for the ContactRemoved event, and then removes the contact from the group.

        /// Removed selected contact from selected group.
        /// Callback triggers update of contact array list and UI.
        /// <param name="contactToRemove">Contact. The contact to be removed</param>
        /// <param name="groupToRemoveFrom">Group. The custom group containing the contact to be removed.</param>
        private void RemoveContactFromGroup(Contact contactToRemove, Group groupToRemoveFrom)
        {
            if (groupToRemoveFrom.Type == GroupType.DistributionGroup)
            {
                return;
            }
            if (contactToRemove.CustomGroups.Contains(groupToRemoveFrom))
            {
                groupToRemoveFrom.ContactRemoved += group_ContactRemoved;
                IAsyncResult ar = groupToRemoveFrom.BeginRemoveContact(contactToRemove, null, null);

                //UI thread execution blocked until operation completes.
                groupToRemoveFrom.EndRemoveContact(ar);
            }
        }

The following method handles the ContactRemoved event by displaying a message dialog, verifying that the contact does not belong to any custom groups, and then cancelling registration for contact events on the contact to be removed.

   void group_ContactRemoved(object source, GroupMemberChangedEventArgs data)
   {
        if (data.Contact.CustomGroups.Count == 0)
        {
            data.Contact.ContactInformationChanged -= c_ContactInformationChanged;
            data.Contact.SettingChanged -= c_ContactSettingChanged;
            data.Contact.UriChanged -= c_UriChanged;
        }

        // Update application UI with event notification.
        System.Windows.Forms.MessageBox.Show(
            "Contact was removed from Group: " 
            + ((Group)source).Name);
            ((Group)source).ContactRemoved -= group_ContactRemoved;

   }

Remove a Contact from All Groups

The following example un-registers for events on the contact to be removed from all groups and then removes the contact from all groups.

        /// Removes contact from all groups.
        /// <param name="contactToRemove">Contact</param>
        private void RemoveContact(Contact contactToRemove)
        {
            contactToRemove.ContactInformationChanged -= c_ContactInformationChanged;
            contactToRemove.SettingChanged -= c_ContactSettingChanged;
            contactToRemove.UriChanged -= c_UriChanged;
            IAsyncResult ar =_ContactManager.BeginRemoveContactFromAllGroups(contactToRemove, null, null);

            //UI thread execution blocked until operation completes.
            _ContactManager.EndRemoveContactFromAllGroups(ar);
        }

See Also

Concepts

Handle Events for a Contact (Lync 2010 SDK)

Lync Model API Contacts and Groups Walkthroughs (Lync 2010 SDK)

Walkthrough: Add, Remove, and Rename Custom Groups (Lync 2010 SDK)