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

This topic and the accompanying video demonstrate how to add, remove, and rename custom groups. A custom group is a user-defined instance of Group whose membership is defined by a user.

When a local user performs any of the group operations described in this topic using Lync 2010, the result of the operation must be visible to the local user immediately on any signed-in endpoint. To make this possible, the API sends the group operation request to Microsoft Lync Server 2010 and result is sent to all of the user’s signed in endpoints. For this reason, group operations are asynchronous even though only the local user sees the result of the operation. For information about asynchronous coding patterns with Microsoft Lync 2010 API, see Lync Asynchronous Programming (Lync 2010 SDK).

Add a Custom Group

To add a new custom group, you call the BeginAddGroup method on the contacts and groups manager, supplying the name of the new group. You must call EndAddGroup to complete the operation. You receive the GroupAdded event when the new custom group is added. Read the Group property to get an instance of the new custom group that is added.

The following figure illustrates the classes, methods, and events used in the process of adding a custom group and adding a contact to the group.

Add a Custom Group

1. In your form class, create an event handler for the GroupAdded event. For additional information about the GroupAdded event, see Handle Events for ContactManager (Lync 2010 SDK).

2. Add a System.AsyncCallback method to be invoked when the BeginAddGroup operation completes.

3. Get a 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).

4. Read the ContactManager property on the LyncClient instance to get the contact manager.

5. Register for the GroupAdded event on ContactManager.

6. Call BeginAddGroup on ContactManager, passing a string containing the requested group name. If you want to block execution on your UI thread until the operation completes, call EndAddGroup after the first call. To avoid blocking your UI thread, pass a System.AsyncCallback method into BeginAddGroup and then call EndAddGroup within the callback when it is invoked from the Lync thread.

Add a Distribution Group

A distribution group is created outside of the scope of this API. It is obtained and added to a user’s contact list using the Microsoft Lync 2010 API. See Walkthrough: Search For a Contact (Lync 2010 SDK) for information about obtaining an existing distribution group.

Once you have obtained a distribution group in a set of search results, you add the distribution group to the contact list by calling into BeginAddGroup, passing the distribution group as the first argument.

See the previous walkthrough for the walkthrough steps to add the distribution group.

Remove a Custom Group

To remove a custom group, you call the BeginRemoveGroup method on the contacts and groups manager, supplying the group to be removed. If the group is removed, you receive the GroupRemoved event on the ContactManager instance.

1. In your form class, create an event handler for the GroupRemoved event. For additional information about the GroupRemoved event, see Handle Events for ContactManager (Lync 2010 SDK).

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

3. Read the Client.ContactManager property to get the Microsoft.Lync.Model.ContactManager instance you use to remove a custom group.

4. Register for the GroupRemoved event on ContactManager.

5. Remove any registrations for events on the group to be removed.

6. Call ContactManager.BeginRemoveGroup on the contact manager, passing the Microsoft.Lync.Model.Group.Group to be removed.

   Note

   If the group to be removed contains contacts, these contained contacts are not removed from any other containing custom groups.

   To remove a contact from all groups, call ContactManager.BeginRemoveContactFromAllGroups.

7. Call ContactManager.EndRemoveGroup to complete the operation.

8. Catch the ContactManager.GroupRemoved event when the state of the contact manager group collection (ContactManager.Groups) has changed.

Rename a Custom Group

The group rename operation is restricted to groups of type Microsoft.Lync.Model.Group.GroupType.CustomGroup

1. 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).

2. Register for the NameChanged event on all Group instances. You should perform this step when you obtain the collection of a local user’s contact list groups in the form load event.

3. Verify that the group to be renamed is of type GroupType. CustomGroup. Only a custom group can be renamed.

4. Cast the group to be renamed to Microsoft.Lync.Model.Group.CustomGroup.

5. Call BeginRename on the custom group, passing the new name of the group as a string.

6. Call EndRename to complete the operation.

7. Catch the Group.NameChanged event raised when the state of the custom group has changed as a result of the operation.

Handle Events

Each of the procedures in this topic includes registration for events triggered by group operations. The ContactManager.GroupAdded and ContactManager.GroupRemoved events are raised by Microsoft.Lync.Model.ContactManager, while the Group.NameChanged event is specific to the instance of Microsoft.Lync.Model.Group.Group that is renamed.

