IDirectPlay8Peer::GetPeerInfo Method

Retrieves peer information set for the specified peer.

Syntax

HRESULT GetPeerInfo(      
    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 peer whose information will be retrieved.

pdpnPlayerInfo

[out] Pointer to a DPN_PLAYER_INFO structure to fill with peer information. If pdwSize is not set to NULL, you must set pdpnPlayerInfo.dwSize to the size of a DPN_PLAYER_INFO structure.

pdwSize

[in, out] Pointer to a variable of type DWORD that contains the size of the peer 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] Reserved. 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_INVALIDFLAGS	The flags passed to this method are invalid.
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.
DPNERR_CONNECTING	The method is in the process of connecting to the network.

Remarks

Call this method after the peer receives a DPN_MSGID_PEER_INFO message from the application, which indicates a peer has updated their information.

Calling IDirectPlay8Peer::GetPeerInfo before the host has returned from IDirectPlay8Peer::Host will cause this method to fail with DPNERR_CONNECTING. If this happens, try calling IDirectPlay8Peer::GetPeerInfo again.

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 IDirectPlay8Peer::SetPeerInfo, to notify DirectPlay of which values have changed.

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