IOCTL_REDIR_QUERY_PATH IOCTL (ntifs.h)

Artikel
08/07/2023

Kode kontrol IOCTL_REDIR_QUERY_PATH dikirim oleh beberapa penyedia UNC (MUP) ke pengalih jaringan untuk menentukan penyedia mana yang dapat menangani jalur UNC tertentu dalam operasi berbasis nama, biasanya permintaan IRP_MJ_CREATE. Permintaan ini disebut sebagai "resolusi awalan."

MUP adalah komponen mode kernel yang bertanggung jawab untuk menyalurkan semua akses sistem file jarak jauh yang menggunakan nama UNC ke pengalih jaringan (penyedia UNC) yang mampu menangani permintaan sistem file jarak jauh. MUP terlibat ketika jalur UNC digunakan seperti yang diilustrasikan oleh contoh berikut yang dapat dijalankan dari baris perintah:

notepad \\server\public\readme.txt

MUP tidak terlibat selama operasi yang membuat huruf drive yang dipetakan (perintah "NET USE", misalnya). Operasi ini ditangani oleh beberapa router penyedia (MPR) dan DLL penyedia WNet mode pengguna untuk pengalihan jaringan. Namun, DLL penyedia WNet mode pengguna mungkin berkomunikasi langsung dengan driver pengalih jaringan mode kernel selama operasi ini.

Pada Windows Server 2003, Windows XP, dan Windows 2000, operasi file jarak jauh yang dilakukan pada drive yang dipetakan yang tidak mewakili drive Distributed File System (DFS) tidak melalui MUP. Operasi ini langsung masuk ke penyedia jaringan yang menangani pemetaan huruf kandar.

Untuk pengalihan jaringan yang sesuai dengan model pengalihan Windows Vista, MUP terlibat bahkan ketika drive jaringan yang dipetakan digunakan. Operasi file yang dilakukan pada drive yang dipetakan melalui MUP ke pengalih jaringan. Perhatikan bahwa dalam hal ini, MUP hanya meneruskan operasi ke pengalihan jaringan yang terlibat.

Kode kontrol IOCTL_REDIR_QUERY_PATH dikirim ke pengalih jaringan yang telah terdaftar di MUP sebagai penyedia Universal Naming Convention (UNC) dengan memanggil FsRtlRegisterUncProvider. Mungkin ada beberapa penyedia UNC yang terdaftar di MUP.

Operasi resolusi awalan melayani dua tujuan:

Operasi berbasis nama yang menghasilkan resolusi awalan dirutekan ke penyedia yang mengklaim awalan. Jika berhasil, MUP memastikan bahwa operasi berbasis handel berikutnya (IRP_MJ_READ dan IRP_MJ_WRITE, misalnya) masuk ke penyedia yang sama sepenuhnya melewati MUP.
Penyedia dan awalan yang diklaim dimasukkan dalam cache awalan yang dikelola oleh MUP. Untuk operasi berbasis nama berikutnya, MUP menggunakan cache awalan ini untuk menentukan apakah penyedia telah mengklaim awalan sebelum MUP mencoba melakukan resolusi awalan. Setiap entri dalam cache awalan ini tunduk pada batas waktu (disebut sebagai TTL) setelah ditambahkan ke cache. Entri dibuang setelah batas waktu ini kedaluwarsa, pada titik waktu mana, MUP akan melakukan resolusi awalan lagi untuk awalan ini pada operasi berbasis nama berikutnya.

Kode utama

IOCTL_REDIR_QUERY_PATH

Buffer input

IrpSp->Parameters.DeviceIoControl.Type3InputBuffer diatur ke struktur data QUERY_PATH_REQUEST yang berisi permintaan.

Panjang buffer input

Panjang buffer input, dalam byte, yang harus setidaknya sizeof(QUERY_PATH_REQUEST).

Buffer output

IRP->UserBuffer diatur ke struktur data QUERY_PATH_RESPONSE yang berisi respons.

Panjang buffer output

Panjang buffer output, dalam byte, yang harus setidaknya sizeof(QUERY_PATH_RESPONSE).

Buffer Input/Output

n/a

Panjang buffer Input/Output

n/a

Blok status

Anggota Status diatur ke STATUS_SUCCESS saat berhasil jika nama awalan \\server\share dikenali atau ke nilai NTSTATUS yang sesuai, seperti salah satu dari berikut ini:

