IDirectPlay8Address::GetComponentByName Method

Retrieves information about the component at the specified key. Values for the component are retrieved in their native format. If the component key is not found, DPNERR_DOESNOTEXIST is returned.

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 GetComponentByName(      
    const WCHAR *const pwszName,
    void *pvBuffer,
    PDWORD pdwBufferSize,
    PDWORD pdwDataType
);

Parameters

pwszName

[in] String specifying the name of the component you want to retrieve.

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 that contains 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.