EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST 콜백 함수(wdfqueryinterface.h)

아티클
07/16/2024

[KMDF에만 적용]

드라이버의 EvtDeviceProcessQueryInterfaceRequest 이벤트 콜백 함수는 프레임워크가 요청 드라이버에 인터페이스를 전달하기 전에 드라이버 정의 인터페이스에 대한 액세스에 대한 다른 드라이버의 요청을 검사합니다.

통사론

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST EvtWdfDeviceProcessQueryInterfaceRequest;

NTSTATUS EvtWdfDeviceProcessQueryInterfaceRequest(
  [in]      WDFDEVICE Device,
  [in]      LPGUID InterfaceType,
  [in, out] PINTERFACE ExposedInterface,
  [in, out] PVOID ExposedInterfaceSpecificData
)
{...}

매개 변수

[in] Device

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

[in] InterfaceType

드라이버 정의 인터페이스를 식별하는 GUID에 대한 포인터입니다.

[in, out] ExposedInterface

드라이버 정의 인터페이스를 설명하고 인터페이스에 대한 액세스를 요청하는 드라이버에서 제공한 INTERFACE 구조체에 대한 포인터입니다.

[in, out] ExposedInterfaceSpecificData

추가적인 선택적 드라이버 정의 인터페이스 관련 정보에 대한 포인터입니다. 프레임워크 기반 드라이버는 WdfFdoQueryForInterface호출할 때NULLInterfaceSpecificData 매개 변수 값을 제공하여 이 값을 지정합니다.

반환 값

EvtDeviceProcessQueryInterfaceRequest 콜백 함수가 지원하는 GUID를 수신하고 함수에 오류가 발생하지 않으면 STATUS_SUCCESS 또는 NT_SUCCESS(상태)가 TRUE다른 상태 값을 반환해야 합니다. 프레임워크는 추가 드라이버도 인터페이스를 지원하는지 확인하기 위해 스택 아래로 요청을 계속 전달합니다.

EvtDeviceProcessQueryInterfaceRequest 콜백 함수는 특정 경우 인터페이스를 서비스하지 않는다고 판단되는 경우 STATUS_NOT_SUPPORTED 반환해야 합니다. 프레임워크는 요청을 스택 아래로 계속 전달하여 다른 드라이버가 인터페이스를 지원하는지 확인합니다. 이 상황에 대한 자세한 내용은 다음 주의 섹션을 참조하세요.

콜백 함수에 오류가 발생하면 NT_SUCCESS(상태)가 FALSE상태 값을 반환해야 합니다. 프레임워크는 인터페이스에 대한 다른 드라이버의 요청에 실패하고 스택 아래로 요청을 전달하지 않습니다.

발언

프레임워크 기반 드라이버는 WdfDeviceAddQueryInterface호출하여 EvtDeviceProcessQueryInterfaceRequest 이벤트 콜백 함수를 등록합니다.

드라이버 정의 인터페이스가 단방향 통신만 지원하고 인터페이스를 설명하는 WDF_QUERY_INTERFACE_CONFIG 구조체의 ImportInterface 멤버를 설정하여 FALSE경우 EvtDeviceProcessQueryInterfaceRequest 콜백 함수는 선택 사항입니다. 다른 드라이버가 WdfFdoQueryForInterface호출하는 경우 프레임워크는 드라이버 정의 인터페이스 값을 요청 드라이버의 INTERFACE 구조에 복사한 다음 콜백 함수를 호출합니다. 단방향 통신의 경우 프레임워크가 요청 드라이버에 반환하기 전에 인터페이스 값을 검사하고 수정하려는 경우에만 콜백 함수를 제공해야 합니다.

드라이버가 양방향 통신을 지원하는 인터페이스를 정의하고 WDF_QUERY_INTERFACE_CONFIG 구조의 ImportInterface 멤버를 TRUE설정하는 경우 드라이버는 EvtDeviceProcessQueryInterfaceRequest 이벤트 콜백 함수를 제공해야 합니다. importInterface TRUE 다른 드라이버가 WdfFdoQueryForInterface호출하는 경우 프레임워크는 드라이버 정의 인터페이스를 요청 드라이버의 인터페이스 구조에 복사하지 않기 때문에 콜백 함수가 필요합니다. 대신 콜백 함수는 요청 드라이버의 인터페이스 구조를 업데이트해야 합니다.

콜백 함수는 인터페이스를 수정할 수 있습니다. 특히 다음을 수행할 수 있습니다.

인터페이스의 모든 멤버에서 값을 변경합니다.
INTERFACE 구조체의 Context 멤버를 수정하여 동적 인스턴스별 컨텍스트를 할당합니다.

프레임워크는 WdfDeviceAddQueryInterface호출하여 드라이버가 등록한 GUID에 대해서만 드라이버의 EvtDeviceProcessQueryInterfaceRequest 콜백 함수를 호출합니다. 따라서 이러한 콜백 함수는 STATUS_NOT_SUPPORTED 반환 값을 사용하여 예기치 않은 GUID를 보고하지 않습니다. 대신, EvtDeviceProcessQueryInterfaceRequest 콜백 함수는 특정 경우 인터페이스를 처리하지 않는다고 결정할 때 STATUS_NOT_SUPPORTED 반환해야 합니다. 예를 들어 요청 드라이버가 제공하는 데이터에 따라 드라이버는 하위 수준 드라이버가 인터페이스 요청을 처리해야 한다고 결정할 수 있습니다. STATUS_NOT_SUPPORTED 반환 값은 드라이버가 인터페이스 요청을 처리하지 않지만 하위 수준 드라이버가 서비스할 수 있음을 프레임워크에 알릴 수 있습니다.

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

예제

EvtDeviceProcessQueryInterfaceRequest 콜백 함수를 정의하려면 먼저 정의하는 콜백 함수의 형식을 식별하는 함수 선언을 제공해야 합니다. Windows는 드라이버에 대한 콜백 함수 형식 집합을 제공합니다. 콜백 함수 형식을 사용하여 함수를 선언하면 드라이버, SDV(정적 드라이버 검증 도구) 및 기타 확인 도구에 대한 코드 분석을 데 도움이 되며 Windows 운영 체제용 드라이버를 작성하기 위한 요구 사항입니다.

예를 들어 MyDeviceProcessQueryInterfaceRequest명명된 EvtDeviceProcessQueryInterfaceRequest 콜백 함수를 정의하려면 다음 코드 예제와 같이 EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST 형식을 사용합니다.

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST  MyDeviceProcessQueryInterfaceRequest;

그런 다음 다음과 같이 콜백 함수를 구현합니다.

_Use_decl_annotations_
NTSTATUS
 MyDeviceProcessQueryInterfaceRequest (
    WDFDEVICE  Device,
    LPGUID  InterfaceType,
    PINTERFACE  ExposedInterface,
    PVOID  ExposedInterfaceSpecificData
    )
  {...}

EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST 함수 형식은 WdfQueryInterface.h 헤더 파일에 정의됩니다. 코드 분석 도구를 실행할 때 오류를 보다 정확하게 식별하려면 함수 정의에 Use_decl_annotations 주석을 추가해야 합니다. Use_decl_annotations 주석은 헤더 파일의 EVT_WDF_DEVICE_PROCESS_QUERY_INTERFACE_REQUEST 함수 형식에 적용되는 주석이 사용되는지 확인합니다. 함수 선언 요구 사항에 대한 자세한 내용은 KMDF 드라이버함수 역할 형식을 사용하여 함수 선언을 참조하세요. Use_decl_annotations대한 자세한 내용은 함수 동작주석 참조하세요.