IDirectPlay8Client::GetServerInfo Method

Retrieves the data set for the server set by the call to the IDirectPlay8Server::SetServerInfo method.

Syntax

HRESULT GetServerInfo(      
    DPN_PLAYER_INFO *const pdpnPlayerInfo,
    DWORD *const pdwSize,
    const DWORD dwFlags
);

Parameters

pdpnPlayerInfo

[out] Pointer to a DPN_PLAYER_INFO structure to be filled with the server's information. If pdwSize is not set to NULL, you must set pdpnPlayerInfo.dwSize to the size of a DPN_PLAYER_INFO structure.

pdwSize

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

dwFlags

[in] Reserved. Must be set to 0.

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.

Remarks

Call this method after the client receives a DPN_MSGID_SERVER_INFO message, indicating that the server 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 your 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 IDirectPlay8Server::SetServerInfo, to notify DirectPlay of which values have changed.

Transmission of nonstatic information should be handled with the IDirectPlay8Server::SendTo method because of the high cost of using the IDirectPlay8Server::SetServerInfo method.