Fungsi RxRegisterMinirdr (mrx.h)

Artikel
08/07/2023

RxRegisterMinirdr dipanggil oleh driver pengalihan mini jaringan untuk mendaftarkan driver dengan RDBSS, yang menambahkan informasi pendaftaran ke tabel pendaftaran internal. RDBSS juga membangun objek perangkat untuk pengalihan mini jaringan.

Sintaks

NTSTATUS RxRegisterMinirdr(
  [out]     OUT PRDBSS_DEVICE_OBJECT *DeviceObject,
  [in, out] IN OUT PDRIVER_OBJECT    DriverObject,
  [in]      IN PMINIRDR_DISPATCH     MrdrDispatch,
  [in]      IN ULONG                 Controls,
  [in]      IN PUNICODE_STRING       DeviceName,
  [in]      IN ULONG                 DeviceExtensionSize,
  [in]      IN DEVICE_TYPE           DeviceType,
  [in]      IN ULONG                 DeviceCharacteristics
);

Parameter

[out] DeviceObject

Penunjuk ke tempat objek perangkat yang dibuat akan disimpan.

[in, out] DriverObject

Penunjuk ke objek driver driver pengalihan mini jaringan. Setiap driver menerima penunjuk ke objek drivernya dalam parameter untuk rutinitas DriverEntry-nya . Obyek pengandar ini akan digunakan untuk membuat objek perangkat untuk pengandar pengalih-mini jaringan.

[in] MrdrDispatch

Penunjuk ke tabel pengiriman untuk pengarah mini jaringan. Tabel pengiriman ini mencakup informasi konfigurasi untuk pengalihan mini jaringan dan tabel penunjuk ke rutinitas panggilan balik yang diterapkan oleh driver kernel pengalihan mini jaringan. RDBSS melakukan panggilan ke driver pengalihan mini jaringan melalui daftar rutinitas panggilan balik ini.

[in] Controls

Kumpulan opsi yang menentukan kemampuan driver pengalihan mini jaringan dan bagaimana RDBSS harus menangani inisialisasi dan penembolokan tabel nama untuk driver pengalihan mini jaringan. Opsi ini dapat mencakup kombinasi bit berikut:

RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS

Ketika bendera ini diatur, ini menunjukkan bahwa pengalih mini jaringan tidak mendukung nama UNC.

RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS

Ketika bendera ini diatur, itu menunjukkan bahwa pengalih mini jaringan tidak mendukung mailslots.

RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH

Ketika bendera ini diatur, itu menunjukkan bahwa pengalih mini jaringan tidak ingin RDBSS menginisialisasi titik masuk pengiriman driver driver mini-redirector untuk menunjuk ke rutinitas internal RDBSS. Opsi ini hanya akan digunakan dalam keadaan yang tidak biasa. Biasanya RDBSS akan mengatur titik masuk pengiriman driver dan pengiriman I/O cepat di objek driver pengalih mini jaringan untuk menunjuk ke rutinitas internal ke RDBSS.

RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER

Ketika bendera ini diatur, itu menunjukkan bahwa pengalih mini jaringan tidak ingin RDBSS menginisialisasi tabel nama jaringan internal dan struktur data pemulung untuk memulung tabel nama ini. Opsi ini akan diatur untuk pengalih mini jaringan yang ingin menangani penembolokan untuk nama berbagi jaringan itu sendiri dan tidak menggunakan fasilitas RDBSS untuk penembolokan nama dan pemulungan.

[in] DeviceName

Penunjuk ke buffer yang berisi string Unicode yang dihentikan nol yang memberi nama objek perangkat. String harus berupa nama jalur lengkap. Parameter ini diteruskan sebagai DeviceName ke rutinitas IoCreateDevice oleh RDBSS.

[in] DeviceExtensionSize

Ukuran yang ditentukan oleh driver pengalih mini untuk jumlah byte yang akan dialokasikan untuk ekstensi perangkat objek perangkat. Struktur internal ekstensi perangkat ditentukan driver. Parameter ini ditambahkan ke ukuran ekstensi perangkat yang digunakan oleh RDBSS dan diteruskan sebagai parameter DeviceExtensionSize ke rutinitas IoCreateDevice oleh RDBSS.

[in] DeviceType