Methods to handle these events are useful in triggering user interface updates and for registering and removing registration for events related to the affected groups. Examples of event handlers for these events are included later in this topic. For more information about handling these events, see Handle Events for a Group (Lync 2010 SDK) and Handle Events for ContactManager (Lync 2010 SDK).

Examples

The following example calls AddCustomGroup on an instance of ContactManager.

        /// <summary>
        /// Adds a custom group.
        /// </summary>
        /// <param name="GroupName">string. The name of the new custom group</param>
        public void AddACustomGroup(string GroupName)
        {
            _ContactManager.BeginAddGroup(GroupName,  AddCustomGroupCallback, _ContactManager);
        }

The following example handles the GroupAdded event raised by ContactManager. For more information about the this.LoadAGroup example method, see Handle Events for ContactManager (Lync 2010 SDK).

        /// <summary>
        /// Handler for event raised when a group is added.
        /// </summary>
        /// <param name="source">Object. The ContactManager instance</param>
        /// <param name="data">GroupCollectionChangedEventArgs. The event state data</param>
        void manager_GroupAdded (Object source, GroupCollectionChangedEventArgs data)
        {
            data.Group.ContactAdded +=Group_ContactAdded;
            data.Group.NameChanged +=Group_NameChanged;
            data.Group.ContactRemoved +=Group_ContactRemoved;
        }

The following example method is called by ContactManager when a custom group is added.

        /// <summary>
        /// Called by LyncClient when a custom group has been added to the Groups collection on ContactManager
        /// </summary>
        /// <param name="ar">IAsyncResult. The Asynchronous result of the operation</param>
        private void AddCustomGroupCallback(IAsyncResult ar)
        {
            ((ContactManager)ar.AsyncState).EndRemoveGroup(ar);
        }

The following example calls RemoveGroup on an instance of ContactManager.

        /// <summary>
        /// Removes a custom group
        /// </summary>
        public void RemoveCurrentCustomGroup()
        {
            Group groupToRemove = null;
            if (_ContactManager.Groups.TryGetGroup("Test Group", out groupToRemove))
            {
                if (groupToRemove.Type == GroupType.CustomGroup)
                {
                    _ContactManager.BeginRemoveGroup(groupToRemove, RemoveCustomGroupCallback, _ContactManager);
                }
            }
        }

The following example handles the GroupRemoved event raised by ContactsAndGroupsManager.

private void manager_GroupRemoved(Object source, GroupCollectionChangedEventArgs data)
        {
            data.Group.ContactAdded -= Group_ContactAdded;
            data.Group.NameChanged -= Group_NameChanged;
            data.Group.ContactRemoved -= Group_ContactRemoved;
        }

The following example method is called by ContactsAndGroupsManager when a custom group is removed.

        /// <summary>
        /// Called by LyncClient when a custom group has been removed from the Groups collection on ContactManager
        /// </summary>
        /// <param name="ar">IAsyncResult. The asynchronous result of the operation.</param>
        private void RemoveCustomGroupCallback(IAsyncResult ar)
        {
            ((ContactManager)ar.AsyncState).EndRemoveGroup(ar);
        }

The following example calls Rename on an instance of Group which is recast as a CustomGroup. The new name for the group is passed as the final parameter of the Rename function (the state parameter).

        /// <summary>
        /// Renames an existing custom group
        /// </summary>
        /// <param name="NewGroupName">String. New group name.</param>
        public void RenameCurrentGroup(string NewGroupName)
        {
            Group groupToRemove = null;
            if (_ContactManager.Groups.TryGetGroup("Test Group", out groupToRemove))
            {
                if (groupToRemove.Type == GroupType.CustomGroup)
                {
                    CustomGroup customGroup = groupToRemove as CustomGroup;
                    if (customGroup != null)
                    {
                        IAsyncResult ar = customGroup.BeginRename(NewGroupName, null, null);
                        customGroup.EndRename(ar);
                    }
                }
            }
        }

The following example displays a message when the name of a group has changed.

void group_NameChanged(Object source, GroupNameChangedEventArgs data)
    {
        System.Windows.Forms.MessageBox.Show ("New Group name " + 
                 data.NewName);
    }

See Also

Concepts

Handle Events for a Group (Lync 2010 SDK)

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

Handle Events for ContactManager (Lync 2010 SDK)

Other Resources

Video: Add, Rename, and Delete Custom Groups in Lync