IDirectPlay4::CreatePlayer
IDirectPlay4 Interface
Creates a local player for the current session.
Syntax
HRESULT CreatePlayer(
LPDPID lpidPlayer,
LPDPNAME lpPlayerName,
HANDLE hEvent,
LPVOID lpData,
DWORD dwDataSize,
DWORD dwFlags
);
Parameters
- lpidPlayer
- Pointer to a variable that will be filled with the DirectPlay player ID. This value is defined by DirectPlay.
- lpPlayerName
- Pointer to a DPNAME structure that holds the name of the player. NULL indicates that the player has no initial name information. The name in lpPlayerName is provided for human use only. It is not used internally and need not be unique.
- hEvent
- An event object created by the application that will be signaled by DirectPlay when a message addressed to this player is received.
- lpData
- Pointer to a block of application-defined data to associate with the player ID. NULL indicates that the player has no initial data. The data specified in this parameter is assumed to be remote data that will be propagated to all the other applications in the session, as if IDirectPlay4::SetPlayerData were called.
- dwDataSize
- Size, in bytes, of the data block that lpData points to.
- dwFlags
- Flags indicating what type of player this is. Default (dwFlags = 0) is a nonspectator, nonserver player.
- DPPLAYER_SERVERPLAYER - the player is a server player for client/server communications. Only the host can create a server player. There can only be one server player in a session. CreatePlayer will always return a player ID of DPID_SERVERPLAYER if this flag is specified.
- DPPLAYER_SPECTATOR - the player is created as a spectator. A spectator player behaves exactly as a normal player except the player is flagged as a spectator. The application can then limit what a spectator player can do. The behavior of a spectator player is completely defined by the application. DirectPlay simply propagates this flag.
Return Value
Returns DP_OK if successful, or one of the following error values otherwise:
DPERR_CANTADDPLAYER DPERR_CANTCREATEPLAYER DPERR_CONNECTIONLOST DPERR_INVALIDFLAGS DPERR_INVALIDPARAMS DPERR_NOCONNECTION
Remarks
A single process can have multiple local players that communicate through a DirectPlay object with other players on the same computer or players on remote computers.
Upon successful completion, this method sends a DPMSG_CREATEPLAYERORGROUP system message to all the other players in the session announcing that a new player has joined the session. By default, all local players receive copies of all the system messages.
Your application should use the player ID returned to the application to identify the player for message passing and data association. Player and group IDs assigned by DirectPlay will always be unique within the session.
Only the application that created the player can:
- change the player's name.
- change the player's remote data.
- send messages from the player.
If the application closes the session, any local players created will be automatically destroyed. Using IDirectPlay4::DestroyPlayer, the session host or the application that created the player can destroy the player at any time.
If the application uses a separate thread to retrieve DirectPlay messages, it is highly recommended that a non-NULL hEvent be supplied and used for synchronization. This event will be set when this player receives a message. Within the message receive thread, use the Win32 API WaitForSingleObject (or use WaitForMultipleObjects if more than one event is used) within the thread to determine if a player has messages. It is inefficient to loop on IDirectPlay4::Receive inside a separate thread waiting for a message. The same event can be used for all the local players, or the application can supply different events for each player. The application is responsible for creating and destroying the event. See Synchronization for more information.
See Also
DPNAME, DPMSG_CREATEPLAYERORGROUP, IDirectPlay4::DestroyPlayer, IDirectPlay4::EnumPlayers, IDirectPlay4::Receive, IDirectPlay4::Send, IDirectPlay4::SetPlayerData, IDirectPlay4::SetPlayerName, IDirectPlay4::GetPlayerFlags
Top of Page
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.