Función RxStartMinirdr (mrx.h)

Artículo
04/18/2024

Se llama a RxStartMinirdr para iniciar un minidirector de red al que se ha llamado anteriormente para registrarse con RDBSS. Como parte de RxStartMinirdr, RDBSS también registrará el controlador mini-redirector de red como proveedor de convención de nomenclatura universal (UNC) con el proveedor unc múltiple (MUP) si el controlador indica compatibilidad con nombres UNC.

Sintaxis

NTSTATUS RxStartMinirdr(
  [in]  IN PRX_CONTEXT RxContext,
  [out] OUT PBOOLEAN   PostToFsp
);

Parámetros

[in] RxContext

Puntero a la estructura RX_CONTEXT que se va a usar para obtener el objeto de dispositivo y determinar si se trata de un proceso del sistema de archivos.

[out] PostToFsp

Puntero a un valor lógico establecido en TRUE al devolver si el proceso del sistema de archivos debe publicar la solicitud para su posterior procesamiento.

Valor devuelto

RxStartMinirdr devuelve STATUS_SUCCESS si la secuencia de inicio se realizó correctamente o uno de los siguientes valores de error:

Código devuelto	Descripción
STATUS_ACCESS_DENIED	Error en la solicitud de registro como proveedor UNC porque se denegó el acceso.
STATUS_ACCESS_VIOLATION	Error en la solicitud para registrarse como proveedor UNC con una infracción de acceso.
STATUS_INSUFFICIENT_RESOURCES	No había recursos suficientes para completar esta rutina.
STATUS_PENDING	La secuencia de inicio para RDBSS y miniireccionadores de red debe completarse en el contexto del proceso del sistema, no en un proceso de aplicación en modo de usuario. Si la llamada a RxStartMinirdr procede de un proceso en modo de usuario (una solicitud de servicio en modo de usuario, por ejemplo), la solicitud se publica para su posterior procesamiento en RDBSS y se devolverá STATUS_PENDING. Este error también se puede devolver si no se pueden adquirir determinados bloqueos RDBSS internos sin esperar. La llamada se completará más adelante desde un subproceso del sistema.
STATUS_REDIRECTOR_STARTED	El minidirector de red ya se inició.

Comentarios

Un minidirector de red se registra con RDBSS cada vez que el kernel carga el controlador y, a continuación, anula el registro con RDBSS cuando se descarga el controlador. Un minidirector de red informa a RDBSS de que se ha cargado llamando a RxRegisterMinirdr, la rutina de registro exportada desde RDBSS. Como parte de este proceso de registro, el minidirector de red pasa un parámetro a RxRegisterMinirdr que es un puntero a una estructura grande, MINIRDR_DISPATCH, que contiene información de configuración para el minidirector de red y una tabla de punteros a rutinas de devolución de llamada implementadas por el controlador de minidirector de red. RDBSS usa las rutinas de devolución de llamada pasadas en esta estructura para comunicarse con el minidirector de red.

El minidirector de red no inicia realmente la operación hasta que recibe una llamada a su rutina MRxStart , una de las rutinas de devolución de llamada pasadas en la estructura MINIRDR_DISPATCH. La rutina de devolución de llamada MrxStart debe implementarse mediante el controlador mini-redirector de red si desea recibir rutinas de devolución de llamada para las operaciones a menos que el minidirector de red conserve sus propios puntos de entrada de envío del controlador. De lo contrario, RDBSS solo permitirá los siguientes paquetes de solicitud de E/S al controlador hasta que MrxStart se devuelva correctamente:

Solicitudes IRP para operaciones de creación de dispositivos y operaciones de dispositivo donde el parámetro FileObject-FileName.Length> en IRPSP es cero y el parámetro FileObject-RelatedFileObject> es NULL.

Para cualquier otra solicitud IRP, la rutina de distribución rdBSS RxFsdDispatch devolverá un estado de STATUS_REDIRECTOR_NOT_STARTED.

La rutina de distribución de RDBSS también producirá un error en las solicitudes de los siguientes paquetes de solicitud de E/S:

