| Microsoft DirectX 8.1 (C++) |
This tutorial extends Tutorial 1, and discusses how to create an address object and advertise your application as a session host. Refer to Tutorial 1: Creating a DirectPlay Object and Enumerating Service Providers for the initial steps in this tutorial. The complete sample code for this tutorial is included with the Microsoft® DirectX® software development kit (SDK) and can be found at (SDK root)\Samples\Multimedia\DirectPlay\Tutorials\Tut02_Host.
Note The error handling code for the examples in this document has been deleted for clarity. See the tutorial sample for a complete version of the code.
When you run this tutorial sample, a Microsoft® MS-DOS® command window opens and a message prints on the screen telling you that you are "currently hosting." To stop hosting, press any key.
The first step in hosting a session is to create a DirectPlay address object (CLSID_DirectPlay8Address) that contains the address of of the device that you host the session on. At a minimum, each address object must contain a service provider. The simplest way to specify a service provider is to call the address object's IDirectPlay8Address::SetSP method. You can optionally specify a particular adapter. If no adapter is specified, and it is allowed, DirectPlay attempts to host the session on all adapters associated with the given service provider. See DirectPlay Addressing for further information on DirectPlay addressing.
The following excerpt from the tutorial sample illustrates how to create an address object for a TCP/IP protocol service provider.
IDirectPlay8Address* g_pDeviceAddress = NULL;
.
.
.
// Create our IDirectPlay8Address Device Address
hr = CoCreateInstance( CLSID_DirectPlay8Address, NULL,
CLSCTX_INPROC_SERVER,
IID_IDirectPlay8Address,
(LPVOID*) &g_pDeviceAddress );
// Set the SP for our Device Address
hr = g_pDeviceAddress->SetSP(&CLSID_DP8SP_TCPIP );
Once you have created the address object, you must then create a description of your application. To do so, assign appropriate values to the members of a DPN_APPLICATION_DESC structure. The information that you can provide includes:
The application GUID uniquely identifies an application, not a particular session. Different applications should not have the same GUID. If you specify a maximum player count of 0, there is no limit on the number of players that can join the session.
To begin hosting a session, call IDirectPlay8Peer::Host. The following excerpt from the tutorial sample illustrates how host a session with an unlimited number of players.
DPN_APPLICATION_DESC dpAppDesc;
.
.
.
// Set up the application description.
ZeroMemory(&dpAppDesc, sizeof(DPN_APPLICATION_DESC));
dpAppDesc.dwSize = sizeof(DPN_APPLICATION_DESC);
dpAppDesc.guidApplication = g_guidApp;
// We are now ready to host the application.
hr = g_pDP->Host( &dpAppDesc, // AppDesc
&g_pDeviceAddress, 1,// Device Address
NULL, NULL, // Reserved
NULL, // Player Context
0); // dwFlags
Hosting a DirectPlay session causes a host player to be created with the player name and data specified when you called the IDirectPlay8Peer::SetPeerInfo method. When the player is created, you are notified through your DirectPlay message handler.
If a DirectPlay peer object was successfully initialized, you should first close the object by calling IDirectPlay8Peer::Close; then release all active objects and terminate the application. See Tutorial 1 for further discussion.