IDirectPlay8Peer::GetGroupInfo Method

Retrieves a block of data associated with a group, including the group name.

This method is typically called after a DPN_MSGID_GROUP_INFO system message is received indicating that the group data has been modified.

Syntax

HRESULT GetGroupInfo(      
    const DPNID dpnid,
    DPN_GROUP_INFO *const pdpnGroupInfo,
    DWORD *const pdwSize,
    const DWORD dwFlags
);

Parameters

dpnid

[in] Variable of type DPNID that specifies the identifier of the group whose data block will be retrieved.

pdpnGroupInfo

[out] Pointer to a DPN_GROUP_INFO structure that describes the group data. If pdwSize is not set to NULL, you must set pdpnGroupInfo.dwSize to the size of a DPN_GROUP_INFO structure.

pdwSize

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

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_INVALIDGROUP	The group ID is not recognized as a valid group ID for this game session.

Remarks

Microsoft® DirectPlay® returns the DPN_GROUP_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_GROUP_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::SetGroupInfo, to notify DirectPlay 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::SetGroupInfo method.