_IUccSessionParticipantEvents.OnStateChanged Method

  • Article

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.

Raised when the participant state changes.

Namespace: Microsoft.Office.Interop.UccApi
Assembly: Microsoft.Office.Interop.UccApi (in microsoft.office.interop.uccapi.dll)

Syntax

'Declaration
Sub OnStateChanged ( _
    pEventSource As IUccSessionParticipant, _
    pEventData As UccSessionParticipantStateChangedEvent _
)

void OnStateChanged (
    IUccSessionParticipant pEventSource,
    UccSessionParticipantStateChangedEvent pEventData
)

void OnStateChanged (
    IUccSessionParticipant^ pEventSource, 
    UccSessionParticipantStateChangedEvent^ pEventData
)

void OnStateChanged (
    IUccSessionParticipant pEventSource, 
    UccSessionParticipantStateChangedEvent pEventData
)

function OnStateChanged (
    pEventSource : IUccSessionParticipant, 
    pEventData : UccSessionParticipantStateChangedEvent
)

Parameters

  • pEventSource
    A value of the IUccSessionParticipant* (IUccSessionParticipant, for a .NET application) type. This identifies the participant experiencing a change of the state.

Remarks

A local client receives this event when a remote session participant state changes. Local participant state changes do not raise this event locally. State changed events can be used by a local inviting user to determine whether the remote invited endpoint has receivied an OnIncomingSession event (UCCSES_CONNECTING), accepted an invitation (UCCSES_CONNECTED), rejected an invitation (UCCSES_DISCONNECTED), or terminated an on-going session (UCCSES_DISCONNECTED).

A client receives an OnStateChange event indicating a remote user has accepted or rejected an invitation after receiving the OnParticipantAdded event from the session participant collection.

Note

Session participants are added to a session participant collection before an invitation has been sent and responded to. OnParticipantAdded must not be used as an indication that the remote user has connected to a session

In a peer-to-peer session, an invitation rejection or remote user termination places the local client's session in an invalid state. The local client should use the state change event indicating rejection to close any opened UI elements dedicated to the session. Calling into methods or reading properties on an invalid session raises the API Error Message, UCC_E_INVALID_SESSION_STATE

Win32 COM/C++ Syntax

HRESULT OnStateChanged
(
   IUccSessionParticipant* pEventSource,
   IUccSessionParticipantStateChangedEvent* pEventData
);

Note

In a Win32 application, the return value of a method or property is always an HRESULT value indicating the status of the call to the interface member. Any result of the operation is returned as a parameter marked with the [out, retval] attribute. In contrast, in a .NET application the HRESULT value indicating an error condition is returned as a COM exception and the [out, retval] parameter becomes the return value. For the UCC API-defined HRESULT values, see Trace and Handle Errors in Unified Communications Client API .

Example

The following example handles the OnStateChanged event by building a string which indicates the status of an invitation to join a session. Note that the state of a rejected session invitation is UCC_SESSION_ENTITY_STATE UCCSES_DISCONNECTED and the state change reason is UCC_PARTICIPANT_STATE_CHANGE_REASON UCCPSCR_NORMAL.

/// <summary>
/// session participant state change event. Remote
/// session participants raise this event when state changes.
/// </summary>
/// <param name="pEventSource">participant source of state change</param>
/// <param name="pEventData">state changed related data</param>
void _IUccSessionParticipantEvents.OnStateChanged(
    IUccSessionParticipant pEventSource, 
    UccSessionParticipantStateChangedEvent pEventData)
{
    StringBuilder sb = new StringBuilder();
    if (pEventData.NewState == UCC_SESSION_ENTITY_STATE.UCCSES_CONNECTING)
    {
        if (pEventData.Reason == UCC_PARTICIPANT_STATE_CHANGE_REASON.UCCPSCR_TRYING)
        {
            sb.Append(pEventSource.Uri.User +
               " endpoint is Connecting " +);
            sb.Append(System.Environment.NewLine);
        }
    }
    else if (pEventData.NewState == UCC_SESSION_ENTITY_STATE.UCCSES_CONNECTED)
    {
        sb.Append("Remote participant is CONNECTED " + pEventSource.Uri.User);
        sb.Append(System.Environment.NewLine);
    }
    else if (pEventData.NewState == UCC_SESSION_ENTITY_STATE.UCCSES_DISCONNECTED)
    {
        switch (pEventSource.Session.Type)
        {
            case UCC_SESSION_TYPE.UCCST_INSTANT_MESSAGING:
                sb.Append("participant endpoint rejected IM " + pEventSource.Uri.User);
                break;
            case UCC_SESSION_TYPE.UCCST_AUDIO_VIDEO:
                sb.Append("participant endpoint rejected AV " + pEventSource.Uri.User);
                break;
            case UCC_SESSION_TYPE.UCCST_CONFERENCE:
                sb.Append("participant endpoint rejected conference invite " + pEventSource.Uri.User);
                break;
            case UCC_SESSION_TYPE.UCCST_APPLICATION:
                sb.Append("participant endpoint rejected App session " + pEventSource.Uri.User);
                break;
        }
    }
    Console.WriteLine(sb.ToString());
}

Thread Safety

All public static (Shared in Visual Basic) members of this type are thread-safe. Instance members are not guaranteed to be thread-safe.

Platforms

Development Platforms

Windows XP Professional with Service Pack 2 (SP2), Windows Server 2000 with Service Pack 4, Windows Server 2003, Windows Vista Ultimate Edition, Windows Vista Business Edition, Windows Vista Enterprise Edition

Target Platforms

See Also

Reference

_IUccSessionParticipantEvents Interface
_IUccSessionParticipantEvents Members
Microsoft.Office.Interop.UccApi Namespace