Fonction RxStartMinirdr (mrx.h)

Article
03/05/2024

RxStartMinirdr est appelé pour démarrer un mini-redirecteur réseau qui a précédemment appelé à s’inscrire auprès de RDBSS. Dans le cadre de RxStartMinirdr, RDBSS inscrit également le pilote de mini-redirecteur réseau en tant que fournisseur UNC (Universal Naming Convention) auprès du fournisseur MUP (Multiple UNC Provider) si le pilote indique la prise en charge des noms UNC.

Syntaxe

NTSTATUS RxStartMinirdr(
  [in]  IN PRX_CONTEXT RxContext,
  [out] OUT PBOOLEAN   PostToFsp
);

Paramètres

[in] RxContext

Pointeur vers la structure RX_CONTEXT à utiliser pour obtenir l’objet d’appareil et déterminer s’il s’agit d’un processus de système de fichiers.

[out] PostToFsp

Pointeur vers une valeur logique définie sur TRUE si la demande doit être publiée pour un traitement ultérieur par le processus du système de fichiers.

Valeur retournée

RxStartMinirdr retourne STATUS_SUCCESS si la séquence de démarrage a réussi ou l’une des valeurs d’erreur suivantes :

Code de retour	Description
STATUS_ACCESS_DENIED	La demande d’inscription en tant que fournisseur UNC a échoué, car l’accès a été refusé.
STATUS_ACCESS_VIOLATION	La demande d’inscription en tant que fournisseur UNC a échoué avec une violation d’accès.
STATUS_INSUFFICIENT_RESOURCES	Les ressources étaient insuffisantes pour effectuer cette routine.
STATUS_PENDING	La séquence de démarrage pour RDBSS et les mini-redirecteurs réseau doit être effectuée dans le contexte du processus système, et non dans un processus d’application en mode utilisateur. Si l’appel à RxStartMinirdr provient d’un processus en mode utilisateur (une demande de service en mode utilisateur, par exemple), la demande est publiée en vue d’un traitement ultérieur dans RDBSS et STATUS_PENDING sera retourné. Cette erreur peut également être retournée si certains verrous RDBSS internes ne peuvent pas être acquis sans attendre. L’appel sera terminé ultérieurement à partir d’un thread système.
STATUS_REDIRECTOR_STARTED	Le mini-redirecteur réseau a déjà démarré.

Remarques

Un mini-redirecteur réseau s’inscrit auprès de RDBSS chaque fois que le pilote est chargé par le noyau, puis se désinscrit auprès de RDBSS lorsque le pilote est déchargé. Un mini-redirecteur réseau informe RDBSS qu’il a été chargé en appelant RxRegisterMinirdr, la routine d’inscription exportée à partir de RDBSS. Dans le cadre de ce processus d’inscription, le mini-redirecteur réseau transmet un paramètre à RxRegisterMinirdr qui est un pointeur vers une structure volumineuse, MINIRDR_DISPATCH, qui contient des informations de configuration pour le mini-redirecteur réseau et une table de pointeurs vers les routines de rappel implémentées par le pilote de mini-redirecteur réseau. RDBSS utilise les routines de rappel transmises dans cette structure pour communiquer avec le mini-redirecteur réseau.

Le mini-redirecteur réseau ne démarre pas l’opération jusqu’à ce qu’il reçoive un appel à sa routine MRxStart , l’une des routines de rappel passées dans la structure MINIRDR_DISPATCH. La routine de rappel MrxStart doit être implémentée par le pilote de mini-redirecteur réseau s’il souhaite recevoir des routines de rappel pour les opérations, sauf si le mini-redirecteur réseau conserve ses propres points d’entrée de répartition du pilote. Dans le cas contraire, RDBSS autorise uniquement les paquets de demande d’E/S suivants au pilote jusqu’à ce que MrxStart retourne correctement :

Demandes IRP pour les opérations de création d’appareil et les opérations d’appareil où le paramètre FileObject-FileName.Length> sur l’IRPSP est égal à zéro et le paramètre FileObject-RelatedFileObject> a la valeur NULL.

Pour toute autre demande IRP, la routine de distribution RDBSS RxFsdDispatch retourne une status de STATUS_REDIRECTOR_NOT_STARTED.

La routine de distribution RDBSS échoue également toutes les demandes pour les paquets de demande d’E/S suivants :

