IWDFUsbTargetDevice::RetrieveDescriptor method (wudfusb.h)

Article
10/21/2021

[Warning: UMDF 2 is the latest version of UMDF and supersedes UMDF 1. All new UMDF drivers should be written using UMDF 2. No new features are being added to UMDF 1 and there is limited support for UMDF 1 on newer versions of Windows 10. Universal Windows drivers must use UMDF 2. For more info, see Getting Started with UMDF.]

The RetrieveDescriptor method retrieves a USB descriptor, which can describe a device, configuration, or string.

Syntax

HRESULT RetrieveDescriptor(
  [in]      UCHAR  DescriptorType,
  [in]      UCHAR  Index,
  [in]      USHORT LanguageID,
  [in, out] ULONG  *BufferLength,
  [out]     PVOID  Buffer
);

Parameters

[in] DescriptorType

A value that specifies the type of descriptor to return. This parameter corresponds to the bDescriptorType field of a standard device descriptor, whose values are described in the Universal Serial Bus specification. (This resource may not be available in some languages

and countries.) Some of these values are listed in the description of the DescriptorType member of the _URB_CONTROL_DESCRIPTOR_REQUEST structure.

[in] Index

The index of the descriptor, according to the Universal Serial Bus specification. (This resource may not be available in some languages

and countries.)

[in] LanguageID

The identifier of the language, if the UMDF driver requests a string descriptor; otherwise, this parameter is zero.

[in, out] BufferLength

A pointer to a variable that, on input, contains the size, in bytes, of the buffer that the Buffer points to. If the operation succeeds, the variable receives the number of bytes that the framework copied into the buffer.

[out] Buffer

A pointer to a caller-supplied buffer that receives the USB descriptor. The type of buffer should match the value specified in DescriptorType.

Return value

RetrieveDescriptor returns one of the following values:

Return code	Description
S_OK	RetrieveDescriptor successfully retrieved the USB descriptor.
E_OUTOFMEMORY	RetrieveDescriptor encountered an allocation failure.
An error code that is defined in Winerror.h	This value corresponds to the error code that the WinUsb API returned.

Remarks

For information about valid descriptor types that a UMDF driver can pass for the DescriptorType parameter, see the WinUsb_GetDescriptor function.

The RetrieveDescriptor method generates a UMDF request and synchronously sends the request to the I/O target.

Examples

The following code example retrieves a USB configuration descriptor.

HRESULT
CUmdfHidDevice::RetrieveConfigDescriptor(
    __out_bcount(ConfigDescriptorCb) PUSB_CONFIGURATION_DESCRIPTOR *ConfigDescriptor,
    __out ULONG *ConfigDescriptorCb
    )
{
    ULONG descriptorCb = sizeof(USB_CONFIGURATION_DESCRIPTOR);
    USB_CONFIGURATION_DESCRIPTOR descriptorHeader;
    PBYTE descriptorBuffer;
    HRESULT hr;

    //
    // Get the configuration descriptor at index 0
    //

    hr = m_UsbTargetDevice->RetrieveDescriptor(
                            USB_CONFIGURATION_DESCRIPTOR_TYPE,
                            0,
                            0,
                            &descriptorCb,
                            &descriptorHeader
                            );
    //
    // Store the buffer in the output parameter, or delete it.
    //
    if (SUCCEEDED(hr)) {
        *ConfigDescriptor = (PUSB_CONFIGURATION_DESCRIPTOR) (descriptorHeader);
        *ConfigDescriptorCb = descriptorCb;
    }
    else {
        delete[] descriptorHeader;
    }
    return hr;
}

Requirements

Requirement	Value
End of support	Unavailable in UMDF 2.0 and later.
Target Platform	Desktop
Minimum UMDF version	1.5
Header	wudfusb.h (include Wudfusb.h)
DLL	WUDFx.dll

Share via