Fonction RxRegisterMinirdr (mrx.h)

Article
08/07/2023

RxRegisterMinirdr est appelé par un pilote de mini-redirecteur réseau pour inscrire le pilote auprès de RDBSS, ce qui ajoute les informations d’inscription à une table d’inscription interne. RDBSS génère également un objet d’appareil pour le mini-redirecteur réseau.

Syntaxe

NTSTATUS RxRegisterMinirdr(
  [out]     OUT PRDBSS_DEVICE_OBJECT *DeviceObject,
  [in, out] IN OUT PDRIVER_OBJECT    DriverObject,
  [in]      IN PMINIRDR_DISPATCH     MrdrDispatch,
  [in]      IN ULONG                 Controls,
  [in]      IN PUNICODE_STRING       DeviceName,
  [in]      IN ULONG                 DeviceExtensionSize,
  [in]      IN DEVICE_TYPE           DeviceType,
  [in]      IN ULONG                 DeviceCharacteristics
);

Paramètres

[out] DeviceObject

Pointeur vers l’emplacement où l’objet d’appareil créé sera stocké.

[in, out] DriverObject

Pointeur vers l’objet pilote du pilote de mini-redirecteur réseau. Chaque pilote reçoit un pointeur vers son objet pilote dans un paramètre vers sa routine DriverEntry . Cet objet de pilote sera utilisé pour créer l’objet d’appareil pour le pilote de mini-redirecteur réseau.

[in] MrdrDispatch

Pointeur vers la table de répartition pour le mini-redirecteur réseau. Cette table de répartition comprend 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 noyau du mini-redirecteur réseau. RDBSS appelle le pilote de mini-redirecteur réseau via cette liste de routines de rappel.

[in] Controls

Ensemble d’options qui déterminent les fonctionnalités du pilote de mini-redirecteur réseau et la façon dont RDBSS doit gérer l’initialisation et la mise en cache des tables de noms pour le pilote de mini-redirecteur réseau. Ces options peuvent inclure n’importe quelle combinaison des bits suivants :

RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS

Lorsque cet indicateur est défini, il indique que le mini-redirecteur réseau ne prend pas en charge les noms UNC.

RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS

Lorsque cet indicateur est défini, il indique que le mini-redirecteur réseau ne prend pas en charge les mailslots.

RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH

Lorsque cet indicateur est défini, il indique que le mini-redirecteur réseau ne souhaite pas que RDBSSs initialise les points d’entrée de répartition du pilote du mini-redirecteur pour pointer vers les routines internes RDBSS. Cette option ne serait utilisée que dans des circonstances inhabituelles. Normalement, RDBSS définit les points d’entrée de distribution du pilote et la répartition rapide des E/S dans l’objet de pilote de mini-redirecteur réseau pour pointer vers des routines internes à RDBSS.

RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER

Lorsque cet indicateur est défini, il indique que le mini-redirecteur réseau ne souhaite pas que RDBSS initialise sa table de noms de réseau interne et les structures de données de récupération de cette table de noms. Cette option est définie pour un mini-redirecteur réseau qui souhaite gérer la mise en cache pour les noms de partage réseau lui-même et ne pas utiliser les fonctionnalités RDBSS pour la mise en cache et la recherche de noms.

[in] DeviceName

Pointeur vers une mémoire tampon qui contient une chaîne Unicode sans fin qui nomme l’objet d’appareil. La chaîne doit être un nom de chemin d’accès complet. Ce paramètre est passé en tant que DeviceName à la routine IoCreateDevice par RDBSS.

[in] DeviceExtensionSize

Taille spécifiée par le pilote de mini-redirecteur pour le nombre d’octets à allouer pour l’extension de périphérique de l’objet d’appareil. La structure interne de l’extension de périphérique est définie par le pilote. Ce paramètre est ajouté à la taille de l’extension d’appareil utilisée par RDBSS et passé en tant que paramètre DeviceExtensionSize à la routine IoCreateDevice par RDBSS.

[in] DeviceType

Type d’appareil utilisé lors de la création de l’objet d’appareil. Cela spécifie l’une des constantes FILE_DEVICE_XXX définies par le système qui indiquent le type d’appareil ou une valeur définie par le fournisseur pour un nouveau type d’appareil. Cette valeur est normalement FILE_DEVICE_NETWORK_FILE_SYSTEM pour les pilotes de mini-redirecteur réseau. Ce paramètre est passé en tant que DeviceType à la routine IoCreateDevice par RDBSS.

[in] DeviceCharacteristics

Caractéristiques de l’appareil utilisées lors de la création de l’objet d’appareil. Cela spécifie une ou plusieurs constantes définies par le système, combinées, qui fournissent des informations supplémentaires sur l’appareil du pilote. Cette valeur doit inclure FILE_REMOTE_DEVICE pour les pilotes de mini-redirecteur réseau, mais elle peut être combinée à d’autres caractéristiques telles que FILE_DEVICE_SECURE_OPEN. Ce paramètre est passé en tant que DeviceCharacteristics à la routine IoCreateDevice par RDBSS.

Valeur retournée

