共用方式為


FILTER_SYNCHRONOUS_OID_REQUEST函式 (ndis.h)

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

篩選驅動程式在 FilterSynchronousOidRequestFilterSynchronousOidRequestComplete 處理程式之間共享狀態的 PVOID 大小儲存位置。 NDIS 保證這一開始指向零值。 如需詳細資訊,請參閱<備註>一節。

傳回值

此函式會傳回下列其中一個適當的NDIS_STATUS碼:

傳回碼 Description
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 讀取/寫入
Flags 讀取/寫入

除了修改 NDIS_OID_REQUEST 結構之外,篩選驅動程式還可以使用 FilterSynchronousOidRequest 的傳回碼來控制要求:

  • NDIS_STATUS_SUCCESS:OID 會繼續向下傳播至迷你埠驅動程式。
  • NDIS_STATUS_ALREADY_COMPLETE:OID 會立即完成回到超載驅動程式,而不需要先向迷你埠驅動程序傳播。 OID 要求已完成至具有NDIS_STATUS_SUCCESS的超載驅動程式。
  • 任何其他狀態代碼:OID 會立即完成回到超載驅動程式,而不需要先向下傳播至迷你埠驅動程式。 OID 要求已完成至超載驅動程式,且篩選驅動程式所傳回的狀態代碼。

如果篩選驅動程式也註冊 FilterSynchronousOidRequestComplete 處理程式,NDIS 會保證 FilterSynchronousOidRequestComplete 處理程式只有在 FilterSynchronousOidRequest 處理程式傳回NDIS_STATUS_SUCCESS時才會呼叫。

FilterSynchronousOidRequest 處理程式可以將任何 PVOID 大小的值寫入 *CallContext,而且當 OID 要求完成時,相同的值將會傳回至篩選驅動程式的 FilterSynchronousOidRequestComplete 處理程式。 篩選驅動程式可以使用這個,在兩個處理程式之間執行狀態。 由於 FilterSynchronousOidRequestComplete 處理程式只有在 FilterSynchronousOidRequest 處理程式傳回NDIS_STATUS_SUCCESS時,才叫用 FilterSynchronousOidRequest 處理程式,因此傳回任何其他程式代碼時,沒有任何理由將值寫入 *CallContext 。 同樣地,如果篩選驅動程式未提供 FilterSynchronousOidRequestComplete 處理程式,則沒有任何理由將值寫入 *CallContext

篩選驅動程式不得從 FilterSynchronousOidRequest 處理程式傳回NDIS_STATUS_PENDING。 同步 OID 要求無法畫筆或取消。

篩選驅動程式預期會從其 FilterSynchronousOidRequest 處理程式快速傳回,而不會封鎖、等候或睡眠。 同步 OID 要求僅用於低延遲作業,而篩選驅動程式應該努力在數毫秒內繼續或完成這些要求。 NDIS 不會針對彼此串行化同步 OID 要求、針對其他 OID 要求,或針對 FilterPause 串行化同步 OID 要求。 篩選驅動程式負責實作任何所需的同步處理。

NDIS 會針對 FilterDetach 串行化同步 OID 要求:NDIS 保證在叫用 FilterDetach 之後,不會有任何同步 OID 要求作用中。

篩選驅動程式不得在同步 OID 要求上呼叫 NdisAllocateCloneOidRequestNdisCancelOidRequest 。 篩選驅動程式不得在透過 FilterSynchronousOidRequest 處理程式收到的 OID 要求上呼叫 NdisFSynchronousOidRequest

如果篩選驅動程式在其 FilterSynchronousOidRequest 處理程式中引發 IRQL,它必須先將 IRQL 還原到初始層級,才能從 FilterSynchronousOidRequest 處理程式傳回。

規格需求

需求
最低支援的用戶端 Windows 10 (版本 1709)
目標平台 Windows
標頭 ndis.h (包括 Ndis.h)
IRQL <= DISPATCH_LEVEL

另請參閱

FilterSynchronousOidRequestComplete

NdisFSynchronousOidRequest

NDIS 6.80 中的同步 OID 要求介面