Handle an InstantMessagingFlow

Instances of the InstantMessagingFlow class represent an instant message (IM) media flow. The InstantMessagingFlow class is derived from the MediaFlow base class and provides methods to send and receive IM messages, delivery notifications, and typing notifications.

InstantMessagingFlowTemplate

The InstantMessagingFlow class has no public constructors, but instead relies on settings in an InstantMessagingFlowTemplate instance to initialize or modify an InstantMessagingFlow instance. After an InstantMessagingFlowTemplate instance has been created, its settings can be copied to an InstantMessagingFlow instance by a call to the Initialize(InstantMessagingFlowTemplate) method on the InstantMessagingFlow class. This initialization must occur within the body of a handler for the InstantMessagingFlowConfigurationRequested event.

The InstantMessagingSettings property provides access to global configuration settings for instant message (IM) flows using an InstantMessagingFlowTemplate object.

Applications specify their consumption mode using the InstantMessageConsumptionMode enumeration. The following table lists the enumeration values for this type.

Enumeration value	Description
ConsumedLocally	The message is consumed locally as soon as it is delivered. This is the default consumption mode.
ProxiedToRemoteEntity	The message is proxied to a remote entity. The success or failure of the delivery is known only later.

If the application hosts a remote client, there can be a delay when the client sends the typing indications to a backend server. For this reason, the default value of three seconds for the idle time-out period may not be long enough. The application can set the idle time-out period to a larger value using flow settings.

The SupportedFormats property lists the content types that the application supports for consuming messages received in the flow.

The internal IM media provider supports the sending and receiving of delivery notification messages that are sent by applications that do not directly consume messages, but serve as proxies for delivering the received messages to remote entities. A user-created Web server application is an example of such an application. If an application configures the flow as ProxiedToRemoteEntity, the application must register for the MessageReceived event on the flow, and must send message delivery notifications with the BeginSendSuccessDeliveryNotification(InstantMessageId, AsyncCallback, Object) or BeginSendFailureDeliveryNotification(InstantMessageId, Int32, AsyncCallback, Object) method. Because the messages are serialized, there might be an impact on application performance.

InstantMessagingFlow exposes the DeliveryNotificationReceived event, which is raised when an incoming delivery notification message is received. InstantMessagingFlow also exposes two methods to send delivery notifications to the message sender: BeginSendFailureDeliveryNotification and BeginSendSuccessDeliveryNotification.

Composing Notifications

A composing notification indicates whether a participant is actively composing a message. A composing notification is an INFO message that is sent to the remote endpoint when the local participant is typing.

The InstantMessagingFlow class exposes a LocalComposingState property to represent the local composing state. Setting the LocalComposingState property to Composing causes the platform to automatically send composing notifications to the remote participant every five seconds. The platform stops sending composing notifications if the application explicitly sets the value of LocalComposingState to Idle. When the user sends the instant message, the platform stops sending composing notifications and automatically sets the value of LocalComposingState to Idle.

The InstantMessageFlow class raises a RemoteComposingStateChanged event to represent the composing state of the remote participant in an IM conversation. The event is raised only when the remote participant sends a composing notification; setting the LocalComposingState property for an endpoint does not raise the RemoteComposingStateChanged event on the remote participant. For this reason, and because composing notifications are sent every five seconds, if the RemoteComposingStateChanged event is not raised within six seconds, the application should assume that the remote participant is idle.

Creating and Manipulating an IM Media Flow

The following code demonstrates creating an IM media flow, sending IM messages on the flow, and sending composing notifications.

// Must be done before Establish is called.
imCall.InstantMessagingFlowConfigurationRequested += IMCall_InstantMessagingFlowConfigurationRequested; 

private void IMCall_InstantMessagingFlowConfigurationRequested (object sender, InstantMessagingFlowConfigurationRequestedEventArgs e)
{
  InstantMessagingFlow imFlow = e.Flow;
  imFlow.StateChanged += IMFlow_StateChanged;
  imFlow.RemoteComposingStateChanged += IMFlow_RemoteComposingStateChanged;
}

private void IMCall_ RemoteComposingStateChanged (object sender, ComposingStateChangedEventArgs e)
{
  // e.Participant indicates the remote participant.
  // e.ComposingState indicates the composing state of this remote participant.
}

private void IMCall_StateChanged(object sender, StateChangedEventArgs<MediaFlowState> e)
{
  // Idle, Active, Terminated are the states. 
  // If Active, the flow is ready to send and receive media.
}

// Send a message on the flow.
myFlow.BeginSendMessage("hi", IMFlow_SendMessageCompleted, myFlow);

// Sending a composing notification.
myFlow.LocalComposingState = ComposingState.Composing;

// Setting the composing state to Idle cancels the autmomatic sending of composing notifications.
// Sending the instant message also cancels the automatic sending of composing notifications.
myFlow.LocalComposingState = ComposingState.Idle;