NdisIMRegisterLayeredMiniport

Article
06/30/2006

NdisIMRegisterLayeredMiniport registers an intermediate driver's MiniportXXX entry points and name with the NDIS library when the driver initializes.

NDIS_STATUS
NdisIMRegisterLayeredMiniport(
IN NDIS_HANDLE NdisWrapperHandle,
IN PNDIS_MINIPORT_CHARACTERISTICS MiniportCharacteristics,
IN UINT CharacteristicsLength,
OUT PNDIS_HANDLE DriverHandle );

Parameters

NdisWrapperHandle
Specifies the handle returned by NdisMInitializeWrapper.

MiniportCharacteristics
Points to an NDISXXX_MINIPORT_CHARACTERISTICS structure set up by the caller. The structure at MiniportCharacteristics is defined as follows:

typedef struct _NDIS_MINIPORT_CHARACTERISTICS {
    UCHAR MajorNdisVersion;
    UCHAR MinorNdisVersion;
    UINT Reserved;
    W_CHECK_FOR_HANG_HANDLER CheckForHangHandler;
    W_DISABLE_INTERRUPT_HANDLER DisableInterruptHandler;
    W_ENABLE_INTERRUPT_HANDLER  EnableInterruptHandler;
    W_HALT_HANDLER HaltHandler;
    W_HANDLE_INTERRUPT_HANDLER  HandleInterruptHandler;
    W_INITIALIZE_HANDLER InitializeHandler;
    W_ISR_HANDLER ISRHandler;
    W_QUERY_INFORMATION_HANDLER QueryInformationHandler;
    W_RECONFIGURE_HANDLER ReconfigureHandler;
    W_RESET_HANDLER ResetHandler;
    W_SEND_HANDLER SendHandler; 
    W_SET_INFORMATION_HANDLER SetInformationHandler;
    W_TRANSFER_DATA_HANDLER TransferDataHandler;
//
// MajorNdisVersion must be set to 0x04 with following members
//
    W_RETURN_PACKET_HANDLER ReturnPacketHandler;
    W_SEND_PACKETS_HANDLER SendPacketsHandler;
    W_ALLOCATE_COMPLETE_HANDLER AllocateCompleteHandler;
} NDIS_MINIPORT_CHARACTERISTICS, *PNDIS_MINIPORT_CHARACTERISTICS;

An NDIS intermediate driver should initialize this structure with zeros before setting up any of the following members:

MajorNdisVersion
Specifies the major version of the NDIS library the driver is using. The current value is 0x04. This member must be set to 0x04 if the caller sets entry points in any members following Name.
MinorNdisVersion
Specifies the minor version of the NDIS library the driver is using. The current value is 0x00, although NDIS continues to support existing drivers.
Reserved
This member is reserved for system use.
CheckForHangHandler
Specifies the entry point of the caller's MiniportCheckforHang function, if any, or NULL.
DisableInterruptHandler
Specifies NULL.
EnableInterruptHandler
Specifies NULL.
HaltHandler
Specifies the entry point of the caller's MiniportHalt function.
HandleInterruptHandler
Specifies NULL.
InitializeHandler
Specifies the entry point of the caller's MiniportInitialize function.
ISRHandler
Specifies NULL.
QueryInformationHandler
Specifies the entry point of the caller's MiniportQueryInformation function.
ReconfigureHandler
Specifies NULL.
ResetHandler
Specifies the entry point of the caller's MiniportReset function.
SendHandler
Specifies the entry point of the caller's MiniportSend function.

If the driver supports multipacket sends or media-specific information, it sets the SendPacketsHandler member instead and sets this member to NULL.
SetInformationHandler
Specifies the entry point of the caller's MiniportSetInformation function.
TransferDataHandler
Specifies the entry point of the caller's MiniportTransferData function, if any, or NULL. This miniport function is required unless the caller is the driver of a WAN network adapter or the caller supports multipacket receives and, therefore, supplies the entry point of its MiniportReturnPacket function at ReturnPacketHandler.
ReturnPacketHandler
Specifies the entry point of the caller's MiniportReturnPacket function, if any, or NULL.
SendPacketsHandler
Specifies the entry point of the caller's MiniportSendPackets function, if any, or NULL.
AllocateCompleteHandler
Specifies NULL.
CharacteristicsLength
Specifies the length in bytes of the caller-supplied characteristics buffer. In Windows CE, this parameter must be sizeof(NDIS40_MINIPORT_CHARACTERISTICS).

If the driver includes the build instruction NDIS40_MINIPORT in its sources or if the driver writer uses the NDIS40_MINIPORT compiler switch, this parameter is set when the driver is built.
DriverHandle
Points to a variable in which NdisIMRegisterLayeredMiniport, if this call is successful, returns a handle that the caller should save. The caller subsequently must pass this handle to NdisIMInitializeDeviceInstance, usually from its ProtocolBindAdapter function.

Return Values

NdisIMRegisterLayeredMiniport returns NDIS_STATUS_SUCCESS if it registered the caller as a miniport, or it can return one of the following status values:

NDIS_STATUS_BAD_CHARACTERISTICS
The CharacteristicsLength is too small for the MajorNdisVersion specified in the buffer at MiniportCharacteristics.
NDIS_STATUS_BAD_VERSION
The MajorNdisVersion or MinorNdisVersion specified in the characteristics structure is invalid.
NDIS_STATUS_RESOURCES
A shortage of resources, possibly memory, prevented the NDIS library from registering the caller as a miniport.
NDIS_STATUS_FAILURE
This is a default error status, returned when none of the preceding errors caused the registration to fail. For example, if the NDIS library cannot load the driver's image and lock it into system memory, it returns this error.

Comments

Any NDIS intermediate driver that exports both MiniportXXX and ProtocolXXX functions usually sets up a characteristics structure and calls NdisIMRegisterLayeredMiniport from its DriverEntry function after DriverEntry calls NdisMInitializeWrapper. This structure is copied in the NdisIMRegisterLayeredMiniport request to the NDIS library's internal storage. Thus, once it has registered, such a driver cannot change its handler functions.

After such an NDIS intermediate driver has called NdisIMRegisterLayeredMiniport successfully, it must call NdisRegisterProtocol to register its ProtocolXXX functions with the NDIS library. Such a driver usually has both ProtocolBindAdapter and ProtocolUnbindAdapter functions. Its ProtocolBindAdapter function will be called next when the underlying network adapter driver has initialized successfully. ProtocolBindAdapter then can establish a binding to that network adapter driver with NdisOpenAdapter.

An intermediate driver can call NdisMRegisterMiniport instead of NdisIMRegisterLayeredMiniport if it is prepared for an immediate call to the MiniportInitialize function.

Requirements

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

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.

Last updated on Tuesday, July 13, 2004

NdisIMRegisterLayeredMiniport

Additional resources