WdfFdoInitQueryProperty, fonction (wdffdo.h)

Article
08/08/2023

[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 de type DEVICE_REGISTRY_PROPERTY qui identifie la propriété d’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 à 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, au 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 retournée

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é d’appareil, 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 le moment où la taille requise est retournée et le moment où 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 la status 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 immuable, car dans ce cas, le pilote ne doit appeler WdfFdoInitQueryProperty qu’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

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
Version UMDF minimale	2.0
En-tête	wdffdo.h (include 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

Partager via