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

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 InstantMessagingCallstate transitions for an outbound call are shown in the following illustration.

  1. The transition from Idleto Establishingoccurs when the application calls BeginEstablishon the call.

  2. The transition from Establishingto Establishingoccurs when the application receives the first ringing notification from the remote side while the call is in the Establishingstate.

  3. The transition from Establishingto Terminatingoccurs when BeginEstablishfails, or when the application calls BeginTerminateon the call, or when the application calls BeginTerminateon the conversation that contains this call.

  4. The transition from Establishingto Establishedoccurs when EndEstablishcompletes successfully.

  5. The transition from Establishedto Transferringoccurs when the application calls BeginTransferon the call.

  6. The transition from Transferringto Establishedoccurs when BeginTransferis unsuccessful.

  7. The transition from Establishedto Terminatingoccurs when the application calls BeginTerminateon the call, or when the remote side terminates the call, or when the application calls BeginTerminateon the conversation that contains this call.

  8. The transition from Idleto Terminatingoccurs when the application calls BeginTerminateon the call, or when the application calls BeginTerminateon the conversation that contains this call.

  9. The transition from Transferringto Terminatingoccurs when the application calls BeginTerminateon the call, or when the transfer operation is successful, or when the application calls BeginTerminateon the conversation that contains this call.

  10. The transition from Terminatingto Terminatedoccurs when EndTerminatecompletes.

InstantMessagingCall State Transitions – Inbound Calls

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

  1. The transition from Incomingto Establishingoccurs when the application calls BeginEstablishon the call.

  2. The transition from Establishingto Terminatingoccurs when the call is not accepted, or when the application calls BeginTerminate, or when the application calls BeginTerminateon the conversation that contains this call.

  3. The transition from Establishingto Establishedoccurs when the call is accepted (when BeginAcceptreturns successfully).

  4. The transition from Establishedto Transferringoccurs when the application calls BeginTransferon the call.

  5. The transition from Transferringto Establishedoccurs when BeginTransferis unsuccessful.

  6. The transition from Establishedto Terminatingoccurs when the application calls BeginTerminateon the call, or when the remote side terminates the call, or when the application calls BeginTerminateon the conversation that contains this call.

  7. The transition from Incomingto Terminatingoccurs when the application calls Decline, Forward, or BeginTerminateon the call, or when the application calls BeginTerminateon the conversation that contains this call, or when the remote side cancels its call request.

  8. The transition from Transferringto Terminatingoccurs when the application calls BeginTerminate, or when the transfer operation completes successfully, or when the application calls BeginTerminateon the conversation that contains this call.

  9. The transition from Terminatingto Terminatedoccurs when EndTerminatecompletes.

InstantMessagingCall Constructors

The InstantMessagingCallclass has the following constructor.

Copy Code 
// 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 InstantMessagingCallclass.

Copy Code 
// 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 InstantMessagingCallclass.

Copy Code 
// 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 InstantMessagingCallclass.

Copy Code 
// 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 InstantMessagingFlowConfigurationRequestedevent is called synchronously. A deadlock in application code can prevent the application from terminating the call or shutting down the platform.