Fungsi FltCreateCommunicationPort (fltkernel.h)

Artikel
02/29/2024

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

Sintaks

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

Parameter

[in] Filter

Penunjuk filter buram untuk pemanggil.

[out] ServerPort

Penunjuk ke variabel yang dialokasikan penelepon yang menerima handel port buram untuk port server komunikasi. Driver minifilter menggunakan handel ini untuk mendengarkan permintaan koneksi masuk dari aplikasi mode pengguna.

[in] ObjectAttributes

Arahkan 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
PanjangULONG	InitializeObjectAttributes mengatur anggota ini ke sizeof(OBJECT_ATTRIBUTES).
PUNICODE_STRING ObjectName	Penunjuk ke struktur UNICODE_STRING yang berisi nama unik (misalnya, L"\\MyFilterPort") untuk objek port.
PSECURITY_DESCRIPTOR SecurityDescriptor	Penunjuk ke deskriptor keamanan (SECURITY_DESCRIPTOR) untuk diterapkan ke objek port. Jika diperlukan, deskriptor keamanan default dapat dibuat dengan memanggil FltBuildDefaultSecurityDescriptor.
AtributULONG	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.

[in, optional] ServerPortCookie

Arahkan ke informasi konteks yang ditentukan oleh driver minifilter. Informasi ini dapat digunakan untuk membedakan di antara beberapa port server komunikasi yang dibuat oleh driver minifilter yang sama. Manajer Filter meneruskan penunjuk konteks ini sebagai parameter ke rutinitas ConnectNotifyCallback . Parameter ini bersifat opsional dan dapat berupa NULL.

[in] ConnectNotifyCallback

Penunjuk ke rutinitas panggilan balik yang disediakan penelepon. Manajer Filter memanggil rutinitas ini setiap kali aplikasi mode pengguna memanggil FilterConnectCommunicationPort untuk mengirim permintaan koneksi ke driver minifilter. Parameter ini diperlukan dan tidak boleh NULL. Rutinitas ini disebut di IRQL = PASSIVE_LEVEL.

Rutinitas ini dinyatakan sebagai berikut:

typedef NTSTATUS
(*PFLT_CONNECT_NOTIFY) (
      IN PFLT_PORT ClientPort,
      IN PVOID ServerPortCookie,
      IN PVOID ConnectionContext,
      IN ULONG SizeOfContext,
      OUT PVOID *ConnectionPortCookie
      );

ClientPort

Handel buram untuk port klien baru yang ditetapkan antara aplikasi mode pengguna dan driver minifilter mode kernel.

Driver minifilter harus meneruskan handel ini sebagai parameter ClientPort ke FltSendMessage saat mengirim dan membalas pesan pada port klien ini. (Perhatikan bahwa ini tidak sama dengan handel ServerPort yang dikembalikan oleh FltCreateCommunicationPort.)

Driver minifilter akhirnya harus menutup port klien ini. Port klien ditutup dengan memanggil FltCloseClientPort, biasanya dari rutinitas DisconnectNotifyCallback driver minifilter.

ServerPortCookie

Arahkan ke informasi konteks yang ditentukan oleh driver minifilter. Informasi ini dapat digunakan untuk membedakan di antara beberapa port server komunikasi yang dibuat oleh driver minifilter yang sama. Ketika port server dibuat, driver minifilter meneruskan penunjuk konteks ini sebagai parameter ke FltCreateCommunicationPort.

ConnectionContext

Penunjuk informasi konteks yang diteruskan aplikasi mode pengguna dalam parameter lpContext ke FilterConnectCommunicationPort.

SizeOfContext

Ukuran, dalam byte, dari buffer yang dituju connectionContext .

ConnectionPortCookie

Arahkan ke informasi yang secara unik mengidentifikasi port klien ini. Informasi ini ditentukan oleh driver minifilter. Manajer Filter meneruskan penunjuk konteks ini sebagai parameter ke rutinitas DisconnectNotifyCallback dan MessageNotifyCallback driver minifilter.

[in] DisconnectNotifyCallback

Penunjuk ke rutinitas panggilan balik yang disediakan penelepon untuk dipanggil setiap kali jumlah handel mode pengguna untuk port klien mencapai nol atau ketika driver minifilter akan dibongkar. Parameter ini diperlukan dan tidak boleh NULL. Rutinitas ini disebut di IRQL = PASSIVE_LEVEL.

