FILTER_SYNCHRONOUS_OID_REQUEST 함수(ndis.h)

아티클
08/07/2023

NDIS는 필터 드라이버의 FilterSynchronousOidRequest 함수를 호출하여 요청이 기본 미니포트 드라이버에 제공되기 전에 동기 OID 요청을 미리 봅니다.

이 함수는 NDIS 6.81 이상에서 지원됩니다.

구문

NDIS_STATUS FILTER_SYNCHRONOUS_OID_REQUEST(
            NDIS_HANDLE      FilterModuleContext,
  [in, out] NDIS_OID_REQUEST *OidRequest,
  [out]     PVOID            *CallContext
);

매개 변수

FilterModuleContext

이 요청의 대상인 필터 모듈의 컨텍스트 영역에 대한 핸들입니다. FilterAttach 함수에서 이 컨텍스트 영역을 만들고 초기화한 필터 드라이버입니다.

[in, out] OidRequest

요청된 작업을 지정하는 NDIS_OID_REQUEST 구조체에 대한 포인터입니다.

[out] CallContext

FilterSynchronousOidRequest와 FilterSynchronousOidRequestComplete 처리기 간에 상태를 공유할 필터 드라이버에 대한 PVOID 크기의 스토리지 슬롯입니다. NDIS는 처음에 이 값이 0을 가리키도록 보장합니다. 자세한 내용은 설명 부분을 참조하세요.

반환 값

이 함수는 다음 적절한 NDIS_STATUS 코드 중 하나를 반환합니다.

반환 코드	설명
NDIS_STATUS_SUCCESS	OID 요청이 미니포트 드라이버로 계속 전파되도록 허용합니다. 필터 드라이버는 인식할 수 없는 유형의 OID에 대해 이 상태 코드를 반환해야 합니다.
NDIS_STATUS_ALREADY_COMPLETE	OID 요청 전파를 중지하고 대신 상태 NDIS_STATUS_SUCCESS 호출자에게 반환합니다.
NDIS_STATUS_BUFFER_TOO_SHORT NDIS_STATUS_INVALID_LENGTH NDIS_STATUS_INVALID_DATA	FilterDirectOidRequest와 동일합니다.
NDIS_STATUS_RESOURCES	FilterDirectOidRequest와 동일하지만 동기 OID 요청을 신속하게 완료해야 하므로 필터 드라이버는 일반적으로 리소스 할당을 피해야 합니다.
NDIS_STATUS_NOT_SUPPORTED	필터 드라이버는 OID를 인식할 수 없기 때문에 이 코드를 반환하면 안됩니다. 필터 드라이버는 필터가 작업을 인식하지만 어떤 이유로 수행할 수 없는 경우에만 이를 반환할 수 있습니다.

설명

FilterSynchronousOidRequest 는 선택적 함수입니다. 필터 드라이버가 미니포트 드라이버로 전송된 동기 OID 요청을 관찰하거나 수정할 필요가 없는 경우 필터 드라이버는 NdisFRegisterFilterDriver를 호출할 때 이 함수의 진입점을 NULL로 설정해야 합니다.

NDIS는 필터 드라이버의 FilterSynchronousOidRequest 함수를 호출하여 지나치게 드라이버에서 시작된 동기 OID 요청을 처리합니다. 필터 드라이버는 다음과 같이 NDIS_OID_REQUEST 구조의 일부 필드를 읽거나 수정할 수 있습니다.

필드	액세스 필터링
헤더	읽기 전용
RequestType	읽기/쓰기
PortNumber	읽기/쓰기
제한 시간	액세스 안 함
RequestId	액세스 안 함
RequestHandle	읽기/쓰기
DATA	읽기/쓰기
NdisReserved	액세스 안 함
MiniportReserved	액세스 안 함
SourceReserved	액세스 안 함
SupportedRevision	읽기/쓰기
Reserved1, Reserved2	액세스 안 함
SwitchId	읽기/쓰기
VPortId	읽기/쓰기
플래그	읽기/쓰기

필터 드라이버는 NDIS_OID_REQUEST 구조를 수정하는 것 외에도 FilterSynchronousOidRequest의 반환 코드를 사용하여 요청을 제어할 수 있습니다.

NDIS_STATUS_SUCCESS: OID는 계속해서 미니포트 드라이버로 전파됩니다.
NDIS_STATUS_ALREADY_COMPLETE: OID는 먼저 미니포트 드라이버로 전파하지 않고 오버리딩 드라이버로 즉시 완료됩니다. OID 요청은 NDIS_STATUS_SUCCESS 있는 오버리딩 드라이버에 완료됩니다.
다른 모든 상태 코드: OID는 먼저 미니포트 드라이버로 전파하지 않고 오버리딩 드라이버로 즉시 다시 완료됩니다. OID 요청은 필터 드라이버에서 반환된 상태 코드를 사용하여 오버리딩 드라이버에 완료됩니다.

필터 드라이버가 FilterSynchronousOidRequestComplete 처리기도 등록하는 경우 NDIS는 FilterSynchronousOidRequest 처리기가 NDIS_STATUS_SUCCESS 반환하는 경우에만 FilterSynchronousOidRequestComplete 처리기가 호출되도록 보장합니다.

FilterSynchronousOidRequest 처리기는 PVOID 크기의 값을 *CallContext에 쓸 수 있으며, OID 요청이 완료되면 동일한 값이 필터 드라이버의 FilterSynchronousOidRequestComplete 처리기에 반환됩니다. 필터 드라이버는 이를 사용하여 두 처리기에서 상태를 전달할 수 있습니다. FilterSynchronousOidRequestComplete 처리기는 FilterSynchronousOidRequest 처리기가 NDIS_STATUS_SUCCESS 반환하는 경우에만 호출되므로 다른 코드를 반환할 때 *CallContext에 값을 쓸 이유가 없습니다. 마찬가지로 필터 드라이버가 FilterSynchronousOidRequestComplete 처리기를 제공하지 않는 경우 *CallContext에 값을 쓸 이유가 없습니다.

필터 드라이버는 FilterSynchronousOidRequest 처리기에서 NDIS_STATUS_PENDING 반환해서는 안 됩니다. 동기 OID 요청은 보류 중이거나 취소할 수 없습니다.

필터 드라이버는 차단, 대기 또는 절전 모드 없이 FilterSynchronousOidRequest 처리기에서 신속하게 반환해야 합니다. 동기 OID 요청은 짧은 대기 시간 작업에만 사용되며 필터 드라이버는 몇 밀리초 내에 계속하거나 완료하기 위해 노력해야 합니다. NDIS는 동기 OID 요청을 서로, 다른 OID 요청 또는 FilterPause에 대해 직렬화하지 않습니다. 필요한 동기화를 구현하는 것은 필터 드라이버의 책임입니다.

NDIS는 FilterDetach에 대해 동기 OID 요청을 직렬화합니다. NDIS는 FilterDetach 가 호출된 후 동기 OID 요청이 활성화되지 않도록 보장합니다.

필터 드라이버는 동기 OID 요청에서 NdisAllocateCloneOidRequest 또는 NdisCancelOidRequest 를 호출해서는 안 됩니다. 필터 드라이버는 FilterSynchronousOidRequest 처리기를 통해 수신되는 OID 요청에서 NdisFSynchronousOidRequest 를 호출해서는 안 됩니다.

필터 드라이버가 FilterSynchronousOidRequest 처리기에서 IRQL을 발생시키는 경우 FilterSynchronousOidRequest 처리기에서 반환하기 전에 IRQL을 초기 수준으로 복원해야 합니다.