IRP_MJ_CREATE_MAILSLOT
IRP_MJ_CREATE_NAMED_PIPE

RDBSS llama a la rutina MrxStart minidirector de red cuando se llama a la rutina RxStartMinirdr . La rutina RDBSS RxStartMinirdr suele llamarse como resultado de una solicitud FSCTL o IOCTL de una aplicación o servicio en modo de usuario para iniciar el minidirector de red. La llamada a RxStartMinirdr no se puede realizar desde la rutina DriverEntry del minidirector de red después de una llamada correcta a RxRegisterMinirdr , ya que algunos de los procesos iniciales requieren que se complete la inicialización del controlador.

Cuando RDBSS recibe una solicitud FSCTL o IOCTL enviada al controlador minidirector de red desde el modo de usuario, RDBSS crea una estructura de RX_CONTEXT y pasa esta llamada a la rutina de devolución de llamada MRxLowIOSubmit[LOWIO_OP_FSCTL] o MRxLowIOSubmit[LOWIO_OP_IOCTL] definida en la estructura de MINIRDR_DISPATCH. La implementación del minidirector de red de esta rutina de devolución de llamada reconocería la solicitud para iniciar y llamar a RxStartMinirdr. Este proceso normal de eventos se muestra a continuación con más detalle:

Una aplicación en modo de usuario emite una solicitud FSCTL o IOCTL privada para iniciar el minidirector de red.
El controlador del kernel RDBSS recibe la solicitud FSCTL o IOCTL en nombre del minidirector de red, ya que RDBSS ha reemplazado los puntos de entrada de envío del controlador del minidirector para que apunten a las rutinas internas de RDBSS. Tenga en cuenta que se supone que el minidirector de red no estableció el RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH en el parámetro Controls al llamar a RxRegisterMinirdr. Esta opción pasada a RxRegisterMinirdr sería inusual e indica que el minidirector de red no quiere que RDBSS reemplace sus puntos de entrada de distribución del controlador.
RDBSS recibe la solicitud FSCTL o IOCTL internamente en nombre del redirector de red. El distribuidor de RDBSS asigna e inicializa una estructura de RX_CONTEXT. A continuación, RDBSS llama a la rutina MRxLowIOSubmit[LOW_OP_FSCTL] o MRxLowIOSubmit[LOW_OP_IOCTL] definida en la estructura de MINIRDR_DISPATCH para este minidirector de red, pasando la estructura de RX_CONTEXT inicializada como parámetro.
La implementación de minidirector de red de esta rutina de devolución de llamada reconocería la solicitud FSCTL o IOCTL privada para iniciar y llamar a RxStartMinirdr, pasando un puntero a la estructura RX_CONTEXT que recibió de RDBSS como el parámetro RxContext y la dirección del miembro PostToFSP de RxContext como el parámetro PostToFsp .
Dado que esta llamada se inició desde el modo de usuario, RxStartMinirdr devolvería STATUS_PENDING y establecería PostToFsp en TRUE.
La rutina MRxLowIOSubmit[LOW_OP_FSCTL] o MRxLowIOSubmit[LOW_OP_IOCTL] de red recibiría este valor devuelto y lo devolvería al distribuidor de RDBSS.
El distribuidor rdbss recibiría el valor devuelto STATUS_PENDING y establecería PostToFsp en TRUE y, a continuación, publicaría una solicitud en un subproceso de trabajo para volver a ejecutar la llamada al minidirector de red.

Después de este punto, hay dos posibles resultados en función de si el FSCTL o el IOCTL se solicitó como una operación asincrónica o sincrónica.

Si se trata de una solicitud asincrónica, se produciría lo siguiente:

El llamador en modo de usuario recibiría la respuesta STATUS_PENDING de la llamada. El subproceso de trabajo publicado llamaría finalmente a RxStartMinirdr desde un subproceso del sistema de archivos y la llamada se procesaría. La rutina RxStartMinirdr intentará registrar el minidirector de red como proveedor UNC, si se solicita. En versiones de Windows anteriores a Windows Vista, RDBSS intentará registrar el minidirector de red como sistema de archivos con el administrador de E/S. Si estas llamadas se realizan correctamente, RxStartMinirdr llama a la rutina de devolución de llamada MrxStart implementada por el minidirector de red. El valor devuelto de MrxStart se devolvería finalmente a la aplicación en modo de usuario que inició el proceso de secuencia de llamada como una operación asincrónica.

