WdfUsbTargetDeviceRetrieveConfigDescriptor 函式 (wdfusb.h)

發行項
02/27/2024

[適用於 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。否則，此方法可以傳回下列其中一個值：

傳回碼	Description
STATUS_INVALID_DEVICE_STATE	指定的目標無法使用組態描述元。
STATUS_INVALID_PARAMETER	偵測到無效的參數。
STATUS_BUFFER_TOO_SMALL	指定的緩衝區大小對數據而言太小，或是為 ConfigDescriptor 參數提供 NULL 的呼叫端。

這個方法也可能傳回其他 NTSTATUS值。

如果驅動程式提供無效的物件句柄，就會發生錯誤檢查。

備註

WdfUsbTargetDeviceRetrieveConfigDescriptor 方法會擷取所有指定的 USB 裝置組態資訊 (，也就是組態描述元加上可能) 的任何介面或端點描述元。若要瞭解這項資訊的格式，請參閱 USB 規格。

您可以使用 WdfUsbTargetDeviceSelectConfig 只選取描述元清單中所列的第一個 USB 組態，但您可以在此單一組態中選取多個介面。

驅動程序應該呼叫 WdfUsbTargetDeviceRetrieveConfigDescriptor 兩次，如下所示：

將 ConfigDescriptor 指標設定為 NULL，讓 WdfUsbTargetDeviceRetrieveConfigDescriptor 會傳回 ConfigDescriptorLength 指向的位址中所需的緩衝區大小。
配置緩衝區空間來保存組態資訊。例如，驅動程式可能會呼叫 ExAllocatePoolWithTag 來配置緩衝區，或者它可能會呼叫 WdfMemoryCreate 來建立架構記憶體物件。
再次呼叫 WdfUsbTargetDeviceRetrieveConfigDescriptor ，並將指標傳遞給新的緩衝區和緩衝區的大小。

第二次呼叫 WdfUsbTargetDeviceRetrieveConfigDescriptor 傳回之後， ConfigDescriptor 所指向的緩衝區會包含 USB_CONFIGURATION_DESCRIPTOR 結構，後面接著一或多個 USB_INTERFACE_DESCRIPTOR 和 USB_ENDPOINT_DESCRIPTOR 結構。這些後者的結構會依照 USB 規格中所述的順序排列。

如需 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;
}

規格需求

需求	值
目標平台	Universal
最小 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)