Initializing a Protocol Driver
The system calls a protocol driver's DriverEntry routine after it loads the driver. Protocol drivers load as system services. They can load at any time before, during, or after the miniport drivers load.
Protocol drivers allocate driver resources and register ProtocolXxx functions in DriverEntry. This includes CoNDIS clients and stand-alone call managers. To register its ProtocolXxx functions with NDIS, a protocol driver calls the NdisRegisterProtocolDriver function.
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.
NDIS protocol drivers provide the following ProtocolXxx functions, which are updated versions of the functions that legacy drivers provide:
ProtocolCloseAdapterCompleteEx
NDIS protocol drivers provide the following ProtocolXxx functions for send and receive operations:
ProtocolSendNetBufferListsComplete
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 allow a protocol driver to configure optional services, NDIS calls the ProtocolSetOptions function within the context of the protocol driver's call to NdisRegisterProtocolDriver. For more information about optional services, see Configuring Optional Protocol Driver Services.
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.
To unregister with NDIS, a protocol driver calls NdisDeregisterProtocolDriver from its Unload routine.
To perform cleanup operations before a protocol driver is uninstalled, a protocol driver can register a ProtocolUninstall function. The ProtocolUninstall function is optional. For example, the protocol lower edge of an intermediate driver might require a ProtocolUninstall function. The intermediate driver can release its protocol edge resources in ProtocolUninstall before NDIS calls its MiniportDriverUnload function.