PMRX_CREATE_V_NET_ROOT fonction de rappel (mrx.h)

Article
10/13/2023

La routine MRxCreateVNetRoot est appelée par RDBSS pour demander au mini-redirecteur réseau de créer une structure V_NET_ROOT et, dans certains cas, une structure NET_ROOT.

Syntaxe

PMRX_CREATE_V_NET_ROOT PmrxCreateVNetRoot;

NTSTATUS PmrxCreateVNetRoot(
  IN OUT PMRX_CREATENETROOT_CONTEXT Context
)
{...}

Paramètres

Context

[in, out] Pointeur vers le contexte de rappel utilisé par le mini-redirecteur réseau pour notifier RDBSS lorsque l’appel est terminé. Cela inclut la structure RX_CONTEXT de la requête dans Context-RxContext>. Le paramètre Context inclut la structure V_NET_ROOT à construire dans Context-pVNetRoot>. Cette structure V_NET_ROOT contient un pointeur vers la structure NET_ROOT sur pVNetRoot-pNetRoot>. La structure NET_ROOT contient également un pointeur vers la structure SRV_CALL sur pNetRoot-pSrvCall>.

Valeur retournée

RDBSS s’attend à ce que MRxCreateVNetRoot retourne STATUS_PENDING en cas de réussite ou d’échec. Ce comportement est dû au fait que RDBSS s’attend à ce que cet appel soit effectué de manière asynchrone. Un mini-redirecteur réseau doit mapper STATUS_SUCCESS à STATUS_PENDING comme valeur de retour pour MRxCreateVNetRoot.

La status d’achèvement finale est retournée dans les membres Context-VirtualNetRootStatus> et Context-NetRootStatus> une fois l’appel terminé et la routine dans le membre de rappel de la structure Context est appelée par le mini-redirecteur réseau. Ces membres contiennent initialement STATUS_SUCCESS jusqu’à ce que le mini-redirecteur réseau modifie cette valeur à l’achèvement. Si l’appel s’est terminé correctement, les deux membres contiennent STATUS_SUCCESS.

En cas d’échec de création d’une structure V_NET_ROOT ou NET_ROOT, l’un des codes d’erreur courants suivants pour le membreVirtualNetRootStatus ou NetRootStatus est retourné (bien que d’autres codes d’erreur soient possibles) :

Code de retour	Description
STATUS_CONNECTION_RESET	La connexion à la ressource distante a été réinitialisée.
STATUS_IO_TIMEOUT	Un délai d’expiration s’est produit sur une demande d’E/S.
STATUS_RETRY	Un serveur de démarrage à distance n’était pas prêt à satisfaire la demande.
STATUS_UNEXPECTED_NETWORK_ERROR	Une erreur réseau inattendue s’est généralement produite en raison d’un handle non valide.

Remarques

Les deux abstractions importantes utilisées dans l’interface entre RDBSS et un mini-redirecteur réseau sont la structure SRV_CALL et la structure NET_ROOT/V_NET_ROOT. Une structure SRV_CALL correspond au contexte associé à un serveur avec lequel une connexion a été établie. Une structure NET_ROOT correspond à un partage sur un serveur. Une structure V_NET_ROOT peut être vue comme une partie de l’espace de noms sous une structure NET_ROOT revendiquée par un mini-redirecteur réseau.

La création d’une structure NET_ROOT/V_NET_ROOT implique généralement au moins un aller-retour réseau. Cette opération peut prendre beaucoup de temps, car il peut être nécessaire d’établir une connexion réseau avec une ressource distante. Pour garantir la poursuite des opérations asynchrones, la création d’une structure NET_ROOT/V_NET_ROOT est modélisée comme une activité en deux phases. Chaque appel à un mini-redirecteur réseau pour la création d’une structure NET_ROOT/V_NET_ROOT est suivi d’un rappel du mini-redirecteur réseau vers RDBSS qui indique à RDBSS l’achèvement status de la demande au mini-redirecteur réseau. Étant donné que RDBSS s’attend à ce que MRxCreateVNetRoot soit terminé de manière asynchrone, RDBSS s’attend à ce que MRxCreateVNetRoot retourne STATUS_PENDING. RdBSS sera averti à l’aide de la routine de rappel lorsque l’appel se terminera finalement.

MRxCreateVNetRoot doit traiter deux cas d’intérêt :

Une nouvelle structure V_NET_ROOT et la nouvelle structure de NET_ROOT associée sont en cours de création.
Une nouvelle structure V_NET_ROOT associée à une structure NET_ROOT existante est en cours de création.

