IOCTL_REDIR_QUERY_PATH IOCTL (ntifs.h)
Le code de contrôle IOCTL_REDIR_QUERY_PATH est envoyé par plusieurs fournisseurs UNC (MUP) 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 requête 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 qui utilisent un nom UNC vers un redirecteur réseau (fournisseur UNC) capable de gérer les demandes de 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.
Sur Windows Server 2003, Windows XP et Windows 2000, les opérations de fichiers distants effectuées sur un lecteur mappé qui ne représente pas un lecteur de système de fichiers distribué (DFS) ne passent pas par MUP. Ces opérations vont directement au fournisseur réseau qui a géré le mappage de lettres de lecteur.
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 est envoyé aux redirecteurs réseau qui se sont inscrits auprès de MUP en tant que fournisseurs UNC (Universal Naming Convention) en appelant FsRtlRegisterUncProvider. 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) vont au même fournisseur en contournant complètement MUP.
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. À quel moment, MUP effectue à nouveau la résolution de préfixe pour ce préfixe lors d’une opération basée sur le nom suivante.
Code principal
IOCTL_REDIR_QUERY_PATH
Mémoire tampon d'entrée
IrpSp->Parameters.DeviceIoControl.Type3InputBuffer est défini sur une structure de données QUERY_PATH_REQUEST qui contient la requête.
Longueur de la mémoire tampon d’entrée
Longueur de la mémoire tampon d’entrée, en octets, qui doit être au moins sizeof(QUERY_PATH_REQUEST).
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
Longueur de la mémoire tampon de sortie, en octets, qui doit être au moins sizeof(QUERY_PATH_RESPONSE).
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 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 à 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, il doit déterminer s’il peut gérer le chemin UNC spécifié dans le membre FilePathName de la structure QUERY_PATH_REQUEST . Si c’est le cas, il 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 requête IOCTL_REDIR_QUERY_PATH 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 les autres membres ou la chaîne FilePathName 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 :
Configuration requise
| Condition requise | Valeur |
|---|---|
| En-tête | ntifs.h (inclure Ntifs.h) |
Voir aussi
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour