NdisMRegisterMiniport function

Article
06/19/2017

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.

NdisMRegisterMiniport registers a miniport's MiniportXxx entry points with the NDIS library as the first step in NIC driver initialization.

Syntax

NDIS_STATUS NdisMRegisterMiniport(
  _In_ NDIS_HANDLE                    NdisWrapperHandle,
  _In_ PNDIS_MINIPORT_CHARACTERISTICS MiniportCharacteristics,
  _In_ UINT                           CharacteristicsLength
);

Parameters

NdisWrapperHandle [in]
Specifies the handle returned by NdisMInitializeWrapper.
MiniportCharacteristics [in]
Pointer to an NDIS_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;
//
// Version used is V4.0 or V5.0
// with following members
//
    W_RETURN_PACKET_HANDLER ReturnPacketHandler;
    W_SEND_PACKETS_HANDLER SendPacketsHandler;
    W_ALLOCATE_COMPLETE_HANDLER AllocateCompleteHandler;
//
// Version used is V5.0 with the following members
//
    W_CO_CREATE_VC_HANDLER CoCreateVcHandler;
    W_CO_DELETE_VC_HANDLER CoDeleteVcHandler;
    W_CO_ACTIVATE_VC_HANDLER CoActivateVcHandler;
    W_CO_DEACTIVATE_VC_HANDLER CoDeactivateVcHandler;
    W_CO_SEND_PACKETS_HANDLER CoSendPacketsHandler;
    W_CO_REQUEST_HANDLER CoRequestHandler;
//
// Version used is V5.1 with the following members
//
    W_CANCEL_SEND_PACKETS_HANDLER CancelSendPacketsHandler;
    W_PNP_EVENT_NOTIFY_HANDLER PnPEventNotifyHandler;
    W_MINIPORT_SHUTDOWN_HANDLER AdapterShutdownHandler;
} NDIS_MINIPORT_CHARACTERISTICS, *PNDIS_MINIPORT_CHARACTERISTICS;The 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 0x05, although the NDIS library continues to support existing NIC drivers developed for NDIS 4.0 and NDIS 3.0.
  
  This member must be set to 0x05 or 0x04 if the caller sets entry points in any members following TransferDataHandler; it must be set to 0x05 if the caller sets entry points in any members following AllocateCompleteHandler.
- MinorNdisVersion
  Specifies the minor version of the NDIS library the driver is using. The current value is 0x00.
- 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 the entry point of the caller's MiniportDisableInterrupt function, if any.
- EnableInterruptHandler
  Specifies the entry point of the caller's MiniportEnableInterrupt function, if any.
- HaltHandler
  Specifies the entry point of the caller's MiniportHalt function.
- HandleInterruptHandler
  Specifies the entry point of the caller's MiniportHandleInterrupt function, if any.
- InitializeHandler
  Specifies the entry point of the caller's MiniportInitialize function.
- ISRHandler
  Specifies the entry point of the caller's MiniportISR function, if any. This miniport driver function is required if the driver later calls NdisMRegisterInterrupt from its MiniportInitialize function.
- QueryInformationHandler
  Specifies the entry point of the caller's MiniportQueryInformation function, which is optional if the caller supplies a MiniportCoRequest function.
- ReconfigureHandler
  Specifies the entry point of the caller's MiniportReconfigure function, or NULL.
- ResetHandler
  Specifies the entry point of the caller's MiniportReset function.
- SendHandler
  Specifies the entry point of the caller's MiniportSend function, MiniportWanSend function, or NULL if the caller supplies a MiniportSendPackets or MiniportCoSendPackets function.
  
  If the miniport driver supports multipacket sends or controls a connection-oriented NIC, it sets the SendPacketsHandler or CoSendPacketsHandler member, respectively, and sets this member to NULL.
- SetInformationHandler
  Specifies the entry point of the caller's MiniportSetInformation function, which is optional if the caller supplies a MiniportCoRequest function.
- TransferDataHandler
  Specifies the entry point of the caller's MiniportTransferData function, if any. This miniport driver function is required unless the caller is the driver of a WAN NIC or the caller supports multipacket receives and, therefore, supplies the entry point of its MiniportReturnPacket function at ReturnPacketHandler. Drivers of connection-oriented NICs must support multipacket receives.
- ReturnPacketHandler
  Specifies the entry point of the caller's MiniportReturnPacket function, if any.
- SendPacketsHandler
  Specifies the entry point of the caller's MiniportSendPackets function, if any. If the driver of a connectionless NIC also sets an entry point in the SendHandler member, NDIS always calls its MiniportSendPackets function. The driver of a connection-oriented NIC must set the CoSendPacketsHandler member instead of this member.
- AllocateCompleteHandler
  Specifies the entry point of the caller's MiniportAllocateComplete function, if any, or NULL.
- CoCreateVcHandler
  Specifies the entry point of the driver's MiniportCoCreateVc function. If the caller is an integrated call manager and connection-oriented NIC (MCM) driver, this member is set to NULL, because such a driver subsequently registers its ProtocolCoCreateVc function as a call manager with NdisMCmRegisterAddressFamily.
- CoDeleteVcHandler
  Specifies the entry point of the caller's MiniportCoDeleteVc function. If the caller is an integrated call manager and connection-oriented NIC (MCM) driver, this member is set to NULL, because such a driver subsequently registers its ProtocolCoDeleteVc function as a call manager with NdisMCmRegisterAddressFamily.
