WdfDeviceAddQueryInterface 함수(wdfqueryinterface.h)

아티클
02/27/2024

[KMDF에만 적용]

WdfDeviceAddQueryInterface 메서드는 다른 드라이버가 쿼리하고 사용할 수 있는 드라이버 정의 인터페이스를 만듭니다.

구문

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

매개 변수

[in] Device

프레임워크 디바이스 개체에 대한 핸들입니다.

[in] InterfaceConfig

인터페이스를 설명하는 드라이버 할당 WDF_QUERY_INTERFACE_CONFIG 구조체에 대한 포인터입니다.

반환 값

WdfDeviceAddQueryInterface 는 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_INVALID_DEVICE_REQUEST	메서드가 잘못된 IRQL에서 호출되었습니다.
STATUS_INVALID_PARAMETER	입력 매개 변수(WDF_QUERY_INTERFACE_CONFIG 구조체의 멤버 포함)가 잘못되었습니다.
STATUS_INFO_LENGTH_MISMATCH	WDF_QUERY_INTERFACE_CONFIG 구조체의 크기가 잘못되었습니다.
STATUS_INSUFFICIENT_RESOURCES	메모리가 부족했습니다.

추가 반환 값 목록은 프레임워크 개체 만들기 오류를 참조하세요.

이 메서드는 다른 NTSTATUS 값을 반환할 수도 있습니다.

드라이버가 잘못된 개체 핸들을 제공하는 경우 시스템 버그 검사 발생합니다.

설명

참고

WdfDeviceAddQueryInterface는 제어 디바이스에 대해 호출할 수 없습니다.

드라이버 정의 인터페이스를 만드는 드라이버는 일반적으로 EvtDriverDeviceAdd 또는 EvtDevicePrepareHardware 콜백 함수 내에서 WdfDeviceAddQueryInterface를 호출합니다.

드라이버가 WdfDeviceAddQueryInterface 를 호출하여 드라이버 정의 인터페이스를 만든 후 다른 프레임워크 기반 드라이버는 WdfFdoQueryForInterface를 호출하여 인터페이스에 액세스할 수 있습니다.

드라이버 정의 인터페이스에 대한 자세한 내용은 Driver-Defined 인터페이스 사용을 참조하세요.

예제

다음 코드 예제는 Toaster 샘플 버스 드라이버에서 가져옵니다. 이 예제에서는 토스터 샘플의 TOASTER_INTERFACE_STANDARD 구조를 사용하는 드라이버 정의 인터페이스를 만듭니다.

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

요구 사항

요구 사항	값
대상 플랫폼	유니버설
최소 KMDF 버전	1.0
머리글	wdfqueryinterface.h(Wdf.h 포함)
라이브러리	Wdf01000.sys(프레임워크 라이브러리 버전 관리 참조)
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)