FltSendMessage 函式 (fltkernel.h)

  • 發行項

FltSendMessage 代表迷你篩選驅動程式或迷你篩選驅動程序實例將訊息傳送至等候的使用者模式應用程式。

語法

NTSTATUS FLTAPI FltSendMessage(
  [in]            PFLT_FILTER    Filter,
  [in]            PFLT_PORT      *ClientPort,
  [in]            PVOID          SenderBuffer,
  [in]            ULONG          SenderBufferLength,
  [out, optional] PVOID          ReplyBuffer,
  [in, out]       PULONG         ReplyLength,
  [in, optional]  PLARGE_INTEGER Timeout
);

參數

[in] Filter

呼叫端的不透明篩選指標。 這個參數是必要的，而且不能是 NULL。

[in] ClientPort

變數的指標，其中包含使用者模式應用程式與核心模式迷你篩選驅動程式之間的聯機埠不透明用戶端埠指標。 如需用戶端埠指標的詳細資訊，請參閱 FltCreateCommunicationPort 參考專案中 ConnectNotifyCallback 參數的描述。

[in] SenderBuffer

呼叫端配置的緩衝區指標，其中包含要傳送至使用者模式應用程式的訊息。 這個參數是必要的，而且不能是 NULL。

[in] SenderBufferLength

SenderBuffer 指向之緩衝區的大小，以位元組為單位。 如需詳細資訊 ，請參閱 。

[out, optional] ReplyBuffer

從應用程式接收回復之呼叫端配置緩衝區的指標。 此參數是選擇性的，可以是 NULL。

[in, out] ReplyLength

ReplyBuffer 指向之緩衝區的大小，以位元組為單位。 此參數是選擇性的，但當 ReplyBuffer 不是 NULL 時，必須是非 NULL。

[in, optional] Timeout

逾時值的指標，指定以100奈秒為單位的總絕對或相對時間長度，呼叫端可以放入等候狀態，直到使用者模式應用程式收到訊息，直到收到回復 (，如果預期) 。

正值會指定絕對時間，相對於 1601 年 1 月 1 日。 負值會指定相對於目前時間的間隔。 如果呼叫端可以無限期地進入等候狀態，請將 設定為 NULL 。

傳回值

FltSendMessage 會傳回STATUS_SUCCESS或適當的 NTSTATUS 值，例如下列其中一項：

傳回碼 Description
STATUS_INSUFFICIENT_RESOURCES FltSendMessage 發生集區配置失敗。 這是錯誤碼。
STATUS_PORT_DISCONNECTED 通訊埠已中斷連線。 這是錯誤碼。
STATUS_THREAD_IS_TERMINATING 等候已中斷，因為線程已由應用程式或用戶終止。
STATUS_TIMEOUT 逾時間隔在訊息可以傳遞之前或收到回復之前過期。 這是成功的程序代碼。

備註

FltSendMessage 代表迷你篩選驅動程式或迷你篩選驅動程序實例將訊息傳送至使用者模式應用程式。

如果應用程式呼叫 FilterGetMessage 以在迷你篩選驅動程式呼叫 FltSendMessage 以傳送訊息之前取得訊息，則會立即傳遞訊息。 這通常是當應用程式從訊息循環內部呼叫 FilterGetMessage 時的情況。

否則，如果應用程式尚未呼叫 以取得訊息，迷你篩選驅動程式會進入等候狀態，如下所示：

  • 如果 Timeout 為非零，且應用程式會在逾時間隔到期之前呼叫 FilterGetMessage，則會傳遞訊息。

  • 如果 Timeout 不是零的，而且應用程式不會在逾時間隔到期之前呼叫 FilterGetMessage，則不會傳遞訊息，且 FltSendMessage 會傳回STATUS_TIMEOUT。 (注意：STATUS_TIMEOUT是成功的程式代碼。)

  • 如果 Timeout 為零，迷你篩選驅動程式會無限期地進入等候狀態。 當應用程式呼叫 FilterGetMessage 時，就會傳遞訊息。

傳遞訊息之後，如果 ReplyBuffer 為 NULL，FltSendMessage 會傳回STATUS_SUCCESS。

否則，如果 ReplyBuffer 不是 NULL，迷你篩選驅動程式會進入等候狀態，如下所示：

  • 如果 Timeout 為非零，而且應用程式會在逾時間隔到期之前呼叫 FilterReplyMessage，則迷你篩選驅動程式會收到回復，而 FltSendMessage 會傳回STATUS_SUCCESS。

  • 如果 Timeout 是非零的，而且迷你篩選驅動程式在 逾 時間隔到期之前不會收到回復， FltSendMessage 會傳回STATUS_TIMEOUT。 (注意：STATUS_TIMEOUT是成功的程式代碼。)

  • 如果迷你篩選驅動程式正在等候回復時，逾時為零，則迷你篩選驅動程式會無限期進入等候狀態。 當應用程式呼叫 FilterReplyMessage 時，迷你篩選驅動程式會收到回復， 而 FltSendMessage 會傳回STATUS_SUCCESS。

注意

 由於 (系統特定的) 結構填補需求，因此當您設定與 FltSendMessage 和 FilterReplyMessage 相關聯的緩衝區大小時，需要精確度。 例如，假設數據必須透過 FilterReplyMessage 傳送至迷你篩選程式。 使用者模式元件可能會宣告下列結構來執行此動作：

typedef struct _REPLY_STRUCT
{
    FILTER_REPLY_HEADER Header;
    MY_STRUCT Data;  // The structure to be sent to the minifilter
} REPLY_STRUCT, *PREPLY_STRUCT;

假設有這個結構，FilterReplyMessage 的呼叫端可能會將 dwReplyBufferSizesizeof(REPLY_STRUCT)設定為 ，並將 FltSendMessage 的 ReplyLength 參數設定為相同的值。 不過，由於結構填補 idiosyncrasies， sizeof(REPLY_STRUCT) 可能會大於 sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT)。 如果是這種情況， FltSendMessage 會傳回STATUS_BUFFER_OVERFLOW。

因此，建議您藉由將 dwReplyBufferSize 和 ReplyLength 設定為 sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT)sizeof(REPLY_STRUCT)，藉此呼叫 FilterReplyMessage 和 FltSendMessage (利用上述範例) 。 這可確保忽略REPLY_STRUCT結構結尾處的任何額外填補。

規格需求

需求 值
最低支援的用戶端 適用於 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

另請參閱

FilterGetMessage

FilterReplyMessage

FilterSendMessage

FltCreateCommunicationPort