IDirectPlay8Address::GetComponentByIndex

Retrieves information on the component at the specified index. Values for the component are retrieved in their native format. If the component key is not found, the method returns DPNERR_DOESNOTEXIST.

The value of the component is retrieved in its native format. Therefore, if the component's value is a DWORD, a DWORD is retrieved by this call. So buffer size = 4 and pvBuffer should be a recast PDWORD.

HRESULT GetComponentByIndex(
const DWORD dwComponentID,
WCHAR* pwszName,
PDWORD pdwNameLen,
void* pvBuffer,
PDWORD pdwBufferSize,
PDWORD pdwDataType 
);

Parameters

dwComponentID

[in] Index of the component to retrieve. This value is zero-based and should be in the range of [0..GetNumComponents()-1].

pwszName

[out] Buffer to retrieve the name of the component on a successful call. To retrieve the size required, specify NULL for this parameter and 0 for the DWORD pointed to by pdwNameLen. The method returns DPNERR_BUFFERTOOSMAL in this case.

pdwNameLen

[in,out] On input, a pointer to a DWORD that contains the size of the buffer, in characters including NULL terminator, pointed to by pwszName. On output, a pointer to a DWORD that contains the number of characters written to the buffer, including NULL terminator, on success and on failure, the number of characters required, including NULL terminator, to store this value.

pvBuffer

[out] Buffer to retrieve the data stored in the value of the component. To retrieve the size required, specify NULL for this parameter and 0 for the DWORD pointed to by pdwBufferSize. The method returns DPNERR_BUFFERTOOSMALL in this case.

pdwBufferSize

[in,out] On input, a pointer to a DWORD containing the size of the buffer, in bytes, pointed to by pvBuffer. On output, a pointer to a DWORD that contains the number of bytes written to the buffer on success and on failure, the number of bytes required to store the data.

pdwDataType

[out] DWORD pointed to by this parameter that is set to the type of data that is stored in this component. This can be one of the following:

DPNA_DATATYPE_STRING

Data is a NULL-terminated string.

DPNA_DATATYPE_DWORD

Data is a DWORD.

DPNA_DATATYPE_GUID

Data is a GUID.

DPNA_DATATYPE_BINARY

Data is raw binary.

Return Values

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

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 Dpaddr.h.