This tutorial pertains only to applications written in C++. See DirectPlay Visual Basic Tutorials.

If the user wants to join an existing session, enumerate the available sessions by using the IDirectPlay4::EnumSessions method, present the choices to the user, and then connect to that session by using the IDirectPlay4::Open method, specifying the DPOPEN_JOIN flag. The service provider might display a dialog box requesting some information from the user before it can enumerate the sessions.

See Tutorial 4 for details on the asynchronous EnumSessions functionality.

The following example shows how to enumerate the available sessions:

// Enum sessions and let DirectPlay decide the timeout.
ZeroMemory( &dpsd, sizeof(dpsd) );
dpsd.dwSize          = sizeof(dpsd);
dpsd.guidApplication = g_AppGUID;
 
// Enumerate all the active DirectPlay games 
//  on the selected connection.
hr = g_pDP->EnumSessions( &dpsd, 0, 
        DPConnect_EnumSessionsCallback, NULL,
        DPENUMSESSIONS_ALL | DPENUMSESSIONS_ASYNC );  

The third parameter in the IDirectPlay4::EnumSessions method is a callback that enumerates the available sessions. The following code shows how the SimpleConnect Sample implements this callback function:

BOOL FAR PASCAL DPConnect_EnumSessionsCallback( 
        LPCDPSESSIONDESC2 pdpsd,
        DWORD*            pdwTimeout,
        DWORD             dwFlags,
        VOID*             pvContext )
{
    DPSessionInfo* pDPSINew = NULL;
 
    if ( dwFlags & DPESC_TIMEDOUT )
        return FALSE; // Timed out, so stop the enumeration.
 
    // Found a good session, save it.
    pDPSINew = new DPSessionInfo;
    if ( NULL == pDPSINew )
        return FALSE;
 
    ZeroMemory( pDPSINew, sizeof(DPSessionInfo) );
 
    // Copy the information into pDPSINew.
    pDPSINew->guidSession = pdpsd->guidInstance;
    sprintf( pDPSINew->szSession, "%s (%d/%d)", 
            pdpsd->lpszSessionNameA,
            pdpsd->dwCurrentPlayers, 
            pdpsd->dwMaxPlayers );
 
    // Add pDPSINew to the circular linked list, g_pDPSIFirst.
    pDPSINew->pDPSINext = g_DPSIHead.pDPSINext;
    g_DPSIHead.pDPSINext = pDPSINew;
 
    return TRUE;
}

After the user has selected a session, your application can allow the user to join an existing session. The following example shows how to join an existing session:

// Set up the DPSESSIONDESC2, and get the session GUID from 
// the selected listbox item.
ZeroMemory( &dpsd, sizeof(dpsd) );
dpsd.dwSize          = sizeof(dpsd);
dpsd.guidInstance    = pDPSISelected->guidSession;
dpsd.guidApplication = g_AppGUID;
 
// Join the session
g_bHostPlayer = FALSE;
if ( FAILED( hr = g_pDP->Open( &dpsd, DPOPEN_JOIN ) ) )
    return hr;

Next: Step 4: Create a Session