IOCTL_REDIR_QUERY_PATH_EX IOCTL (ntifs.h)

Article
12/21/2024

À compter de Windows Vista, plusieurs fournisseurs UNC (MUP) envoient 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 de système de fichiers distantes. 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é pendant 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 de plusieurs fournisseurs (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 vers le 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 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éfixes sert à deux fins :

L’opération basée sur le nom qui a entraîné la résolution de préfixes est routée vers le fournisseur qui prétend le préfixe. En cas de réussite, MUP garantit que les opérations basées sur le handle (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 sera envoyé IOCTL_REDIR_QUERY_PATH pour la résolution de préfixes. 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 de handle suivantes.
Le fournisseur et le préfixe qu’il a revendiqués sont entrés dans un cache de préfixe 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, à quel point MUP effectue une nouvelle résolution de préfixe pour ce préfixe sur une opération basée sur un nom suivant.

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 sur une valeur NTSTATUS appropriée, par exemple 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 (\\server, 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 ne peut pas être localisé. Le nom de l’ordinateur (\\server, par exemple) n’est pas valide ou le redirecteur réseau ne peut pas résoudre le nom de l’ordinateur (à l’aide des mécanismes de résolution de noms disponibles).
STATUS_INSUFFICIENT_RESOURCES	Il n’y avait pas suffisamment de ressources disponibles pour allouer de la mémoire pour les mémoires tampons.
STATUS_INVALID_DEVICE_REQUEST	Une requête IOCTL_REDIR_QUERY_PATH_EX doit uniquement provenir de MUP et du membre RequestorMode de la structure IRP doit toujours être KernelMode. Ce code d’erreur est retourné si le mode demandeur du thread appelant n’a pas été 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 incorrectes 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 servent 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 l’utilisateur automatiquement à entrer les informations d’identification. Sans ces codes d’erreur, l’utilisateur peut supposer que l’ordinateur 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 respecter 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 une 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 utilisent 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 PathName membre 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 UNC spécifié, il doit échouer à la demande IOCTL_REDIR_QUERY_PATH_EX avec un code d’erreur NTSTATUS approprié et ne doit pas mettre à jour le LengthAccepted membre de la structure QUERY_PATH_RESPONSE. Les fournisseurs ne doivent pas modifier d’autres membres ou le PathName membre sous n’importe quelle condition.

La longueur du préfixe revendiqué par le fournisseur dépend d’un fournisseur UNC individuel. La plupart des fournisseurs réclament généralement le nom de serveur \\\nom de partage partie d’un chemin d’accès du formulaire \\nom_serveur\nom_serveur\chemin d’accès. Par exemple, si un fournisseur a revendiqué \\serveur\ public donné un chemin d’accès \\serveur\public\dir1\dir2, toutes les opérations basées sur le nom pour le préfixe \\serveur\ public (\\serveur\\fichierpublic, par exemple) sera routé automatiquement vers ce fournisseur sans résolution de préfixe, car le préfixe se trouve déjà dans le fichier cache de préfixe. Toutefois, un chemin avec le préfixe \\serveur\marketing\présentation passe par la résolution de préfixe.

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

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