Tutorial 4: Connecting to a Session

If you have found a session, you can then connect to it. This tutorial extends Tutorial 3 and discusses how to connect to a session. 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\Tut04_Connect.

• User's Guide
• Connecting to a Session
• Terminating the Application

Refer to the preceding tutorials for a discussion of the initial steps in the process:

• Tutorial 1: Creating a DirectPlay Object and Enumerating Service Providers
• Tutorial 2: Hosting a Session
• Tutorial 3: Enumerating Hosted Sessions

User's Guide

When you run this tutorial sample, a window opens and you can choose to either begin hosting a session or connect to an existing session.

To host, click the Host... button and the Host New Session window opens. Enter a session name and click OK. the session status will change to 'Hosting Session "YourSessionName".'

To connect to an existing session, enter an Internet Protocol (IP) address in the Search Address box and click Search. The application prints all the sessions found at the address in the Detected Sessions box. The Search button will turn grey while the search is taking place. Select one of the Detected Sessions and click Connect.

You can run this sample twice—once to host a session and once to connect. When connecting, enter your computer's IP address.

To end the sample, click Exit.

Connecting to a Session

Once you have selected a host, you can connect to the session. To do so, you will need:

• A DPN_APPLICATION_DESC structure. The structure should include the application's globally unique identifier (GUID) and a password if one is required for joining the session.
• The host address that you received when you enumerated the available hosts.
• An address object with your device address. See Creating an Address Object for a discussion of how to create an address object.

To connect to a session, call IDirectPlay8Peer::Connect. The host receives a DPN_MSGID_INDICATE_CONNECT message with your information. The host might reject the connection at this point by returning a value other than DPN_OK. In that case, if IDirectPlay8Peer::Connect is called synchronously, as it is in the tutorial, the method returns an error value. If the connection is accepted, your Microsoft DirectPlay® message handler receives a DPN_MSGID_CONNECT_COMPLETE message. You also receive a DPN_MSGID_CREATE_PLAYER messages for yourself and each player already in the session.

The following excerpt from the tutorial sample illustrates how to connect to a selected session.

    DPN_APPLICATION_DESC        dpnAppDesc;
    IDirectPlay8Address*        pHostAddress = NULL;
.
.
.
    ZeroMemory(&dpnAppDesc, sizeof(DPN_APPLICATION_DESC));
    dpnAppDesc.dwSize = sizeof(DPN_APPLICATION_DESC);
    dpnAppDesc.guidApplication = g_guidApp;
.
.
.
    hr = g_pDP->Connect(&dpnAppDesc,    // Application Description
                        pHostAddress,       // Host Address
                        g_pDeviceAddress,   
                        NULL,  
                        NULL,
                        NULL, 0, 
                        NULL, 
                        NULL,
                        NULL, 
                        DPNCONNECT_SYNC);

        if( FAILED( hr))
            //Failed Connecting to Host
    }
 

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.