This documentation is archived and is not being maintained.

Publishing User Availability

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.

When a user signs in to a server using multiple devices simultaneously, the individual devices can be in different machine states. For example, a client can set the currently used device to an active state while setting others to an inactive state. The client can also set all the devices to an active state regardless of which one the user is actively using. The server uses a combination of the user state and machine state to determine the effective presence state and how to route a communication request to the user. This combined presence state is known as the aggregate state. To facilitate the state aggregation by the server, a Unified Communications Client API application should publish both the user and machine states.

The server performs the state aggregation only for presence category instances published in container 2 and 3. For this reason, you must publish updates to presence state to both container 2 and 3. The aggregated state calculated by a server is published to containers 100 through 32000 for the benefit of subscribing users.

Calling the Enable method starts to enable an endpoint. The endpoint is enabled only when the endpoint object raises an OnEnable event without errors. An application can verify this or other operational status, and execute appropriate application logic, for an endpoint by implementing the _IUccEndpointEvents members. For example, the following code example checks the operational status in the OnEnable event and then informs the user whether the sign-in process succeeded. When the endpoint is enabled without error, the application proceeds to identify the user's presence state and specify who can view the user's availability status.

The following example illustrates how to set the user and machine states that can be published as aggregated. If your client application is designed to interoperate with Office Communicator, you must publish presence state to both container 2 and 3. The example creates a new instance of the "state" category and publishes it to container 2.

    /// <summary>
    /// Publishes availability information to the server
    /// </summary>
    /// <param name="strAvail">Avaliability string: 
    ///   This has to be one of "Available", "Busy",
    ///   "Do Not Disturb", "Away" and "Offline". 
    ///   Actual availability is publiushed as an integer.
    ///   The server and client have a contract that defines 
    ///   the mapping of integer ranges to strings. 
    ///   An approximation of this mapping is used in the 
    ///   AvailabilityIntToString and AvailabilityStringToInt
    ///   methods listed later in example.</param>
    public void PublishAvailability(string strAvail)
    { 
        // Create a publishable category instance for the "state" 
        // category to publish the user state. This is indicated by 
        // setting the Type to "machinestate". The availability for
        // userState is set to the availability specifed by 
        // the user.                
        IUccCategoryInstance catStateForUserState = 
            publicationManager.CreatePublishableCategoryInstance(
              "state",                     // category name
              2,                           // container ID
              0x20000000,                  // instance ID
              UCC_CATEGORY_INSTANCE_EXPIRATION_TYPE.UCCCIET_USER, 
              0);
        IUccPresenceStateInstance userState = 
            catStateForUserState as IUccPresenceStateInstance;
        userState.IsManual = true;
        userState.Type = UCC_PRESENCE_STATE_TYPE.UCCPST_USER_STATE;

        //Convert availablity string to integer for publication
        userState.Availability = AvailabilityStringToInt(strAvail); 

        catStateForUserState.PublicationOperation = UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_ADD;

        // Create a publishable category instance for "state" 
        // category to publish the machine state.
        // This is indicated by setting the Type to "machinestate".
        // The availability for machinestate is set to 3500 - "Available". 
        // The server aggregates the userstate and machinestate
        // to compute an aggregate state which is then 
        // published on behalf of the user. It is important to 
        // publish machinestate to make this aggregation possible.
        IUccCategoryInstance catStateForMachineState = 
           publicationManager.CreatePublishableCategoryInstance(
              "state", 
              2, 
              0x30000000, 
              UCC_CATEGORY_INSTANCE_EXPIRE_TYPE.UCCCIET_DEVICE,
              10000);
        IUccPresenceStateInstance machineState = catStateForMachineState as IUccPresenceStateInstance;
        machineState.IsManual = true;
        machineState.Availability = 3500;
        machineState.Type = UCC_PRESENCE_STATE_TYPE.UCCPST_MACHINE_STATE; 
        catStateForMachineState.PublicationOperation = UCC_PUBLICATION_OPERATION_TYPE.UCCPOT_ADD;
        // Create a publication and advise for publication events.
        IUccPublication pub = publicationManager.CreatePublication();
        UCC_Advise<_IUccPublicationEvent>(pub, this);

        // Add the two publishable category instances 
        // to the publication.
        pub.AddPublishableCategoryInstance(
                              catStateForUserState);
        pub.AddPublishableCategoryInstance(
                              catStateForMachineState);
         // Publish the publication.
        pub.Publish(null);
    }

    /// <summary>
    /// Converts availability from a string to an integer.
    /// </summary>
    /// <param name="avail">String representation of availability</param>
    /// <returns>Integer representation of availability</returns>
    private int AvailabilityStringToInt(string avail)
    {
        if (avail == "Available")
            return 3500;
        else if (avail == "Busy")
            return 6500;
        else if (avail == "Do Not Disturb")
            return 9500;
        else if (avail == "Away")
            return 15500;
        else if (avail == "Appear Offline")
            return 18500;
        else
            return 0;
    }

Show: