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, AddDevice, and optional Reinitialize routines and to its Unload routine, if any.

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

Accessible Members

PDEVICE_OBJECT DeviceObject

Pointer to the device objects created by the driver. This member is automatically updated when the driver calls IoCreateDevice successfully. A driver can use this member and the NextDevice member of DEVICE_OBJECT to step through a list of all the device objects that the driver created.

PDRIVER_EXTENSION DriverExtension

Pointer to the driver extension. The only accessible member of the driver extension is DriverExtension->AddDevice, into which a driver's DriverEntry routine stores the driver's AddDevice routine.

PUNICODE_STRING HardwareDatabase

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

PFAST_IO_DISPATCH FastIoDispatch

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

PDRIVER_INITIALIZE DriverInit

The entry point for the DriverEntry routine, which is set up by the I/O Manager.

PDRIVER_STARTIO DriverStartIo

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 member is NULL.

PDRIVER_UNLOAD DriverUnload

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 member is NULL.

PDRIVER_DISPATCH MajorFunction[IRP_MJ_MAXIMUM_FUNCTION+1]

A dispatch table consisting of an array of entry points for the driver’s DispatchXxx routines. The array's index values are the IRP_MJ_Xxx values representing each IRP major function code. Each driver must set entry points in this array for the IRP_MJ_Xxx requests that the driver handles. For more information, see Writing Dispatch Routines. Each DispatchXxx routine is declared as follows:

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

Headers

Defined in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

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 DispatchXxx entry points 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 DispatchXxx 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 DispatchXxx 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 DispatchXxx 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 IRP Major Function Codes.

The DriverEntry routine also sets the driver’s AddDevice, 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 members within a driver object should be considered inaccessible. Drivers with dependencies on object member locations or on access to undocumented members might not remain portable and interoperable with other drivers over time.

See Also

DriverEntry, IoCreateDevice, IoDeleteDevice, StartIo, Unload