IDirectPlay8Address::GetComponentByIndex Method

Retrieves information about 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.

Syntax

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 the terminating NULL character, pointed to by pwszName. On output, a pointer to a DWORD that contains the number of characters written to the buffer, including the terminating NULL character, on success and on failure, the number of characters required, including the terminating NULL character, 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 globally unique identifier (GUID).

DPNA_DATATYPE_BINARY

Data is raw binary.

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_DOESNOTEXIST	Requested element is not part of the address.
DPNERR_INVALIDPARAM	One or more of the parameters passed to the method are invalid.