- CoActivateVcHandler
  Specifies the entry point of the caller's MiniportCoActivateVc function.
- CoDeactivateVcHandler
  Specifies the entry point of the caller's MiniportCoDeactivateVc function.
- CoSendPacketsHandler
  Specifies the entry point of the caller's MiniportCoSendPackets function. The SendHandler and SendPacketsHandler members should be NULL if the driver supplies a MiniportCoSendPackets function.
- CoRequestHandler
  Specifies the entry point of the caller's MiniportCoRequest function. If the driver also supplies MiniportQueryInformation and MiniportSetInformation functions, its MiniportCoRequest function handles only OID_GEN_CO_XXX and connection-oriented medium-specific OID_XXX requests. If such a driver sets the QueryInformationHandler and SetInformationHandler members to NULL, its MiniportCoRequest function must respond to all possible OID requests, including the OID_GEN_XXX that all NDIS miniports must handle.
- CancelSendPacketsHandler
  Specifies the entry point of the caller's MiniportCancelSendPackets function, if any, or NULL. Miniport drivers that queue send packets for more than one second should register a MiniportCancelSendPackets function.
- PnPEventNotifyHandler
  Specifies the entry point of the caller's MiniportPnPEventNotify function. NDIS 5.1 miniport drivers must register a MiniportPnPEventNotify function. Miniport drivers ''that have a WDM lower edge should register a MiniportPnPEventNotify function.
- AdapterShutdownHandler
  Specifies the entry point of the caller's MiniportShutdown function, if any, or NULL. NDIS 5.1 miniports must register a MiniportShutdown function. NDIS 5.1 miniports should register a MiniportShutdown function by calling NdisMRegisterMiniport--not by calling NdisMRegisterAdapterShutdownHandler.
CharacteristicsLength [in]
Specifies the size in bytes of the caller-supplied characteristics buffer, which is sizeof(NDIS_MINIPORT_CHARACTERISTICS). The exact buffer size allocated depends on the compiler or build directives set for the miniport driver.

For example, the following shows the appropriate compiler directives to embed at the start of a miniport driver's source code if the driver uses an NDIS 5.0 NDIS_MINIPORT_CHARACTERISTICS structure:
```
#define NDIS_MINIPORT_DRIVER
#define NDIS50_MINIPORT   1 
#include <Ndis.h>  // AFTER preceding directives
```
The inclusion of ndis.h must occur after the NDIS_MINIPORT_DRIVER and NDIS XX_MINIPORT directives, where XX can be 40, as well as the 50 shown here. If the NDIS XX_MINIPORT directive is omitted, the NDIS_MINIPORT_CHARACTERISTICS structure size defaults to version 3.0.

As an alternative, the same driver could set the following build directive in its sources file, instead of using the preceding compiler directives:
```
... 
C_FLAGS=$(C_FLAGS) -DNDIS_MINIPORT_DRIVER -DNDIS50_MINIPORT_DRIVER
...
```
As for the corresponding compiler directive, the driver writer can specify a -DNDIS XX_MINIPORT_DRIVER directive, where XX can be 40, as well as the 50 shown here.

Setting the appropriate compiler/build directives sets the CharacteristicsLength automatically. The values set in the MajorNdisVersion and MinorNdisVersion members of the characteristics structure must be consistent with the compiler/build directives set for the miniport driver.

Return value

NdisMRegisterMiniport returns NDIS_STATUS_SUCCESS if it registered the miniport driver, or it can return one of the following status values:

Return code	Description
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.
NDIS_STATUS_FAILURE	This is a default error status, returned when none of the preceding errors caused the registration to fail.

Remarks

A NIC driver calls NdisMRegisterMiniport from its DriverEntry function, following its call to NdisMInitializeWrapper.

Every NIC driver exports a set of standard MiniportXxx functions by setting up the characteristics structure and calling NdisMRegisterMiniport. This structure is copied in the NdisMRegisterMiniport request to the NDIS library's internal storage. Thus, once it has registered, a miniport driver cannot change its MiniportXxx functions.

After the driver has called NdisMRegisterMiniport and after its DriverEntry function returns control, it should be prepared to be called back at the MiniportInitialize entry point specified in the characteristics structure. In the PnP environment, a NIC driver's call to NdisMRegisterMiniport simply registers the miniport driver's entry points with NDIS, which defers calling the driver's MiniportInitialize function until the PnP manager sends NDIS a request to start the NIC. For more information about PnP, see NDIS Miniport Driver DriverEntry Function (NDIS 5.1), Plug and Play for NDIS Miniport Drivers (NDIS 5.1), and Power Management for NDISMiniport Drivers (NDIS 5.1).

The NDIS library currently does not call MiniportReconfigure functions, so such a function in an existing miniport driver is dead code unless the miniport driver makes internal calls to its MiniportReconfigure function from MiniportInitialize.

NDIS intermediate drivers, which export both MiniportXxx and ProtocolXxx functions, must call NdisIMRegisterLayeredMiniport instead of NdisMRegisterMiniport. Connection-oriented MCM drivers, however, which export MiniportXxx and ProtocolXxx functions, call NdisMRegisterMiniport.

Requirements

Target platform	Universal
Version	Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisMRegisterMiniportDriverinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.
Header	Ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL