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\Multimedia\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

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.

User's Guide

When you run this tutorial sample, a Microsoft® MS-DOS® command window opens and you have the choice to either Host or Connect.

If you choose Host, enter a session name. A message prints on the screen telling you that you are "currently hosting."

If you choose Connect, enter an IP address. If a session is found at that address, you will be connected. If the address does not exist or if no session is found at the address, the application prints error messages.

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

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 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 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.