Step 3: Joining a Session

If the user wants to join an existing session, enumerate the available sessions by using the IDirectPlay3::EnumSessions method, present the choices to the user, and then connect to that session by using the IDirectPlay3::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:

// Search for this kind of session.

ZeroMemory(&sessionDesc, sizeof(DPSESSIONDESC2));

sessionDesc.dwSize = sizeof(DPSESSIONDESC2);

sessionDesc.guidApplication = DPCHAT_GUID;

hr = lpDirectPlay3A->EnumSessions(&sessionDesc, 0, EnumSessionsCallback,

hWnd, DPENUMSESSIONS_AVAILABLE);

if FAILED(hr)

goto FAILURE;

In the previous example, the third parameter in the IDirectPlay3A::EnumSessions method is a callback that enumerates the available sessions. The following example shows one way to implement this callback function:

BOOL FAR PASCAL EnumSessionsCallback(

LPCDPSESSIONDESC2 lpSessionDesc, LPDWORD lpdwTimeOut,

DWORD dwFlags, LPVOID lpContext)

{

HWND hWnd = lpContext;

LPGUID lpGuid;

LONG iIndex;

// Determine if the enumeration has timed out.

if (dwFlags & DPESC_TIMEDOUT)

return (FALSE); // Do not try again

// Store the session name in the list.

iIndex = SendDlgItemMessage(hWnd, IDC_SESSIONLIST, LB_ADDSTRING,

(WPARAM) 0, (LPARAM) lpSessionDesc->lpszSessionNameA);

if (iIndex == CB_ERR)

goto FAILURE;

// Make space for the session instance GUID.

lpGuid = (LPGUID) GlobalAllocPtr(GHND, sizeof(GUID));

if (lpGuid == NULL)

goto FAILURE;

// Store the pointer to the GUID in the list.

*lpGuid = lpSessionDesc->guidInstance;

SendDlgItemMessage(hWnd, IDC_SESSIONLIST, LB_SETITEMDATA,

(WPARAM) iIndex, (LPARAM) lpGuid);

FAILURE:

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:

// Join an existing session.

ZeroMemory(&sessionDesc, sizeof(DPSESSIONDESC2));

sessionDesc.dwSize = sizeof(DPSESSIONDESC2);

sessionDesc.guidInstance = *lpguidSessionInstance;

hr = lpDirectPlay3A->Open(&sessionDesc, DPOPEN_JOIN);

if FAILED(hr)

goto OPEN_FAILURE;