DriverEntry

DriverEntry is a required function, which the system calls first in any NDIS driver.

NDIS_STATUS DriverEntry(
IN PDRIVER_OBJECT DriverObject,
IN PUNICODE_STRING RegistryPath ); 

Parameters

• DriverObject
  Points to a system-supplied parameter. For Windows® CE drivers, this points to a driver object, which is opaque to any NDIS driver that exports only MiniportXXX functions.
• RegistryPath
  Points to a second system-supplied parameter. For Windows CE drivers, this points to a registry path, which is opaque to any NDIS driver that exports only MiniportXXX functions.

Return Values

DriverEntry returns the value returned by NdisMRegisterMiniport or NdisIMRegisterLayeredMiniport.

Remarks

NDIS miniports and intermediate drivers carry out two basic tasks in their DriverEntry functions:

1. Call NdisMInitializeWrapper to notify the NDIS library that the driver is about to register itself as a miniport.

   NDIS sets up the state it needs to track the driver and returns an NdisWrapperHandle, which the driver saves for subsequent calls to NdisXXX configuration and initialization functions.

2. Fill in an NDISXXX_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, which effectively defers the initialization of such a driver's virtual network adapter until the driver calls NdisIMInitializeDeviceInstance from its ProtocolBindAdapter function.

DriverEntry can allocate the NDISXXX_MINIPORT_CHARACTERISTICS structure on the stack since 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 4, 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 defers 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 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 will need to carry out network I/O operations.

Drivers that call NdisIMRegisterLayeredMiniport defer 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, which makes the call to NdisIMInitializeDeviceInstance from the ProtocolBindAdapter function, 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 is unloaded if this occurs.

Requirements

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

NdisIMInitializeDeviceInstance, MiniportInitialize, NdisIMRegisterLayeredMiniport, NdisMInitializeWrapper, NdisMRegisterMiniport, NdisTerminateWrapper, NdisZeroMemory, ProtocolBindAdapter

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.