Asynchronous Messaging

The ability to send messages asynchronously frees the application's communication code from blocking while each message is transmitted. It offloads management of outgoing messages to DirectPlay while still giving the application the ability to monitor the message queue and to cancel messages.

The asynchronous messaging feature is only available if the session is using the DirectPlay protocol or if it is supported by the service provider. For example, the TCP/IP service provider supports asynchronous messages only when the computer is using Windows Sockets 2.0 or later.

[C++]

If the DirectPlay protocol is not being used, it is important to use the IDirectPlay4::GetCaps method to check the DPCAPS_ASYNCSUPPORTED flag after the session has been established, to determine whether asynchronous messages are supported.

To send an asynchronous message, you must use the IDirectPlay4::SendEx method with the DPSEND_ASYNC flag set in the dwFlags parameter. SendEx will return immediately. Later, the application will receive a DPMSG_SENDCOMPLETE system message with the status result for the sent message. You can disable the notification by setting the DPSEND_NOSENDCOMPLETEMSG flag when the message is sent. The application can track individual messages using the dwMsgID parameter returned by SendEx. This ID can be used to cancel individual messages or to match completion notification messages.

SendEx can be used to assign a timeout value and a priority to a message in sessions that support these properties. You can also cancel messages in the send queue by using the IDirectPlay4::CancelMessage or IDirectPlay4::CancelPriority method. Timeout, priority, and cancellation functionality require the DirectPlay protocol or service provider support, as determined by the IDirectPlay4::GetCaps method.

[Visual Basic]

If the DirectPlay protocol is not being used, after the session has been established it is important to use the DirectPlay4.GetCaps method to check for the DPCAPS_ASYNCSUPPORTED flag, to determine whether asynchronous messages are supported.

To send an asynchronous message, you must use the DirectPlay4.SendEx method with the DPSEND_ASYNC flag set in the flags parameter. SendEx will return immediately. Later, the application will receive a DPMSG_SENDCOMPLETE system message with the status result for the sent message. You can disable the notification by setting the DPSEND_NOSENDCOMPLETEMSG flag when the message is sent. The application can track individual messages using the ID returned by SendEx. This ID can be used to cancel individual messages or to match completion notification messages.

SendEx can be used to assign a timeout value and a priority to a message in sessions that support these properties. You can also cancel messages in the send queue by using the DirectPlay4.CancelMessage or DirectPlay4.CancelPriority method. Timeout, priority, and cancellation functionality require the DirectPlay protocol or service provider support, as determined by the DirectPlay4.GetCaps method.

You should exercise great care when mixing asynchronous and synchronous messages. A synchronous message will be sent after any asynchronous messages ahead of it in the queue and will then block until completed.

If supported, timeouts and priorities can be used with synchronous messages. Message tracking by ID and cancellation do not apply to synchronous messages.