WdfDeviceAddQueryInterface, fonction (wdfqueryinterface.h)

Article
08/08/2023

[S’applique à KMDF uniquement]

La méthode WdfDeviceAddQueryInterface crée une interface définie par le pilote que d’autres pilotes peuvent interroger et utiliser.

Syntaxe

NTSTATUS WdfDeviceAddQueryInterface(
  [in] WDFDEVICE                   Device,
  [in] PWDF_QUERY_INTERFACE_CONFIG InterfaceConfig
);

Paramètres

[in] Device

Handle pour un objet d’appareil d’infrastructure.

[in] InterfaceConfig

Pointeur vers une structure de WDF_QUERY_INTERFACE_CONFIG allouée par le pilote qui décrit l’interface.

Valeur retournée

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

Code de retour	Description
STATUS_INVALID_DEVICE_REQUEST	La méthode a été appelée au niveau de l’IRQL incorrect.
STATUS_INVALID_PARAMETER	Un paramètre d’entrée (y compris éventuellement des membres de la structure WDF_QUERY_INTERFACE_CONFIG) n’était pas valide.
STATUS_INFO_LENGTH_MISMATCH	La taille de la structure WDF_QUERY_INTERFACE_CONFIG était incorrecte.
STATUS_INSUFFICIENT_RESOURCES	La mémoire était insuffisante.

Pour obtenir la liste des valeurs de retour supplémentaires, consultez Erreurs de création d’objets framework.

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

Un bogue système case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

Notes

WdfDeviceAddQueryInterface ne peut pas être appelé pour un périphérique de contrôle.

Les pilotes qui créent des interfaces définies par le pilote appellent généralement WdfDeviceAddQueryInterface à partir d’une fonction de rappel EvtDriverDeviceAdd ou EvtDevicePrepareHardware .

Après qu’un pilote a appelé WdfDeviceAddQueryInterface pour créer une interface définie par le pilote, un autre pilote basé sur l’infrastructure peut accéder à l’interface en appelant WdfFdoQueryForInterface.

Pour plus d’informations sur les interfaces définies par le pilote, consultez Utilisation d’interfaces Driver-Defined.

Exemples

L’exemple de code suivant provient de l’exemple de pilote de bus Toaster . Cet exemple crée une interface définie par le pilote qui utilise la structure TOASTER_INTERFACE_STANDARD de l’exemple de grille-pain.

typedef struct _TOASTER_INTERFACE_STANDARD {
 INTERFACE  InterfaceHeader;
  PTOASTER_GET_CRISPINESS_LEVEL  GetCrispinessLevel;
  PTOASTER_SET_CRISPINESS_LEVEL  SetCrispinessLevel;
  PTOASTER_IS_CHILD_PROTECTED  IsSafetyLockEnabled;
} TOASTER_INTERFACE_STANDARD, *PTOASTER_INTERFACE_STANDARD;

TOASTER_INTERFACE_STANDARD  ToasterInterface;
WDF_QUERY_INTERFACE_CONFIG  qiConfig;

//
// Initialize the ToasterInterface structure.
//
RtlZeroMemory(
              &ToasterInterface,
              sizeof(ToasterInterface)
              );

ToasterInterface.InterfaceHeader.Size = sizeof(ToasterInterface);
ToasterInterface.InterfaceHeader.Version = 1;
ToasterInterface.InterfaceHeader.Context = (PVOID)hChild;

ToasterInterface.InterfaceHeader.InterfaceReference =
        WdfDeviceInterfaceReferenceNoOp;
ToasterInterface.InterfaceHeader.InterfaceDereference =
        WdfDeviceInterfaceDereferenceNoOp;

ToasterInterface.GetCrispinessLevel = Bus_GetCrispinessLevel;
ToasterInterface.SetCrispinessLevel = Bus_SetCrispinessLevel;
ToasterInterface.IsSafetyLockEnabled = Bus_IsSafetyLockEnabled;

//
// Initialize the qiConfig structure.
//
WDF_QUERY_INTERFACE_CONFIG_INIT(
                                &qiConfig,
                                (PINTERFACE)&ToasterInterface,
                                &GUID_TOASTER_INTERFACE_STANDARD,
                                NULL
                                );

//
// Create the interface.
//
status = WdfDeviceAddQueryInterface(
                                    hChild,
                                    &qiConfig
                                    );
if (!NT_SUCCESS(status)) {
    return status;
}

Configuration requise

Condition requise	Valeur
Plateforme cible	Universal
Version KMDF minimale	1.0
En-tête	wdfqueryinterface.h (inclure Wdf.h)
Bibliothèque	Wdf01000.sys (consultez Gestion des versions de la bibliothèque d’infrastructure).)
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)