Platform SDK: DirectX

Using Player Messages

[C++]

Player messages can be sent by using IDirectPlay4::Send or IDirectPlay4::SendEx. Messages sent by using SendEx can be assigned a priority. Higher-priority messages are sent first. Priority does not affect the order in which messages are received.

The organization of data within a player message is determined solely by the application. Conventionally, the first element is an application-defined message identifier.

Typically, the C++ application will use IDirectPlay4::Receive to obtain the message buffer, cast it to DPMSG_GENERIC, and check to see whether the message is from DPID_SYSMSG. If it is not, the application casts the data to an application-defined generic type, checks the message type within this structure, then casts once again to a application-defined type appropriate for the message. For an example, see the Duel sample, in particular the ReceiveMessages and DoApplicationMessage functions.

[Visual Basic]

Player messages can be sent by using DirectPlay4.Send or DirectPlay4.SendEx. Messages sent by SendEx can be assigned a priority. Higher-priority messages are sent first. Priority does not affect the order in which messages are received.

The organization of data within a player message is determined solely by the application. Conventionally, the first element is an application-defined message identifier.

Message data is represented by DirectPlayMessage object. The sending application obtains this object by using the DirectPlay4.CreateMessage method.

There are two ways to construct player message data. The first way is to write the data one element at a time, using the various write methods of DirectPlayMessage. As each element is written, an internal write pointer is advanced. The second way is to pass a user-defined type to DirectPlayMessage.SetMessageData. Most applications should use the first technique, because SetMessageData requires you to know the exact size of the data being passed to the method, which is not always straightforward.

Note  You cannot mix these two ways of setting the message data. For example, you cannot use DirectPlayMessage.WriteLong to write the message type, then SetMessageData to write additional data. SetMessageData sets the entire contents of the message.

Data is retrieved from the message by using the corresponding read methods of DirectPlayMessage, or by using DirectPlayMessage.GetMessageData. When using the read methods, the application must read the elements in the same order as they were written. GetMessageData should be used only if the data was set by SetMessageData.