Jenis perangkat yang digunakan ketika objek perangkat dibuat. Ini menentukan salah satu konstanta FILE_DEVICE_XXX yang ditentukan sistem yang menunjukkan jenis perangkat atau nilai yang ditentukan vendor untuk jenis perangkat baru. Nilai ini biasanya akan FILE_DEVICE_NETWORK_FILE_SYSTEM untuk driver pengalihan mini jaringan. Parameter ini diteruskan sebagai DeviceType ke rutinitas IoCreateDevice oleh RDBSS.

[in] DeviceCharacteristics

Karakteristik perangkat yang digunakan saat objek perangkat dibuat. Ini menentukan satu atau beberapa konstanta yang ditentukan sistem, digabungkan bersama-sama, yang memberikan informasi tambahan tentang perangkat driver. Nilai ini harus mencakup FILE_REMOTE_DEVICE untuk driver pengalihan mini jaringan, tetapi ini mungkin dikombinasikan dengan karakteristik lain seperti FILE_DEVICE_SECURE_OPEN. Parameter ini diteruskan sebagai DeviceCharacteristics ke rutinitas IoCreateDevice oleh RDBSS.

Nilai kembali

RxRegisterMinirdr mengembalikan STATUS_SUCCESS pada keberhasilan atau salah satu nilai kesalahan berikut pada kegagalan:

Menampilkan kode	Deskripsi
STATUS_INSUFFICIENT_RESOURCES	Sumber daya tidak cukup untuk membuat objek perangkat.
STATUS_INVALID_PARAMETER	Parameter yang tidak valid diteruskan ke rutinitas. Kesalahan ini akan dikembalikan jika parameter DeviceObject adalah penunjuk NULL .
STATUS_OBJECT_NAME_COLLISION	Terjadi tabrakan nama ketika mencoba membuat objek perangkat ini.
STATUS_OBJECT_NAME_EXISTS	Objek perangkat dengan nama ini sudah ada.
STATUS_UNSUCCESSFUL	Panggilan untuk membuat objek perangkat mengembalikan objek perangkat NULL .

Keterangan

Pengalih mini jaringan mendaftar dengan RDBSS setiap kali driver dimuat oleh kernel dan membatalkan pendaftaran dengan RDBSS saat driver dibongkar. Driver non-monolitik (pengalih mini jaringan SMB) berkomunikasi dengan Rdbss.sys, driver kernel lain. Untuk driver mini-redirector jaringan monolitik yang secara statis terhubung dengan Rdbsslib.lib, komunikasi ini hanyalah panggilan ke rutinitas pustaka Rdbsslib.lib .

Pengalih mini jaringan menginformasikan RDBSS bahwa telah dimuat dengan memanggil RxRegisterMinirdr, pendaftaran rutin yang diekspor dari RDBSS. Ketika driver pengalihan mini jaringan pertama kali dimulai (dalam rutinitas DriverEntry-nya ), driver memanggil rutinitas RDBSS RxRegisterMinirdr untuk mendaftarkan driver pengalihan mini jaringan dengan RDBSS. Berdasarkan parameter yang diteruskan ke RxRegisterMinirdr, RDBSS memanggil IoCreateDevice untuk membuat objek perangkat untuk driver pengalihan mini jaringan.

Sebagai bagian dari proses pendaftaran ini, pengalih mini jaringan meneruskan parameter ke RxRegisterMinirdr yang merupakan penunjuk ke struktur besar, MINIRDR_DISPATCH, yang berisi informasi konfigurasi untuk pengalihan mini jaringan dan tabel pengiriman pointer ke rutinitas panggilan balik yang diterapkan oleh driver mini-redirector jaringan. Data konfigurasi ini digunakan untuk mengonfigurasi tabel RDBSS internal untuk digunakan dengan pengalih mini jaringan ini. RDBSS menggunakan rutinitas panggilan balik yang diteruskan dalam struktur ini untuk berkomunikasi dengan pengarah mini jaringan. Pengalih mini jaringan hanya dapat memilih untuk mengimplementasikan beberapa rutinitas panggilan balik ini. Rutinitas panggilan balik apa pun yang tidak diimplementasikan harus diatur ke penunjuk NULL dalam tabel pengiriman yang diteruskan ke RDBSS. Hanya rutinitas panggilan balik yang diterapkan oleh pengalih mini jaringan yang akan dipanggil oleh RDBSS.

