DriverEntry (Compact 2013)
This is a required function that the system calls first in any NDIS driver.
NDIS miniports and intermediate drivers perform two basic tasks in their DriverEntry functions:
Call NdisMInitializeWrapper to notify the NDIS library that the driver is about to register itself as a miniport.
NDIS sets up the state that it has to have to track the driver and returns an NdisWrapperHandle, which the driver saves for subsequent calls to NdisXxx configuration and initialization functions.
Fill in an NDISXX_MINIPORT_CHARCTERISTICS structure with the appropriate version numbers and the entry points for driver-supplied MiniportXxx functions and, then, call NdisMRegisterMiniport or NdisIMRegisterLayeredMiniport.
Usually, network adapter drivers call NdisMRegisterMiniport, as do intermediate drivers that export only a set of MiniportXxx functions. Usually, NDIS intermediate drivers call NdisIMRegisterLayeredMiniport. This effectively delays the initialization of such a driver's virtual network adapter until the driver calls NdisIMInitializeDeviceInstance from its ProtocolBindAdapter function.
DriverEntry can allocate the NDISXX_MINIPORT_CHARACTERISTICS structure on the stack because the NDIS library copies the relevant information to its own storage. DriverEntry should clear the memory for this structure with NdisZeroMemory before setting any driver-supplied values in its members. The current MajorNdisVersion is 0x05, and the current MinorNdisVersion is 0x00. In each XxxHandler member of the characteristics structure, DriverEntry must set the name of a driver-supplied MiniportXxx function, or the member must be NULL.
Calling NdisMRegisterMiniport causes the driver's MiniportInitialize function to run in the context of NdisMRegisterMiniport. Calling NdisIMRegisterLayeredMiniport postpones the call to MiniportInitialize until the driver calls NdisIMInitializeDeviceInstance.
Drivers that call NdisMRegisterMiniport must be prepared for an immediate call to their MiniportInitialize functions. Such a driver must have sufficient installation and configuration information that is stored in the registry or available from calls to an NdisXxx bus-type-specific configuration function to set up any network adapter-specific resources the driver must perform network I/O operations.
Drivers that call NdisIMRegisterLayeredMiniport delay the call to their MiniportInitialize functions to another driver-supplied function that makes a call to NdisIMInitializeDeviceInstance. NDIS intermediate drivers usually register a ProtocolBindAdapter function and call NdisIMRegisterLayeredMiniport so that NDIS will call the ProtocolBindAdapter function after all underlying network adapter drivers have initialized. This strategy gives such an NDIS intermediate driver. This makes the call to NdisIMInitializeDeviceInstance from ProtocolBindAdapter, the advantage of having its MiniportInitialize function configure driver-allocated resources for the intermediate's virtual network adapter to the features of the underlying network adapter driver to which the intermediate has already bound itself.
If NdisMRegisterMiniport or NdisIMRegisterLayeredMiniport does not return NDIS_STATUS_SUCCESS, DriverEntry must release any resources it allocated, such as memory to hold the NdisWrapperHandle, and must call NdisTerminateWrapper before it returns control. The driver will not be loaded if this occurs.