Getting Started

[Previous] [Next]

Setting up your project to be able to use the DirectPlay API is easy. As with other DirectX APIs, to use DirectPlay, you must link the dxguid.lib library into your application or define the INITGUID symbol before all your other #include and #define statements. You'll also need to link your program to the dplayx.lib library.

Once you've integrated DirectPlay into your project, you're ready to write the code to add DirectPlay support to your Direct3D application. Just as the DirectX SDK provides the Direct3D Framework code to do some common Direct3D tasks, it also provides a file named dpconnect.cpp, which performs the basic tasks involved in getting into a DirectPlay session. RoadRage uses this code, and I recommend that you try it as well because the initial steps in using DirectPlay are nearly identical for all multiplayer programs.

You'll insert the first piece of code you need to add to the application into the WinMain function. The following code block (from roadrage.cpp) walks through the steps that WinMain takes and lists the other routines you need to create to enable multiplayer game play:

 INT WINAPI WinMain( HINSTANCE hInst, HINSTANCE,                     LPSTR strCmdLine, INT ) {     HRESULT hr;          // STEP 1         // Read information from the registry.     ReadDpInfoFromRegistry();     // STEP 2     g_hDPMessageEvent = CreateEvent( NULL, FALSE, FALSE, NULL );     // STEP 3     if( FAILED( hr = CoInitialize( NULL ) ) )         return FALSE;          // STEP 4     // Determine whether the application was launched from a     // lobby server.     hr = DPConnect_CheckForLobbyLaunch( &bLaunchedByLobby );     if( FAILED(hr) )     {         if( hr == DPERR_USERCANCEL )             return S_OK;         return hr;     }     // STEP 5     if( !bLaunchedByLobby )     {         // If not, the first step is to prompt the user about the          // network connection and ask which session he would like to          // join or whether he wants to create a new session.         nExitCode = DPConnect_StartDirectPlayConnect( hInst, FALSE );         // See the above EXITCODE #defines for what nExitCode         // could be.          if( nExitCode == EXITCODE_QUIT )         {             // The user canceled the multiplayer connect.             // The sample will now quit.             return E_ABORT;         }         if( nExitCode == EXITCODE_ERROR || g_pDP == NULL )         {             MessageBox( NULL, TEXT("Multiplayer connect failed. "                         "The sample will now quit."),                         TEXT("DirectPlay Sample"),                         MB_OK | MB_ICONERROR );                          return E_FAIL;         }     }          // STEP 6     // The next step is to start the game.     return d3dApp.Run();     if( SUCCEEDED( hr ) )     {         // Write information to the registry.         WriteRegisteryInfo();     }     // STEP 7     // Clean up DirectPlay.     if( g_pDP )     {         PrintMessage(NULL, "Cleanup DirectPlay FAILED", NULL,                       LOGFILE_ONLY);                  // STEP 8         g_pDP->DestroyPlayer( g_LocalPlayerDPID );         g_pDP->Close();         SAFE_DELETE_ARRAY( g_pDPLConnection );         SAFE_RELEASE( g_pDPLobby );         SAFE_RELEASE( g_pDP );     }     // STEP 9     CoUninitialize();     // STEP 10     CloseHandle( g_hDPlaySampleRegKey );     CloseHandle( g_hDPMessageEvent );      } 

In STEP 1, the code calls the ReadDpInfoFromRegistry routine. This function acquires the default player, session, and preferred service provider name from the registry.

STEP 2 of the WinMain code calls CreateEvent. The CreateEvent function creates an event object. This object will be used to detect when DirectPlay messages have arrived. The handle returned by this routine has EVENT_ALL_ACCESS access to the new event object and can be used in any function that requires a handle to an event object. You can have any thread for the calling process specify the event-object handle using a call to one of the wait functions. Each of the single-object wait functions will return when the state of the object specified is signaled. Each of the multiple-object wait functions can be requested to return when one or all of the objects specified are signaled. When the wait function returns, the waiting thread is released so that it can continue executing.

STEP 3 of the code for the WinMain function calls the CoInitialize function. This function initializes the COM library for use. You will typically pass NULL as the parameter to CoInitialize.

With the COM library initialized, you're now ready to call to the first DirectPlay-related routine (STEP 4 in the code for the WinMain function). The DPConnect_CheckForLobbyLaunch routine determines whether the DirectPlay session was launched by a lobby. If it was, the routine retrieves the information for starting and connecting an application and then calls DPConnect_DoLobbyLaunch to create the session or to join it.

If this is not a lobby launch, RoadRage calls the DPConnect_StartDirectPlayConnect routine (STEP 5) to prompt the user for the DirectPlay connection and the DirectPlay session he or she wants to join or create. The DPConnect_StartDirectPlayConnect routine first determines whether the user has already been through the connection process and has backtracked from the main game. If the user hasn't yet gone through the connection process, it uses the DPConnect_ConnectionsDlgProc routine to display the Multiplayer Connect dialog box, which is shown in Figure 15-1. If the user has already connected, it creates the Multiplayer Games dialog box (shown in Figure 15-2) by using the DPConnect_SessionsDlgProc routine.

Figure 15-1 The Multiplayer Connect dialog box

Figure 15-2 The Multiplayer Games dialog box