Handling DirectPlay Messaging
This set of documents provides information about how to handle Microsoft® DirectPlay® messaging. This particular document introduces general considerations for all DirectPlay messaging. Details for messaging with particular session types and roles can be found in the following documents.
General Messaging Considerations
The following general considerations apply to all DirectPlay messaging.
- You will frequently receive a message following a method call. For instance, when you ask to join a host's session by calling IDirectPlay8Peer::Connect, you receive a DPN_MSGID_CONNECT_COMPLETE message that provides the result of your request. Two events thus follow your method call: The method returns and you receive a message. The order in which these events occur depend on whether you call the method synchronously or asynchronously, and may not be predictable.
- By default, DirectPlay performs most operations asynchronously. To use synchronous operations, you typically need to set an XXX_SYNC flag in the method's dwFlags parameter. As long as an asynchronous method call does not fail for reasons such as parameter validation, it immediately returns DPNSUCCESS_PENDING. DirectPlay notifies you that the operation is complete by sending you a message such as DPN_MSGID_SEND_COMPLETE or DPN_MSGID_ASYNC_OP_COMPLETE. These messages can arrive before or after the method returns.
- DirectPlay signals the end of most asynchronous operations by sending you a completion message, usually DPN_MSGID_ASYNC_OP_COMPLETE. Two exceptions to this rule occur: Send/SendTo, and Connect operations. The end of those operations is signaled by DPN_MSGID_SEND_COMPLETE and DPN_MSGID_CONNECT_COMPLETE, respectively. Synchronous operations do not return until the operation is complete. For that reason, most do not generate a completion message. The exception is synchronous connection operations that may generate a DPN_MSGID_CONNECT_COMPLETE message. See Handling Standard Peer-to-Peer Messages for further discussion.
- You can force many asynchronous operations to terminate at any time by calling IDirectPlay8Peer::CancelAsyncOperation. Group operations cannot be terminated.
- By default, DirectPlay serializes the messages associated with each player. As long as the DPNSEND_NONSEQUENTIAL flag is not set, you receive messages from a particular player in the order in which they are sent. This is true for messages sent to you directly, and to you as a member of a group. When a player sends a message to your group, the message appears to you as coming from the player, not from the group. You receive all messages from a particular player on one thread at a time, regardless of whether DPNSEND_NONSEQUENTIAL is set. You will not receive messages from a player before you have processed the corresponding DPN_MSGID_CREATE_PLAYER message, or after you have processed the corresponding DPN_MSGID_DESTROY_PLAYER message.
- Group messages are also serialized. For instance, you will not receive a DPN_MSGID_ADD_PLAYER_TO_GROUP message until you have processed DPN_MSGID_CREATE_GROUP. You will not receive any group-related messages after you have processed the corresponding DPN_MSGID_DESTROY_GROUP message.
- Create and destroy messages are always paired. For instance, every DPN_MSGID_CREATE_GROUP message will be matched by a corresponding DPN_MSGID_DESTROY_GROUP message.
- You should spend as little time in your message handler as possible. Executing a long blocking operation while handling a DirectPlay message may seriously impede network performance. For example, when you send data to another player in a peer-to-peer session by calling IDirectPlay8Peer::SendTo within your message handler, do so asynchronously. This allows you to return from the message handler as soon as the method returns. You can process the result of the operation when the DPN_MSGID_SEND_COMPLETE message arrives.