IUccSessionParticipantStateChangedEvent.Reason Property

  • 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.

Gets the reason for the state change.

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

Syntax

'Declaration
ReadOnly Property Reason As UCC_PARTICIPANT_STATE_CHANGE_REASON

UCC_PARTICIPANT_STATE_CHANGE_REASON Reason { get; }

property UCC_PARTICIPANT_STATE_CHANGE_REASON Reason {
    UCC_PARTICIPANT_STATE_CHANGE_REASON get ();
}

/** @property */
UCC_PARTICIPANT_STATE_CHANGE_REASON get_Reason ()

function get Reason () : UCC_PARTICIPANT_STATE_CHANGE_REASON

Property Value

A value of the UCC_PARTICIPANT_STATE_CHANGE_REASON* (UCC_PARTICIPANT_STATE_CHANGE_REASON, for a .NET application) type.

Remarks

Reason is most helpful in UCC_SESSION_TYPE.UCCST_AUDIO_VIDEO sessions such as a telephone session where a remote user can terminate a session for many legitimate reasons. Providing a Reason of UCC_PARTICIPANT_STATE_CHANGE_REASON. UCCPSCR_NORMAL for this type does not provide a calling client with the necessary information. For example, a local client should know if the remote user disconnected to transfer or forward a call rather than a simple hang up. Redirecting, forwarding, and transfering calls are considered normal disconnect activities but need to be specified to allow a local client to respond properly.

Peer-to-peer sessions such as instant messaging sessions can be terminated for only two normal reasons. Either the remote user rejected a session invitation or disconnected from an active session. In this case, a client can use OldState and NewState to determine which of the two disconnecti types happened.

Win32 COM/C++ Syntax

HRESULT get_Reason
(
   UCC_PARTICIPANT_STATE_CHANGE_REASON* penReason
);

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 session participant state changed events for an application class that wraps an instance of IUccSession where the Type is UCC_SESSION_TYPE.UCCST_AUDIO_VIDEO

/// <summary>
/// Handles telephone AV session and informs local
/// user of status of phone call along with disconnect reason
/// </summary>
/// <param name="pEventSource">remote user whose session state has changed</param>
/// <param name="pEventData">state change</param>
void _IUccSessionParticipantEvents.OnStateChanged(
    IUccSessionParticipant pEventSource, 
    UccSessionParticipantStateChangedEvent pEventData)
{
    if (pEventSource.Session.Type == UCC_SESSION_TYPE.UCCST_AUDIO_VIDEO 
        && pEventData.NewState == UCC_SESSION_ENTITY_STATE.UCCSES_DISCONNECTED)
    {
        if (pEventData.Reason == UCC_PARTICIPANT_STATE_CHANGE_REASON.UCCPSCR_FORWARD_DISCONNECT)
        {
            Console.WriteLine(pEventSource.Uri.User + " has forwarded your call");
        }
        else if (pEventData.Reason == UCC_PARTICIPANT_STATE_CHANGE_REASON.UCCPSCR_TRANSFER_ACTION)
        {
            Console.WriteLine (pEventSource.Uri.User + " has transfered your call" );
        }
        else if (pEventData.Reason == UCC_PARTICIPANT_STATE_CHANGE_REASON.UCCPSCR_RINGING)
        {
            Console.WriteLine (pEventSource.Uri.User + " is making another call");
            // session terminated. clean up session
        }
        else if (pEventData.Reason == UCC_PARTICIPANT_STATE_CHANGE_REASON.UCCPSCR_REMOTE_HANGUP_ACTION)
        {
            Console.WriteLine (pEventSource.Uri.User + " hung up the phone");
            // session terminated. clean up session
        }
        else if (pEventData.Reason == UCC_PARTICIPANT_STATE_CHANGE_REASON.UCCPSCR_ENDPOINT_NOT_EXIST)
        {
            Console.WriteLine (pEventSource.Uri.AddressOfRecord + " is not a valid telephone #");
            // session terminated. clean up session
        }
    }
}

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

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