| ?/TD> |
| Microsoft DirectX 9.0 |
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:
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.
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.
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.
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.
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.
You receive this message for each player that you accept into your session.
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.
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.
When the server sends you data, it is delivered to your message handler with a DPN_MSGID_RECEIVE message.
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.
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.
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.
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.
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.
When a client sends you data, it is delivered to your message handler with a DPN_MSGID_RECEIVE message.
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.
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.
You will receive a DPN_MSGID_DESTROY_PLAYER message for each player in your session.
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.