|Microsoft DirectX 9.0|
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\C++\DirectPlay\Tutorials\Tut02_Host.
When you run this tutorial sample, a window opens which contains information about the session status, which initially will be "Not connected to a session". To begin hosting a session, click the Start Hosting button. Once you are hosting a session, the session status will change to "Hosting a Session." To stop hosting, click Exit.
The first step in hosting a session is to create a Microsoft 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 about DirectPlay addressing.
The following excerpt from the tutorial sample illustrates how to create an address object for a Transmission Control Protocol/Internet Protocol (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; // You 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.