Ces deux cas peuvent être distingués en vérifiant si le contexte associé à une structure NET_ROOT est NULL.

Une implémentation de mini-redirecteur réseau de MRxCreateVNetRoot est censée retourner STATUS_PENDING à l’appel initial. Une fois le traitement terminé, le mini-redirecteur réseau appelle la routine de rappel passée dans le cadre du paramètre Context pour informer RDBSS que l’appel a été effectué et retourner l’achèvement status. La routine de rappel à laquelle le mini-redirecteur réseau doit appeler est spécifiée en tant que membre de rappel dans la structure MRX_CREATENETROOT_CONTEXT passée en tant que paramètre Context . La status d’achèvement finale de l’appel MRxCreateVNetRoot doit être stockée dans les membres VirtualNetRootStatus et NetRootStatus du paramètre Context. Notez que des status distinctes sont retournées pour les structures NET_ROOT et V_NET_ROOT.

L’implémentation de MRxCreateVNetRoot dans un mini-redirecteur réseau est également compliquée par la nécessité de handles de transport. Certaines interfaces liées au transport nécessitent la création et l’utilisation d’un handle pour toutes les communications. La création d’une structure NET_ROOT ou V_NET_ROOT peut nécessiter l’établissement de handles liés au transport pour les communications réseau. Étant donné que le processus d’établissement d’une connexion réseau peut prendre beaucoup de temps, une fois qu’une connexion est établie, il est judicieux d’utiliser la connexion pour la communication aussi longtemps que possible. Une fois qu’un handle de transport vers une ressource réseau distante est établi, il peut être réutilisé par n’importe quel nombre d’autres demandes d’application. Lorsqu’une application utilisateur s’arrête, les handles associés au processus sont supprimés. Pour cette raison, l’établissement de handles de transport dans le contexte d’un processus temporaire en mode utilisateur qui peut être de courte durée n’a pas de sens. Par conséquent, une structure NET_ROOT ou V_NET_ROOT doit normalement être initialisée dans le contexte d’un processus bien connu qui ne disparaît pas pendant que ces poignées de transport sont utilisées pour la communication.

L’une des méthodes utilisées pour gérer cela dans les mini-redirecteurs réseau consiste à ce que le processus système RDBSS alloue ces handles de transport. Cela affecte la façon dont la routine MRxCreateVNetRoot est exécutée. Si la demande adressée à MRxCreateVNetRoot a été émise dans le contexte du processus système RDBSS, cet appel peut être exécuté immédiatement et n’a pas besoin d’être publié dans une file d’attente de travail. Toutefois, afin d’éviter les problèmes, si la demande adressée à MRxCreateVNetRoot provient d’un autre processus, la demande est publiée dans une file d’attente de travail système à l’aide de RxDispatchToWorkerThread pour une exécution ultérieure. RDBSS utilisera ultérieurement l’un de ses threads système pour traiter la demande de file d’attente de travail et exécuter MRxCreateVNetRoot. Cela garantit que tous les handles de transport appartiennent à un processus système.

Un mini-redirecteur réseau peut déterminer si un appel à MRxCreateVNetRoot a été reçu directement à partir de RDBSS en appelant RxGetRDBSSProcess. RxGetRDBSSProcess retourne le processus RDBBS et cette valeur peut être comparée au processus actuel retourné en appelant IoGetCurrentProcess. Si l’appel à MRxCreateVNetRoot n’a pas été lancé dans le contexte du processus système RDBSS, MRxCreateVNetRoot peut retourner STATUS_PENDING et publier l’appel dans une file d’attente de travail à l’aide de RxDispatchToWorkerThread pour une exécution ultérieure par RDBSS. Normalement, ces appels sont publiés sur delayedWorkQueue.

C’est au mini-redirecteur réseau de décider comment MRxCreateVNetRoot est implémenté. Si ce processus peut prendre beaucoup de temps, cet appel doit être effectué de manière asynchrone. Si des handles de transport sont nécessaires, le mini-redirecteur réseau peut souhaiter un processus système de longue durée pour établir ces handles.

Si la connexion ne peut pas être établie, le mini-redirecteur réseau peut essayer de faire passer les structures NET_ROOT et V_NET_ROOT en mode déconnecté (si cela est pris en charge) et d’établir la connexion hors connexion.

Une fois MRxCreateVNetRoot terminé, le paramètre Context doit être modifié avec les NET_ROOT et V_NET_ROOT informations de structure appropriées qui sont mises à jour à partir du mini-redirecteur réseau.