WdfFdoInitQueryProperty, fonction (wdffdo.h)

[S’applique à KMDF et à UMDF]

La méthode WdfFdoInitQueryProperty récupère une propriété d’appareil spécifiée.

Syntaxe

NTSTATUS WdfFdoInitQueryProperty(
  [in]  PWDFDEVICE_INIT          DeviceInit,
  [in]  DEVICE_REGISTRY_PROPERTY DeviceProperty,
  [in]  ULONG                    BufferLength,
  [out] PVOID                    PropertyBuffer,
  [out] PULONG                   ResultLength
);

Paramètres

[in] DeviceInit

Pointeur vers une structure WDFDEVICE_INIT que le pilote a obtenue à partir de sa fonction de rappel EvtDriverDeviceAdd .

[in] DeviceProperty

Valeur d’énumérateur DEVICE_REGISTRY_PROPERTY typée qui identifie la propriété de l’appareil à récupérer.

[in] BufferLength

Taille, en octets, de la mémoire tampon pointée par PropertyBuffer.

[out] PropertyBuffer

Pointeur fourni par l’appelant vers une mémoire tampon allouée par l’appelant qui reçoit la propriété d’appareil demandée. Ce pointeur peut être NULL si le paramètre BufferLength est égal à zéro.

[out] ResultLength

Emplacement fourni par l’appelant qui, en retour, contient la taille, en octets, des informations stockées par WdfFdoInitQueryProperty dans PropertyBuffer. Si la valeur de retour de cette méthode est STATUS_BUFFER_TOO_SMALL, ResultLength reçoit la taille de mémoire tampon requise.

Valeur de retour

Si l’opération réussit, la méthode retourne STATUS_SUCCESS. Les valeurs de retour supplémentaires sont les suivantes :

Code de retour Description
STATUS_BUFFER_TOO_SMALL
La mémoire tampon fournie est trop petite pour recevoir les informations.
STATUS_INVALID_PARAMETER_2
La valeur DeviceProperty spécifiée n’est pas valide.
STATUS_INVALID_DEVICE_REQUEST
La structure WDFDEVICE_INIT n’a pas été obtenue à partir de la fonction de rappel EvtDriverDeviceAdd du pilote.
 

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

Remarques

Avant de recevoir des données de propriété de périphérique, les pilotes doivent généralement effectuer un appel initial à WdfFdoInitQueryProperty pour obtenir la taille de mémoire tampon requise. Pour certaines propriétés, la taille des données peut changer entre l’heure à laquelle la taille requise est retournée et l’heure à laquelle le pilote appelle à nouveau cette routine. Par conséquent, les pilotes doivent appeler WdfFdoInitQueryProperty à l’intérieur d’une boucle qui s’exécute jusqu’à ce que l’état de retour ne soit pas STATUS_BUFFER_TOO_SMALL.

Il est préférable d’utiliser WdfFdoInitQueryProperty uniquement si la taille de mémoire tampon requise est connue et inchangée, car dans ce cas, le pilote doit appeler WdfFdoInitQueryProperty une seule fois. Si la taille de mémoire tampon requise est inconnue ou varie, le pilote doit appeler WdfFdoInitAllocAndQueryProperty.

Le pilote peut appeler WdfFdoInitQueryProperty uniquement avant d’appeler WdfDeviceCreate. Pour plus d’informations sur l’appel de WdfDeviceCreate, consultez Création d’un objet d’appareil Framework.

Après avoir appelé WdfDeviceCreate, un pilote peut obtenir des informations de propriété de périphérique en appelant WdfDeviceQueryProperty.

Pour plus d’informations sur la méthode WdfFdoInitQueryProperty , consultez Création d’objets d’appareil dans un pilote de fonction.

Vous pouvez également utiliser WdfFdoInitQueryPropertyEx pour accéder aux propriétés d’appareil exposées via le modèle de propriété unifié.

Exemples

L’exemple de code suivant obtient une chaîne Unicode qui représente le nom de l’énumérateur d’un appareil et retourne TRUE si la chaîne est « PCI ».

NTSTATUS  status = STATUS_SUCCESS;
WCHAR  enumeratorName[64] = {0};
ULONG  returnSize;
UNICODE_STRING  unicodeEnumName, temp;

status = WdfFdoInitQueryProperty(
                                 DeviceInit,
                                 DevicePropertyEnumeratorName,
                                 sizeof(enumeratorName),
                                 enumeratorName,
                                 &returnSize
                                 );
if(!NT_SUCCESS(status)){
    return status;
}

RtlInitUnicodeString(
                     &unicodeEnumName,
                     enumeratorName
                     );
RtlInitUnicodeString(
                     &temp,
                     L"PCI"
                     );
if(RtlCompareUnicodeString(
                           &unicodeEnumName,
                           &temp,
                           TRUE
                           ) == 0) {
    //
    // This device is a PCI device.
    //
    return TRUE;
}

Configuration requise

   
Plateforme cible Universal
Version KMDF minimale 1.0
Version UMDF minimale 2,0
En-tête wdffdo.h (inclure Wdf.h)
Bibliothèque Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL PASSIVE_LEVEL
Règles de conformité DDI DeviceInitAPI(kmdf), DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)

Voir aussi

WdfDeviceQueryProperty

WdfFdoInitAllocAndQueryProperty