Receive User's Presence States

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.

Publishing and receiving user presence states must be done to provide a user with accurate presence information for subscribing users. User presence states are published when a local user wants to actively change his apparent state. This is known as publishing a user state. Machine state is published by an application without action on the part of a user. Application logic determines when a computer is deemed to be active or otherwise. Remote applications perform the same functionality and publish presence states for a local application's consumption. Office Communications Server publishes an aggregation of a remote user's published user and machine state in the form of an state instance of the aggregateState or aggregateUserState type.

Receiving Subscribed User's Availability State

The users that a Unified Communications Client API application subscribes to can log on from other custom clients or an Office Communicator client. For this reason, the custom client must be able to process state categories containing both standard Office Communicator user availability states and other custom states. The following C# code example method is called by code in the OnCategoryInstanceAdded callback function. For information about this callback function, see Receive Subscribed Categories.

The following C# sample uses the following programming pattern:

1. Read the Type property of the presence state instance interface to determine the state type. Aggregate state, Aggregate User state, and User state are the state types of interest.
2. Call processAggregateState, an example application method that extracts any custom user availability state that exists.

/// <summary>
/// Processes an instance of "state" category to obtain availability
/// </summary>
private void ProcessStateCategoryInstance(IUccCategoryInstance category)
{
    try
    {
        // Need to cast the category into IUccPresenceStateInstance to obtain
        // state properties
        IUccPresenceStateInstance state = category as IUccPresenceStateInstance;
        switch (state.Type)
        {
            case UCC_PRESENCE_STATE_TYPE.UCCPST_AGGREGATE_MACHINE_STATE:
                MessageBox.Show("Machine State " + processAggregateState(state));
                break;
            case UCC_PRESENCE_STATE_TYPE.UCCPST_AGGREGATE_STATE:
                MessageBox.Show("User State " + processAggregateState(state));
                break;
            case UCC_PRESENCE_STATE_TYPE.UCCPST_CALENDAR_STATE:
                break;
            case UCC_PRESENCE_STATE_TYPE.UCCPST_CONFERENCE_STATE:
                break;
            case UCC_PRESENCE_STATE_TYPE.UCCPST_MACHINE_STATE:
                break; 
            case UCC_PRESENCE_STATE_TYPE.UCCPST_PHONE_STATE:
                break;
            case UCC_PRESENCE_STATE_TYPE.UCCPST_USER_STATE:
                processAggregateState(state);
                break;
            case UCC_PRESENCE_STATE_TYPE.UCCPST_UNKNOWN:
                break;
        }

       // Raise a property update event so any observers observing this contact can
       // update their own state
       ContactPropertyUpdated(this);
   }
   catch (COMException ex)
   {
      Throw ex;
   }
}

The processAggregateState method uses the following programming pattern:

1. Obtain a collection of user state activity objects from the presence state interface.
2. Iterate on the collection, casting individual collection members to the IUccPresenceActivity interface.
3. The activity state value range is obtained by calling into GetAvailabilityRange.
4. If the Availability property of the presence state instance falls within the range of this activity, the activity description string is extracted to display in the application contact list for this contact.
5. If no custom user application states exist, the IUccCollection obtained has no members. In this case, the application determines the activity string to display based on the Availability property of the presence state instance.

private string processAggregateState(IUccPresenceStateInstance state)
{
    string returnValue = String.Empty;
    IUccCollection contactActivity = state.Activities;
    if (contactActivity.Count > 0)
    {
        foreach (IUccPresenceActivity pa in contactActivity)
        {
           int minActivity;
           int maxActivity;
           pa.GetAvailabilityRange(out minActivity, out maxActivity);
           if (state.Availability >= minActivity &&  state.Availability <= maxActivity)
           {
              foreach (UccLocaleString ls in pa.CustomStrings)
              {
                 returnValue = ls.String;
              }
           }
        }
    }
    else
    {
       if (state.Availability < 3000)
           returnValue = "Unknown";
       else if (state.Availability < 6000)
           returnValue = "Available";
       else if (state.Availability < 9000)
           returnValue = "Busy";
       else if (state.Availability < 12000)
           returnValue = "Do Not Disturb";
       else if (state.Availability < 18000)
           returnValue = "Away";
       else
           returnValue = "Offline";
    }
    return returnValue;
}

See Also

Concepts

Presence Availability State
Managing Remote Contacts
Publishing User Availability