Tutorial 3: Enumerating Hosted Sessions

Before your application can join a peer-to-peer session, you need the address of the session host. In some cases, lobby-launched applications might give you the host address. With Microsoft® DirectPlay®, you can use that address to connect to the session. There is no need to enumerate the available hosted sessions. However, if you do not have the address of a session host, you must obtain it by enumerating the available hosted sessions. This tutorial extends Tutorial 2, and discusses how to enumerate available hosts. 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\Tut03_EnumHosts.

• User's Guide
• Initiating Host Enumeration
• Handling Host Responses
• 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

User's Guide

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

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 enumerate existing sessions, 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. If the address does not exist, a message box opens containing the error. If no session is found at the address, the Detected Sessions box will have a message that says "No hosts found."

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

To end the sample, click Exit.

Initiating Host Enumeration

To enumerate hosts, you must basically advertise a description of the type of session that you are interested in, your target address, and the device you perform the enumeration on. You then wait for any available hosts to respond.

You describe your application by assigning values to a DPN_APPLICATION_DESC structure, as discussed in Tutorial 2. Tutorial 2 also describes how to create an address object to contain your address.

To start the host enumeration, pass the DPN_APPLICATION_DESC structure and your address object to IDirectPlay8Peer::EnumHosts. You can specify a host address if you want to direct your enumeration query to a particular address. Otherwise, host enumeration queries are broadcast to every address in your Transmission Control Protocol/Internet Protocol (TCP/IP) subnet.

The following excerpt from the tutorial sample illustrates how to start enumerating the available hosts at a specified address.

    ZeroMemory(&dpAppDesc, sizeof(DPN_APPLICATION_DESC));
    dpAppDesc.dwSize = sizeof(DPN_APPLICATION_DESC);
    dpAppDesc.guidApplication = g_guidApp;

    hr = g_pDP->EnumHosts( &dpAppDesc,          // pApplicationDesc
                           g_pHostAddress,      // Host Address
                           g_pDeviceAddress,    // Device Address
                           NULL, 0,             // pvUserEnumData, size
                           4,                   // dwEnumCount
                           0,                   // dwRetryInterval
                           0,                   // dwTimeOut
                           NULL,                // pvUserContext
                           NULL,                // pAsyncHandle
                           DPNENUMHOSTS_SYNC ); // dwFlags

 

Handling Host Responses

A host receives your query in the form of a DPN_MSGID_ENUM_HOSTS_QUERY message sent to the message handler. The associated structure includes the information that you passed to IDirectPlay8Peer::EnumHosts. After examining this information, the host can respond to your query by returning DPN_OK, or reject the query by returning a different value.

When a host responds affirmatively, your application's message handler receives a DPN_MSGID_ENUM_HOSTS_RESPONSE message. The structure associated with the message contains information describing the session.

The following excerpt from the tutorial sample illustrates how to process a DPN_MSGID_ENUM_HOSTS_RESPONSE message. Essentially, the message handler places the associated structure in a list, to be examined after the enumeration is finished. Refer to the tutorial sample for details.

HRESULT WINAPI DirectPlayMessageHandler( PVOID pvUserContext, DWORD dwMessageId, PVOID pMsgBuffer )
{
.
.
.
  switch( dwMessageId )
    {
        case DPN_MSGID_ENUM_HOSTS_RESPONSE:
        {
            PDPNMSG_ENUM_HOSTS_RESPONSE     pEnumHostsResponseMsg;
            const DPN_APPLICATION_DESC*     pAppDesc;
            HOST_NODE*                      pHostNode = NULL;
            WCHAR*                          pwszSession = NULL;

            pEnumHostsResponseMsg = (PDPNMSG_ENUM_HOSTS_RESPONSE) pMsgBuffer;
            pAppDesc = pEnumHostsResponseMsg->pApplicationDescription;
            .
            .
            .
            // Copy the Host Address
             pEnumHostsResponseMsg->pAddressSender->Duplicate(&pHostNode->pHostAddress); 

             pHostNode->pAppDesc = new DPN_APPLICATION_DESC;

             ZeroMemory(pHostNode->pAppDesc, sizeof(DPN_APPLICATION_DESC));
             memcpy(pHostNode->pAppDesc, pAppDesc, sizeof(DPN_APPLICATION_DESC));      

When enumeration is finished, the IDirectPlay8Peer::EnumHosts method returns, and your application can decide which session to join.

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.