Kode status	Makna
STATUS_BAD_NETWORK_NAME	Nama berbagi yang ditentukan tidak dapat ditemukan pada server jarak jauh. Nama komputer (\\server, misalnya) valid, tetapi nama berbagi yang ditentukan tidak dapat ditemukan di server jarak jauh.
STATUS_BAD_NETWORK_PATH	Jalur jaringan tidak dapat ditemukan. Nama komputer (\\server, misalnya) tidak valid atau pengalih jaringan tidak dapat menyelesaikan nama komputer (menggunakan mekanisme resolusi nama apa pun yang tersedia).
STATUS_INSUFFICIENT_RESOURCES	Tidak tersedia cukup sumber daya untuk mengalokasikan memori untuk buffer.
STATUS_INVALID_DEVICE_REQUEST	Permintaan IOCTL_REDIR_QUERY_PATH_EX hanya boleh berasal dari MUP dan anggota RequestorMode dari struktur IRP harus selalu KernelMode. Kode kesalahan ini dikembalikan jika mode pemohon dari utas panggilan bukan KernelMode.
STATUS_INVALID_PARAMETER	Anggota PathNameLength dalam struktur QUERY_PATH_REQUEST melebihi panjang maksimum yang diizinkan, UNICODE_STRING_MAX_BYTES, untuk string Unicode.
STATUS_LOGON_FAILURE atau STATUS_ACCESS_DENIED	Jika operasi resolusi awalan gagal karena kredensial yang tidak valid atau salah, penyedia harus mengembalikan kode kesalahan yang tepat yang dikembalikan oleh server jarak jauh; kode kesalahan ini tidak boleh diterjemahkan ke STATUS_BAD_NETWORK_NAME atau STATUS_BAD_NETWORK_PATH. Kode kesalahan seperti STATUS_LOGON_FAILURE dan STATUS_ACCESS_DENIED berfungsi sebagai mekanisme umpan balik kepada pengguna dan menunjukkan persyaratan untuk menggunakan kredensial yang sesuai. Kode kesalahan ini juga digunakan dalam kasus tertentu untuk meminta kredensial kepada pengguna secara otomatis. Tanpa kode kesalahan ini, pengguna mungkin berasumsi bahwa komputer tidak dapat diakses.

Jika pengalih jaringan tidak dapat menyelesaikan awalan, pengalihan jaringan harus mengembalikan kode NTSTATUS yang sangat cocok dengan semantik yang dimaksudkan dari daftar kode NTSTATUS yang direkomendasikan di atas. Pengalih jaringan tidak boleh mengembalikan kesalahan yang ditemui aktual (STATUS_CONNECTION_REFUSED, misalnya) langsung ke MUP jika kode NTSTATUS bukan dari daftar di atas.

Keterangan

Pengalih jaringan hanya boleh menghormati pengirim mode kernel IOCTL ini, dengan memverifikasi bahwa Irp-RequestorMode> adalah KernelMode.

Perhatikan bahwa IOCTL_REDIR_QUERY_PATH adalah IOCTL METHOD_NEITHER. Ini berarti bahwa buffer input dan output mungkin tidak berada di alamat yang sama. Kesalahan umum oleh penyedia UNC adalah mengasumsikan bahwa buffer input dan buffer output sama dan menggunakan penunjuk buffer input untuk memberikan respons.

Ketika penyedia UNC menerima permintaan IOCTL_REDIR_QUERY_PATH, penyedia UNC harus menentukan apakah ia dapat menangani jalur UNC yang ditentukan dalam anggota FilePathName dari struktur QUERY_PATH_REQUEST . Jika demikian, ia harus memperbarui anggota LengthAccepted dari struktur QUERY_PATH_RESPONSE dengan panjang, dalam byte, dari awalan yang telah diklaim dan menyelesaikan IRP dengan STATUS_SUCCESS. Jika penyedia tidak dapat menangani jalur UNC yang ditentukan, itu harus gagal permintaan IOCTL_REDIR_QUERY_PATH dengan kode kesalahan NTSTATUS yang sesuai dan tidak boleh memperbarui anggota LengthAccepted dari struktur QUERY_PATH_RESPONSE . Penyedia tidak boleh mengubah anggota lain atau string FilePathName dalam kondisi apa pun.

Panjang awalan yang diklaim oleh penyedia tergantung pada penyedia UNC individu. Sebagian besar penyedia biasanya mengklaim bagian \\servername\sharename dari jalur formulir \\servername\sharename\path. Misalnya, jika penyedia mengklaim \\server\publik diberikan jalur \\server\public\dir1\dir2, semua operasi berbasis nama untuk awalan \\server\public (\\server\public\file1, misalnya) akan dirutekan ke penyedia tersebut secara otomatis tanpa resolusi awalan karena awalan sudah ada di cache awalan. Namun, jalur dengan prefiks \\server\presentasi pemasaran\ akan melalui resolusi awalan.

Jika pengalih jaringan mengklaim nama server (\\server, misalnya), semua permintaan berbagi di server ini akan masuk ke pengalihan jaringan ini. Perilaku ini hanya dapat diterima jika tidak ada kemungkinan berbagi lain di server yang sama diakses oleh pengalih jaringan yang berbeda. Misalnya, pengalihan jaringan yang mengklaim \\server jalur UNC akan mencegah akses oleh pengalihan jaringan lain ke berbagi lain di server ini (akses WebDAV ke \\server\web, misalnya).

Untuk informasi selengkapnya, lihat bagian berikut ini di Panduan Desain: