IDirectPlay4::SetPlayerData
IDirectPlay4 Interface
Associates an application-specific data block with a player ID.
Syntax
HRESULT SetPlayerData(
DPID idPlayer,
LPVOID lpData,
DWORD dwDataSize,
DWORD dwFlags
);
Parameters
- idPlayer
- ID of the player for which data is being set.
- lpData
- Pointer to the data to be set. Set this parameter to NULL and dwDataSize to zero to clear out any existing player data.
- dwDataSize
- Size of the data buffer. If lpData is NULL and this parameter does not equal zero, the method returns DPERR_INVALIDPARAMS.
- dwFlags
- If this parameter is set to 0, the remote player data will be set and propagated by using nonguaranteed messaging.
- DPSET_GUARANTEED
- Propagates the data by using guaranteed messaging (if available). This flag can only be used with DPSET_REMOTE.
- DPSET_LOCAL
- This data is for local use only and will not be propagated.
- DPSET_REMOTE
- This data is for use by all the applications, and will be propagated to all the other applications in the session.
Return Value
Returns DP_OK if successful, or one of the following error values otherwise:
DPERR_ACCESSDENIED DPERR_CONNECTIONLOST DPERR_INVALIDFLAGS DPERR_INVALIDOBJECT DPERR_INVALIDPARAMS DPERR_INVALIDPLAYER
Remarks
SetPlayerData should not be used for updating real-time information (such as position updates) due to the overhead introduced. It is much more efficient to use Send for this. SetPlayerData is more appropriate for shared state information that doesn't change very often and is not time critical (such as a player's name).
DirectPlay can maintain two types of player data: local and remote. Local data is available only to the application on the local computer. Remote data is propagated to all the other applications in the session. This method returns DPERR_ACCESSDENIED if you try to set player data for a remote player. A DPMSG_SETPLAYERORGROUPDATA system message will be sent to all players (including the sender) notifying them of the change unless DPSESSION_NODATAMESSAGES is set in the session description. It is safe to store pointers to resources in the local data; the local data block is available (in the DPMSG_DESTROYPLAYERORGROUP system message) when the player is being destroyed, so the application can free those resources. For a list of system messages, see Using System Messages.
See Also
DPMSG_SETPLAYERORGROUPDATA, IDirectPlay4::GetPlayerData, IDirectPlay4::Send
Top of Page
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.