Función RxRegisterMinirdr (mrx.h)

Artículo
08/07/2023

Un controlador minidirector de red llama a RxRegisterMinirdr para registrar el controlador con RDBSS, que agrega la información de registro a una tabla de registro interna. RDBSS también crea un objeto de dispositivo para el minidirector de red.

Sintaxis

NTSTATUS RxRegisterMinirdr(
  [out]     OUT PRDBSS_DEVICE_OBJECT *DeviceObject,
  [in, out] IN OUT PDRIVER_OBJECT    DriverObject,
  [in]      IN PMINIRDR_DISPATCH     MrdrDispatch,
  [in]      IN ULONG                 Controls,
  [in]      IN PUNICODE_STRING       DeviceName,
  [in]      IN ULONG                 DeviceExtensionSize,
  [in]      IN DEVICE_TYPE           DeviceType,
  [in]      IN ULONG                 DeviceCharacteristics
);

Parámetros

[out] DeviceObject

Puntero a donde se almacenará el objeto de dispositivo creado.

[in, out] DriverObject

Puntero al objeto de controlador del controlador del controlador de minidirector de red. Cada controlador recibe un puntero a su objeto driver en un parámetro a su rutina DriverEntry . Este objeto de controlador se usará para crear el objeto de dispositivo para el controlador minidirector de red.

[in] MrdrDispatch

Puntero a la tabla de distribución del minidirector de red. Esta tabla de distribución incluye información de configuración para el minidirector de red y una tabla de punteros para las rutinas de devolución de llamada implementadas por el controlador de kernel minidirector de red. RDBSS realiza llamadas al controlador minidirector de red a través de esta lista de rutinas de devolución de llamada.

[in] Controls

Conjunto de opciones que determinan las funcionalidades del controlador minidirector de red y cómo RDBSS debe controlar la inicialización y el almacenamiento en caché de tablas de nombres para el controlador minidirector de red. Estas opciones pueden incluir cualquier combinación de los bits siguientes:

RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS

Cuando se establece esta marca, indica que el minidirector de red no admite nombres UNC.

RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS

Cuando se establece esta marca, indica que el minidirector de red no admite los gráficos de correo.

RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH

Cuando se establece esta marca, indica que el minidirector de red no quiere que RDBSS inicialice los puntos de entrada de distribución del controlador del controlador mini-redirector para que apunten a rutinas internas de RDBSS. Esta opción solo se usaría en circunstancias inusuales. Normalmente, RDBSS establecería los puntos de entrada de envío del controlador y el envío de E/S rápido en el objeto de controlador minidirector de red para que apunte a rutinas internas en RDBSS.

RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER

Cuando se establece esta marca, indica que el minidirector de red no quiere que RDBSS inicialice su tabla de nombres de red interna y las estructuras de datos de scavenger para eliminar esta tabla de nombres. Esta opción se establecería para un minidirector de red que quiera controlar el almacenamiento en caché para los nombres de recursos compartidos de red y no usar las instalaciones de RDBSS para el almacenamiento en caché de nombres y el scavenging.

[in] DeviceName

Puntero a un búfer que contiene una cadena Unicode terminada en cero que asigna un nombre al objeto de dispositivo. La cadena debe ser un nombre de ruta de acceso completa. Este parámetro se pasa como DeviceName a la rutina IoCreateDevice por RDBSS.

[in] DeviceExtensionSize

Tamaño especificado por el controlador minidirector para el número de bytes que se asignarán para la extensión del dispositivo del objeto de dispositivo. La estructura interna de la extensión de dispositivo está definida por el controlador. Este parámetro se agrega al tamaño de la extensión de dispositivo usada por RDBSS y se pasa como el parámetro DeviceExtensionSize a la rutina IoCreateDevice por RDBSS.

[in] DeviceType

Tipo de dispositivo que se usa cuando se crea el objeto de dispositivo. Esto especifica una de las constantes de FILE_DEVICE_XXX definidas por el sistema que indican el tipo de dispositivo o un valor definido por el proveedor para un nuevo tipo de dispositivo. Normalmente, este valor sería FILE_DEVICE_NETWORK_FILE_SYSTEM para los controladores de minidirector de red. Este parámetro se pasa como DeviceType a la rutina IoCreateDevice por RDBSS.

[in] DeviceCharacteristics

Características del dispositivo usadas cuando se crea el objeto de dispositivo. Esto especifica una o varias constantes definidas por el sistema, combinadas juntas, que proporcionan información adicional sobre el dispositivo del controlador. Este valor debe incluir FILE_REMOTE_DEVICE para los controladores de minidirector de red, pero esto puede combinarse con otras características, como FILE_DEVICE_SECURE_OPEN. Este parámetro se pasa como DeviceCharacteristics a la rutina IoCreateDevice por RDBSS.

Valor devuelto

RxRegisterMinirdr devuelve STATUS_SUCCESS si se ha realizado correctamente o uno de los siguientes valores de error en caso de error:

Código devuelto	Descripción
STATUS_INSUFFICIENT_RESOURCES	No había recursos suficientes para crear el objeto de dispositivo.
STATUS_INVALID_PARAMETER	Se pasó un parámetro no válido a la rutina. Este error se devolverá si el parámetro DeviceObject es un puntero NULL .
STATUS_OBJECT_NAME_COLLISION	Se produjo una colisión de nombres al intentar crear este objeto de dispositivo.
STATUS_OBJECT_NAME_EXISTS	Ya existe un objeto de dispositivo con este nombre.
STATUS_UNSUCCESSFUL	La llamada para crear el objeto de dispositivo devolvió un objeto de dispositivo NULL .

