NdisMRegisterDevice function (ndis.h)

Article
01/05/2023

Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

The NdisMRegisterDevice function creates a named device object and a symbolic link between the device object and a user-visible name for that device.

Syntax

NDIS_STATUS NdisMRegisterDevice(
  [in]  NDIS_HANDLE      NdisWrapperHandle,
  [in]  PNDIS_STRING     DeviceName,
  [in]  PNDIS_STRING     SymbolicName,
  [in]  PDRIVER_DISPATCH *MajorFunctions,
  [in]  PDEVICE_OBJECT   *pDeviceObject,
  [out] NDIS_HANDLE      *NdisDeviceHandle
);

Parameters

[in] NdisWrapperHandle

Specifies the handle returned by NdisMInitializeWrapper.

[in] DeviceName

Pointer to an NDIS_STRING type containing a null-terminated Unicode string that names the device object. The string must be a full-path name--for example, \Device\DeviceName. For Windows 2000 and later, NDIS defines the NDIS_STRING type as a UNICODE_STRING type.

[in] SymbolicName

Pointer to an NDIS_STRING type containing a Unicode string that is the Win32-visible name of the device being registered. Typically, the SymbolicName has the following format: \DosDevices\SymbolicName.

[in] MajorFunctions

Pointer to an array of one or more entry points for the device driver's dispatch routines. A driver must set as many separate dispatch entry points as the IRP_MJ_XXX codes that the driver handles for the device object. Each dispatch routine is declared as follows:

NTSTATUS
(*PDRIVER_DISPATCH) (
    IN PDEVICE_OBJECT Device Object,
    IN PIRP Irp
)   ;

A driver must not supply entry points for Plug and Play or Power Management handlers since the created device object is not for a physical device and therefore does not receive Plug and Play or Power Management IRPs.

[in] pDeviceObject

Pointer to the newly created device object if the call succeeds.

[out] NdisDeviceHandle

Pointer to a caller-supplied variable in which this function, if it succeeds, returns a handle to the device object. This handle is a required parameter to the NdisMDeregisterDevice function that the driver calls subsequently.

Return value

NdisMRegisterDevice returns STATUS_SUCCESS if it succeeds, NDIS_STATUS_NOT_SUPPORTED if the caller is not an NDIS miniport driver, or a failure code if it fails.

Remarks

An intermediate driver or miniport driver may require a separate, stand-alone device object. For example, an intermediate miniport driver might require a stand-alone device object to monitor the status of an underlying NIC when the NIC's miniport driver is not up and running. To obtain the NIC's status in such a case, a user-mode application or environmental subsystem sends an IRP to the device object. The IRP is processed by the intermediate driver. Without the stand-alone device object, the NIC's status is available only when the NIC's miniport driver is up and running.

An intermediate driver or miniport driver creates a device object by calling NdisMRegisterDevice from its DriverEntry function after DriverEntry has called NdisMInitializeWrapper. NdisMRegisterDevice creates a named device object and also a symbolic link between the device object name and a user-visible name for that device. If the call to NdisMRegisterDevice succeeds, the I/O manager allocates storage in nonpaged pool for the device object itself and for all other data structures associated with the device object, including the driver's device extension. The device extension for an object created with NdisMRegisterDevice is reserved for use by NDIS and cannot be used by the driver.

A device object created with NdisMRegisterDevice functions in the same way as a device object and symbolic link that were created with IoCreateDevice and IoCreateSymbolicLink, respectively. The miniport driver is responsible for processing all IRPs that it receives for the device object. (NDIS processes all Plug and Play and power management IRPs sent to the device object.) The driver processes IRPs sent to the device object using dispatch routines that it registered when it supplied the MajorFunctions pointer to NdisMRegisterDevice. For more information about device objects, IRPs, and dispatch routines, see Device Objects and Device Stacks, Handling IRPs, and Writing Dispatch Routines.

NDIS miniport and intermediate drivers should never call IoCreateDevice or IoCreateSymbolicLink. Instead, if an NDIS driver must create a device object, it should call NdisMRegisterDevice. Miniport and intermediate drivers should never attempt to stack the device object over the physical device object by calling IoAttachDevice.

The device object that is created with NdisMRegisterDevice is not a physical device object and therefore does not receive Plug and Play or Power Management IRPs. Callers of NdisMRegisterDevice must therefore omit entry points for Plug and Play or Power Management handlers in the array that is pointed to by MajorFunctions.

Note that, if a handle to the device object that is created with NdisMRegisterDevice is open, the driver that created the device object cannot be unloaded. A user-mode application should therefore do either of the following:

When the application registers for device event notification on the underlying device by calling the RegisterDeviceNotification function, specify a DBT_DEVTYP_HANDLE type notification filter. (For more information about the RegisterDeviceNotification function, see the Microsoft Windows SDK documentation.) If the application subsequently receives a DBT_DEVICEQUERYREMOVE event for the device, the application should close the open handle.
When the application registers for device event notification on the underlying device by calling the RegisterDeviceNotification function, specify a DBT_DEVTYP_DEVICEINTERFACE type notification filter and GUID_NDIS_LAN_CLASS as the interface class GUID. If the application subsequently receives a DBT_DEVICEREMOVECOMPLETE event for the device interface to which the handle corresponds, the application should close the open handle.

If a driver's call to NdisMRegisterDevice fails, the driver can continue to load or not, depending on how critical the stand-alone device object is for the driver's operation.

Target platform: Universal
Version: Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisRegisterDeviceExinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.

Requirements

Requirement	Value
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL