PMRX_CREATE_SRVCALL fonction de rappel (mrx.h)

Article
02/26/2024

La routine MRxCreateSrvCall est appelée par RDBSS pour demander au mini-redirecteur réseau de créer une structure SRV_CALL et d’établir une connexion avec un serveur.

Syntaxe

PMRX_CREATE_SRVCALL PmrxCreateSrvcall;

NTSTATUS PmrxCreateSrvcall(
  IN OUT PMRX_SRV_CALL SrvCall,
  IN OUT PMRX_SRVCALL_CALLBACK_CONTEXT SrvCallCallBackContext
)
{...}

Paramètres

SrvCall

[in, out] Pointeur vers la structure SRV_CALL à créer.

SrvCallCallBackContext

[in, out] Pointeur vers le contexte de rappel utilisé par le mini-redirecteur réseau pour notifier RDBSS lorsque la demande MRxCreateSrvCall est enfin terminée. Le paramètre SrvCallCallBackContext pointe vers une structure MRX_SRVCALLDOWN_STRUCTURE qui contient la structure RX_CONTEXT de cette requête, ainsi que la routine de rappel que le mini-redirecteur appelle lorsque la demande MRxCreateSrvCall est enfin terminée.

Valeur retournée

RDBSS s’attend à ce que MRxCreateSrvCall retourne STATUS_PENDING en cas de réussite ou d’échec. Ce comportement se produit, car 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 MRxCreateSrvCall.

Le status d’achèvement final est retourné dans le membre SrvCallCallBackContext-Status> une fois l’appel terminé et la routine dans le membre de rappel de la structure MRX_SRVCALLDOWN_STRUCTURE est appelée par le mini-redirecteur réseau. Ce membre contient initialement STATUS_BAD_NETWORK_PATH jusqu’à ce que le mini-redirecteur réseau modifie cette valeur à l’achèvement.

Le membre SrvCallCallBackContext-Status> contient STATUS_SUCCESS sur la réussite une fois l’appel terminé ou l’un des codes d’erreur courants suivants en cas d’échec (bien que d’autres codes d’erreur soient possibles) :

Code de retour	Description
STATUS_BAD_NETWORK_PATH	Le chemin d’accès réseau spécifié est incorrect.
STATUS_NETWORK_UNREACHABLE	Le réseau était inaccessible.

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. Une structure SRV_CALL correspond au contexte associé à un serveur une fois qu’une connexion est établie. Une structure NET_ROOT correspond à un partage sur un serveur (il peut également être vu comme une partie de l’espace de noms revendiqué par un mini-redirecteur réseau).

La création d’une structure de SRV_CALL 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 SRV_CALL est modélisée comme une activité en deux phases. Chaque appel à un mini-redirecteur réseau pour créer une structure de SRV_CALL est accompagné d’un appel du mini-redirecteur réseau vers RDBSS qui spécifie l’achèvement status de la demande. RDBSS suppose que MRxCreateSrvCall sera effectué de manière asynchrone. Par conséquent, RDBSS s’attend à ce que MRxCreateSrvCall retourne STATUS_PENDING. RDBSS sera averti à l’aide de la routine de rappel une fois l’appel terminé.

Une implémentation de mini-redirecteur réseau de MRxCreateSrvCall est censée retourner STATUS_PENDING à l’appel initial. Une fois le traitement terminé, le mini-redirecteur réseau appelle la routine de rappel transmise dans le cadre du paramètre SrvCallCallBackContext pour informer RDBSS que l’appel a été terminé et pour retourner la status d’achèvement. La routine de rappel que le mini-redirecteur réseau appelle est spécifiée en tant que membre de rappel dans le MRX_SRVCALLDOWN_STRUCTURE du paramètre SrvCallCallBackContext . L’achèvement final status de l’appel doit être stocké dans le membre Status du paramètre SrvCallCallBackContext.

En cas de réussite, le mini-redirecteur réseau doit également stocker une valeur dans le membre RecommunicateContext du SrvCallCallBackContext. La valeur stockée dans le membre RecommunicateContext est la valeur que RDBSS passera à MRxSrvCallWinnerNotify dans le paramètre RecommunicateContext si MRxCreateSrvCall a réussi. Le mini-redirecteur réseau doit également remplir les données appropriées dans le paramètre SrvCall pour la structure SRV_CALL qui a été créée. Notez que le paramètre SrvCall passé à MRxCreateSrvCall est identique au membre SrvCall dans le MRX_SRVCALLDOWN_STRUCTURE du paramètre SrvCallCallBackContext . Ce même paramètre SrvCall est également passé à MRxSrvCallWinnerNotify dans le paramètre SrvCall .

L’implémentation de MRxCreateSrvCall dans un mini-redirecteur réseau est également compliquée par le besoin 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 SRV_CALL 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 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 pourrait être de courte durée n’a pas de sens. Par conséquent, une structure de SRV_CALL 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.

L’une des méthodes utilisées pour contourner les problèmes potentiels liés aux poignées de transport consiste à ce que le processus système RDBSS alloue les handles de transport. Cela affecte la façon dont la routine MRxCreateSrvCall est exécutée. Si la demande adressée à MRxCreateSrvCall 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 à MRxCreateSrvCall 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 MRxCreateSrvCall. Cela garantit que tous les handles de transport seront détenus par un processus système.

Un mini-redirecteur réseau peut déterminer si un appel à MRxCreateSrvCall 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é à l’aide d’IoGetCurrentProcess. Si l’appel à MRxCreateSrvCall n’a pas été lancé dans le contexte du processus système RDBSS, MRxCreateSrvCall peut retourner STATUS_PENDING et publier l’appel à une file d’attente de travail à l’aide de RxDispatchToWorkerThreadpour une exécution ultérieure par RDBSS. Normalement, ces appels sont affichés dans la DelayedWorkQueue.

Il incombe au développeur du mini-redirecteur réseau de décider de la façon dont MRxCreateSrvCall est implémenté. Si le processus de création d’un SRV_CALL peut prendre beaucoup de temps, MRxCreateSrvCall doit être effectué de manière asynchrone. Si des handles de transport sont nécessaires, le mini-redirecteur réseau doit trouver un processus système de longue durée pour établir ces handles.

Une fois cet appel terminé, le paramètre SrvCall doit être modifié avec les informations de structure SRV_CALL mises à jour à partir du mini-redirecteur réseau.

Un mini-redirecteur réseau qui indique la prise en charge en tant que fournisseur UNC reçoit une revendication de préfixe de la part du fournisseur MULTIPLE UNC (MUP) en tant qu’appel à MRxCreateSrvCall. Pour plus d’informations sur le nommage UNC et MUP, consultez Prise en charge de l’affectation de noms UNC et de MUP.