Fungsi FltSendMessage (fltkernel.h)

  • Artikel

FltSendMessage mengirimkan pesan ke aplikasi mode pengguna yang menunggu atas nama driver minifilter atau instans driver minifilter.

Sintaks

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
);

Parameter

[in] Filter

Penunjuk filter buram untuk pemanggil. Parameter ini diperlukan dan tidak boleh NULL.

[in] ClientPort

Penunjuk ke variabel yang berisi penunjuk port klien buram untuk port koneksi antara aplikasi mode pengguna dan driver minifilter mode kernel. Untuk informasi selengkapnya tentang penunjuk port klien, lihat deskripsi parameter ConnectNotifyCallback dalam entri referensi untuk FltCreateCommunicationPort.

[in] SenderBuffer

Penunjuk ke buffer yang dialokasikan pemanggil yang berisi pesan yang akan dikirim ke aplikasi mode pengguna. Parameter ini diperlukan dan tidak boleh NULL.

[in] SenderBufferLength

Ukuran, dalam byte, dari buffer yang dirujuk SenderBuffer . Lihat Keterangan untuk informasi selengkapnya.

[out, optional] ReplyBuffer

Pointer ke buffer yang dialokasikan penelepon yang menerima balasan, jika ada, dari aplikasi. Parameter ini bersifat opsional dan dapat berupa NULL.

[in, out] ReplyLength

Ukuran, dalam byte, dari buffer yang dirujuk ReplyBuffer . Parameter ini bersifat opsional, tetapi harus non-NULL ketika ReplyBuffer bukan NULL.

[in, optional] Timeout

Penunjuk ke nilai batas waktu yang menentukan total waktu absolut atau relatif, dalam satuan 100 nanodetik, di mana pemanggil dapat dimasukkan ke dalam status tunggu sampai pesan diterima oleh aplikasi mode pengguna dan sampai menerima balasan (jika ada yang diharapkan).

Nilai positif menentukan waktu absolut, relatif terhadap 1 Januari 1601. Nilai negatif menentukan interval relatif terhadap waktu saat ini. Atur ke NULL jika penelepon dapat dimasukkan ke dalam status tunggu tanpa batas waktu.

Mengembalikan nilai

FltSendMessage mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai seperti salah satu hal berikut ini:

Menampilkan kode Deskripsi
STATUS_INSUFFICIENT_RESOURCES FltSendMessage mengalami kegagalan alokasi kumpulan. Ini adalah kode kesalahan.
STATUS_PORT_DISCONNECTED Porta komunikasi telah terputus. Ini adalah kode kesalahan.
STATUS_THREAD_IS_TERMINATING Penantian terganggu karena utas telah dihentikan oleh aplikasi atau pengguna.
STATUS_TIMEOUT Interval Batas waktu kedaluwarsa sebelum pesan dapat dikirim atau sebelum balasan diterima. Ini adalah kode sukses.

Keterangan

FltSendMessage mengirimkan pesan ke aplikasi mode pengguna atas nama driver minifilter atau instans driver minifilter.

Jika aplikasi memanggil FilterGetMessage untuk mendapatkan pesan sebelum driver minifilter memanggil FltSendMessage untuk mengirimnya, pesan akan segera dikirimkan. Ini biasanya terjadi ketika aplikasi memanggil FilterGetMessage dari dalam perulangan pesan.

Jika tidak, jika aplikasi belum menelepon untuk mendapatkan pesan, driver minifilter dimasukkan ke dalam status tunggu sebagai berikut:

  • Jika Waktu habis bukan nol dan aplikasi memanggil FilterGetMessage sebelum interval Batas Waktu berakhir, pesan akan dikirimkan.

  • Jika Waktu habis bukan nol dan aplikasi tidak memanggil FilterGetMessage sebelum interval Batas waktu berakhir, pesan tidak dikirim, dan FltSendMessage mengembalikan STATUS_TIMEOUT. (Catatan: STATUS_TIMEOUT adalah kode keberhasilan.)

  • Jika Timeout adalah nol, driver minifilter dimasukkan ke dalam status tunggu tanpa batas waktu. Ketika aplikasi memanggil FilterGetMessage, pesan dikirimkan.

Setelah pesan dikirim, jika ReplyBufferNULL, FltSendMessage mengembalikan STATUS_SUCCESS.

Jika tidak, jika ReplyBuffer bukan NULL, driver minifilter dimasukkan ke dalam status tunggu sebagai berikut:

  • Jika Timeout bukan nol dan aplikasi memanggil FilterReplyMessage sebelum interval Timeout kedaluwarsa, driver minifilter menerima balasan, dan FltSendMessage mengembalikan STATUS_SUCCESS.

  • Jika Timeout bukan nol dan driver minifilter tidak menerima balasan sebelum interval Timeout kedaluwarsa, FltSendMessage akan mengembalikan STATUS_TIMEOUT. (Catatan: STATUS_TIMEOUT adalah kode keberhasilan.)

  • Jika Timeout adalah nol ketika driver minifilter menunggu balasan, driver minifilter dimasukkan ke dalam status tunggu tanpa batas waktu. Ketika aplikasi memanggil FilterReplyMessage, driver minifilter menerima balasan, dan FltSendMessage mengembalikan STATUS_SUCCESS.

Catatan

 Karena persyaratan padding struktur (khusus sistem), akurasi diperlukan saat Anda mengatur ukuran buffer yang terkait dengan FltSendMessage dan FilterReplyMessage. Sebagai contoh, asumsikan data harus dikirim melalui FilterReplyMessage ke minifilter. Komponen mode pengguna mungkin mendeklarasikan struktur berikut untuk melakukannya:

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

Mengingat struktur ini, mungkin tampak jelas bahwa pemanggil FilterReplyMessage akan mengatur dwReplyBufferSize ke sizeof(REPLY_STRUCT), dan mengatur parameter ReplyLengthFltSendMessage ke nilai yang sama. Namun, karena struktur padding idiosyncrasies, sizeof(REPLY_STRUCT) mungkin lebih besar dari sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT). Jika demikian, FltSendMessage mengembalikan STATUS_BUFFER_OVERFLOW.

Oleh karena itu, disarankan agar Anda memanggil FilterReplyMessage dan FltSendMessage (memanfaatkan contoh di atas) dengan mengatur dwReplyBufferSize dan ReplyLength ke sizeof(FILTER_REPLY_HEADER) + sizeof(MY_STRUCT) bukan sizeof(REPLY_STRUCT). Ini memastikan bahwa setiap padding tambahan di akhir struktur REPLY_STRUCT diabaikan.

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Microsoft Windows 2000 Update Rollup 1 untuk SP4, Windows XP SP2, Windows Server 2003 SP1, dan sistem operasi yang lebih baru.
Target Platform Universal
Header fltkernel.h (termasuk FltKernel.h)
Pustaka FltMgr.lib
DLL Fltmgr.sys
IRQL <= APC_LEVEL

Lihat juga

FilterGetMessage

FilterReplyMessage

FilterSendMessage

FltCreateCommunicationPort