WdfDeviceAddQueryInterface, fonction (wdfqueryinterface.h)

2025-03-22

[S’applique uniquement à KMDF]

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 vers un objet d’appareil framework.

[in] InterfaceConfig

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

Valeur de retour

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 mauvais IRQL.
STATUS_INVALID_PARAMETER	Un paramètre d’entrée (y compris éventuellement les 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	Il y avait une mémoire 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 .

Une vérification des bogues système se produit si le pilote fournit un handle d’objet non valide.

Remarques

Remarque

WdfDeviceAddQueryInterface ne peut pas être appelé pour un appareil de contrôle .

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

Une fois qu’un pilote appelle WdfDeviceAddQueryInterface pour créer une interface définie par le pilote, un autre pilote basé sur le framework peut accéder à l’interface en appelant WdfFdoQueryForInterface.

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

Exemples

L’exemple de code suivant provient de l’exemple de pilote Grille-pain bus. 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;
}

Spécifications

Besoin	Valeur
plateforme cible	Universel
version minimale de KMDF	1.0
En-tête	wdfqueryinterface.h (include Wdf.h)
Bibliothèque	Wdf01000.sys (voir Versioning de la bibliothèque Framework.)
IRQL	PASSIVE_LEVEL
règles de conformité DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)