WdfUsbTargetDeviceRetrieveInformation 函式 (wdfusb.h)

[適用於 KMDF 和 UMDF]

WdfUsbTargetDeviceRetrieveInformation 方法會擷取與指定架構 USB 裝置對象相關聯的 USB 裝置相關信息。

語法

NTSTATUS WdfUsbTargetDeviceRetrieveInformation(
  [in]      WDFUSBDEVICE                UsbDevice,
  [in, out] PWDF_USB_DEVICE_INFORMATION Information
);

參數

[in] UsbDevice

從先前呼叫 WdfUsbTargetDeviceCreateWithParameters 取得的 USB 裝置物件的句柄。

[in, out] Information

接收 USB 裝置資訊的呼叫端配置 WDF_USB_DEVICE_INFORMATION 結構的指標。

傳回值

如果作業成功，WdfUsbTargetDeviceRetrieveInformation 會傳回STATUS_SUCCESS。 否則，此方法可以傳回下列其中一個值：

傳回碼	Description
STATUS_INVALID_PARAMETER	偵測到無效的參數。

 

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

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

備註

如需 WdfUsbTargetDeviceRetrieveInformation 方法和 USB I/O 目標的詳細資訊，請參閱 USB I/O 目標。

在架構 1.11 版和更新版本中，驅動程式可以呼叫 WdfUsbTargetDeviceQueryUsbCapability 來擷取裝置的作業速度。

範例

下列程式代碼範例是 EvtDevicePrepareHardware 回呼函式的一部分，可建立 USB 裝置物件、初始化 WDF_USB_DEVICE_INFORMATION 結構，以及呼叫 WdfUsbTargetDeviceRetrieveInformation。

NTSTATUS
MyEvtDevicePrepareHardware(
    IN WDFDEVICE  Device,
    IN WDFCMRESLIST  ResourceList,
    IN WDFCMRESLIST  ResourceListTranslated
    )
{
    NTSTATUS  status;
    PMY_DEVICE_CONTEXT  pMyDeviceContext;
    WDF_USB_DEVICE_CREATE_CONFIG  Config;

    pMyDeviceContext = GetDeviceContext(Device);

    // If object handle is not NULL, MyEvtDevicePrepareHardware
    // was called previously and the handle is still valid.
    if (pMyDeviceContext->UsbDevice != NULL) {
        return STATUS_SUCCESS;
    }

    WDF_USB_DEVICE_CREATE_CONFIG_INIT(
                                      &Config,
                                      USBD_CLIENT_CONTRACT_VERSION_602
                                      );

    status = WdfUsbTargetDeviceCreateWithParameters(
                                      Device,
                                      &Config,
                                      WDF_NO_OBJECT_ATTRIBUTES,
                                      &pMyDeviceContext->UsbDevice
                                      );
    if (!NT_SUCCESS(status)) {
        return status;
    }

    WDF_USB_DEVICE_INFORMATION_INIT(&deviceInfo);

    status = WdfUsbTargetDeviceRetrieveInformation(
                                      pDeviceContext->UsbDevice, 
                                      &deviceInfo
                                      );
...
}

規格需求

需求	值
目標平台	Universal
最小 KMDF 版本	1.0
最低UMDF版本	2.0
標頭	wdfusb.h (包含 Wdfusb.h)
程式庫	Wdf01000.sys (KMDF) ;WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
DDI 合規性規則	DriverCreate (kmdf) ， KmdfIrql (kmdf) ， KmdfIrql2 (kmdf) ， KmdfIrqlExplicit (kmdf) ， UsbKmdfIrql (kmdf) 、 UsbKmdfIrql2 (kmdf) 、UsbKmdfIrqlExplicit (kmdf)

另請參閱

WDF_USB_DEVICE_INFORMATION

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceQueryUsbCapability