Tutorial 2: Hosting a Session

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.

• User's Guide
• Creating an Address Object
• Hosting a Session
• Terminating the Application

User's Guide

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.

Creating an Address Object

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 );

Hosting a Session

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's globally unique identifier (GUID)
• The maximum number of players (optional)
• The session name (optional)
• A session password (optional)
• Application-specific data (optional)

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.

Terminating the Application

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.