//----------------------------------------------------------------------------- // // Sample Name: SimplePeer Sample // // Copyright (c) 1999-2001 Microsoft Corporation. All rights reserved. // //----------------------------------------------------------------------------- Description =========== SimplePeer illustrates how to network other players using DirectPlay. After joining or creating a session, a simple game begins immediately. Other players may join the game in progress at any time. The game itself is very simple, passing a single DirectPlay message to all connected players when the "Wave To other players" button is pressed. Path ==== Source: DXSDK\Samples\Multimedia\DirectPlay\SimplePeer Executable: DXSDK\Samples\Multimedia\DirectPlay\Bin User's Guide ============ Enter the player's name, and choose a connection type. You can either choose "Wait for Lobby Connection" to wait for a lobby connection or choose a service provider. Use the Multiplayer Games dialog to either search for an active game to join, or to start a new game. After game has been joined or created, the game begins immediately. Other players may join the game at any time. If host migration is on, then the host player may also leave at anytime since DirectPlay will automatically migrate the host player. Programming Notes ================= This sample was intended to be very simple, showing the basics of using the DirectPlay API. Here's a quick run through the various steps of SimplePeer: * Initialize DirectPlay. See InitDirectPlay() 1. Init COM with CoInitialize() 2. Create a IDirectPlay8Peer with CoCreateInstance() 3. Create a IDirectPlay8LobbiedApplication with CoCreateInstance() 4. Call IDirectPlay8Peer::Initialize to tell the interface about our message handler 5. Call IDirectPlay8LobbiedApplication::Initialize to tell the interface about our message handler 6. Check if IDirectPlay8LobbiedApplication::Initialize returned a non-NULL lobby client connection handle. If it did, then we know we were launched by a lobby client, so it may (but not necessarily) also have sent us connection settings we can use to either host or join a game. * Either host or connect to a DirectPlay game. See WinMain(). If we were launched from a lobby client, then we may have connection settings that we can use either host or join a game. If not, then we'll need to prompt the user to determine how to connect. - Host/connect using the connection settings obtained from lobby client. See CNetConnectWizard::ConnectUsingLobbySettings(). 1. Call IDirectPlay8LobbiedApplication::GetConnectionSettings() to get the connection settings from a lobby client. Note: the connection settings are also present in the DPL_MSGID_CONNECT message, but if we use those we would need to make a deep copy of the data since we don't own pConnectMsg->pdplConnectionSettings. 2. Check dwFlags for DPLCONNECTSETTINGS_HOST. This will tell us if we are hosting or not. 3. Call IDirectPlay8Peer::SetPeerInfo so other players know our player name. This isn't necessary, but SetPeerInfo is an easy way to post data such as the player name so that all of the other clients can access it. 4. If hosting call IDirectPlay8Peer::Host(), otherwise call IDirectPlay8Peer::Connect(). 5. Cleanup DPL_CONNECTION_SETTINGS. - Host/connect by prompting user for connect settings. See CNetConnectWizard::DoConnectWizard(): This sample calls upon the helper class CNetConnectWizard for this task. It uses dialog boxes to query the user what to do, however most games will want to use a fanicer graphics layer such as Direct3D. Here's what CNetConnectWizard does after calling CNetConnectWizard::DoConnectWizard(): 1. CNetConnectWizard enumerates and displays DirectPlay's service providers with IDirectPlay8Peer::EnumServiceProviders. See CNetConnectWizard::ConnectionsDlgFillListBox() 2. When a service provider has been chosen via the UI... See CNetConnectWizard::ConnectionsDlgOnOK(). - If the user chooses "Wait for Lobby Connection", then it calls IDirectPlay8LobbiedApplication::SetAppAvailable. This tells the lobby client that our app is available for connection, so it doesn't need to launch a new instance of the application. Then pops a dialog box that has timer. The timer checks to see if m_hLobbyConnectionEvent is signaled (it becomes signaled when a DPL_MSGID_CONNECT is received). When it is, then we can call ConnectUsingLobbySettings(). - If the user chooses a SP, it creates a DirectPlay host and device addresses calling CoCreateInstance. Then it calls IDirectPlay8Address::SetSP to pass SP's guid into the two IDirectPlay8Address's. 3. Call IDirectPlay8Peer::EnumHosts to enum all the games in progress on that SP. See CNetConnectWizard::SessionsDlgEnumHosts(). We pass in a device address to specify which device to use, and a host address to specify the address of the host. For TCP/IP, the host address may contain just the SP to search the local subnet, or it may have the SP and a have an IP address to search. If too little information is supplied and the flag DPNENUMHOSTS_OKTOQUERYFORADDRESSING is passed then DirectPlay will popup a dialog box to prompt the user for any extra needed information. More complex games would probably want to not pass this flag, and supply the needed information so as to avoid unnecessary dialog boxes. 4. Process DPN_MSGID_ENUM_HOSTS_RESPONSE messages that come in on the callback. Upon receiving these messages, put them in a data structure. You will need to deep copy the DPN_APPLICATION_DESC, and the pAddressSender. Also be careful to not add duplicates to the list. You will need to manage this structure yourself including expiring old enumerations. See CNetConnectWizard::SessionsDlgNoteEnumResponse() and CNetConnectWizard::SessionsDlgExpireOldHostEnums(). 5. The wizard displays the list of current sessions (built with step #4) and allows the user to either choose a game from the list or create a new one. - If joining a game from the list, it calls IDirectPlay8Peer::SetPeerInfo() to set the player's name, and then calls IDirectPlay8Peer::Connect() passing in the DPN_APPLICATION_DESC, as well as pAddressSender from the selected game. This will async complete, so wait for DPN_MSGID_CONNECT_COMPLETE, and read the connect result from msg. See CNetConnectWizard::SessionsDlgJoinGame(), and CNetConnectWizard::SessionsDlgProc()'s WM_TIMER. - If creating a new game, it calls IDirectPlay8Peer::SetPeerInfo() to set the player's name, and then calls IDirectPlay8Peer::Host() passing in a DPN_APPLICATION_DESC filled with various info such as the game name, max players, and the app guid. It also passes in the IDirectPlay8Address that describes which SP to use. See CNetConnectWizard::SessionsDlgCreateGame(). After either prompting the user with dialog boxes or connecting using settings from a lobby connection, the IDirectPlay8Peer interface will be connected to a DirectPlay session by either hosting a new one or join an existing one. * Handle DirectPlay system messages. See DirectPlayMessageHandler() - Upon DPN_MSGID_CREATE_PLAYER it calls IDirectPlay8Peer::GetPeerInfo to retrieve the player's name. It then creates a app specific structure for the player, APP_PLAYER_INFO. It passes the pointer to this structure to DirectPlay in the pvPlayerContext field. This prompts DirectPlay to return that pointer whenever a message from or about that player is received, so instead of traversing a data structure to find the player's structure the pvPlayerContext will be pointing directly to the correct structure. Note that since player can be deleted at any time, we need to use ref counting to make sure this player context struct isn't deleted while we are still using it. - Upon DPN_MSGID_DELETE_PLAYER it gets the player's structure from pDeletePlayerMsg->pvPlayerContext and then decrements the ref count for the structure. If the struct's ref count is zero, the struct is deleted. - Upon DPN_MSGID_CONNECTION_TERMINATED it shuts down the dialog. - Upon DPN_MSGID_RECEIVE it casts pReceiveMsg->pReceiveData into a generic app defined structure that helps it figure out what structure is really contained in pReceiveMsg->pReceiveData. For this simple example, if the type is GAME_MSGID_WAVE it just executes an simple action. * Send a DirectPlay packet. See WaveToAllPlayers(). - If the user presses, "Wave to other players!" button then it calls IDirectPlay8Peer::SendTo() with DPNID_ALL_PLAYERS_GROUP and a data message that is simply a DWORD containing GAME_MSGID_WAVE. * Clean up. See bottom of WinMain() 1. Delete the connection wizard class. 2. Call IDirectPlay8LobbiedApplication::Close() 3. Release the IDirectPlay8LobbiedApplication 4. Call IDirectPlay8Peer::Close() 5. Release the IDirectPlay8Peer 1. Free any app-specific resources 6. Call CoUninitialize().