Migrating to the IDirectPlay2 Interface

To migrate your application to use the IDirectPlay2 interface, carry out the following steps:

1Find out if your application was launched from a lobby client. For more information, see Step 2: Retrieving the Connection Settings in the DirectPlay tutorials.

2If your application is enumerating service providers, use the DirectPlayEnumerate callback function to determine if a service provider is available. If so, call the DirectPlayCreate function on the service provider. If the DirectPlayEnumerate callback function returns an error, the service provider cannot run on the system, and you should not add that service provider to the list to show to the user. If the call succeeds, use the Release method to release the DirectPlay object and add the service provider to the list.

3Call the QueryInterface method on the IDirectPlay interface to obtain an IDirectPlay2 (Unicode) or IDirectPlay2A (ANSI) interface. The only difference between the two interfaces is how strings in the structures are read and written. For the Unicode interface, Unicode strings are read and written to the member of the structure that is of the LPWSTR type. For the ANSI interface, ANSI strings are read and written to the member of the structure that is of the LPSTR type.

4Make all the changes necessary to use the new structures in existing APIs. For example, instead of the following:

lpDP->SetPlayerName(pidPlayer, lpszFriendlyName, lpszFormalName)

where lpDP is an IDirectPlay interface, use the following:

DPNAME PlayerName, *lpPlayerName;

PlayerName.dwSize = sizeof(DPNAME);

lpPlayerName = &PlayerName;

lpPayerName->lpszShortNameA = lpszFriendlyName;

lpPlayerName->lpszLongNameA = lpszFormalName;

lpDP2A->SetPlayerName(pidPlayer, lpPlayerName, 0)

where lpDP2A is an IDirectPlay2A interface. If the application is using Unicode strings (and therefore instantiates an IDirectPlay2 interface), use the following:

lpPayerName->lpszShortName = lpwszFriendlyName;

lpPlayerName->lpszLongName = lpwszFormalName;

lpDP2->SetPlayerName(pidPlayer, lpPlayerName, 0)

where lpDP2 is an IDirectPlay2 interface.

5Update the following system messages:

·DPSYS_ADDPLAYER has been replaced by DPSYS_CREATEPLAYERORGROUP.

·DPSYS_DELETEPLAYER and DPSYS_DELETEGROUP have been combined in a single DPSYS_DESTROYPLAYERORGROUP message.

·DPSYS_DELETEPLAYERFROMGRP has been changed to DPSYS_DELETEPLAYERFROMGROUP.

6Update your application to generate a DPSYS_SETPLAYERORGROUPNAME message when a player or group name changes, and a DPSYS_SETPLAYERORGROUPDATA message when the player or group data changes.

7Update the DPSESSIONDESC structure to DPSESSIONDESC2, and add the new members to the DPCAPS structure.

8Update the callback functions for IDirectPlay2::EnumSessions, IDirectPlay2::EnumGroups, IDirectPlay2::EnumGroupPlayers, and IDirectPlay2::EnumPlayers.

9Update the manner in which the hEvent parameter is supplied to the IDirectPlay2::CreatePlayer method. In previous versions of DirectPlay, this parameter was lpEvent. DirectPlay does not return an event; instead, the application must create it. This allows the application the flexibility of creating one event for all the players.

10Set the DPSESSION_KEEPALIVE flag in the DPSESSIONDESC2 structure if the application needs DirectPlay to detect when players drop out of the game abnormally.

11Update your application to create sessions with the DPSESSION_MIGRATEHOST flag. This enables another computer to become the host if the current host drops out of the session. If your application has any special code that only the host runs, then your application should set this flag when it creates a session. It should also add support for the DPSYS_HOST system message. For a list of system messages, see Using System Messages.

12Become familiar with the new methods of the IDirectPlay2 interface and use them in your application. Pay particular attention to the IDirectPlay2::SetPlayerData and IDirectPlay2::GetPlayerData methods. You might be able to substitute the code where you broadcast player state information to all the other players by using the IDirectPlay2::Send and IDirectPlay2::Receive methods.