Funzione WdfDeviceAddQueryInterface (wdfqueryinterface.h)

Articolo
02/27/2024

[Si applica solo a KMDF]

Il metodo WdfDeviceAddQueryInterface crea un'interfaccia definita dal driver che altri driver possono eseguire query e usare.

Sintassi

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

Parametri

[in] Device

Handle per un oggetto dispositivo framework.

[in] InterfaceConfig

Puntatore a una struttura di WDF_QUERY_INTERFACE_CONFIG allocata dal driver che descrive l'interfaccia.

Valore restituito

WdfDeviceAddQueryInterface restituisce STATUS_SUCCESS se l'operazione ha esito positivo. In caso contrario, questo metodo potrebbe restituire uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_INVALID_DEVICE_REQUEST	Il metodo è stato chiamato in irQL errato.
STATUS_INVALID_PARAMETER	Un parametro di input (possibilmente inclusi i membri della struttura WDF_QUERY_INTERFACE_CONFIG) non è valido.
STATUS_INFO_LENGTH_MISMATCH	La dimensione della struttura WDF_QUERY_INTERFACE_CONFIG non è corretta.
STATUS_INSUFFICIENT_RESOURCES	Memoria insufficiente.

Per un elenco di valori restituiti aggiuntivi, vedere Errori di creazione di oggetti framework.

Questo metodo potrebbe anche restituire altri valori NTSTATUS.

Un controllo dei bug di sistema si verifica se il driver fornisce un handle di oggetto non valido.

Commenti

Nota

WdfDeviceAddQueryInterface non può essere chiamato per un dispositivo di controllo.

I driver che creano interfacce definite dal driver in genere chiamano WdfDeviceAddQueryInterface dall'interno di una funzione di callback EvtDriverDeviceAdd o EvtDevicePrepareHardware .

Dopo che un driver chiama WdfDeviceAddQueryInterface per creare un'interfaccia definita dal driver, un altro driver basato su framework può accedere all'interfaccia chiamando WdfFdoQueryForInterface.

Per altre informazioni sulle interfacce definite dal driver, vedere Using Driver-Defined Interfaces.For more information about driver-defined interfaces, see Using Driver-Defined Interfaces.

Esempio

L'esempio di codice seguente è tratto dal driver del bus di esempio Tostapane . In questo esempio viene creata un'interfaccia definita dal driver che usa la struttura di TOASTER_INTERFACE_STANDARD dell'esempio di tostapane.

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;
}

Requisiti

Requisito	Valore
Piattaforma di destinazione	Universale
Versione KMDF minima	1.0
Intestazione	wdfqueryinterface.h (include Wdf.h)
Libreria	Wdf01000.sys (vedere Controllo delle versioni della libreria framework).
IRQL	PASSIVE_LEVEL
Regole di conformità DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)