NdisIMRegisterLayeredMiniport 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.

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

Syntax

NDIS_STATUS NdisIMRegisterLayeredMiniport(
  _In_  NDIS_HANDLE                    NdisWrapperHandle,
  _In_  PNDIS_MINIPORT_CHARACTERISTICS MiniportCharacteristics,
  _In_  UINT                           CharacteristicsLength,
  _Out_ PNDIS_HANDLE                   DriverHandle
);

Parameters

  • NdisWrapperHandle [in]
    Specifies the handle returned by NdisMInitializeWrapper.

  • MiniportCharacteristics [in]
    Pointer to an NDIS XX_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_MINIPORT_PNPEVENTNOTIFY_HANDLER PnPEventNotifyHandler;
        W_MINIPORT_SHUTDOWN_HANDLER AdapterShutdownHandler;
    } 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 0x05, although the NDIS library continues to support existing miniport drivers developed for NDIS 4.0.

    • 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, MiniportWanSend function, or NULL if the caller supplies a MiniportSendPackets 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 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.

    • 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.

    • CoCreateVcHandler
      Specifies NULL.

    • CoDeleteVcHandler
      Specifies NULL.

    • CoActivateVcHandler
      Specifies NULL.

    • CoDeactivateVcHandler
      Specifies NULL.

    • CoSendPacketsHandler
      Specifies NULL.

    • CoRequestHandler
      Specifies NULL.

    • CancelSendPacketsHandler
      Specifies the entry point of the caller's MiniportCancelSendPackets function, if any, or NULL. Intermediate 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 intermediate drivers must register a MiniportShutdown function. NDIS 5.1 intermediate drivers should register a MiniportShutdown function by calling NdisIMRegisterLayeredMiniport--not by calling NdisMRegisterAdapterShutdownHandler.

  • CharacteristicsLength [in]
    Specifies the length in bytes of the caller-supplied characteristics buffer. Depending on the value of MajorNdisVersion, this parameter must be either sizeof(NDIS50_MINIPORT_CHARACTERISTICS) if the driver supplies an NDIS50_MINIPORT_CHARACTERISTICS structure or sizeof(NDIS40_MINIPORT_CHARACTERISTICS) if the driver supplies an NDIS40_MINIPORT_CHARACTERISTICS structure.

    If the driver includes the build instruction NDIS50_MINIPORT (or NDIS40_MINIPORT, as appropriate) in its sources or if the driver writer uses the -NDIS50_MINIPORT (or ..40..) compiler switch, this parameter is set when the driver is built.

  • DriverHandle [out]
    Pointer 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 value

NdisIMRegisterLayeredMiniport returns NDIS_STATUS_SUCCESS if it registered the caller as a 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 MajorNdisVersion 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 driver.

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.

Remarks

Any NDIS intermediate driver that exports both MiniportXxx and ProtocolXxx functions 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 NIC driver has initialized successfully. ProtocolBindAdapter then can establish a binding to that NIC driver with NdisOpenAdapter.

An NDIS intermediate driver should have a MiniportSendPackets function if an underlying NIC driver might support multipacket sends or consume media-specific information, such as packet priorities, sent down in a packet array from a higher-level protocol. An NDIS intermediate driver should have a MiniportReturnPacket function if an underlying NIC driver might support multipacket receive indications or indicate packet arrays containing media-specific information. The NDIS library handles packet arrays transferred between an underlying NIC driver and higher-level protocol that support only single-packet transfers on behalf of such an intermediate driver.

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

See also

DriverEntry of NDIS Miniport Drivers

DriverEntry of NDIS Protocol Drivers

MiniportCheckForHang

MiniportHalt

MiniportInitialize

MiniportQueryInformation

MiniportReset

MiniportReturnPacket

MiniportSend

MiniportSendPackets

MiniportSetInformation

MiniportTransferData

MiniportWanSend

NdisIMInitializeDeviceInstance

NdisMRegisterAdapterShutdownHandler

NdisMRegisterMiniport

NdisOpenAdapter

NdisRegisterProtocol

NdisZeroMemory

ProtocolBindAdapter

ProtocolReceivePacket

ProtocolUnbindAdapter

Send comments about this topic to Microsoft