IOCTL_REDIR_QUERY_PATH_EX IOCTL (ntifs.h)

Article
10/10/2023

À compter de Windows Vista, le fournisseur UNC multiple (MUP) envoie un code de contrôle IOCTL_REDIR_QUERY_PATH_EX aux redirecteurs réseau pour déterminer quel fournisseur peut gérer un chemin UNC spécifique dans une opération basée sur un nom, généralement une demande de IRP_MJ_CREATE. Cette demande est appelée « résolution de préfixe ».

MUP est un composant en mode noyau chargé de canaliser tous les accès au système de fichiers distants à l’aide d’un nom UNC vers un redirecteur réseau (fournisseur UNC) capable de gérer les demandes du système de fichiers distant. MUP est impliqué lorsqu’un chemin UNC est utilisé comme illustré par l’exemple suivant qui peut être exécuté à partir d’une ligne de commande :

notepad \\server\public\readme.txt

MUP n’est pas impliqué lors d’une opération qui crée une lettre de lecteur mappée (la commande « NET USE », par exemple). Cette opération est gérée par le routeur multi-fournisseur (MPR) et une DLL de fournisseur WNet en mode utilisateur pour le redirecteur réseau. Toutefois, une DLL de fournisseur WNet en mode utilisateur peut communiquer directement avec un pilote de redirecteur réseau en mode noyau pendant cette opération.

Pour les redirecteurs réseau conformes au modèle de redirecteur Windows Vista, MUP est impliqué même lorsqu’un lecteur réseau mappé est utilisé. Les opérations de fichier effectuées sur le lecteur mappé passent par MUP au redirecteur réseau. Notez que dans ce cas, MUP transmet simplement l’opération au redirecteur réseau impliqué.

Le code de contrôle IOCTL_REDIR_QUERY_PATH_EX est envoyé aux redirecteurs réseau qui se sont inscrits auprès de MUP en tant que fournisseurs UNC (Universal Naming Convention) en appelant FsRtlRegisterUncProviderEx. Plusieurs fournisseurs UNC peuvent être inscrits auprès de MUP.

L’opération de résolution de préfixe a deux objectifs :

L’opération basée sur le nom qui a abouti à la résolution du préfixe est acheminée vers le fournisseur qui revendique le préfixe. En cas de réussite, MUP garantit que les opérations basées sur le handle suivantes (IRP_MJ_READ et IRP_MJ_WRITE, par exemple) passent par MUP au même fournisseur. Notez que ce comportement est différent pour les redirecteurs réseau qui ne sont pas conformes au modèle de redirecteur Windows Vista, qui seront envoyés IOCTL_REDIR_QUERY_PATH pour la résolution du préfixe. Pour les redirecteurs réseau qui ne sont pas conformes au modèle de redirecteur Windows Vista, MUP est complètement contourné pour les opérations suivantes basées sur le handle.
Le fournisseur et le préfixe qu’il a revendiqué sont entrés dans un cache de préfixes géré par MUP. Pour les opérations basées sur le nom suivantes, MUP utilise ce cache de préfixes pour déterminer si un fournisseur a déjà revendiqué un préfixe avant que MUP tente d’effectuer une résolution de préfixe. Chaque entrée de ce cache de préfixe est soumise à un délai d’expiration (appelé TTL) une fois qu’elle est ajoutée au cache. Une entrée est levée après l’expiration de ce délai d’expiration, à partir de laquelle MUP effectue à nouveau la résolution de préfixe pour ce préfixe lors d’une opération de nom ultérieure.

Code principal

IOCTL_REDIR_QUERY_PATH_EX

Mémoire tampon d'entrée

IrpSp->Parameters.DeviceIoControl.Type3InputBuffer est défini sur une structure de données QUERY_PATH_REQUEST_EX qui contient la requête.

Longueur de la mémoire tampon d’entrée

Taille de la structure QUERY_PATH_REQUEST_EX vers laquelle pointe la mémoire tampon d’entrée, en octets.

Mémoire tampon de sortie

IRP->UserBuffer est défini sur une structure de données QUERY_PATH_RESPONSE qui contient la réponse.

Longueur de la mémoire tampon de sortie

Taille de la structure QUERY_PATH_RESPONSE vers laquelle pointe la mémoire tampon de sortie, en octets.

Mémoire tampon d’entrée/sortie

n/a

Longueur de la mémoire tampon d’entrée/sortie

n/a

Bloc d’état

Le membre Status est défini sur STATUS_SUCCESS en cas de réussite si le nom du préfixe \\server\share est reconnu, ou avec une valeur NTSTATUS appropriée, comme l’une des valeurs suivantes :