Rutinitas ini dinyatakan sebagai berikut:

typedef VOID
(*PFLT_DISCONNECT_NOTIFY) (
      IN PVOID ConnectionCookie
      );

ConnectionCookie

Arahkan ke informasi yang secara unik mengidentifikasi port klien ini. Informasi ini ditentukan oleh driver minifilter. Ketika port klien dibuat, driver minifilter mengembalikan penunjuk konteks ini dalam parameter ConnectionPortCookie dari rutinitas ConnectNotifyCallback-nya .

[in, optional] MessageNotifyCallback

Penunjuk ke rutinitas panggilan balik yang disediakan penelepon. Manajer Filter memanggil rutinitas ini, di IRQL = PASSIVE_LEVEL, setiap kali aplikasi mode pengguna memanggil FilterSendMessage untuk mengirim pesan ke driver 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.

Rutinitas ini dinyatakan sebagai berikut:

typedef NTSTATUS
(*PFLT_MESSAGE_NOTIFY) (
      IN PVOID PortCookie,
      IN PVOID InputBuffer OPTIONAL,
      IN ULONG InputBufferLength,
      OUT PVOID OutputBuffer OPTIONAL,
      IN ULONG OutputBufferLength,
      OUT PULONG ReturnOutputBufferLength
      );

PortCookie

InputBuffer

Pointer ke buffer yang dialokasikan penelepon yang berisi pesan yang akan dikirim ke driver minifilter.

Perhatikan bahwa InputBuffer adalah penunjuk ke buffer mode pengguna yang mentah dan tidak terkunci. Penunjuk ini hanya valid dalam konteks proses mode pengguna dan hanya boleh diakses dari dalam blok coba/kecuali .

Manajer filter memanggil ProbeForRead untuk memvalidasi pointer ini, tetapi tidak memastikan bahwa buffer diratakan dengan benar. Jika buffer berisi struktur yang memiliki persyaratan penyelarasan, driver minifilter bertanggung jawab untuk melakukan pemeriksaan penyelarasan yang diperlukan. Untuk melakukan ini, driver minifilter dapat menggunakan makro IS_ALIGNED seperti yang ditunjukkan pada driver minifilter sampel MiniSpy.

Parameter ini bersifat opsional dan dapat berupa NULL.

InputBufferLength

Ukuran, dalam byte, dari buffer yang dirujuk InputBuffer . Parameter ini diabaikan jika InputBufferADALAH NULL.

OutputBuffer

Pointer ke buffer yang dialokasikan penelepon yang menerima balasan (jika ada) dari driver minifilter.

Perhatikan bahwa OutputBuffer adalah penunjuk ke buffer mode pengguna yang mentah dan tidak terkunci. Penunjuk ini hanya valid dalam konteks proses mode pengguna dan hanya boleh diakses dari dalam blok coba/kecuali .

Manajer filter memanggil ProbeForWrite untuk memvalidasi pointer ini, tetapi tidak memastikan bahwa buffer diselaraskan dengan benar. Jika buffer berisi struktur yang memiliki persyaratan penyelarasan, driver minifilter bertanggung jawab untuk melakukan pemeriksaan penyelarasan yang diperlukan. Untuk melakukan ini, driver minifilter dapat menggunakan makro IS_ALIGNED seperti yang ditunjukkan pada driver minifilter sampel MiniSpy.

Parameter ini bersifat opsional dan dapat berupa NULL.

OutputBufferLength

Ukuran, dalam byte, dari buffer yang dirujuk OutputBuffer . Parameter ini diabaikan jika OutputBuffer adalah NULL.

ReturnOutputBufferLength

Penunjuk ke variabel yang dialokasikan pemanggil yang menerima jumlah byte yang dikembalikan dalam buffer yang dituju oleh OutputBuffer .

[in] MaxConnections

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:

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

Keterangan

Driver minifilter memanggil FltCreateCommunicationPort untuk membuat objek port server komunikasi.

Setelah port server dibuat, aplikasi mode pengguna dapat tersambung 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 driver minifilter digunakan oleh proses mode pengguna yang konteksnya pemanggil FltCreateCommunicationPort mungkin berjalan. Jika bendera ini tidak diatur, FltCreateCommunicationPort mengembalikan STATUS_INVALID_PARAMETER.

Port server apa pun yang dibuat oleh FltCreateCommunicationPort 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 driver minifilter, atau sampai driver minifilter dibongkar.