FltSetStreamHandleContext 函式 (fltkernel.h)

發行項
02/29/2024

FltSetStreamHandleContext 例程會設定數據流句柄的內容。

語法

NTSTATUS FLTAPI FltSetStreamHandleContext(
  [in]            PFLT_INSTANCE             Instance,
  [in]            PFILE_OBJECT              FileObject,
  [in]            FLT_SET_CONTEXT_OPERATION Operation,
  [in]            PFLT_CONTEXT              NewContext,
  [out, optional] PFLT_CONTEXT              *OldContext
);

參數

[in] Instance

迷你篩選驅動程序實例的不透明實例指標，其內容要插入、移除或取代至數據流句柄的內容清單中。

[in] FileObject

檔案數據流之檔案物件的指標。這個參數是必要的，而且不能是 NULL。

[in] Operation

旗標，指定要執行之作業的詳細數據。此參數必須是下列其中一項：

值	意義
FLT_SET_CONTEXT_REPLACE_IF_EXISTS	如果此實例已設定內容， FltSetStreamHandleContext 就會將它取代為 NewContext 中指定的內容。否則，它會將 NewContext 插入數據流句柄的內容清單中。
FLT_SET_CONTEXT_KEEP_IF_EXISTS	如果此實例已設定內容， FltSetStreamHandleContext 會傳回STATUS_FLT_CONTEXT_ALREADY_DEFINED，而且不會取代現有的內容或遞增參考計數。如果尚未設定內容，例程會將 NewContext 插入數據流句柄的內容清單中，並遞增參考計數。

[in] NewContext

要為數據流句柄設定之新內容的指標。這個參數是必要的，而且不能是 NULL。

[out, optional] OldContext

如果已設定 實例參數， 則為呼叫端配置的變數指標，該變數會接收現有數據流句柄內容的位址。這個參數是選擇性的，而且可以是 NULL。如需此參數的詳細資訊，請參閱下列一節。

傳回值

FltSetStreamHandleContext 例程會傳回STATUS_SUCCESS或適當的 NTSTATUS 值，例如下列其中一個錯誤碼：

傳回碼	Description
STATUS_FLT_CONTEXT_ALREADY_DEFINED	如果已為 Operation 指定FLT_SET_CONTEXT_KEEP_IF_EXISTS，這個錯誤碼會指出內容已經附加至數據流句柄。
STATUS_FLT_CONTEXT_ALREADY_LINKED	NewContext 指向的內容已經連結至物件。換句話說，這個錯誤碼表示 NewContext 已在使用中，因為 FltSetXxxContext 例程的呼叫成功。
STATUS_FLT_DELETING_OBJECT	指定的實例正在損毀。這是錯誤碼。
STATUS_INVALID_PARAMETER	傳遞了一個無效的參數。例如， NewContext 參數不會指向有效的數據流句柄內容，或為 Operation 指定了無效的值。
STATUS_NOT_SUPPORTED	發生不支持的情況，例如文件系統不支援此檔案數據流的每個數據流內容，或呼叫端提供 NULL FileObject。

備註

如需內容的詳細資訊，請參閱關於迷你篩選內容。

FltSetStreamHandleContext 例程會在數據流句柄上新增、移除或取代迷你篩選驅動程序實例的內容。迷你篩選驅動程式可以將每個迷你篩選驅動程序實例一個內容附加至數據流句柄。

無法在未開啟的 FileObject 上呼叫 FltSetStreamHandleContext。因此，無法從數據流的預先建立回呼呼叫 FltSetStreamHandleContext ，因為該時間點尚未開啟數據流。不過，迷你篩選可以在預先建立回呼中配置和設定數據流句柄內容、使用完成內容參數將它傳遞至建立后回呼，並在建立后回呼中設定數據流的數據流句柄內容。

參考計數

如果 FltSetStreamHandleContext 成功：

NewContext 上的參考計數會遞增。不再需要 NewContext 時，迷你篩選必須呼叫 FltReleaseContext 以遞減其參考計數。

否則 ，如果 FltSetStreamHandleContext 失敗：

NewContext 上的參考計數保持不變。
如果 OldContext 不是 NULL 且未指向 NULL_CONTEXT則 OldContext 是目前與數據流句柄相關聯之內容的參考指標。呼叫 FltSetStreamHandleContext 的篩選，必須在不再需要內容指標時呼叫 OldContext 的 FltReleaseContext。

不論成功：

呼叫 FltSetStreamHandleContext 的篩選條件必須呼叫 FltReleaseContext，以遞減由 FltAllocateContext 遞增之 NewContext 物件的參考計數。

如需詳細資訊，請參閱參考內容。

其他內容作業

如需詳細資訊，請參閱設定內容和釋放內容：

若要判斷指定檔案是否支持數據流句柄內容，請呼叫 FltSupportsStreamHandleContexts
若要配置新的內容，請呼叫 FltAllocateContext。
若要取得數據流句柄內容，請呼叫 FltGetStreamHandleContext。
若要刪除數據流句柄內容，請呼叫 FltDeleteStreamHandleContext 或 FltDeleteContext。

規格需求

需求	值
最低支援的用戶端	適用於 SP4、Windows XP SP2、Windows Server 2003 SP1 和更新版本的作業系統的 Microsoft Windows 2000 Update 匯總 1 中提供及支援。
目標平台	Universal
標頭	fltkernel.h (包含 Fltkernel.h)
程式庫	Fltmgr.lib
Dll	Fltmgr.sys
IRQL	<= APC_LEVEL