WdfUsbTargetDeviceRetrieveInformation, fonction (wdfusb.h)

Article
02/07/2025

[S’applique à KMDF et UMDF]

La méthode WdfUsbTargetDeviceRetrieveInformation récupère des informations sur le périphérique USB associé à un objet d’appareil USB de framework spécifié.

Syntaxe

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

Paramètres

[in] UsbDevice

Handle vers un objet de périphérique USB obtenu à partir d’un appel précédent à WdfUsbTargetDeviceCreateWithParameters.

[in, out] Information

Pointeur vers une structure WDF_USB_DEVICE_INFORMATION allouée par l’appelant qui reçoit des informations sur l’appareil USB.

Valeur de retour

WdfUsbTargetDeviceRetrieveInformation retourne STATUS_SUCCESS si l’opération réussit. Sinon, cette méthode peut retourner l’une des valeurs suivantes :

Retourner le code	Description
STATUS_INVALID_PARAMETER	Un paramètre non valide a été détecté.

Cette méthode peut également retourner d’autres valeurs NTSTATUS .

Une vérification de bogue se produit si le pilote fournit un handle d’objet non valide.

Remarques

Pour plus d’informations sur la méthode WdfUsbTargetDeviceRetrieveInformation et les cibles d’E/S USB, consultez cibles d’E/S USB.

Dans les versions 1.11 et ultérieures de l’infrastructure, le pilote peut appeler WdfUsbTargetDeviceQueryUsbCapability pour récupérer la vitesse d’exploitation d’un appareil.

Exemples

L’exemple de code suivant fait partie d’une fonction de rappel EvtDevicePrepareHardware qui crée un objet d’appareil USB, initialise une structure de WDF_USB_DEVICE_INFORMATION et appelle 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
                                      );
...
}

Exigences

Exigence	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
version minimale de UMDF	2.0
d’en-tête	wdfusb.h (include Wdfusb.h)
bibliothèque	Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL	<=DISPATCH_LEVEL
règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), UsbKmdfIrql(kmdf), UsbKmdfIrql2(kmdf), UsbKmdfIrqlExplicit(kmdf)

Voir aussi

WDF_USB_DEVICE_INFORMATION

WdfUsbTargetDeviceCreateWithParameters

WdfUsbTargetDeviceQueryUsbCapability

Partager via