DriverEntry of NDIS Protocol Drivers function

The DriverEntry function is required and is the first function that the system calls in any NDIS protocol driver, including CoNDIS clients and stand-alone call managers.

Syntax


NTSTATUS DriverEntry(
  _In_  PDRIVER_OBJECT DriverObject,
  _In_  PUNICODE_STRING RegistryPath
);

Parameters

DriverObject [in]

A pointer to the driver object that represents this driver.

RegistryPath [in]

A pointer to a driver-specific registry path specification set up by the driver's installation file (.inf). For more information about driver installation files, see Device Installation Overview.

Return value

DriverEntry returns STATUS_SUCCESS, or its equivalent NDIS_STATUS_SUCCESS, if the driver registered as an NDIS protocol driver successfully. If DriverEntry fails initialization by propagating an error status that was returned by an NdisXxx function or by a kernel-mode support routine, the driver will not remain loaded. DriverEntry must execute synchronously; that is, it cannot return STATUS_PENDING or its equivalent NDIS_STATUS_PENDING.

Remarks

The DriverEntry function of an NDIS protocol driver must call the NdisRegisterProtocolDriver function. To register the driver's ProtocolXxx entry points with the NDIS library, a protocol driver initializes an NDIS_PROTOCOL_DRIVER_CHARACTERISTICS structure and passes it to NdisRegisterProtocolDriver.

Drivers that call NdisRegisterProtocolDriver must be prepared for an immediate call to any of their ProtocolXxx functions.

All types of NDIS protocol drivers should register fully functional ProtocolBindAdapterEx and ProtocolUnbindAdapterEx functions to support Plug and Play (PnP). In general, a DriverEntry function should call NdisRegisterProtocolDriver immediately before it returns control with a status value of STATUS_SUCCESS or NDIS_STATUS_SUCCESS.

Any protocol driver that exports a set of standard kernel-mode driver routines in addition to its NDIS-defined ProtocolXxx functions must set the entry points for those driver routines in the given driver object that is passed in to its DriverEntry function. For more information about the functionality of such a protocol driver's DriverEntry function, see Writing a DriverEntry Routine.

If an attempt to allocate resources that the driver needs to carry out network I/O operations fails, DriverEntry should release all resources that it already allocated before it returns control with a status other than STATUS_SUCCESS or NDIS_STATUS_SUCCESS.

If an error occurs after a successful call to NdisRegisterProtocolDriver, the driver must call the NdisDeregisterProtocolDriver function before DriverEntry returns.

To enable protocol drivers to register optional services, NDIS calls the ProtocolSetOptions function, if this function exists, within the context of NdisRegisterProtocolDriver.

CoNDIS client drivers must call the NdisSetOptionalHandlers function from the ProtocolSetOptions function. The driver initializes an NDIS_CO_CLIENT_OPTIONAL_HANDLERS structure and passes it at the OptionalHandlers parameter of NdisSetOptionalHandlers.

CoNDIS stand-alone call managers must also call the NdisSetOptionalHandlers function from the ProtocolSetOptions function. The driver initializes an NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS structure and passes it at the OptionalHandlers parameter of NdisSetOptionalHandlers.

MCMs are not protocol drivers. Therefore, they must call the NdisSetOptionalHandlers function from the MiniportSetOptions function. The MCM initializes an NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS structure and passes it at the OptionalHandlers parameter of NdisSetOptionalHandlers.

Intermediate drivers share most of the DriverEntry requirements of protocol drivers. For more information about the DriverEntry function for intermediate drivers, see DriverEntry of NDIS Intermediate Drivers.

Requirements

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers (see DriverEntry of NDIS Protocol Drivers (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see DriverEntry of NDIS Protocol Drivers (NDIS 5.1)) in Windows XP.

Header

Ndis.h (include Ndis.h)

IRQL

PASSIVE_LEVEL

See also

MiniportSetOptions
NDIS_CO_CLIENT_OPTIONAL_HANDLERS
NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS
NDIS_PROTOCOL_DRIVER_CHARACTERISTICS
NdisDeregisterProtocolDriver
NdisRegisterProtocolDriver
NdisSetOptionalHandlers
ProtocolBindAdapterEx
ProtocolSetOptions
ProtocolUnbindAdapterEx

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft