Tutorial 5: Sending Messages to Other Players

Once you have connected to a session, you can begin game play by sending messages to the other peers in the session for whom you have received a DPN_MSGID_CREATE_PLAYER message. This tutorial extends Tutorial 4 and discusses how to send messages. The complete sample code for this tutorial is included with the Microsoft® DirectX® software development kit (SDK) and can be found at (SDK root)\Samples\Multimedia\DirectPlay\Tutorials\Tut05_Send.

• User's Guide
• Sending a Message
• Receiving a Message
• Terminating the Application

Refer to the preceding tutorials for a discussion of the initial steps in the process:

• Tutorial 1: Creating a DirectPlay Object and Enumerating Service Providers
• Tutorial 2: Hosting a Session
• Tutorial 3: Enumerating Hosted Sessions
• Tutorial 4: Connecting to a Session

Note  The error handling code for the examples in this document has been deleted for clarity. See the tutorial sample for a complete version of the code.

User's Guide

When you run this tutorial sample, a Microsoft® MS-DOS® command window opens and you have the choice to either Host or Connect.

If you choose Host, do the following:

1. Enter a session name. A message prints on the screen telling you that you are "currently hosting."
2. Choose to Send or Exit. If you choose Send, you will be prompted to enter a text string. If you choose Exit, the session ends.

If you choose Connect, do the following:

1. Enter an IP address. If a session is found at that address, you will be connected. If the address does not exist or if no session is found at the address, the application prints error messages.
2. Once connected, choose Send or Exit. If you choose Send, you are prompted to enter a text string. If you choose Exit, the session ends.

You can run this sample twice—once to host a session and once to connect. When connecting, enter your computer's IP address. Once connected, you can send messages between the host and the client application.

Sending a Message

Once the session is initiated, the peers manage the progress of the game by sending a stream of messages to each other. The content of the message is up to the application but typically includes such information as game state updates or player-to-player communication. Sending a message is straightforward. Select the player to which you wish to send the message, package your data in a buffer, and pass the data to the target player by calling IDirectPlay8Peer::SendTo. You also have the option of using a single IDirectPlay8Peer::SendTo call to broadcast a message to all players.

The following excerpt from the tutorial sample illustrates how to send a message to every player in the session.

    DPN_BUFFER_DESC dpnBuffer;
    WCHAR           wszData[256];


    dpnBuffer.pBufferData = (BYTE*) wszData;
    dpnBuffer.dwBufferSize = 2 * (wcslen(wszData) + 1);

    hr = g_pDP->SendTo( DPNID_ALL_PLAYERS_GROUP, // dpnid
                                    &dpnBuffer,  // pBufferDesc
                                    1,           // cBufferDesc
                                    0,           // dwTimeOut
                                    NULL,        // pvAsyncContext
                                    NULL,        // pvAsyncHandle
                                    DPNSEND_SYNC |
                                    DPNSEND_NOLOOPBACK );    // dwFlags

Receiving a Message

When another player sends you a message, your DirectPlay message handler receives a DPN_MSGID_RECEIVE message containing the data buffer.

The following excerpt from the tutorial sample illustrates a simple message handler for received messages.

//In the receiving player's message handler:

HRESULT WINAPI DirectPlayMessageHandler(void *pvContext, DWORD dwMsgId, void *pvMessage)
{
switch( dwMsgId )
{
case DPN_MSGID_RECEIVE:
{
	 case DPN_MSGID_RECEIVE:
        {
            PDPNMSG_RECEIVE     pMsg;

            pMsg = (PDPNMSG_RECEIVE) pMsgBuffer;
			//process message
			.
			.
			.
            break;
        }

}
}
return(DPN_OK);
}

Terminating the Application

If a DirectPlay peer object was successfully initialized, you should first close the object by calling IDirectPlay8Peer::Close then release all active objects and terminate the application. See Tutorial 1 for further discussion.