PMRX_CREATE_V_NET_ROOT fonction de rappel (mrx.h)

Article
02/07/2025

La routine MRxCreateVNetRoot est appelée par RDBSS pour demander que le mini-redirecteur réseau crée 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 enfin terminé. Cela inclut la structure RX_CONTEXT de la requête à Context->RxContext. Le paramètre Context inclut la structure de V_NET_ROOT à construire à Context->pVNetRoot. Cette structure V_NET_ROOT contient un pointeur vers la structure NET_ROOT à pVNetRoot->pNetRoot. La structure NET_ROOT contient également un pointeur vers la structure SRV_CALL à pNetRoot->pSrvCall.

Valeur de retour

RDBSS s’attend à ce que MRxCreateVNetRoot retourne STATUS_PENDING en cas de réussite ou d’échec. Ce comportement résulte du fait que RDBSS s’attend à ce que cet appel soit effectué de façon asynchrone. Un mini-redirecteur réseau doit mapper STATUS_SUCCESS à STATUS_PENDING comme valeur de retour pour MRxCreateVNetRoot.

L’état d’achèvement final est retourné dans Context->VirtualNetRootStatus et Context->Membres NetRootStat us une fois l’appel terminé et la routine dans le membre de Contexte est appelé par le mini-redirecteur réseau. Ces membres contiennent initialement STATUS_SUCCESS jusqu’à ce que le mini-redirecteur réseau modifie cette valeur à la fin. Si l’appel s’est terminé avec succès, 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 lesVirtualNetRootStatus ou membre NetRootStatus est retourné (bien que d’autres codes d’erreur soient possibles) :

Retourner le code	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 distant n’était pas prêt à satisfaire la demande.
STATUS_UNEXPECTED_NETWORK_ERROR	Une erreur réseau inattendue s’est produite généralement à cause 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 sous la forme d’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 une connexion réseau avec une ressource distante peut avoir besoin d’être établie. Pour vous assurer que les opérations asynchrones continuent, 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’état d’achèvement de la demande adressée au mini-redirecteur réseau. Étant donné que RDBSS attend MRxCreateVNetRoot est terminé de façon asynchrone, RDBSS s’attend à ce que MRxCreateVNetRoot retourne STATUS_PENDING. RdBSS sera averti à l’aide de la routine de rappel une fois l’appel terminé.

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

Une nouvelle structure V_NET_ROOT et la nouvelle structure NET_ROOT associée sont créées.
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 avertir RDBSS que l’appel a été terminé et retourner l’état d’achèvement. La routine de rappel à laquelle le mini-redirecteur réseau doit appeler est spécifiée en tant que membre rappel dans la structure MRX_CREATENETROOT_CONTEXT passée en tant que paramètre de contexte . L’état d’achèvement final de l’appel MRxCreateVNetRoot doit être stocké dans le VirtualNetRootStatus et les membres NetRootStatus du paramètre Context. Notez que l’état distinct est retourné 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 du 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 se termine, 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’est pas logique. 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îtra pas pendant que ces handles de transport sont utilisés pour la communication.

Une méthode utilisée pour gérer cela dans les mini-redirecteurs réseau consiste à faire en sorte 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 d'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, pour éviter les problèmes, si la demande d'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 toutes les poignées de transport seront détenues par un processus système.

Un mini-redirecteur réseau peut déterminer si un appel à MRxCreateVNetRoot a été reçu directement 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 à une file d’attente de travail à l’aide de RxDispatchToWorkerThread pour une exécution ultérieure par RDBSS. Normalement, ces appels seront publiés sur le DelayedWorkQueue.

Il incombe 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 qui est 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 la NET_ROOT et V_NET_ROOT structures en mode déconnecté (si cela est pris en charge) et établir la connexion hors connexion.

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