DriverEntry of NDIS Protocol Drivers (NDIS 5.1) function
Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.
The DriverEntry function is required and is the first function that the system calls in any NDIS protocol or intermediate driver, including connection-oriented clients and stand-alone call managers.
Syntax
NTSTATUS DriverEntry(
_In_ PDRIVER_OBJECT DriverObject,
_In_ PUNICODE_STRING RegistryPath
);
Parameters
DriverObject [in]
Pointer to the driver object that represents this driver.RegistryPath [in]
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.
Return value
DriverEntry returns STATUS_SUCCESS, or its equivalent NDIS_STATUS_SUCCESS, if the driver registered as an NDIS protocol successfully. If DriverEntry fails initialization by propagating an error status 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.
Remarks
The DriverEntry function of every type of NDIS protocol driver must call NdisRegisterProtocol to register the driver's Protocol Xxx entry points with the NDIS library. All types of NDIS protocols should register fully functional ProtocolBindAdapter and ProtocolUnbindAdapter functions to support plug and play. In general, a DriverEntry function should call NdisRegisterProtocol just before it returns control with 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 Protocol Xxx functions must set the entry points for those driver routines in the given driver object passed in to its DriverEntry function. For more information about the functionality of such a protocol's DriverEntry function, see Writing a DriverEntry Routine. For more information about the TdiDispatchXxx routines exported by TDI transport protocols, see TDI Transport Driver Dispatch Routines.
If an attempt to allocate resources that the driver needs to carry out network I/O operations fails, DriverEntry should release all resources it already allocated before it returns control with a status other than STATUS_SUCCESS or NDIS_STATUS_SUCCESS.
After calling NdisRegisterProtocol, connection-oriented client protocols subsequently call NdisClOpenAddressFamily from their ProtocolCoAfRegisterNotify functions to register their ProtocolClXxx functions with NDIS. Similarly, connection-oriented call managers and MCM drivers subsequently call NdisCmRegisterAddressFamily from their ProtocolBindAdapter functions or NdisMCmRegisterAddressFamily from their MiniportInitialize functions, respectively, to register their ProtocolCmXxx functions.
An NDIS intermediate driver, such as one that translates an underlying NIC driver's native frame format into another format for higher level protocols, simply passes the input parameters to its DriverEntry function, uninterpreted, to certain NdisXxx functions.
Usually, the DriverEntry function of such an NDIS intermediate driver calls the following NdisXxx functions in the following order:
NdisMInitializeWrapper to notify the NDIS library that the driver is about to register as a miniport driver
NdisIMRegisterLayeredMiniport to register the driver's MiniportXxx functions
NdisRegisterProtocol to register the driver's Protocol Xxx functions
Such an intermediate driver must register ProtocolBindAdapter and ProtocolUnbindAdapter functions with the NDIS library when it calls NdisRegisterProtocol. Its ProtocolBindAdapter function will be called later to complete driver initialization and to bind the intermediate driver to an underlying miniport driver.
In effect, the DriverEntry function of an NDIS intermediate driver can ignore the RegistryPath pointer after passing it to NdisMInitializeWrapper. Such a driver also can ignore the DriverObject pointer after passing it to NdisIMRegisterLayeredMiniport. However, the driver should save the DriverHandle returned by NdisIMRegisterLayeredMiniport and the NdisProtocolHandle returned by NdisRegisterProtocol for subsequent calls to NdisXxx functions. The intermediate driver's ProtocolBindAdapter function binds the driver to each underlying NIC driver before its MiniportInitialize function is called to initialize the intermediate driver's virtual NIC, and still higher level protocols subsequently bind themselves to the virtual NIC it creates. This strategy allows an NDIS intermediate driver to allocate resources at the creation of the virtual NIC according to the features of the underlying NIC driver to which it is bound.
Requirements
Target platform |
Desktop |
Version |
See DriverEntry of NDIS Protocol Drivers. |
Header |
Ndis.h (include Ndis.h) |
IRQL |
PASSIVE_LEVEL |
See also