Export (0) Print
Expand All

How to: Manage Persistent Chat users and user groups

Learn how to manage Persistent Chat users and user groups by using the Microsoft Lync Server 2013 Persistent Chat API.

Last modified: August 16, 2013

Applies to: Lync 2013 | Lync Server 2013

The Lync Server 2013 Persistent Chat API provides the following user administration services, which are encapsulated by the PersistentChatUserServices type:

  • Find Persistent Chat users with matching first name, last name, or email address.

  • Retrieve a Persistent Chat user of a given SIP URI.

  • Get detailed information of a Persistent Chat user group.

The user services are exposed by the UserServices property on the PersistentChatServices type.

To find Persistent Chat users with matching first name, last name, or email address, call BeginFindUsers(String, String, String, AsyncCallback, Object) followed by EndFindUsers(IAsyncResult, Boolean). The following code example shows how to find all users whose first name is John, whose last name is Doe, or whose email address is johndoe@contoso.com.


         PersistentChatEndpoint chatEndpoint = …;
         PersistentChatUserServices ChatUserServices = chatEndpoint.PersistentChatServices.UserServices;
    bool moreAvailable;
    var res = ChatUserServices.EndFindUsers(
        ChatUserServices.BeginFindUsers("Doe", "John", "johndoe@contoso.com", null, null),
        out moreAvailable);
    if (moreAvailable)
        Console.WriteLine("Only a subset of the results are returned. You may need to retry with more restricted search criteria");

When the output parameter moreAvailable returns true, some results are truncated and not returned. An application might want to retry the search by restricting the search criteria.

The results are returned as a collection of PersistentChatPrincipalSummary objects. Each of such objects is a lightweight version of the PersistentChatPrincipal object and contains a subset of the information about a user or group, including the name, SIP URI, and type of an Active Directory security principal object matching specified search criteria. For a user, the principal type is LocalUser. For a user group, the principal type is DirectoryGroup, DirectoryFolder or Domain.

To retrieve a Persistent Chat user of a given SIP URI, call BeginGetUser(Uri, AsyncCallback, Object) followed by EndGetUser(IAsyncResult). The following code example shows how to get the complete user information from the first entry of a user query against a given first name, last name, or email address.


PersistentChatEndpoint chatEndpoint = ...;
PersistentChatUserServices ChatUserServices = chatEndpoint.PersistentChatServices.UserServices;

public PersistentChatUser GetUser(string lastName, string firstName, string email)
{
    bool moreAvailable;
    PersistentChatPrincipalSummary ps = ChatUserServices.EndFindUsers(
        ChatUserServices.BeginFindUsers(lastName, firstName, email, null, null), out moreAvailable).FirstOrDefault();
    if (ps == null)
        return null;
    PersistentChatUser pu = ChatUserServices.EndGetUser(
        ChatUserServices.BeginGetUser(ps.Uri, null, null));
    return pu;
}

NoteNote

The GetUser operation succeeds only when the caller is a System User or when the caller tries to get the detailed user information about himself or herself. Otherwise, a CommandFailedException is raised stating that the caller is not authorized to perform the action.

In the example above, if the search returns an empty results set, the GetUser routine returns null. Otherwise, the first entry of the search results is used as the intended user. The final result is a PersistentChatUser object. It inherits from PersistentChatPrincipal and exposes additional information pertinent to the user, including the company name, display name, and email address, as well as whether the user is disabled for Persistent Chat or not.

To get detailed information of Persistent Chat user group, call BeginGetUserGroup(PersistentChatPrincipalSummary, AsyncCallback, Object) followed by EndGetUserGroup(IAsyncResult). The following code example shows how to get a Persistent Chat user group of a given name (groupName) intended for the specified chat room (roomUri).


PersistentChatEndpoint chatEndpoint = ...;

public PersistentChatUserGroup GetUserGroup(Uri roomUri, string groupName)
{
    ChatRoomManagementServices rms = chatEndpoint.PersistentChatServices.ChatRoomManagementServices;
    PersistentChatPrincipalSummary pSummary = rms.EndFindUsersOrGroupsForRole(
        rms.BeginFindUsersOrGroupsForRole(ChatRoomRole.Member, roomUri, groupName, null, null)).FirstOrDefault();
    if (pSummary == null)
        return null;
    PersistentChatUserServices pus = chatEndpoint.PersistentChatServices.UserServices;
    PersistentChatUserGroup pug = pus.EndGetUserGroup(pus.BeginGetUserGroup(pSummary, null, null));
    return pug;
}

NoteNote

The GetUserGroup operation succeeds only when the caller is a System User. Otherwise, a CommandFailedException is raised stating that the caller is not authorized to perform the action.

The returned results are a collection of PersistentChatUserGroup objects.

Show:
© 2014 Microsoft