Code d’état	Signification
STATUS_BAD_NETWORK_NAME	Le nom de partage spécifié est introuvable sur le serveur distant. Le nom de l’ordinateur (\\serveur, par exemple) est valide, mais le nom de partage spécifié est introuvable sur le serveur distant.
STATUS_BAD_NETWORK_PATH	Le chemin d’accès réseau est introuvable. Le nom de l’ordinateur (\\serveur, par exemple) n’est pas valide ou le redirecteur réseau ne peut pas résoudre le nom de l’ordinateur (en utilisant les mécanismes de résolution de noms disponibles).
STATUS_INSUFFICIENT_RESOURCES	Les ressources disponibles étaient insuffisantes pour allouer de la mémoire pour les mémoires tampons.
STATUS_INVALID_DEVICE_REQUEST	Une requête IOCTL_REDIR_QUERY_PATH_EX doit provenir uniquement de MUP et le membre RequestorMode de la structure IRP doit toujours être KernelMode. Ce code d’erreur est retourné si le mode demandeur du thread appelant n’était pas KernelMode.
STATUS_INVALID_PARAMETER	Le membre PathNameLength dans la structure QUERY_PATH_REQUEST dépasse la longueur maximale autorisée, UNICODE_STRING_MAX_BYTES, pour une chaîne Unicode.
STATUS_LOGON_FAILURE ou STATUS_ACCESS_DENIED	Si l’opération de résolution de préfixe a échoué en raison d’informations d’identification non valides ou incorrectes, le fournisseur doit retourner le code d’erreur exact retourné par le serveur distant ; ces codes d’erreur ne doivent pas être traduits en STATUS_BAD_NETWORK_NAME ou STATUS_BAD_NETWORK_PATH. Les codes d’erreur tels que STATUS_LOGON_FAILURE et STATUS_ACCESS_DENIED servir de mécanisme de commentaires à l’utilisateur et indiquent la nécessité d’utiliser les informations d’identification appropriées. Ces codes d’erreur sont également utilisés dans certains cas pour inviter automatiquement l’utilisateur à entrer des informations d’identification. Sans ces codes d’erreur, l’utilisateur peut supposer que la machine n’est pas accessible.

Si le redirecteur réseau ne parvient pas à résoudre un préfixe, il doit retourner un code NTSTATUS qui correspond étroitement à la sémantique prévue de la liste ci-dessus des codes NTSTATUS recommandés. Un redirecteur réseau ne doit pas renvoyer l’erreur réelle rencontrée (STATUS_CONNECTION_REFUSED, par exemple) directement à MUP si le code NTSTATUS ne figure pas dans la liste ci-dessus.

Remarques

Les redirecteurs réseau doivent uniquement honorer les expéditeurs en mode noyau de cette IOCTL, en vérifiant que Irp-RequestorMode> est KernelMode.

Notez que IOCTL_REDIR_QUERY_PATH_EX est un METHOD_NEITHER IOCTL. Cela signifie que les mémoires tampons d’entrée et de sortie peuvent ne pas se trouver à la même adresse. Une erreur courante des fournisseurs UNC consiste à supposer que la mémoire tampon d’entrée et la mémoire tampon de sortie sont identiques et à utiliser le pointeur de mémoire tampon d’entrée pour fournir la réponse.

Lorsqu’un fournisseur UNC reçoit une demande de IOCTL_REDIR_QUERY_PATH_EX, il doit déterminer s’il peut gérer le chemin UNC spécifié dans le membre PathName de la structure QUERY_PATH_REQUEST_EX . Si c’est le cas, le fournisseur UNC doit mettre à jour le membre LengthAccepted de la structure QUERY_PATH_RESPONSE avec la longueur, en octets, du préfixe qu’il a revendiqué et terminer l’IRP avec STATUS_SUCCESS. Si le fournisseur ne peut pas gérer le chemin d’accès UNC spécifié, il doit échouer la demande de IOCTL_REDIR_QUERY_PATH_EX avec un code d’erreur NTSTATUS approprié et ne doit pas mettre à jour le membre LengthAccepted de la structure QUERY_PATH_RESPONSE . Les fournisseurs ne doivent pas modifier d’autres membres ou le membre PathName sous aucune condition.

La longueur du préfixe revendiqué par le fournisseur dépend d’un fournisseur UNC individuel. La plupart des fournisseurs revendiquent généralement la partie \\servername\sharename d’un chemin d’accès de la forme \\servername\sharename\path. Par exemple, si un fournisseur a revendiqué \\server\public donné un chemin d’accès \\server\public\dir1\dir2, toutes les opérations basées sur le nom pour le préfixe \\server\public (\\server\public\file1, par exemple) sont routées automatiquement vers ce fournisseur sans aucune résolution de préfixe, car le préfixe se trouve déjà dans le cache de préfixes. Toutefois, un chemin avec le préfixe \\server\marketing\presentation passe par la résolution de préfixe.

Si un redirecteur réseau revendique un nom de serveur (\\serveur, par exemple), toutes les demandes de partage sur ce serveur sont envoyées à ce redirecteur réseau. Ce comportement n’est acceptable que s’il n’est pas possible d’accéder à un autre partage sur le même serveur par un autre redirecteur réseau. Par exemple, un redirecteur réseau qui revendique \\serveur d’un chemin UNC empêche d’autres redirecteurs réseau d’accéder à d’autres partages sur ce serveur (accès WebDAV à \\serveur\web, par exemple).

Pour plus d’informations, consultez les sections suivantes du Guide de conception :