WdfUsbTargetDeviceRetrieveConfigDescriptor 函式 (wdfusb.h)
[適用於 KMDF 和 UMDF]
WdfUsbTargetDeviceRetrieveConfigDescriptor 方法會擷取與指定架構 USB 裝置對象相關聯之 USB 裝置的 USB 組態描述元。
語法
NTSTATUS WdfUsbTargetDeviceRetrieveConfigDescriptor(
[in] WDFUSBDEVICE UsbDevice,
[out] PVOID ConfigDescriptor,
[in, out] PUSHORT ConfigDescriptorLength
);
參數
[in] UsbDevice
從先前呼叫 WdfUsbTargetDeviceCreateWithParameters 取得之 USB 裝置物件的句柄。
[out] ConfigDescriptor
接收 USB_CONFIGURATION_DESCRIPTOR 結構的呼叫端配置緩衝區指標,後面接著一或多個 USB_INTERFACE_DESCRIPTOR 和 USB_ENDPOINT_DESCRIPTOR 結構。 此參數是選擇性的,而且可以 NULL,在此情況下 WdfUsbTargetDeviceRetrieveConfigDescriptor 會傳回所需的緩衝區長度。 如需詳細資訊,請參閱下列一節。
[in, out] ConfigDescriptorLength
提供 ConfigDescriptor 指向之緩衝區長度的位置指標。 如果為 ConfigDescriptor 提供的指標 NULL,WdfUsbTargetDeviceRetrieveConfigDescriptor 會傳回 ConfigDescriptorLength所指向的位置所需的緩衝區長度。
傳回值
如果作業成功,WdfUsbTargetDeviceRetrieveConfigDescriptor 會傳回STATUS_SUCCESS。 否則,這個方法可以傳回下列其中一個值:
傳回碼 | 描述 |
---|---|
|
指定的目標無法使用組態描述元。 |
|
偵測到無效的參數。 |
|
對於數據而言,指定的緩衝區大小太小,或是針對 ConfigDescriptor 參數提供的呼叫端 NULL。 |
此方法也可能 傳回其他NTSTATUS 值。
如果驅動程式提供無效的物件句柄,就會發生錯誤檢查。
言論
WdfUsbTargetDeviceRetrieveConfigDescriptor 方法會擷取所有指定的 USB 裝置組態資訊(也就是組態描述元加上可能存在的任何介面或端點描述元)。 若要瞭解這項資訊的格式,請參閱 USB 規格。
您可以使用 WdfUsbTargetDeviceSelectConfig 只選取描述元清單中所列的第一個 USB 組態,但您可以在此單一設定中選取多個介面。
驅動程式應呼叫 WdfUsbTargetDeviceRetrieveConfigDescriptor 兩次,如下所示:
- 將 ConfigDescriptor 指標設定為 NULL,讓 WdfUsbTargetDeviceRetrieveConfigDescriptor 會傳回 ConfigDescriptorLength 指向的 位址中所需的緩衝區大小。
- 配置緩衝區空間來保存組態資訊。 例如,驅動程式可能會呼叫 ExAllocatePoolWithTag 來配置緩衝區,或者可能會呼叫 WdfMemoryCreate 來建立架構記憶體物件。
- 再次呼叫 WdfUsbTargetDeviceRetrieveConfigDescriptor,將指標傳遞給新的緩衝區和緩衝區的大小。
如需 WdfUsbTargetDeviceRetrieveConfigDescriptor 方法和 USB I/O 目標的詳細資訊,請參閱 USB I/O 目標。
例子
下列程式代碼範例會呼叫 WdfUsbTargetDeviceRetrieveConfigDescriptor 以取得所需的緩衝區大小、呼叫 WdfMemoryCreate 來建立記憶體對象和緩衝區,然後呼叫 WdfUsbTargetDeviceRetrieveConfigDescriptor 以取得裝置的組態資訊。
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;
}
要求
要求 | 價值 |
---|---|
目標平臺 | 普遍 |
最低 KMDF 版本 | 1.0 |
最低 UMDF 版本 | 2.0 |
標頭 | wdfusb.h (包括 Wdfusb.h) |
連結庫 | Wdf01000.sys (KMDF):WUDFx02000.dll (UMDF) |
IRQL | PASSIVE_LEVEL |
DDI 合規性規則 | DriverCreate(kmdf),KmdfIrql(kmdf),KmdfIrql2(kmdf),KmdfIrqlExplicit(kmdf),UsbKmdfIrql(kmdf),UsbKmdfIrql2(kmdf),UsbKmdfIrqlExplicit(kmdf) |