Fungsi FltSendMessage (fltkernel.h)
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 |