InstantMessagingFlow

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 InstantMessagingFlow instance represents an instant messaging connection with a single remote participant.

InstantMessagingFlow Constructors

The InstantMessagingFlow class has no public constructors.

InstantMessagingFlow Properties

The following are the public properties on the InstantMessagingFlow class.

// Gets or sets the value (in seconds) for a composing time-out. 
public int ComposingTimeoutValue {get; set;}

// Gets or sets the local composing state.
public ComposingState LocalComposingState {get; set;}

The ComposingTimeoutValue property is used to control the time-out value that reverts the local composing state to Idle. If an application sets LocalComposingState to Composing, it is automatically reverted to Idle if the application does not set LocalComposingState to Composing again within this idle time-out. Several seconds can elapse after the time-out occurs for the state to change to Idle.

Getting or setting LocalComposingState will result in a "Typing" or "Idle" notification to be sent to remote participants. Setting the state automatically sends Typing/Idle notifications to remote participants. After being set to Typing, automatic refresh of the Typing state occurs every five seconds until a message is sent or the state is set explicitly to Idle. If a message is sent, it is not necessary to set the state to Idle because the composing state will be automatically reset to Idle. A RemoteComposingStateChanged event will not be raised when this property is set.

InstantMessagingFlow Methods

The following are the public methods on the InstantMessagingFlow class.

// Optionally overwrites settings of the flow.
// Can only be called by application from within an InstantMessagingFlowConfigurationRequested event handler.
public void Initialize(InstantMessagingFlowTemplate template);

// Sends a mesage in the conversation. It is delivered to all remote participants currently 
// capable of receiving instant messages.
public IAsyncResult BeginSendMessage(
    ContentType contentType,
    byte[] body,
    AsyncCallback userCallback,
    object state);

// Sends a text message in the conversation. It is delivered to all remote participants currently 
// capable of receiving instant messages.
public IAsyncResult BeginSendMessage(
    string textBody,
    AsyncCallback userCallback,
    object state);

// Sends a success delivery notification for a received message
// delivering the received message to a remote entity.
public IAsyncResult BeginSendSuccessDeliveryNotification(
    InstantMessageId messageId,
    AsyncCallback userCallback,
    object state);

// Sends a failure delivery notification for a received message.
// This is normally called only by applications that do not
// directly consume messages but serve as proxies for 
// delivering the received message to a remote entity.
public IAsyncResult BeginSendFailureDeliveryNotification(
    InstantMessageId messageId,
    int responseCode,
    AsyncCallback userCallback,
    object state);

// Gets the results of the Send operation.
public InstantMessageId EndSendMessage(IAsyncResult result);

// Gets the results of sending a delivery notification.
public void EndSendSuccessDeliveryNotification(IAsyncResult result);

// Gets the results of sending a delivery notification.
public void EndSendFailureDeliveryNotification(IAsyncResult result)

An application uses the Initialize() method to configure an InstantMessagingFlow instance as ConsumedLocally (the default) or as ProxiedToRemoteEntity, values of the InstantMessageConsumptionMode enumeration. If the flow is configured for ProxiedToRemoteEntity, an application must register for the MessageReceived event and must send message delivery notifications using BeginSendSuccessDeliveryNotification() or BeginSendFailureDeliveryNotification() on each received message. Failure to send these delivery notification messages can result in a memory leak.

InstantMessagingFlow Events

The following are the public events on the InstantMessagingFlow class.

// Raised when the typing state for a remote participant changes.
public event EventHandler<ComposingStateChangedEventArgs> RemoteComposingStateChanged;

// Raised when a message is received.
public event EventHandler<InstantMessageReceivedEventArgs> MessageReceived;

// Raised when a message delivery notification is received.
public event EventHandler<DeliveryNotificationReceivedEventArgs> DeliveryNotificationReceived;