Comentarios

Un minidirector de red se registra con RDBSS cada vez que el kernel carga el controlador y anula el registro con RDBSS cuando se descarga el controlador. Un controlador no monolítico (el minidirector de red SMB) se comunica con el Rdbss.sys, otro controlador de kernel. Para un controlador minidirector de red monolítico que se vincula estáticamente con Rdbsslib.lib, esta comunicación es simplemente una llamada a una rutina de biblioteca Rdbsslib.lib .

Un minidirector de red informa a RDBSS de que se ha cargado mediante una llamada a RxRegisterMinirdr, la rutina de registro exportada desde RDBSS. Cuando se inicia por primera vez un controlador minidirector de red (en su rutina DriverEntry ), el controlador llama a la rutina RDBSS RxRegisterMinirdr para registrar el controlador minidirector de red con RDBSS. En función de los parámetros pasados a RxRegisterMinirdr, RDBSS llama a IoCreateDevice para crear el objeto de dispositivo para el controlador de minidirector de red.

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 distribución de punteros para las rutinas de devolución de llamada implementadas por el controlador mini-redirector de red. Estos datos de configuración se usan para configurar tablas RDBSS internas para su uso con este minidirector de red. RDBSS usa las rutinas de devolución de llamada pasadas en esta estructura para comunicarse con el minidirector de red. Un minidirector de red puede optar por implementar solo algunas de estas rutinas de devolución de llamada. Cualquier rutina de devolución de llamada que no se implemente debe establecerse en un puntero NULL en la tabla de distribución que se pasa a RDBSS. RdBSS llamará solo a las rutinas de devolución de llamada implementadas por el minidirector de red.

Tenga en cuenta que la rutina RxRegisterMinirdr establece todas las rutinas de distribución del controlador del minidirector de red para que apunten a la rutina de distribución rdBSS de nivel superior, RxFsdDispatch. Un minidirector de red puede invalidar este comportamiento guardando una copia de sus puntos de entrada de distribución del controlador, llamando a RxRegisterMinirdr y reescribiendo el envío del controlador con sus propios puntos de entrada después de la llamada a RxRegisterMinirdr devuelve. Un minidirector de red también puede impedir que la rutina rxRegisterMinirdr copie sus rutinas de distribución del controlador si el bit de RX_REGISTERMINI_FLAG_DONT_INIT_DRIVER_DISPATCH está establecido en el parámetro Controls .

Si la llamada a RxRegisterMinirdr se realiza correctamente, se inicializan varios miembros de RDBSS_DEVICE_OBJECT señalados por el parámetro DeviceObject , incluidos los siguientes:

El miembro Dispatch se establece en el parámetro MrdrDispatch .
El miembro RegistrationControls se establece en el parámetro Controls .
El miembro DeviceName se establece en el parámetro DeviceName .
El miembro RegisterUncProvider se establece en TRUE si no se estableció el bit de RX_REGISTERMINI_FLAG_DONT_PROVIDE_UNCS en el parámetro Controls .
El miembro RegisterMailSlotProvider se establece en TRUE si no se estableció el bit de RX_REGISTERMINI_FLAG_DONT_PROVIDE_MAILSLOTS en el parámetro Controls .
El miembro NetworkProviderPriority se establece en la prioridad del proveedor de red que usará MUP.

Si la llamada a RxRegisterMinirdr se realiza correctamente y no se establece el bit de RX_REGISTERMINI_FLAG_DONT_INIT_PREFIX_N_SCAVENGER en el parámetro Controls , se inicializa un número de otros miembros de RDBSS_DEVICE_OBJECT señalados por el parámetro DeviceObject , incluidos los siguientes:

Se inicializa la estructura de miembros pRxNetNameTable .
El miembro RxNetNameTableInDeviceObject.IsNetNameTable se establece en TRUE.
Se inicializa la estructura de miembros pRdbssScavenger .

Si la llamada a RxRegisterMinirdr se realiza correctamente, RDBSS establece el estado interno del minidirector de red en RDBSS en RDBSS_STARTABLE.

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 de MINIRDR_DISPATCH. La rutina de devolución de llamada MrxStart debe implementarse mediante el controlador minidirector de red si desea recibir devoluciones de llamada para las operaciones, a menos que el minidirector de red conserve sus propios puntos de entrada de distribución de controladores. De lo contrario, RDBSS solo permitirá los siguientes paquetes de solicitud de E/S al controlador hasta que MrxStart 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 de 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 . Normalmente, se llama a RDBSS RxStartMinirdr como resultado de una solicitud FSCTL o IOCTL de una aplicación o servicio en modo de usuario para iniciar el minidirector de red. No se puede realizar la llamada a RxStartMinirdr desde la rutina DriverEntry del minidirector de red después de una llamada correcta a RxRegisterMinirdr porque parte del procesamiento inicial requiere que se complete la inicialización del controlador. Una vez recibida la llamada a RxStartMinirdr , RDBSS completa el proceso de inicio llamando a la rutina MrxStart del minidirector de red. Si la llamada a MrxStart devuelve éxito, RDBSS establece el estado interno del minidirector en RDBSS en RDBSS_STARTED.