DRIVER_OBJECT

DRIVER_OBJECT

Each driver object represents the image of a loaded kernel-mode driver. A pointer to the driver object is an input parameter to a driver's DriverEntry and optional Reinitialize routines and to its Unload routine, if any.

A driver object is partially opaque. Driver writers must know about certain fields of a driver object to initialize a driver and to unload it if the driver is unloadable. The following fields in the driver object are accessible to drivers.

Accessible Fields

PDEVICE_OBJECT DeviceObject

Points to the device object(s) created by the driver. This field is automatically updated when the DriverEntry routine calls IoCreateDevice successfully. If a driver is unloaded, its Unload routine uses this field and the NextDevice field of the DEVICE_OBJECT to call IoDeleteDevice with each device object that the driver created.

PUNICODE_STRING HardwareDatabase

Points to the \Registry\Machine\Hardware path to the hardware configuration information in the registry.

PFAST_IO_DISPATCH FastIoDispatch

Points to a structure defining the driver's fast I/O entry points. This field is used only by FSDs and network transport drivers.

PDRIVER_INITIALIZE DriverInit

Is the entry point for the DriverEntry routine, which is set up by the I/O Manager. A DriverEntry routine is declared as follows:

NTSTATUS (*PDRIVER_INITIALIZE) ( IN PDRIVER_OBJECT DriverObject, IN PUNICODE_STRING RegistryPath );

PDRIVER_STARTIO DriverStartIo

Is the entry point for the driver's StartIo routine, if any, which is set by the DriverEntry routine when the driver initializes. If a driver has no StartIo routine, this field is NULL. A StartIo routine is declared as follows:

VOID (*PDRIVER_STARTIO) ( IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp );

PDRIVER_UNLOAD DriverUnload

Is the entry point for the driver's Unload routine, if any, which is set by the DriverEntry routine when the driver initializes. If a driver has no Unload routine, this field is NULL. An Unload routine is declared as follows:

VOID (*PDRIVER_UNLOAD) ( IN PDRIVER_OBJECT DriverObject );

PDRIVER_DISPATCH MajorFunction[IRP_MJ_MAXIMUM_FUNCTION+1]

Is an array of one or more entry points for the driver's Dispatch routines. Each driver must set at least one Dispatch entry point in this array for the IRP_MJ_XXX requests that the driver handles. Any driver can set as many separate Dispatch entry points as the IRP_MJ_XXX codes that the driver handles. Each Dispatch routine is declared as follows:

NTSTATUS (*PDRIVER_DISPATCH) ( IN PDEVICE_OBJECT DeviceObject, IN PIRP Irp );

Comments

Each kernel-mode driver's initialization routine should be named DriverEntry so the system will load the driver automatically. If this routine's name is something else, the driver writer must define the name of the initialization routine for the linker; otherwise, the OS loader or I/O Manager cannot find the driver's transfer address. The names of other standard driver routines can be chosen at the discretion of the driver writer.

A driver must set its Dispatch entry point(s) in the driver object that is passed in to the DriverEntry routine when the driver is loaded. A device driver must set one or more Dispatch entry points for the IRP_MJ_XXX that any driver of the same type of device is required to handle. A higher-level driver must set one or more Dispatch entry points for all the IRP_MJ_XXX that it must pass on to the underlying device driver. Otherwise, a driver is not sent IRPs for any IRP_MJ_XXX for which it does not set up a Dispatch routine in the driver object. For more information about the set of IRP_MJ_XXX that drivers for different types of underlying devices are required to handle, see Part II of this manual.

The DriverEntry routine also sets the driver's StartIo and/or Unload entry points, if any, in the driver object.

The HardwareDatabase string can be used by device drivers to get hardware configuration information from the registry when the driver is loaded. A driver is given read-only access to this string.

The RegistryPath input to the DriverEntry routine points to the \Registry\Machine\System\CurrentControlSet\Services\DriverName key, where the value entry of DriverName identifies the driver. As for the HardwareDatabase in the input driver object, a driver is given read-only access to this string.

Undocumented fields within a driver object should be considered inaccessible. Drivers with dependencies on object field locations or access to undocumented fields might not remain portable and interoperable with other drivers over time.