Handling Client/Server Messages

This document describes how to handle Microsoft® DirectPlay® messaging for client/server sessions.

Messaging within client/server sessions is handled in much the same way as it is for peer-to-peer sessions (see Handling DirectPlay Messaging, Handling Standard Peer-to-Peer Messages, and Peer-to-Peer Host Messages). The primary differences are that within client/server sessions:

• A client receives no messages that carry information about other players—and no group-related messages—because DirectPlay provides no way for a client to know about or to communicate with other clients.
• DirectPlay provides no host-migration messaging because the server must be the host. A client/server session cannot be hosted by a client.

This document focuses on the issues specific to client/server sessions.

• Client Startup Messages
• Server Startup Messages
• Client Messaging During Normal Game Play
• Server Messaging During Normal Game Play
• Client Session Termination Messages
• Server Session Termination Messages

Client Startup Messages

To select and join a session, you must locate the server that is the session host, connect to the server, and handle the messaging used to set up the session. As with peer-to-peer sessions, the server hosting the session can either arrange the session in advance or create a stand-alone session.

To locate and connect to the server, you will need to handle some—or all—of the following messages. The process is essentially identical to that used for a peer-to-peer session. Refer to Handling Standard Peer-to-Peer Messages for details on how to handle individual messages.

• DPN_MSGID_ENUM_HOSTS_RESPONSE

  To enumerate the available servers, call IDirectPlay8Client::EnumHosts, then handle DPN_MSGID_ENUM_HOSTS_RESPONSE messages from each server that responds to your enumeration request.

• DPN_MSGID_CONNECT_COMPLETE

  After you have located the server and called IDirectPlay8Client::Connect to attempt to connect to the session, you will normally need to handle a DPN_MSGID_CONNECT_COMPLETE message, containing the server's response.

Server Startup Messages

Since the server is, by definition, the host of a client/server session, the startup procedure and messaging is virtually identical to a peer-to-peer host. As with peer-to-peer sessions, the host server can either arrange the session in advance, or create a stand-alone session. You will need to handle some or all of the following messages while starting up your session. Refer to Peer-to-Peer Host Messages for details on how to handle the individual messages.

• DPN_MSGID_ENUM_HOSTS_QUERY

  If you are hosting a session, you will need to handle DPN_MSGID_ENUM_HOSTS_QUERY from potential players who are attempting to find a suitable host. Even if you are not hosting a session, you may still receive this message and must handle it.

• DPN_MSGID_INDICATE_CONNECT

  You receive this message when a player attempts to connect to your session. Return DPN_OK to accept connection attempt and allow the player into the session. Return any other value to reject the connection attempt.

• DPN_MSGID_CREATE_PLAYER

  You receive this message for each player that you accept into your session.

• DPN_MSGID_INDICATED_CONNECT_ABORTED

  You receive this message if a client drops the connection after you have processed the DPN_MSGID_INDICATE_CONNECT message but before you have processed DPN_MSGID_CREATE_PLAYER.

Client Messaging During Normal Game Play

The messages that you can receive during normal game play are basically a subset of the messages that are used by normal members of a peer-to-peer session. You will not receive messages that carry information about other players, and no group-related messages. You also will not receive a host-migration message, because the host cannot migrate.

You must process the following messages. Refer to Handling Standard Peer-to-Peer Messages for details on how to handle individual messages.

• DPN_MSGID_SEND_COMPLETE

  You can send messages to the server by calling IDirectPlay8Client::Send. As with peer-to-peer sessions, you receive a DPN_MSGID_SEND_COMPLETE message notifying you that the message has been sent.

• DPN_MSGID_RECEIVE

  When the server sends you data, it is delivered to your message handler with a DPN_MSGID_RECEIVE message.

• DPN_MSGID_APPLICATION_DESC, DPN_MSGID_SERVER_INFO

  Information structures are associated with the application and the server. If this information changes during a session, you will receive a corresponding message. To retrieve the updated application and server information structures, you must must call IDirectPlay8Client::GetApplicationDesc, IDirectPlay8Client::GetServerInfo.

Server Messaging During Normal Game Play

The server receives essentially the same messages as a peer-to-peer host during normal game play. You will need to process the following messages. Refer to Handling Standard Peer-to-Peer Messages for details on how to handle the individual messages.

• DPN_MSGID_CREATE_PLAYER and DPN_MSGID_DESTROY_PLAYER

  You receive DPN_MSGID_CREATE_PLAYER when a player enters a game, and a DPN_MSGID_DESTROY_PLAYER message when that player leaves the game.

• DPN_MSGID_CREATE_GROUP and DPN_MSGID_DESTROY_GROUP

  Groups are visible only to the server. You receive a DPN_MSGID_CREATE_GROUP message when you create a group, and DPN_MSGID_DESTROY_GROUP when you destroy the group.

• DPN_MSGID_ADD_PLAYER_TO_GROUP and DPN_MSGID_REMOVE_PLAYER_FROM_GROUP

  You receive a DPN_MSGID_ADD_PLAYER_TO_GROUP message each time you add a player to a group, and DPN_MSGID_REMOVE_PLAYER_FROM_GROUP each time you remove a player. When you destroy a group, you receive a DPN_MSGID_REMOVE_PLAYER_FROM_GROUP message for each group member.

• DPN_MSGID_SEND_COMPLETE

  When you send messages to a client by calling IDirectPlay8Server::SendTo, you receive a DPN_MSGID_SEND_COMPLETE message to notify you that the message was sent.

• DPN_MSGID_RECEIVE

  When a client sends you data, it is delivered to your message handler with a DPN_MSGID_RECEIVE message.

• DPN_MSGID_APPLICATION_DESC, DPN_MSGID_CLIENT_INFO, DPN_MSGID_GROUP_INFO

  Information structures are associated with the application, the server, and your groups. If this information changes during a session, you will receive the corresponding message. To retrieve the updated application, client, and group information structures, you must must call IDirectPlay8Client::GetApplicationDesc, IDirectPlay8Server::GetClientInfo, and IDirectPlay8Server::GetGroupInfo.

Client Session Termination Messages

A client/server session normally ends when the server calls IDirectPlay8Server::Close. A session can also end if the server is disconnected. When the session ends, each client receives the following messages. Refer to Handling Standard Peer-to-Peer Messages for details on how to handle the individual messages.

• DPN_MSGID_TERMINATE_SESSION

  This messages notifies you that the session is over.

Server Session Termination Messages

After you end the session, you will receive the following messages. Refer to Handling Standard Peer-to-Peer Messages.

• DPN_MSGID_DESTROY_PLAYER

  You will receive a DPN_MSGID_DESTROY_PLAYER message for each player in your session.

• DPN_MSGID_DESTROY_GROUP and DPN_MSGID_REMOVE_PLAYER_FROM_GROUP

  You will receive a DPN_MSGID_REMOVE_PLAYER_FROM_GROUP message for each player in each group, and a DPN_MSGID_DESTROY_GROUP message for each group.