IRP_MJ_CREATE_MAILSLOT
IRP_MJ_CREATE_NAMED_PIPE

La routine mrxStart du mini-redirecteur réseau est appelée par RDBSS lorsque la routine RxStartMinirdr est appelée. La routine RDBSS RxStartMinirdr est généralement appelée à la suite d’une demande FSCTL ou IOCTL d’une application ou d’un service en mode utilisateur pour démarrer le mini-redirecteur réseau. L’appel à RxStartMinirdr ne peut pas être effectué à partir de la routine DriverEntry du mini-redirecteur réseau après un appel réussi à RxRegisterMinirdr , car une partie du traitement de début nécessite que l’initialisation du pilote soit terminée.

Lorsque RDBSS reçoit une requête FSCTL ou IOCTL envoyée au pilote de mini-redirecteur réseau à partir du mode utilisateur, RDBSS crée une structure de RX_CONTEXT et transmet cet appel à la routine de rappel MRxLowIOSubmit[LOWIO_OP_FSCTL] ou MRxLowIOSubmit[LOWIO_OP_IOCTL] du mini-redirecteur réseau définie dans la structure MINIRDR_DISPATCH. L’implémentation par le mini-redirecteur réseau de cette routine de rappel reconnaîtrait la demande de démarrage et d’appel de RxStartMinirdr. Ce processus normal d’événements est répertorié ci-dessous plus en détail :

Une application en mode utilisateur émet une demande FSCTL ou IOCTL privée pour démarrer le mini-redirecteur réseau.
Le pilote de noyau RDBSS reçoit la demande FSCTL ou IOCTL pour le compte du mini-redirecteur réseau, car RDBSS a remplacé les points d’entrée de distribution du pilote du mini-redirecteur pour pointer vers les routines internes RDBSS. Notez que cela suppose que le mini-redirecteur réseau n’a pas défini le RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH dans le paramètre Controls lors de l’appel de RxRegisterMinirdr. Cette option passée à RxRegisterMinirdr est inhabituelle et indique que le mini-redirecteur réseau ne souhaite pas que RDBSS remplace ses points d’entrée de distribution de pilote.
RDBSS reçoit la demande FSCTL ou IOCTL en interne pour le compte du redirecteur réseau. Le répartiteur RDBSS alloue et initialise une structure RX_CONTEXT. RDBSS appelle ensuite la routine de mini-redirecteur réseau MRxLowIOSubmit[LOW_OP_FSCTL] ou MRxLowIOSubmit[LOW_OP_IOCTL] définie dans la structure de MINIRDR_DISPATCH pour ce mini-redirecteur réseau, en passant la structure RX_CONTEXT initialisée en tant que paramètre.
L’implémentation du mini-redirecteur réseau de cette routine de rappel reconnaît la demande privée FSCTL ou IOCTL de démarrage et d’appel de RxStartMinirdr, en passant un pointeur la structure RX_CONTEXT qu’elle a reçue de RDBSS comme paramètre RxContext et l’adresse du membre PostToFSP de RxContext en tant que paramètre PostToFsp .
Étant donné que cet appel a été lancé à partir du mode utilisateur, RxStartMinirdr retourne STATUS_PENDING et définit PostToFsp sur TRUE.
La routine de mini-redirecteur réseau MRxLowIOSubmit[LOW_OP_FSCTL] ou MRxLowIOSubmit[LOW_OP_IOCTL] reçoit cette valeur de retour et la transmet au répartiteur RDBSS.
Le répartiteur RDBSS recevait la valeur de retour STATUS_PENDING et affectait à PostToFsp la valeur TRUE, puis postait une demande à un thread de travail pour réexécérer l’appel au mini-redirecteur réseau.

Après ce point, il existe deux résultats possibles selon que le FSCTL ou IOCTL a été demandé en tant qu’opération asynchrone ou synchrone.

S’il s’agissait d’une requête asynchrone, les événements suivants se produiraient :

L’appelant en mode utilisateur reçoit la réponse STATUS_PENDING de l’appel. Le thread de travail publié appelait finalement RxStartMinirdr à partir d’un thread de système de fichiers et l’appel serait traité. La routine RxStartMinirdr tente d’inscrire le mini-redirecteur réseau en tant que fournisseur UNC, si nécessaire. Sur les versions de Windows antérieures à Windows Vista, RDBSS essaiera ensuite d’inscrire le mini-redirecteur réseau en tant que système de fichiers auprès du gestionnaire d’E/S. Si ces appels réussissent, RxStartMinirdr appelle la routine de rappel MrxStart implémentée par le mini-redirecteur réseau. La valeur de retour de MrxStart serait finalement retournée à l’application en mode utilisateur qui a lancé le processus de séquence d’appel en tant qu’opération asynchrone.

