IDirectPlay8Peer::GetPeerInfo

Retrieves peer information set for the specified peer.

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, 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] Reserved. Set to 0.

Return Values

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

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 GetPeerInfo before the host has returned from IDirectPlay8Peer::Host will cause this method to fail with DPNERR_CONNECTING. If this happens, try calling 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.

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.