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.
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.
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 broadcast 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 broadcast 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.
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.
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.
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.
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.