Driver Registration and Start/Stop Control
When the operating system is started, Windows loads RDBSS and any network mini-redirector drivers based on settings in the registry. For a monolithic network mini-redirector driver, which is linked statically with rdbsslib.lib, the driver must call the RxDriverEntry routine from its DriverEntry routine to initialize the copy of the RDBSSLIB library linked with the network driver. In this case, the RxDriverEntry routine must be called before any other RDBSS routines are called and used. For a non-monolithic network mini-redirector driver (the Microsoft SMB redirector), the rdbss.sys device driver is initialized in its own DriverEntry routine when loaded.
A network mini-redirector registers with RDBSS when the driver is loaded by the kernel and unregisters with RDBSS when the driver is unloaded. A network mini-redirector informs RDBSS that it has been loaded by calling RxRegisterMinirdr, the registration routine exported from RDBSS. As part of this registration process, the network mini-redirector passes a parameter to RxRegisterMinirdr that is a pointer to a large structure, MINIRDR_DISPATCH. This structure contains configuration information for the network mini-redirector and a dispatch table of pointers to callback routines implemented by the network mini-redirector kernel driver. RDBSS makes calls to the network mini-redirector driver through this list of callback routines.
The RxRegisterMinirdr routine sets all of the driver dispatch routines of the network mini-redirector driver to point to the top-level RDBSS dispatch routine, RxFsdDispatch. A network mini-redirector can override this behavior by saving its own entry points and rewriting the driver dispatch with its own entry points after the call to RxRegisterMinirdr returns or by setting a special parameter when calling RxRegisterMinirdr.
The network mini-redirector driver does not actually start operation until it receives a call to its MRxStart routine, one of the callback routines passed in the MINIRDR_DISPATCH structure. The MrxStart callback routine must be implemented by the network mini-redirector driver if it wishes to receive callback routines for operations unless the network mini-redirector preserves its own driver dispatch entry points. Otherwise, RDBSS will only allow the following I/O request packets through to the driver until MrxStart returns successfully:
- IRP requests for device creates and device operations where the FileObject->FileName.Length on the IRPSP is zero and the FileObject->RelatedFileObject is NULL.
For any other IRP request, the RDBSS dispatch routine RxFsdDispatch will return a status of STATUS_REDIRECTOR_NOT_STARTED.
The RDBSS dispatch routine will also fail any requests for the following I/O request packets:
IRP_MJ_CREATE_MAILSLOT
IRP_MJ_CREATE_NAMED_PIPE
The MrxStart callback routine implemented by the network mini-redirector is called by RDBSS when the RxStartMinirdr routine is called. The RDBSS RxStartMinirdr routine is usually called as a result of a file system control code (FSCTL) or I/O control code (IOCTL) request from a user-mode application or service to start the network mini-redirector. The call to RxStartMinirdr cannot be made from the DriverEntry routine of the network mini-redirector after a successful call to RxRegisterMinirdrsince some of the start processing requires that the driver initialization be completed. Once the RxStartMinirdr call is received, RDBSS completes the start process by calling the MrxStart routine of the network mini-redirector. If the call to MrxStart returns success, RDBSS sets the internal state of the mini-redirector in RDBSS to RDBSS_STARTED.
RDBSS exports a routine, RxSetDomainForMailslotBroadcast, to set the domain for mailslot broadcasts. This routine is used during registration if the network mini-redirector supports mailslots.
A convenience routine, __RxFillAndInstallFastIoDispatch, exported by RDBSS can be used to copy all of the IRP_MJ_XXX driver routine pointers for handling I/O request processing to the comparable fast I/O dispatch vectors, but this routine only works for non-monolithic drivers.
RDBSS also exports routines to notify RDBSS that the network mini-redirector is starting or stopping. These calls are used if a network mini-redirector includes a user-mode administration service or utility application that starts and stops the redirector. This user-mode service or application can send custom FSCTL or IOCTL requests to the network mini-redirector driver to indicate that it should start or stop. The redirector can call the RDBSS RxStartMinirdr or RxStopMinirdr routines to notify RDBSS to start or stop this network mini-redirector.
The following table lists the RDBSS driver registration and start/stop control routines.
| Routine | Description |
|---|---|
This routine is called by a monolithic network mini-redirector driver from its DriverEntry routine to initialize RDBSS. For non-monolithic drivers, this initialization routine is equivalent to the DriverEntry routine of the rbss.sys device driver. |
|
This routine is called by a network mini-redirector driver to register the driver with RDBSS, which adds the registration information to an internal registration table. RDBSS also builds a device object for the network mini-redirector. |
|
This routine is called by a network mini-redirector driver to set the domain used for mailslot broadcasts, if mailslots are supported by the driver. |
|
This routine starts up a network mini-redirector that called to register itself. RDBSS will also register the network mini-redirector driver as a UNC provider with the MUP if the driver indicates support for UNC names. |
|
This routine stops a network mini-redirector driver. A driver that is stopped will no longer receive new commands except IOCTL or FSCTL requests. |
|
This routine is called by a network mini-redirector driver to de-register the driver with RDBSS and remove the registration information from the internal RDBSS registration table. |
|
This routine is an inline function defined in rxstruc.h that is called by a network mini-redirector driver to de-register the driver with RDBSS and remove the registration information from the internal RDBSS registration table. The RxUnregisterMinirdr inline function internally calls RxpUnregisterMinirdr. |
|
This routine fills out a fast I/O dispatch vector to be identical with the normal dispatch I/O vector and installs it into the driver object associated with the device object passed. |
The following macro is defined in the mrx.h header file that calls one of these routines. This macro is normally used instead of calling the __RxFillAndInstallFastIoDispatch routine directly.
| Macro | Description |
|---|---|
RxFillAndInstallFastIoDispatch(__devobj, __fastiodisp) |
This macro calls __RxFillAndInstallFastIoDispatchto fill out a fast I/O dispatch vector to be identical with the normal dispatch I/O vector and installs it into the driver object associated with the device object passed. |