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
篩選驅動程式在 FilterSynchronousOidRequest 和 FilterSynchronousOidRequestComplete 處理程式之間共享狀態的 PVOID 大小儲存位置。 NDIS 保證這一開始指向零值。 如需詳細資訊,請參閱<備註>一節。
傳回值
此函式會傳回下列其中一個適當的NDIS_STATUS碼:
傳回碼 | Description |
---|---|
NDIS_STATUS_SUCCESS | 允許 OID 要求繼續向迷你埠驅動程序傳播。 篩選驅動程式必須針對任何無法辨識的 OID 類型傳回此狀態代碼。 |
NDIS_STATUS_ALREADY_COMPLETE | 停止將 OID 要求向下傳播,並改為將它傳回給狀態為NDIS_STATUS_SUCCESS的呼叫端。 |
|
與 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 要求上呼叫 NdisAllocateCloneOidRequest 或 NdisCancelOidRequest 。 篩選驅動程式不得在透過 FilterSynchronousOidRequest 處理程式收到的 OID 要求上呼叫 NdisFSynchronousOidRequest。
如果篩選驅動程式在其 FilterSynchronousOidRequest 處理程式中引發 IRQL,它必須先將 IRQL 還原到初始層級,才能從 FilterSynchronousOidRequest 處理程式傳回。
規格需求
需求 | 值 |
---|---|
最低支援的用戶端 | Windows 10 (版本 1709) |
目標平台 | Windows |
標頭 | ndis.h (包括 Ndis.h) |
IRQL | <= DISPATCH_LEVEL |
另請參閱
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應