| UID | title | description | old-location | tech.root | ms.date | keywords | ms.keywords | req.header | req.include-header | req.target-type | req.target-min-winverclnt | req.target-min-winversvr | req.kmdf-ver | req.umdf-ver | req.ddi-compliance | req.unicode-ansi | req.idl | req.max-support | req.namespace | req.assembly | req.type-library | req.lib | req.dll | req.irql | targetos | req.typenames | f1_keywords | topic_type | api_type | api_location | api_name | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
NF:wdfusb.WdfUsbTargetDeviceRetrieveConfigDescriptor |
WdfUsbTargetDeviceRetrieveConfigDescriptor function (wdfusb.h) |
The WdfUsbTargetDeviceRetrieveConfigDescriptor method retrieves the USB configuration descriptor for the USB device that is associated with a specified framework USB device object. |
wdf\wdfusbtargetdeviceretrieveconfigdescriptor.htm |
wdf |
02/26/2018 |
|
DFUsbRef_6c3748fe-16c0-4151-8cbd-42c5882475eb.xml, WdfUsbTargetDeviceRetrieveConfigDescriptor, WdfUsbTargetDeviceRetrieveConfigDescriptor method, kmdf.wdfusbtargetdeviceretrieveconfigdescriptor, wdf.wdfusbtargetdeviceretrieveconfigdescriptor, wdfusb/WdfUsbTargetDeviceRetrieveConfigDescriptor |
wdfusb.h |
Wdfusb.h |
Universal |
1.0 |
2.0 |
DriverCreate, KmdfIrql, KmdfIrql2, UsbKmdfIrql, UsbKmdfIrql2 |
Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF) |
PASSIVE_LEVEL |
Windows |
|
|
|
|
|
[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.
A handle to a USB device object that was obtained from a previous call to WdfUsbTargetDeviceCreateWithParameters.
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.
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 |
|---|---|
|
A configuration descriptor was not available for the specified target. |
|
An invalid parameter was detected. |
|
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:
- Set the ConfigDescriptor pointer to NULL, so that WdfUsbTargetDeviceRetrieveConfigDescriptor will return the required buffer size in the address that ConfigDescriptorLength points to.
- Allocate buffer space to hold the configuration information. For example, a driver might call ExAllocatePoolWithTag to allocate a buffer, or it might call WdfMemoryCreate to create a framework memory object.
- Call WdfUsbTargetDeviceRetrieveConfigDescriptor again, passing it a pointer to the new buffer and the buffer's size.
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;
}