DriverEntry

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

DriverEntryis 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 Miniport XXXfunctions.

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 Miniport XXXfunctions.

Return Values

DriverEntryreturns the value returned by NdisMRegisterMiniportor NdisIMRegisterLayeredMiniport.

Remarks

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

1. Call NdisMInitializeWrapperto 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 Ndis XXXconfiguration and initialization functions.

2. Fill in an NDIS XXX_MINIPORT_CHARCTERISTICSstructure with the appropriate version numbers and the entry points for driver-supplied Miniport XXXfunctions and, then, call NdisMRegisterMiniportor NdisIMRegisterLayeredMiniport.

   Usually, network adapter drivers call NdisMRegisterMiniport, as do intermediate drivers that export only a set of Miniport XXXfunctions. Usually, NDIS intermediate drivers call NdisIMRegisterLayeredMiniport, which effectively defers the initialization of such a driver's virtual network adapter until the driver calls NdisIMInitializeDeviceInstancefrom its ProtocolBindAdapterfunction.

   DriverEntrycan allocate the NDIS XXX_MINIPORT_CHARACTERISTICSstructure on the stack since the NDIS library copies the relevant information to its own storage. DriverEntryshould clear the memory for this structure with NdisZeroMemorybefore setting any driver-supplied values in its members. The current MajorNdisVersionis 4, and the current MinorNdisVersionis 0x00. In each XXXHandlermember of the characteristics structure, DriverEntrymust set the name of a driver-supplied Miniport XXXfunction, or the member must be NULL.

   Calling NdisMRegisterMiniportcauses the driver's MiniportInitializefunction to run in the context of NdisMRegisterMiniport. Calling NdisIMRegisterLayeredMiniportdefers the call to MiniportInitializeuntil the driver calls NdisIMInitializeDeviceInstance.

   Drivers that call NdisMRegisterMiniportmust be prepared for an immediate call to their MiniportInitializefunctions. Such a driver must have sufficient installation and configuration information stored in the registry or available from calls to an Ndis XXXbus-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 NdisIMRegisterLayeredMiniportdefer the call to their MiniportInitializefunctions to another driver-supplied function that makes a call to NdisIMInitializeDeviceInstance. NDIS intermediate drivers usually register a ProtocolBindAdapter function and call NdisIMRegisterLayeredMiniportso that NDIS will call the ProtocolBindAdapterfunction after all underlying network adapter drivers have initialized. This strategy gives such an NDIS intermediate driver, which makes the call to NdisIMInitializeDeviceInstancefrom the ProtocolBindAdapterfunction, the advantage of having its MiniportInitializefunction 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 NdisMRegisterMiniportor NdisIMRegisterLayeredMiniportdoes not return NDIS_STATUS_SUCCESS, DriverEntrymust release any resources it allocated, such as memory to hold the NdisWrapperHandle, and must call NdisTerminateWrapperbefore it returns control. The driver is unloaded if this occurs.

   Requirements

   Runs on	Versions	Defined in	Include	Link to
   Windows CE OS	2.0 and later	Ndis.h

   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 Friday, May 26, 2006

   © 2004 Microsoft Corporation. All rights reserved.