InstantMessagingCall

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.

An InstantMessagingCall object represents an SDP-based instant message (IM) session between a local participant and a remote participant. An InstantMessagingCall object cannot exist on its own; it must be associated with a Conversation object.

Because an IM call can be forked by Microsoft Office Communications Server, the receiving end should have logic to determine which endpoint should accept the IM call. Normally, this process is done by the most active endpoint as determined by the device state published by all of the endpoints. If there is only one endpoint, the IM can be autoaccepted immediately. Otherwise, the user should be given the opportunity to click the toast message so that the IM can be accepted on that endpoint. If the user does not click any of the toast messages within 10 seconds, the most active endpoint should accept the IM. This allows the message to flow so that the user can see the missed message when returning to the device.

When an IM call is established, it is customary to include a “toast” message, which is generally a text/plain message.

InstantMessagingCall State Transitions – Outbound Calls

The InstantMessagingCall state transitions for an outbound call are shown in the following illustration.

1. The transition from Idle to Establishing occurs when the application calls BeginEstablish() on the call.

2. The transition from Establishing to Establishing occurs when the application receives the first ringing notification from the remote side while the call is in the Establishing state.

3. The transition from Establishing to Terminating occurs when BeginEstablish fails, or when the application calls BeginTerminate on the call, or when the application calls BeginTerminate() on the conversation that contains this call.

4. The transition from Establishing to Established occurs when EndEstablish completes successfully.

5. The transition from Established to Transferring occurs when the application calls BeginTransfer() on the call.

6. The transition from Transferring to Established occurs when BeginTransfer is unsuccessful.

7. The transition from Established to Terminating occurs when the application calls BeginTerminate on the call, or when the remote side terminates the call, or when the application calls BeginTerminate on the conversation that contains this call.

8. The transition from Idle to Terminating occurs when the application calls BeginTerminate on the call, or when the application calls BeginTerminate on the conversation that contains this call.

9. The transition from Transferring to Terminating occurs when the application calls BeginTerminate on the call, or when the transfer operation is successful, or when the application calls BeginTerminate on the conversation that contains this call.

10. The transition from Terminating to Terminated occurs when EndTerminate() completes.

InstantMessagingCall State Transitions – Inbound Calls

The InstantMessagingCall state transitions for an inbound call are shown in the following illustration.

1. The transition from Incoming to Establishing occurs when the application calls BeginEstablish on the call.

2. The transition from Establishing to Terminating occurs when the call is not accepted, or when the application calls BeginTerminate, or when the application calls BeginTerminate on the conversation that contains this call.

3. The transition from Establishing to Established occurs when the call is accepted (when BeginAccept() returns successfully).

4. The transition from Established to Transferring occurs when the application calls BeginTransfer on the call.

5. The transition from Transferring to Established occurs when BeginTransfer is unsuccessful.

6. The transition from Established to Terminating occurs when the application calls BeginTerminate on the call, or when the remote side terminates the call, or when the application calls BeginTerminate on the conversation that contains this call.

7. The transition from Incoming to Terminating occurs when the application calls Decline, Forward, or BeginTerminate on the call, or when the application calls BeginTerminate on the conversation that contains this call, or when the remote side cancels its call request.

8. The transition from Transferring to Terminating occurs when the application calls BeginTerminate, or when the transfer operation completes successfully, or when the application calls BeginTerminate on the conversation that contains this call.

9. The transition from Terminating to Terminated occurs when EndTerminate completes.

InstantMessagingCall Constructors

The InstantMessagingCall class has the following constructor.

// Initializes the call based on the conversation and the signaling session.
public InstantMessagingCall(Conversation conversation);

InstantMessagingCall Properties

The following are the public properties on the InstantMessagingCall class.

// Gets whether this call should be accepted immediately upon receipt.
public bool IsImmediateAutoAcceptNeeded {get;}

// Gets the default media type for this call. For InstantMessagingCall, default mediaType is Message.  
public override string DefaultMediaType {get;}

/ Gets the list of supported Media names,
// which are acceptable m-lines in and SDP offer/answer. 
// For InstantMessagingCall, Message is the only supported MediaType.
public override IEnumerable<string> SupportedMediaTypes {get;}

// Gets the InstantMessagingFlow instance for this call.
public InstantMessagingFlow Flow {get;}

InstantMessagingCall Methods

The following are the public methods on the InstantMessagingCall class.

// Establishes an instant messaging call to the remote participant 
public IAsyncResult BeginEstablish(
    string destinationUri,
    ToastMessage toastMessage,
    CallEstablishOptions options,
    AsyncCallback userCallback,
    object state);

// Asynchronously establishes the session. 
public IAsyncResult BeginEstablish(
    ToastMessage toastMessage,
    CallEstablishOptions options, 
    AsyncCallback userCallback, 
    object state)

InstantMessagingCall Events

The following are the public events on the InstantMessagingCall class.

// Raised when the call must be autoaccepted by the application.
// The implementation of the handler for this event should use a lock object 
// to eliminate a possible race condition between this event being 
// raised on the application's event thread and the application calling
// BeginAccept(), Decline(), and other methods on the application's main thread
// or on any other thread.
public event EventHandler<EventArgs> AutoAcceptNeeded;

// Raised when the instant messaging flow is created.
public event EventHandler<InstantMessagingFlowCreatedEventArgs> InstantMessagingFlowConfigurationRequested;

Important

An event handler for the InstantMessagingFlowConfigurationRequested event is called synchronously. A deadlock in application code can prevent the application from terminating the call or shutting down the platform.