Fonction FsRtlRegisterUncProviderEx (ntifs.h)

Article
02/26/2024

La routine FsRtlRegisterUncProviderEx enregistre un redirecteur réseau en tant que fournisseur UNC (Universal Naming Convention) avec le système multiple fournisseur UNC (MUP).

Syntaxe

NTSTATUS FsRtlRegisterUncProviderEx(
  [out] PHANDLE                  MupHandle,
  [in]  PCUNICODE_STRING         RedirDevName,
  [in]  PDEVICE_OBJECT           DeviceObject,
  [in]  FSRTL_UNC_PROVIDER_FLAGS Flags
);

Paramètres

[out] MupHandle

Pointeur vers un emplacement dans lequel renvoyer un handle MUP à utiliser lors de l’appel de FsRtlDeregisterUncProvider pour désinscrire le redirecteur réseau. Le handle retourné est valide uniquement si FsRtlRegisterUncProviderEx retourne STATUS_SUCCESS.

[in] RedirDevName

Pointeur vers une chaîne Unicode qui contient le nom de l’appareil du redirecteur réseau. MUP utilise ce nom d’appareil pour créer un lien symbolique dans l’espace de noms du Gestionnaire d’objets dont la cible est \Device\Mup.

[in] DeviceObject

Pointeur vers un objet d’appareil sans nom qui représente le redirecteur réseau.

[in] Flags

Masque de bits qui indique les fonctionnalités prises en charge par le redirecteur réseau. Un redirecteur réseau définit un bit pour indiquer qu’une fonctionnalité est prise en charge. Le paramètre Flags propose deux options :

FSRTL_UNC_PROVIDER_FLAGS_MAILSLOTS_SUPPORTED

Le redirecteur réseau prend en charge les mailslots. Cette option est normalement réservée au redirecteur Microsoft SMB.

FSRTL_UNC_PROVIDER_FLAGS_CSC_ENABLED

Le redirecteur réseau prend en charge l’accès hors connexion à l’aide de la mise en cache côté client.

Valeur retournée

FsRtlRegisterUncProviderEx retourne STATUS_SUCCESS sur la réussite ou une valeur NTSTATUS appropriée, comme l’une des valeurs suivantes :

Code de retour	Description
STATUS_ACCESS_DENIED	Le mode demandeur de l’IRP envoyé à MUP ne provient pas du mode noyau.
STATUS_ACCESS_VIOLATION	Une violation d’accès s’est produite lors de la tentative d’accès à l’appareil MUP.
STATUS_DATATYPE_MISALIGNMENT	Il y a eu un mauvais alignement des données.
STATUS_INSUFFICIENT_RESOURCES	Les ressources disponibles étaient insuffisantes pour allouer de la mémoire pour les mémoires tampons.
STATUS_INVALID_DEVICE_REQUEST	Une demande a été faite pour inscrire un fournisseur connu qui était déjà inscrit.
STATUS_INVALID_PARAMETER	Le paramètre RedirDevName n’était pas valide, car la longueur de RedirDevName était égale à zéro.
STATUS_OBJECT_TYPE_MISMATCH	Une incompatibilité de type d’objet a été rencontrée avec le paramètre DeviceObject .

Remarques

Un redirecteur réseau doit s’inscrire auprès de plusieurs fournisseurs UNC (MUP) pour gérer les noms UNC (Universal Naming Convention). 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 (Universal Naming Convention) vers un redirecteur réseau (le fournisseur UNC) capable de gérer les demandes de système de fichiers distant. MUP est impliqué lorsqu’un chemin UNC est utilisé par une application, comme illustré dans 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é.

FsRtlRegisterUncProviderEx envoie un contrôle de système de fichiers privé (FSCTL) à MUP pour effectuer l’inscription.

Le nom de l’appareil spécifié dans le paramètre RedirDevName dans l’appel à FsRtlRegisterUncProviderEx devient un lien symbolique vers \device\Mup dans l’espace de noms du gestionnaire d’objets. En outre, une demande ouverte du nom de l’appareil, RedirDevName, s’acheminera vers l’objet d’appareil du redirecteur réseau réel pointé par le paramètre DeviceObject .

Les redirecteurs réseau qui appellent FsRtlRegisterUncProviderEx ne doivent pas s’inscrire en tant que système de fichiers (les redirecteurs réseau ne doivent pas appeler IoRegisterFileSystem). Les mini-redirecteurs réseau qui utilisent le RDBSS Windows Vista (liaison dynamique ou statique) ne seront pas inscrits en tant que système de fichiers.

Les objets de fichier sur la pile du système de fichiers distant appartenant à un redirecteur réseau conforme au modèle de redirecteur Windows Vista sont résolus en MUP. Par conséquent, IoGetDeviceAttachmentBaseRef retourne l’objet d’appareil pour MUP, et non le redirecteur réseau qui possède l’objet file. Toutefois, le contenu de l’objet fichier appartient toujours au redirecteur réseau.

La valeur de Registre ProviderOrder détermine l’ordre dans lequel MUP émet des demandes de résolution de préfixe à des redirecteurs réseau individuels. Cet ordre peut être modifié dynamiquement sans redémarrage. Cette valeur de Registre se trouve sous la clé de Registre suivante :

HKLM\CurrentControlSet\Control\NetworkProvider\Order

Un seul fournisseur réseau sur un système peut prendre en charge les mailslots. Par conséquent, l’option FSRTL_UNC_PROVIDER_FLAGS_MAILSLOTS_SUPPORTED dans le paramètre Flags est normalement définie uniquement pour le redirecteur SMB Microsoft.

Pour désinscrire un fournisseur UNC, utilisez FsRtlDeregisterUncProvider et transmettez le paramètre MupHandle .

Si un pilote s’inscrit en tant que système de fichiers de disque local (en appelant IoCreateDevice avec le paramètre DeviceType défini sur FILE_DEVICE_DISK_FILE_SYSTEM), le pilote ne doit pas appeler FsRtlRegisterUncProviderEx pour s’inscrire en tant que fournisseur UNC auprès de MUP.

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

Prise en charge du nommage UNC et de la MUP

Modifications MUP dans Microsoft Windows Vista

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Plateforme cible	Universal
En-tête	ntifs.h (inclure Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Règles de conformité DDI	HwStorPortProhibitedDDIs(storport),PowerIrpDDis(wdm)