HRESULT CreatePlayer(LPDPID lpidPlayer,
LPDPNAME lpPlayerName, HANDLE hEvent,
LPVOID lpData, DWORD dwDataSize, DWORD dwFlags);
Creates a local player for the current session.
·Returns DP_OK if successful, or one of the following error values otherwise:
lpidPlayer
Address of a variable that will be filled with the DirectPlay player ID. This value is defined by DirectPlay.
lpPlayerName
Address of a DPNAME structure that holds the name of the player. NULL indicates that the player has no initial name information.
hEvent
An event object created by the application that will be triggered by DirectPlay when a message addressed to this player is received.
lpData
Address of 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 IDirectPlay2::SetPlayerData were called.
dwDataSize
Size, in bytes, of the data block that lpData points to.
dwFlags
Reserved; do not use.
A single process can have multiple local players that communicate through a DirectPlay object with any number of other local or remote players running on multiple computers. 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.
The application can associate an initial name with the player at creation by using the IDirectPlay2::SetPlayerName method. The names in lpPlayerName are provided for human use only; they are not used internally and need not be unique. The application can also associate initial data with the player at creation by using the IDirectPlay2::SetPlayerData method.
Upon successful completion, this method sends a DPSYS_CREATEPLAYERORGROUP system message to all the other players in the session announcing that a new player has joined the session. For a list of system messages, see Using System Messages.
If the application uses a separate thread to retrieve DirectPlay messages, it may supply a synchronization event by using the hEvent parameter. This event will be set when this player receives a message. Multiple players can use the same event object specified in hEvent.