IDirectPlay::CreatePlayer

HRESULT CreatePlayer(LPDPID lppidID,

LPSTR lpPlayerFriendlyName,

LPSTR lpPlayerFormalName, LPHANDLE lpEvent);

Creates a player for the current game session.

·Returns DP_OK if successful, or one of the following error values otherwise:

lppidID

Address for the DPID that will hold the DirectPlay player ID.

lpPlayerFriendlyName

Address for the zero-terminated string that contains the friendly name of the player.

lpPlayerFormalName

Address for the zero-terminated string that contains the formal name of the player.

lpEvent

Pointer to an event that will be triggered when a message addressed to this player is received.

A single process can have multiple players that communicate through a DirectPlay object with any number of other players running on multiple computers. The player ID returned to the caller will be used internally to direct the player's message traffic and manage the player. The lpPlayerFriendlyName and lpPlayerFormalName parameters are provided for players' convenience only; they are not used internally and need not be unique. Player IDs assigned by DirectPlay will always be unique within the session.

Upon successful completion, this method sends a DPMSG_ADDPLAYER system message to all of the other players in the game session announcing that a new player has joined the session. The newly created player can use the IDirectPlay::EnumPlayers method to find out who else is in the game session.

It is highly recommended that an application provide a non-NULL lpEvent and use this event for synchronization. After creation of a player, use WaitForSingleObject(*lpEvent, dwTimeout = 0) from Win32 to determine if a player has messages (the return value will be WAIT_TIMEOUT if there are not any waiting messages) or use a different time-out to wait for a message to come in. It is inefficient to loop on the IDirectPlay::Receive method.