PMRX_CREATE_V_NET_ROOT función de devolución de llamada (mrx.h)

Artículo
10/13/2023

RDBSS llama a la rutina MRxCreateVNetRoot para solicitar que el minidirector de red cree una estructura de V_NET_ROOT y, en algunos casos, una estructura de NET_ROOT.

Sintaxis

PMRX_CREATE_V_NET_ROOT PmrxCreateVNetRoot;

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

Parámetros

Context

[in, out] Puntero al contexto de devolución de llamada usado por el minidirector de red para notificar a RDBSS cuando se complete la llamada. Esto incluye la estructura RX_CONTEXT de la solicitud en Context-RxContext>. El parámetro Context incluye la estructura V_NET_ROOT que se va a construir en Context-pVNetRoot>. Esta estructura V_NET_ROOT contiene un puntero a la estructura de NET_ROOT en pVNetRoot-pNetRoot>. La estructura NET_ROOT también contiene un puntero a la estructura de SRV_CALL en pNetRoot-pSrvCall>.

Valor devuelto

RDBSS espera que MRxCreateVNetRoot devuelva STATUS_PENDING en caso de éxito o error. Este comportamiento resulta porque RDBSS espera que esta llamada se complete de forma asincrónica. Un minidirector de red debe asignar STATUS_SUCCESS a STATUS_PENDING como valor devuelto para MRxCreateVNetRoot.

El estado de finalización final se devuelve en los miembros Context-VirtualNetRootStatus> y Context-NetRootStatus> una vez completada la llamada y la rutina del miembro Callback de la estructura Context la llama el minidirector de red. Estos miembros contienen inicialmente STATUS_SUCCESS hasta que el minidirector de red cambia este valor al finalizar. Si la llamada se completó correctamente, ambos miembros contienen STATUS_SUCCESS.

Si no se crea una estructura de V_NET_ROOT o NET_ROOT, se devuelve uno de los siguientes códigos de error comunes para el miembroVirtualNetRootStatus o NetRootStatus (aunque son posibles otros códigos de error):

Código devuelto	Descripción
STATUS_CONNECTION_RESET	Se restableció la conexión al recurso remoto.
STATUS_IO_TIMEOUT	Se ha agotado el tiempo de espera en una solicitud de E/S.
STATUS_RETRY	Un servidor de arranque remoto no estaba listo para satisfacer la solicitud.
STATUS_UNEXPECTED_NETWORK_ERROR	Normalmente, se produjo un error de red inesperado causado por un identificador no válido.

Comentarios

Las dos abstracciones importantes usadas en la interfaz entre RDBSS y un minidirector de red son la estructura de SRV_CALL y la estructura NET_ROOT/V_NET_ROOT. Una estructura de SRV_CALL corresponde al contexto asociado a un servidor con el que se ha establecido una conexión. Una estructura de NET_ROOT corresponde a un recurso compartido en un servidor. Una estructura de V_NET_ROOT podría verse como una parte del espacio de nombres debajo de una estructura de NET_ROOT reclamada por un minidirector de red.

La creación de una estructura de NET_ROOT/V_NET_ROOT normalmente implica al menos un recorrido de ida y vuelta de red. Esta operación puede tardar mucho tiempo en completarse porque es posible que sea necesario establecer una conexión de red con un recurso remoto. Para asegurarse de que las operaciones asincrónicas continúan, la creación de una estructura de NET_ROOT o V_NET_ROOT se modela como una actividad en dos fases. Cada llamada a un minidirector de red para crear una estructura de NET_ROOT/V_NET_ROOT va seguida de una llamada desde el minidirector de red a RDBSS que indica al RDBSS el estado de finalización de la solicitud al minidirector de red. Dado que RDBSS espera que MRxCreateVNetRoot se complete de forma asincrónica, RDBSS espera que MRxCreateVNetRoot devuelva STATUS_PENDING. Se notificará a RDBSS mediante la rutina de devolución de llamada cuando finalice la llamada.

MRxCreateVNetRoot debe tratar dos casos de interés:

Se va a crear una nueva estructura de V_NET_ROOT y la nueva estructura de NET_ROOT asociada.
Se crea una nueva estructura de V_NET_ROOT asociada a una estructura de NET_ROOT existente.

Estos dos casos se pueden distinguir comprobando si el contexto asociado a una estructura de NET_ROOT es NULL.

