Fungsi FltCreateCommunicationPort (fltkernel.h)

Artikel
07/16/2024

FltCreateCommunicationPort membuat port server komunikasi tempat minifilter dapat menerima permintaan koneksi dari aplikasi dan layanan mode pengguna.

Sintaksis

NTSTATUS FLTAPI FltCreateCommunicationPort(
  PFLT_FILTER            Filter,
  PFLT_PORT              *ServerPort,
  POBJECT_ATTRIBUTES     ObjectAttributes,
  PVOID                  ServerPortCookie,
  PFLT_CONNECT_NOTIFY    ConnectNotifyCallback,
  PFLT_DISCONNECT_NOTIFY DisconnectNotifyCallback,
  PFLT_MESSAGE_NOTIFY    MessageNotifyCallback,
  LONG                   MaxConnections
);

Parameter

Filter

[di] Penunjuk filter buram untuk pemanggil.

ServerPort

[out] Penunjuk ke variabel yang dialokasikan pemanggil yang menerima handel port buram untuk port server komunikasi. Minifilter menggunakan handel ini untuk mendengarkan permintaan koneksi masuk dari aplikasi mode pengguna.

ObjectAttributes

[di] Penunjuk ke struktur OBJECT_ATTRIBUTES yang menentukan atribut port server komunikasi. Struktur ini harus diinisialisasi oleh panggilan sebelumnya ke InitializeObjectAttributes. Parameter ini diperlukan dan tidak boleh NULL. Anggota struktur ini untuk objek port komunikasi mencakup yang berikut ini.

Anggota	Nilai
Panjang	InitializeObjectAttributes mengatur anggota ini ke `sizeof(OBJECT_ATTRIBUTES)`.
ObjectName	Penunjuk ke struktur UNICODE_STRING yang berisi nama unik (misalnya, L"\MyFilterPort") untuk objek port.
SecurityDescriptor	Penunjuk ke deskriptor keamanan (SECURITY_DESCRIPTOR) untuk diterapkan ke objek port. Jika diperlukan, deskriptor keamanan default dapat dibuat dengan memanggil FltBuildDefaultSecurityDescriptor.
Atribut	Bitmask bendera yang menentukan atribut yang diinginkan untuk handel port. Bendera ini harus menyertakan OBJ_KERNEL_HANDLE. Pemanggil juga dapat secara opsional mengatur bendera OBJ_CASE_INSENSITIVE, yang menunjukkan bahwa kode pencarian nama harus mengabaikan kasus ObjectName daripada melakukan pencarian yang sama persis.

ServerPortCookie

[dalam, opsional] Penunjuk ke informasi konteks yang ditentukan oleh minifilter. Informasi ini dapat digunakan untuk membedakan antara beberapa port server komunikasi yang dibuat oleh minifilter yang sama. FltMgr meneruskan penunjuk konteks ini sebagai parameter ke connectNotifyCallback rutinitas. Parameter ini bersifat opsional dan dapat berupa NULL.

ConnectNotifyCallback

[di] Penunjuk ke rutinitas panggilan balik ConnectNotifyCallback. FltMgr memanggil rutinitas ini setiap kali aplikasi mode pengguna memanggil FilterConnectCommunicationPort untuk mengirim permintaan koneksi ke minifilter. Parameter ini diperlukan dan tidak boleh NULL.

DisconnectNotifyCallback

[di] Penunjuk ke rutinitas panggilan balik DisconnectNotifyCallback. FltMgr memanggil rutinitas ini setiap kali jumlah handel mode pengguna untuk port klien mencapai nol atau ketika minifilter akan dibongkar. Parameter ini diperlukan dan tidak boleh NULL.

MessageNotifyCallback

[dalam, opsional] Penunjuk ke rutinitas panggilan balik messageNotifyCallback yang disediakan penelepon. FltMgr memanggil rutinitas ini setiap kali aplikasi mode pengguna memanggil FilterSendMessage untuk mengirim pesan ke minifilter melalui port klien. Parameter ini bersifat opsional dan dapat berupa NULL. Jika NULL, setiap permintaan yang dibuat dari mode pengguna untuk mengirim data ke port akan menerima kesalahan.

MaxConnections

[di] Jumlah maksimum koneksi klien simultan yang akan diizinkan untuk port server ini. Parameter ini diperlukan dan harus lebih besar dari nol.

Mengembalikan nilai

FltCreateCommunicationPort mengembalikan STATUS_SUCCESS atau nilai NTSTATUS yang sesuai seperti salah satu hal berikut ini.

Mengembalikan kode	Deskripsi
STATUS_FLT_DELETING_OBJECT	Filter yang ditentukan sedang dicabik-cabik. Ini adalah kode kesalahan.
STATUS_INSUFFICIENT_RESOURCES	FltCreateCommunicationPort mengalami kegagalan alokasi kumpulan. Ini adalah kode kesalahan.
STATUS_OBJECT_NAME_COLLISION	Port komunikasi minifilter dengan nama yang sama sudah ada. Nama port harus unik. Ini adalah kode kesalahan.

Komentar

Minifilter memanggil FltCreateCommunicationPort untuk membuat objek port server komunikasi.

Setelah port server dibuat, aplikasi mode pengguna dapat terhubung ke port dengan memanggil FilterConnectCommunicationPort. Saat tersambung, aplikasi mode pengguna dapat mengirim dan menerima pesan dengan memanggil fungsi olahpesan mode pengguna seperti FilterSendMessage, FilterGetMessage, dan FilterReplyMessage.

Penelepon harus mengatur bendera Atribut OBJ_KERNEL_HANDLE untuk parameter ObjectAttributes dari FltCreateCommunicationPort. Pengaturan bendera ini mencegah handel port server komunikasi minifilter digunakan oleh proses mode pengguna dalam konteks pemanggil FltCreateCommunicationPort mungkin berjalan. Jika bendera ini tidak diatur, FltCreateCommunicationPort mengembalikan STATUS_INVALID_PARAMETER.

Setiap port server yang FltCreateCommunicationPort buat akhirnya harus ditutup dengan memanggil FltCloseCommunicationPort. Ketika port server ditutup, tidak ada koneksi baru ke port server yang diizinkan, dan semua panggilan ke FilterConnectCommunicationPort gagal. Namun, koneksi yang ada tetap terbuka sampai ditutup oleh aplikasi mode pengguna atau minifilter, atau sampai minifilter dibongkar.

Untuk informasi selengkapnya, lihat Komunikasi antara mode pengguna dan minifilter.