Si se trata de una solicitud sincrónica, se produciría lo siguiente:

El llamador en modo de usuario no recibiría la respuesta de STATUS_PENDING, pero se forzaría a esperar hasta que la llamada devuelta desde el subproceso de trabajo publicado. El subproceso de trabajo publicado llamaría finalmente a RxStartMinirdr desde un subproceso del sistema de archivos y la llamada se procesaría. La rutina RxStartMinirdr intentará registrar el minidirector de red como proveedor UNC, si se solicita. En versiones de Windows anteriores a Windows Vista, RDBSS intentará registrar el minidirector de red como sistema de archivos con el administrador de E/S. Si estas llamadas se realizan correctamente, RxStartMinirdr llama a la rutina de devolución de llamada MrxStart implementada por el minidirector de red. El valor devuelto de MrxStart se devolvería a la aplicación en modo de usuario que inició el proceso de secuencia de llamada.

Si un minidirector de red indica compatibilidad con UNC al registrarse con RDBSS (el parámetro Controls en RxRegisterMinirdr), RxStartMinirdr intentará registrar el parámetro DeviceName del minidirector de red como proveedor UNC con MUP (RDBSS llama a FsRtlRegisterUncProvider en nombre del minidirector de red).

En las versiones de Windows anteriores a Windows Vista, RxStartMinirdr registra el sistema de archivos con el administrador de E/S (RDBSS llama a IoRegisterFileSystem en nombre del minidirector de red).

Si las llamadas se realizan correctamente, RxStartMinirdr llama a la rutina MrxStart minidirector de red. Si MrxStart devuelve éxito, el estado interno del minidirector en RDBSS se establece en RDBSS_STARTED. El miembro StartStopContext.Version del objeto de dispositivo minidirector también se incrementará.

La secuencia de inicio para RDBSS y el minidirector de red deben completarse en el contexto del proceso del sistema si se solicita una operación asincrónica. Si la llamada a RxStartMinirdr procede de un proceso en modo de usuario (una solicitud de servicio en modo de usuario, por ejemplo), RDBSS publicará internamente la solicitud en una cola de trabajo para su procesamiento posterior y se devolverá STATUS_PENDING y el parámetro PostToFsp se establecerá en TRUE. Además, si no se pueden obtener determinados bloqueos RDBSS internos sin esperar, se devuelve STATUS_PENDING y PostToFsp se establece en TRUE. Cuando se devuelve STATUS_PENDING, se volverá a llamar a RxStartMinirdr desde un proceso del sistema. Si la solicitud FSCTL o IOCTL que inició la llamada a RxStartMinirdr se estableció para la operación asincrónica, RDBSS devolvería STATUS_PENDING realizar una copia de seguridad de la cadena de llamadas a la solicitud FSCTL o IOCTL original desde el modo de usuario. Por el contrario, si la solicitud FSCTL o IOCTL era para una operación sincrónica, la llamada también se publicaría en un subproceso de trabajo para su posterior ejecución, pero la llamada FSCTL o IOCTL no volvería al modo de usuario hasta que RxStartMinirdr se hubiera ejecutado en el contexto del proceso del sistema de archivos. En este caso, el autor de la llamada del FSCTL o IOCTL nunca vería la devolución del error STATUS_PENDING. El comportamiento más típico es iniciar una solicitud sincrónica para estas operaciones de inicio y detención para simplificar el código de la aplicación en modo de usuario.

En una terminación anómala u otro error, RxStartMinirdr intentará deshacer estas operaciones, incluido anular el registro del proveedor UNC con MUP, anular el registro del sistema de archivos, liberar memoria asignada para almacenar el nombre de dominio que usarán las difusiones de mailslot y actualizar las tablas RDBSS internas.