S’il s’agissait d’une requête synchrone, les opérations suivantes se produiraient :

L’appelant en mode utilisateur ne recevrait pas la réponse STATUS_PENDING, mais il serait obligé d’attendre que l’appel soit retourné à partir du thread de travail publié. Le thread de travail publié appelait finalement RxStartMinirdr à partir d’un thread de système de fichiers et l’appel serait traité. La routine RxStartMinirdr tente d’inscrire le mini-redirecteur réseau en tant que fournisseur UNC, si nécessaire. Sur les versions de Windows antérieures à Windows Vista, RDBSS essaiera ensuite d’inscrire le mini-redirecteur réseau en tant que système de fichiers auprès du gestionnaire d’E/S. Si ces appels réussissent, RxStartMinirdr appelle la routine de rappel MrxStart implémentée par le mini-redirecteur réseau. La valeur de retour de MrxStart est retournée à l’application en mode utilisateur qui a lancé le processus de séquence d’appel.

Si un mini-redirecteur réseau indique la prise en charge d’UNC lors de l’inscription auprès de RDBSS (paramètre Controls sur RxRegisterMinirdr), RxStartMinirdr essaie d’inscrire le paramètre DeviceName du mini-redirecteur réseau en tant que fournisseur UNC avec MUP (RDBSS appelle FsRtlRegisterUncProvider au nom du mini-redirecteur réseau).

Sur les versions de Windows antérieures à Windows Vista, RxStartMinirdr inscrit le système de fichiers auprès du gestionnaire d’E/S (RDBSS appelle IoRegisterFileSystem pour le compte du mini-redirecteur réseau).

Si les appels réussissent, RxStartMinirdr appelle la routine mrxStart du mini-redirecteur réseau. Si MrxStart retourne la réussite, l’état interne du mini-redirecteur dans RDBSS est défini sur RDBSS_STARTED. Le membre StartStopContext.Version de l’objet d’appareil mini-redirecteur sera également incrémenté.

La séquence de démarrage pour RDBSS et le mini-redirecteur réseau doit être effectuée dans le contexte du processus système si une opération asynchrone est demandée. Si l’appel à RxStartMinirdr provient d’un processus en mode utilisateur (une demande de service en mode utilisateur, par exemple), la demande sera publiée en interne par RDBSS dans une file d’attente de travail pour un traitement ultérieur et STATUS_PENDING sera retourné et le paramètre PostToFsp sera défini sur TRUE. En outre, si certains verrous RDBSS internes ne peuvent pas être obtenus sans attendre, STATUS_PENDING est retourné et PostToFsp est défini sur TRUE. Lorsque STATUS_PENDING est retourné, RxStartMinirdr est appelé à nouveau à partir d’un processus système. Si la demande FSCTL ou IOCTL qui a lancé l’appel à RxStartMinirdr a été définie pour une opération asynchrone, RDBSS retournerait STATUS_PENDING sauvegarder la chaîne d’appels à la demande FSCTL ou IOCTL d’origine à partir du mode utilisateur. En revanche, si la demande FSCTL ou IOCTL était pour une opération synchrone, l’appel serait également publié sur un thread de travail pour une exécution ultérieure, mais l’appel FSCTL ou IOCTL ne retournerait pas en mode utilisateur tant que RxStartMinirdr n’aurait pas été exécuté dans le contexte du processus du système de fichiers. Dans ce cas, l’appelant du FSCTL ou du IOCTL ne verrait jamais le STATUS_PENDING d’erreur retourné. Le comportement le plus courant consiste à lancer une demande synchrone pour ces opérations de démarrage/arrêt afin de simplifier le code d’application en mode utilisateur.

En cas d’arrêt anormal ou d’autre défaillance, RxStartMinirdr essaiera d’annuler ces opérations, notamment la désinscription du fournisseur UNC auprès de MUP, la désinscription du système de fichiers, la libération de la mémoire allouée pour le stockage du nom de domaine à utiliser par les diffusions de maillot et la mise à jour des tables RDBSS internes.