IDirectPlay8Server::GetClientInfo Method

Retrieves the client information set for the specified client.

Syntax

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 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 Value

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

DPNERR_BUFFERTOOSMALL	The supplied buffer is not large enough to contain the requested data.
DPNERR_INVALIDPARAM	One or more of the parameters passed to the method are invalid.
DPNERR_INVALIDPLAYER	The player ID is not recognized as a valid player ID for this game session.

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 IDirectPlay8Peer::SetPeerInfo method.

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