Perhatikan bahwa rutinitas RxRegisterMinirdr mengatur semua rutinitas pengiriman driver driver driver mini-redirector jaringan untuk menunjuk ke rutinitas pengiriman RDBSS tingkat atas, RxFsdDispatch. Pengalih mini jaringan dapat menimpa perilaku ini dengan menyimpan salinan titik masuk pengiriman drivernya, memanggil RxRegisterMinirdr, dan menulis ulang pengiriman driver dengan titik masuknya sendiri setelah panggilan ke RxRegisterMinirdr kembali. Pengalih mini jaringan juga dapat mencegah rutinitas pengiriman drivernya disalin oleh rutinitas RxRegisterMinirdr jika bit RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH diatur dalam parameter Kontrol .

Jika panggilan RxRegisterMinirdr berhasil, sejumlah anggota di RDBSS_DEVICE_OBJECT yang diacu oleh parameter DeviceObject diinisialisasi termasuk yang berikut ini:

Anggota Pengiriman diatur ke parameter MrdrDispatch .
Anggota RegistrationControls diatur ke parameter Kontrol .
Anggota DeviceName diatur ke parameter DeviceName .
Anggota RegisterUncProvider diatur ke TRUE jika bit RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS dalam parameter Kontrol tidak diatur.
Anggota RegisterMailSlotProvider diatur ke TRUE jika bit RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS dalam parameter Kontrol tidak diatur.
Anggota NetworkProviderPriority diatur ke prioritas penyedia jaringan yang akan digunakan MUP.

Jika panggilan RxRegisterMinirdr berhasil dan bit RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER dalam parameter Kontrol tidak diatur, sejumlah anggota lain di RDBSS_DEVICE_OBJECT ditunjukkan oleh parameter DeviceObject diinisialisasi, termasuk yang berikut ini:

Struktur anggota pRxNetNameTable diinisialisasi.
Anggota RxNetNameTableInDeviceObject.IsNetNameTable diatur ke TRUE.
Struktur anggota pRdbssScavenger diinisialisasi.

Jika panggilan RxRegisterMinirdr berhasil, RDBSS mengatur status internal pengalihan mini jaringan di RDBSS ke RDBSS_STARTABLE.

Pengalih mini jaringan sebenarnya tidak memulai operasi sampai menerima panggilan ke rutinitas MRxStart-nya , salah satu rutinitas panggilan balik yang diteruskan dalam struktur MINIRDR_DISPATCH. Rutinitas panggilan balik MrxStart harus diimplementasikan oleh driver pengalih mini jaringan jika ingin menerima panggilan balik untuk operasi, kecuali jika pengalih mini jaringan mempertahankan titik masuk pengiriman drivernya sendiri. Jika tidak, RDBSS hanya akan mengizinkan paket permintaan I/O berikut ke driver sampai MrxStart berhasil kembali:

Permintaan IRP untuk operasi pembuatan perangkat dan operasi perangkat di mana parameter FileObject->FileName.Length pada IRPSP adalah nol dan parameter FileObject->RelatedFileObject adalah NULL.

Untuk permintaan IRP lainnya, rutinitas pengiriman RDBSS, RxFsdDispatch, akan mengembalikan status STATUS_REDIRECTOR_NOT_STARTED.

Rutinitas pengiriman RDBSS juga akan gagal setiap permintaan untuk paket permintaan I/O berikut:

IRP_MJ_CREATE_MAILSLOT
IRP_MJ_CREATE_NAMED_PIPE

Rutinitas MrxStart pengalih mini jaringan dipanggil oleh RDBSS ketika rutinitas RxStartMiniRdr dipanggil. RDBSS RxStartMinirdr biasanya dipanggil sebagai akibat dari permintaan FSCTL atau IOCTL dari aplikasi atau layanan mode pengguna untuk memulai pengalihan mini jaringan. Panggilan ke RxStartMinirdr tidak dapat dilakukan dari rutinitas DriverEntry dari pengalih mini jaringan setelah panggilan berhasil ke RxRegisterMinirdr karena beberapa pemrosesan mulai mengharuskan inisialisasi driver selesai. Setelah panggilan RxStartMinirdr diterima, RDBSS menyelesaikan proses mulai dengan memanggil rutinitas MrxStart dari pengalihan mini jaringan. Jika panggilan ke MrxStart mengembalikan keberhasilan, RDBSS menetapkan status internal pengalihan mini di RDBSS ke RDBSS_STARTED.