// wdfusb.h
NTSTATUS WdfUsbTargetDeviceRetrieveConfigDescriptor(
[in] WDFUSBDEVICE UsbDevice,
[out] PVOID ConfigDescriptor,
[in, out] PUSHORT ConfigDescriptorLength
);
View the official Windows Driver Kit DDI reference
No description available.
[Applies to KMDF and UMDF]
The WdfUsbTargetDeviceRetrieveConfigDescriptor method retrieves the USB configuration descriptor for the USB device that is associated with a specified framework USB device object.
UsbDevice
[in]A handle to a USB device object that was obtained from a previous call to WdfUsbTargetDeviceCreateWithParameters.
ConfigDescriptor
[out]A pointer to a caller-allocated buffer that receives a USB_CONFIGURATION_DESCRIPTOR structure, followed by one or more USB_INTERFACE_DESCRIPTOR and USB_ENDPOINT_DESCRIPTOR structures. This parameter is optional and can be NULL, in which case WdfUsbTargetDeviceRetrieveConfigDescriptor returns the required buffer length. For more information, see the following Remarks section.
ConfigDescriptorLength
[in, out]A pointer to a location that supplies the length of the buffer that ConfigDescriptor points to. If the pointer that is supplied for ConfigDescriptor is NULL, WdfUsbTargetDeviceRetrieveConfigDescriptor returns the required buffer length at the location that is pointed to by ConfigDescriptorLength.
WdfUsbTargetDeviceRetrieveConfigDescriptor returns STATUS_SUCCESS if the operation succeeds. Otherwise, this method can return one of the following values:
Return code | Description |
---|---|
STATUS_INVALID_DEVICE_STATE | A configuration descriptor was not available for the specified target. |
STATUS_INVALID_PARAMETER | An invalid parameter was detected. |
STATUS_BUFFER_TOO_SMALL | The specified buffer size was too small for the data, or the caller supplied NULL for the ConfigDescriptor parameter. |
This method also might return other NTSTATUS values.
A bug check occurs if the driver supplies an invalid object handle.
The WdfUsbTargetDeviceRetrieveConfigDescriptor method retrieves all of the specified USB device's configuration information (that is, the configuration descriptor plus any interface or endpoint descriptors that might be present). To learn about the format of this information, see the USB specification.
You can use WdfUsbTargetDeviceSelectConfig to select only the first USB configuration listed in the descriptor list, but you can select multiple interfaces within this single configuration.
Drivers should call WdfUsbTargetDeviceRetrieveConfigDescriptor twice, as follows:
After the second call to WdfUsbTargetDeviceRetrieveConfigDescriptor returns, the buffer that is pointed to by ConfigDescriptor contains a USB_CONFIGURATION_DESCRIPTOR structure, followed by one or more USB_INTERFACE_DESCRIPTOR and USB_ENDPOINT_DESCRIPTOR structures. These latter structures are arranged in the order that is described in the USB specification.
For more information about the WdfUsbTargetDeviceRetrieveConfigDescriptor method and USB I/O targets, see USB I/O Targets.
The following code example calls WdfUsbTargetDeviceRetrieveConfigDescriptor to obtain the required buffer size, calls WdfMemoryCreate to create a memory object and buffer, and then calls WdfUsbTargetDeviceRetrieveConfigDescriptor again to obtain a device's configuration information.
USHORT size;
NTSTATUS ntStatus;
PMY_DEVICE_CONTEXT myDeviceContext;
PUSB_CONFIGURATION_DESCRIPTOR configurationDescriptor = NULL;
WDF_OBJECT_ATTRIBUTES objectAttribs;
WDFMEMORY memoryHandle;
myDeviceContext = GetDeviceContext(Device);
ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
myDeviceContext->WdfUsbTargetDevice,
NULL,
&size
);
if (ntStatus != STATUS_BUFFER_TOO_SMALL) {
return ntStatus;
}
WDF_OBJECT_ATTRIBUTES_INIT(&objectAttribs);
objectAttribs.ParentObject = myDeviceContext->WdfUsbTargetDevice;
ntStatus = WdfMemoryCreate(
&objectAttribs,
NonPagedPool,
POOL_TAG,
size,
&memoryHandle,
(PVOID)&configurationDescriptor
);
if (!NT_SUCCESS(ntStatus)) {
return ntStatus;
}
ntStatus = WdfUsbTargetDeviceRetrieveConfigDescriptor(
myDeviceContext->WdfUsbTargetDevice,
configurationDescriptor,
&size
);
if (!NT_SUCCESS(ntStatus)) {
return ntStatus;
}
WdfUsbTargetDeviceCreateWithParameters
WdfUsbTargetDeviceGetDeviceDescriptor