RxRegisterMinirdr retourne STATUS_SUCCESS en cas de réussite ou l’une des valeurs d’erreur suivantes en cas d’échec :

Code de retour	Description
STATUS_INSUFFICIENT_RESOURCES	Les ressources étaient insuffisantes pour créer l’objet d’appareil.
STATUS_INVALID_PARAMETER	Un paramètre non valide a été passé à la routine. Cette erreur sera retournée si le paramètre DeviceObject est un pointeur NULL .
STATUS_OBJECT_NAME_COLLISION	Une collision de nom s’est produite lors de la tentative de création de cet objet d’appareil.
STATUS_OBJECT_NAME_EXISTS	Un objet d’appareil portant ce nom existe déjà.
STATUS_UNSUCCESSFUL	L’appel de création de l’objet d’appareil a renvoyé un objet d’appareil NULL .

Remarques

Un mini-redirecteur réseau s’inscrit auprès de RDBSS chaque fois que le pilote est chargé par le noyau et se désinscrit auprès de RDBSS lorsque le pilote est déchargé. Un pilote non monolithique (le mini-redirecteur réseau SMB) communique avec le Rdbss.sys, un autre pilote de noyau. Pour un pilote de mini-redirecteur réseau monolithique qui établit un lien statique avec Rdbsslib.lib, cette communication est simplement un appel à une routine de bibliothèque Rdbsslib.lib .

Un mini-redirecteur réseau informe RDBSS qu’il a été chargé en appelant RxRegisterMinirdr, la routine d’inscription exportée à partir de RDBSS. Lorsqu’un pilote de mini-redirecteur réseau démarre pour la première fois (dans sa routine DriverEntry ), le pilote appelle la routine RDBSS RxRegisterMinirdr pour inscrire le pilote de mini-redirecteur réseau auprès de RDBSS. En fonction des paramètres passés à RxRegisterMinirdr, RDBSS appelle IoCreateDevice pour créer l’objet d’appareil pour le pilote de mini-redirecteur réseau.

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 répartition des pointeurs vers les routines de rappel implémentées par le pilote de mini-redirecteur réseau. Ces données de configuration sont utilisées pour configurer des tables RDBSS internes à utiliser avec ce mini-redirecteur réseau. RDBSS utilise les routines de rappel transmises dans cette structure pour communiquer avec le mini-redirecteur réseau. Un mini-redirecteur réseau peut choisir d’implémenter uniquement certaines de ces routines de rappel. Toute routine de rappel qui n’est pas implémentée doit être définie sur un pointeur NULL dans la table de répartition passée à RDBSS. Seules les routines de rappel implémentées par le mini-redirecteur réseau seront appelées par RDBSS.

Notez que la routine RxRegisterMinirdr définit toutes les routines de répartition des pilotes du pilote de mini-redirecteur réseau pour qu’elles pointent vers la routine de répartition RDBSS de niveau supérieur, RxFsdDispatch. Un mini-redirecteur réseau peut remplacer ce comportement en enregistrant une copie de ses points d’entrée de répartition du pilote, en appelant RxRegisterMinirdr et en réécrivant la répartition du pilote avec ses propres points d’entrée après le retour de l’appel à RxRegisterMinirdr . Un mini-redirecteur réseau peut également empêcher la copie de ses routines de distribution de pilotes par la routine RxRegisterMinirdr si le RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH bit est défini dans le paramètre Controls .

Si l’appel RxRegisterMinirdr réussit, un certain nombre de membres dans RDBSS_DEVICE_OBJECT pointés par le paramètre DeviceObject sont initialisés, notamment :

Le membre Dispatch est défini sur le paramètre MrdrDispatch .
Le membre RegistrationControls est défini sur le paramètre Controls .
Le membre DeviceName est défini sur le paramètre DeviceName .
Le membre RegisterUncProvider a la valeur TRUE si le bit RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS dans le paramètre Controls n’a pas été défini.
Le membre RegisterMailSlotProvider a la valeur TRUE si le bit RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS dans le paramètre Controls n’a pas été défini.
Le membre NetworkProviderPriority est défini sur la priorité du fournisseur réseau que MUP utilisera.

Si l’appel RxRegisterMinirdr réussit et que le RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER bit du paramètre Controls n’est pas défini, un certain nombre d’autres membres dans RDBSS_DEVICE_OBJECT pointés vers le paramètre DeviceObject sont initialisés, notamment :

La structure de membre pRxNetNameTable est initialisée.
Le membre RxNetNameTableInDeviceObject.IsNetNameTable a la valeur TRUE.
La structure de membre pRdbssScavenger est initialisée.

Si l’appel RxRegisterMinirdr réussit, RDBSS définit l’état interne du mini-redirecteur réseau dans RDBSS pour RDBSS_STARTABLE.

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 rappels 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. Le RDBSS RxStartMinirdr est généralement appelé à 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. Une fois l’appel RxStartMinirdr reçu, RDBSS termine le processus de démarrage en appelant la routine MrxStart du mini-redirecteur réseau. Si l’appel à MrxStart retourne la réussite, RDBSS définit l’état interne du mini-redirecteur dans RDBSS sur RDBSS_STARTED.