IDirectPlay8Server::GetClientInfo

Retrieves the client information set for the specified client.

HRESULT GetClientInfo(
const DPNID dpnid,
DPN_PLAYER_INFO *const pdpnPlayerInfo,
DWORD *const pdwSize,
const DWORD dwFlags
);

Parameters

dpnid

[in] Variable of type DPNID that specifies the identifier of the client to retrieve the information for.

pdpnPlayerInfo

[out] Pointer to a DPN_PLAYER_INFO structure that is filled with client information. If pdwSize is not set to NULL, you must set pdpnPlayerInfo.dwSize to an appropriate value.

pdwSize

[in,out] Pointer to a variable of type DWORD that contains the size of the client data, in bytes, returned in the pdpnPlayerInfo parameter. If the buffer is too small, this method returns DPNERR_BUFFERTOOSMALL and this parameter contains the size of the required buffer.

dwFlags

[in] Flags describing the information returned for the client. Currently, both of the following flags are returned.

DPNINFO_NAME

The DPN_PLAYER_INFO structure contains the name set for the client.

DPNINFO_DATA

The DPN_PLAYER_INFO structure contains the data set for the client.

Return Values

Returns S_OK if successful, or one of the following error values.

Remarks

Call this method after the server receives a DPN_MSGID_CLIENT_INFO message from the application. This message indicates that a client has updated its information.

Microsoft® DirectPlay® returns the DPN_PLAYER_INFO structure, and the pointers assigned to the structure's pwszName and pvData members in a contiguous buffer. If the two pointers were set, you must have allocated enough memory for the structure, plus the two pointers. The most robust way to use this method is to first call it with pdwSize set to NULL. When the method returns, pdwSize will point to the correct value. Use that value to allocate memory for the structure and call the method a second time to retrieve the information.

When the method returns, the dwInfoFlags member of the DPN_PLAYER_INFO structure will always have the DPNINFO_DATA and DPNINFO_NAME flags set, even if the corresponding pointers are set to NULL. These flags are used when calling IDirectPlay8Client::SetClientInfo, to notify DirectPlay of which values have changed.

Transmission of nonstatic information should be handled with the IDirectPlay8Client::Send method because of the high cost of using the IDirectPlay8Client::SetPeerInfo method.

The player sets the information by calling IDirectPlay8Client::SetClientInfo.

Requirements

  Windows NT/2000/XP: Available as a redistributable for Windows 2000 and later.
  Windows 98/Me: Available as a redistributable for Windows 98 and later.
  Header: Declared in Dplay8.h.