Manage ACL Container Membership

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

You can create a custom client application that allows your user to block remote subscribers from accessing enhance presence categories published by your user. A subscriber is blocked from seeing a category when the subscriber is not a member of any container that publishes that category. In other words, a subscriber is blocked when the intersection of all containers that contain the published category and all containers that contain the subscriber in their membership lists result in an empty set.

Unified Communications Client API provides a standard set of ACL containers with a predefined collection of ACE members. This standard set of ACL containers is designed to work with most access control requirements. Presence category state data published to private ACL container 2 is automatically aggregated to the public ACL containers 100, 200, 300, 400, and 32000. Other presence categories such as contactCard and calendarData must be explicitly published to one of the ACL containers. For information about what categories Microsoft Office Communicator publishes to the ACL containers, see Publish Category Instances.

Individual organizational and user requirements can require a custom collection of ACE members in existing containers or entirely new containers. It is a good idea to design ACL containers to allow the smallest number of containers to include the greatest number of subscribers. While you can create one container and place everyone in it, that solution provides no real access control. The five containers provided by Unified Communications Client API provide a good balance between functional access control and simplicity of design. Each container holds an increasing number of category instances as the scope of the container moves from the blocked scope to general public, company, team, and finally private scope.

The best practice for creating new ACL containers considers any additional containers to be exception containers. For example, a user might want to provide only contactCard, Instance ID 1 instead of instances 1, 2, and 3 to a small subset of the subscribers who normally fit in the 200 container (same company). In this case, a new container with the ID like 205 might be created. The ACE membership list would be composed of individual employees and the desired set of category instances published to the new container.

If you create a custom container with an ID value greater than the ID value of the container it is to replace, it is not necessary to remove users from the original category. Office Communications Server provides presence category data from the highest container ID a given user is a member of.

In general, a subscriber added to any container with the membership scope of UCC_CONTAINER_MEMBERSHIP_SCOPE.UCCCMS_USER cannot be in any other container as a member with that scope. If you have added a domain such as "contoso.com" with the scope of UCC_CONTAINER_MEMBERSHIP_SCOPE.UCCCMS_DOMAIN to a container, you cannot put that combination of scope and entity into a second container. The membership scopes of UCC_CONTAINER_MEMBERSHIP_SCOPE. UCCCMS_FEDERATED, UCC_CONTAINER_MEMBERSHIP_SCOPE. UCCCMS_COMPANY, or UCC_CONTAINER_MEMBERSHIP_SCOPE. UCCCMS_EVERYONE should never be placed in multiple containers.

Creating a New Container

A container is a strongly typed instance of a category. The same programming pattern used to publish any category instance is followed to create a container. The C# code snippet demonstrates creating container 305 as an "exception" container to further define access control for team members.

    //Create a publishable category instance representing the container members to be added
    IUccCategoryInstance ci = pubMgr.CreatePublishableCategoryInstance(
                                  "containers", 
                                  0, 
                                  305, 
                                  UCC_CATEGORY_INSTANCE_EXPIRATION_TYPE
                                 .UCCCIET_STATIC, 
                                  0);

    //Create a publishable category instance representing the container members to be removed
    IUccCategoryInstance cr = pubMgr.CreatePublishableCategoryInstance(
                                  "containers", 
                                  0, 
                                  300, 
                                  UCC_CATEGORY_INSTANCE_EXPIRATION_TYPE
                                 .UCCCIET_STATIC, 
                                  0);

   //Set publication operation type for the category
    ci.PublicationOperation = UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_ADD;
    cr.PublicationOperation = UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_ADD;

Adding ACE Members

The example C# illustrates adding individual subscribers to the new container with the membership scope level of UCC_CONTAINER_MEMBERSHIP_SCOPE.UCCCMS_USER. Each user added to container 305 must be removed from container 300.

   //Cast IUccContainerInstance to IUccContainer object to add members to it
    IUccContainer container305 = ci as IUccContainer;
    IUccContainer container300 = cr as IUccContainer;

    string[] a_URI = new string[] {"sip:jaya@contoso.com","sip:jimp@contoso.com"};
    foreach (string s_URI in a_URI)
    {
       //Create an ACE container member for each user in team subset
        IUccContainerMember member = pubMgr.CreateContainerMember(
                                         s_URI, //string URI 
                                         UCC_CONTAINER_MEMBERSHIP_SCOPE
                                        .UCCCMS_USER);
       // Add the container member to the container
        Container305.AddMember(member);

       // remove member from container 300 
       Container300.RemoveMember(member);
    }

Publish Containers

Create a publication object by calling CreatePublication on the publication manager. With the new publication, you must register for the publication events to see the result of the publication request. Finally, add the new category instance representing the containers to the publication and call the Publish method.

    IUccPublication pub = pubMgr.CreatePublication() as IUccPublication;
    if (pub != null)
    {
        UCC_Advise<_IUccPublicationEvent>(pub, this);

        //add container 305 category to publication
        pub.AddPublishableCategoryInstance(ci);

        //add container 300 category to publication
        pub.AddPublishableCategoryInstance(cr);
        pub.Publish(null);
    }

Handling the Publication Event

This event handler is a good place to determine the success of the container publish request. You can trigger a process to publish category instance objects to this new container in this callback function.

void _IUccPublicationEvent.OnPublish(IUccPublication pEventSource, IUccOperationProgressEvent pEventData)
{
    // Similar to OnSubscribe, we can examine the result of the publication oepration
    // here and do error handling
    if (pEventData.StatusCode >= 0)
    {
        IUccOperationContext oc = pEventData.OriginalOperationContext;
    // additional event handling logic to publish category instance
    }
}

Publishing Category Instances to the Container

The container you created and published is now available to accept categories.

Container 305 is an exception container that holds the categories normally held in container 300 with the exception of the extendedCalendarState**category instance. In this example, extendedCalendarState is replaced by calendarState. The ACE members of container 305 are added in a previous step. Each category of presence information is added in the same way.

For information about publishing to the new category, see Publish Category Instances.

Create calendarData Category Instance

When creating an instance of a Microsoft Office Communicator category, call GetPresenceCategoryName on the publication manager with the UCC_PRESENCE_CATEGORY_TYPE enumeration to return the category name. In addition, supply the container ID (305 in this case) of the container to which you want to publish.

string epId = thisEndpoint.Id;

string catName = pubMgr.GetCategoryName(
                                        UCC_PRESENCE_CATEGORY_TYPE
                                       .UCCPCT_CALENDARDATA);
IUccCategoryInstance calData = pubMgr.CreatePublishableCategoryInstance(
                                         catName, 
                                         305, 
                                         0x40000000, 
                                         UCC_CATEGORY_INSTANCE_EXPIRATION_TYPE
                                         .UCCCIET_DEVICE, 
                                         0);
calData.PublicationOperation = UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_ADD;

Publish calendarData Category

Create a publication object by calling CreatePublication on the publication manager. With the new publication, you must register for the publication events to see the result of the publication request. Finally, add the new category instance representing the container to the publication and call the Publish method.

 // Create a publication and advise for publication events
IUccPublication pub = pubMgr.CreatePublication() as IUccPublication;
UCC_Advise<_IUccPublicationEvent>(pub, this);

// Add the two publishable category instances to the publication
pub.AddPublishableCategoryInstance(calData);

//Publish the publication
pub.Publish(null);

In This Section

Granting Permissions to View Published Presence States

Using the Container Membership Manager

See Also

Concepts

Receive User's Presence States
Granting Permissions to View Published Presence States