| Platform SDK: DirectX |
The information in this topic pertains only to applications developed in C++.
The names of the DirectPlay DLLs in DirectX version 3.0 and later are different from those in previous versions. Applications compiled with DirectX 2.0 or earlier do not use the new DirectPlay DLLs. To use the new DLLs, the application must be recompiled and linked to the Dplayx.lib import library.
It is also recommended that you add the code necessary to make the application lobby-aware. This means that an external lobby or matchmaking program can start the application and supply it with all the information necessary to connect to a session. The application need not ask the user to decide on a service provider, select a session, or supply any other information (such as a telephone number or network address).
In addition, several other new features were added to DirectPlay in DirectX version 6.0. The new features include:
To migrate an application created with DirectPlay version 2.0 or earlier, carry out the following steps:
Find out if your application was launched from a lobby client. For more information, see Step 2: Retrieve the Connection Settings.
If your application is enumerating service providers, use the DirectPlay4::EnumConnections method to determine if a service provider is available. If so, call the DirectPlay4::InitializeConnection method on the service provider. If InitializeConnection 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.
Call the QueryInterface method on the IDirectPlay interface to obtain an IDirectPlay4 (Unicode) or IDirectPlay4A (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.
Make 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 lpPlayerName->lpszShortNameA = lpszFriendlyName lpPlayerName->lpszLongNameA = lpszFormalName lpDP4A->SetPlayerName(pidPlayer, lpPlayerName, 0)
where lpDP4A is an IDirectPlay4A interface. If the application is using Unicode strings (and therefore creates an instance of the IDirectPlay4 interface), use the following:
lpPlayerName->lpszShortName = lpwszFriendlyName lpPlayerName->lpszLongName = lpwszFormalName lpDP4->SetPlayerName(pidPlayer, lpPlayerName, 0)
where lpDP4 is an IDirectPlay4 interface.
Update 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.
Update 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.
Update the DPSESSIONDESC structure to DPSESSIONDESC2, and add the new members to the DPCAPS structure.
Update the callback functions for IDirectPlay4::EnumSessions, IDirectPlay4::EnumGroups, IDirectPlay4::EnumGroupPlayers, and IDirectPlay4::EnumPlayers.
Update the manner in which the hEvent parameter is supplied to the IDirectPlay4::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.
Set the DPSESSION_KEEPALIVE flag in the DPSESSIONDESC2 structure if the application needs DirectPlay to detect when players drop out of the game abnormally.
Update 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.
Become familiar with the new methods of the IDirectPlay4 interface and use them in your application. You might be able to substitute the code where you broadcast player state information to all the other players by using the IDirectPlay4::SendEx and IDirectPlay4::Receive methods.