This topic demonstrates 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 Asynchronous Programming .

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 GroupAddedevent, see Handle Events for ContactManager .

  2. Add a System.AsyncCallbackmethod 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 .

  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.AsyncCallbackmethod into BeginAddGroupand 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 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 GroupRemovedevent, see Handle Events for ContactManager .

  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 .

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

  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.

Tip Tip

You should not register for the Group . . :: . . NameChanged event for groups whose Group . . :: . . Type property value is not Microsoft.Lync.Model.Group . . :: . . GroupType . CustomGroup.

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 and Handle Events for ContactManager .

Examples

The following example calls AddCustomGroupon an instance of ContactManager.

C#  Copy imageCopy Code 
		/// <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 GroupAddedevent raised by ContactManager. For more information about the this.LoadAGroupexample method, see Handle Events for ContactManager .

C#  Copy imageCopy Code 
		/// <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 ContactManagerwhen a custom group is added.

C#  Copy imageCopy Code 
		/// <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 RemoveGroupon an instance of ContactManager.

C#  Copy imageCopy Code 
		/// <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 GroupRemovedevent raised by ContactsAndGroupsManager.

  Copy imageCopy Code 
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 ContactsAndGroupsManagerwhen a custom group is removed.

C#  Copy imageCopy Code 
		/// <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 Renameon an instance of Groupwhich is recast as a CustomGroup. The new name for the group is passed as the final parameter of the Renamefunction (the state parameter).

C#  Copy imageCopy Code 
		/// <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.

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

See Also