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.
NTSTATUS DriverEntry( _In_ PDRIVER_OBJECT DriverObject, _In_ PUNICODE_STRING RegistryPath );
- 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.
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.
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.
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.
|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.|