Se espera que una implementación de minidirectora de red de MRxCreateVNetRoot devuelva STATUS_PENDING a la llamada inicial. Cuando se completa el procesamiento, el minidirector de red llamaría a la rutina de devolución de llamada pasada como parte del parámetro Context para notificar a RDBSS que la llamada se completó y devolvería el estado de finalización. La rutina de devolución de llamada a la que debe llamar el minidirector de red se especifica como miembro de devolución de llamada en la estructura de MRX_CREATENETROOT_CONTEXT pasada como parámetro Context . El estado de finalización final de la llamada MRxCreateVNetRoot debe almacenarse en los miembros VirtualNetRootStatus y NetRootStatus del parámetro Context . Tenga en cuenta que se devuelve un estado independiente para las estructuras de NET_ROOT y V_NET_ROOT.

La implementación de MRxCreateVNetRoot en un minidirector de red también es complicada por la necesidad de controladores de transporte. Ciertas interfaces relacionadas con el transporte requieren que se cree y use un identificador para toda la comunicación. La creación de una estructura de NET_ROOT o V_NET_ROOT puede requerir el establecimiento de identificadores relacionados con el transporte para las comunicaciones de red. Dado que el proceso de establecimiento de una conexión de red puede llevar mucho tiempo, una vez establecida una conexión, tiene sentido usar la conexión para la comunicación siempre que sea posible. Una vez establecido un identificador de transporte a un recurso de red remota, se puede reutilizar mediante cualquier número de solicitudes de aplicación. Cuando finaliza una aplicación de usuario, se eliminan los identificadores asociados al proceso. Por este motivo, establecer controladores de transporte en el contexto de un proceso transitorio en modo de usuario que podría ser de corta duración no tiene sentido. Por lo tanto, una estructura NET_ROOT o V_NET_ROOT normalmente debe inicializarse en el contexto de un proceso conocido que no desaparecerá mientras se usan estos controladores de transporte para la comunicación.

Un método que se usa para administrar esto en los mini-redireccionadores de red es hacer que el proceso del sistema RDBSS asigne estos identificadores de transporte. Esto afecta a cómo se ejecuta la rutina MRxCreateVNetRoot . Si la solicitud a MRxCreateVNetRoot se emitió en el contexto del proceso del sistema RDBSS, esta llamada se puede ejecutar inmediatamente y no es necesario publicarla en una cola de trabajo. Sin embargo, para evitar problemas, si la solicitud a MRxCreateVNetRoot procede de cualquier otro proceso, la solicitud se publicaría en una cola de trabajo del sistema mediante RxDispatchToWorkerThread para su posterior ejecución. RDBSS usará más adelante uno de sus subprocesos del sistema para procesar la solicitud de cola de trabajo y ejecutar MRxCreateVNetRoot. Esto garantiza que los controladores de transporte sean propiedad de un proceso del sistema.

Un minidirector de red puede determinar si una llamada a MRxCreateVNetRoot se recibió directamente desde RDBSS mediante una llamada a RxGetRDBSSProcess. RxGetRDBSSProcess devuelve el proceso RDBBS y este valor se puede comparar con el proceso actual devuelto mediante una llamada a IoGetCurrentProcess. Si la llamada a MRxCreateVNetRoot no se inició en el contexto del proceso del sistema RDBSS, MRxCreateVNetRoot puede devolver STATUS_PENDING y publicar la llamada a una cola de trabajo mediante RxDispatchToWorkerThread para su posterior ejecución mediante RDBSS. Normalmente, estas llamadas se publicarían en DelayedWorkQueue.

Es el minidirector de red el que decide cómo se implementa MRxCreateVNetRoot . Si este proceso puede tardar mucho tiempo, esta llamada se debe completar de forma asincrónica. Si se necesitan controladores de transporte, es posible que el minidirector de red quiera un proceso del sistema de larga duración para establecer estos identificadores.

En caso de que no se pueda establecer la conexión, el minidirector de red puede intentar realizar la transición de la NET_ROOT y V_NET_ROOT estructuras a un modo desconectado (si se admite) y establecer la conexión sin conexión.

Cuando se completa MRxCreateVNetRoot , el parámetro Context debe modificarse con la información de estructura NET_ROOT y V_NET_ROOT adecuada que se actualiza desde el minidirector de red.