NdisRegisterProtocol function (ndis.h)

Article
01/05/2023

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.

NdisRegisterProtocol registers an NDIS driver's ProtocolXxx entry points and name with the NDIS library when the driver initializes.

Syntax

void NdisRegisterProtocol(
  [out] PNDIS_STATUS                   Status,
  [out] PNDIS_HANDLE                   NdisProtocolHandle,
  [in]  PNDIS_PROTOCOL_CHARACTERISTICS ProtocolCharacteristics,
  [in]  UINT                           CharacteristicsLength
);

Parameters

[out] Status

Pointer to a caller-supplied variable that can be one of the following values on return from this function:

NDIS_STATUS_SUCCESS
The NDIS library registered the caller as a protocol driver.
NDIS_STATUS_BAD_CHARACTERISTICS
The CharacteristicsLength is too small for the MajorNdisVersion specified in the buffer at ProtocolCharacteristics.
NDIS_STATUS_BAD_VERSION
The MajorNdisVersion specified in the buffer at ProtocolCharacteristics is invalid.
NDIS_STATUS_RESOURCES
A shortage of resources, possibly memory, prevented the NDIS library from registering the caller.

[out] NdisProtocolHandle

Pointer to a caller-supplied variable in which this function returns a handle representing the registered driver.

[in] ProtocolCharacteristics

Pointer to an NDIS_PROTOCOL_CHARACTERISTICS structure set up by the caller. The structure at ProtocolCharacteristics is defined as follows:

        typedef struct _NDIS_PROTOCOL_CHARACTERISTICS {
            UCHAR MajorNdisVersion;
            UCHAR MinorNdisVersion;
            UINT Reserved;
            OPEN_ADAPTER_COMPLETE_HANDLER OpenAdapterCompleteHandler;
            CLOSE_ADAPTER_COMPLETE_HANDLER CloseAdapterCompleteHandler;
            SEND_COMPLETE_HANDLER SendCompleteHandler;
            TRANSFER_DATA_COMPLETE_HANDLER TransferDataCompleteHandler;
            RESET_COMPLETE_HANDLER ResetCompleteHandler;
            REQUEST_COMPLETE_HANDLER RequestCompleteHandler;
            RECEIVE_HANDLER ReceiveHandler;
            RECEIVE_COMPLETE_HANDLER ReceiveCompleteHandler;
            STATUS_HANDLER StatusHandler;
            STATUS_COMPLETE_HANDLER StatusCompleteHandler;
            NDIS_STRING Name;
        //
        // MajorNdisVersion must be set to 0x04 or 0x05
        // with any of the following members.
        //
            RECEIVE_PACKET_HANDLER ReceivePacketHandler;
            BIND_HANDLER BindAdapterHandler;
            UNBIND_HANDLER UnbindAdapterHandler;
            PNP_EVENT_HANDLER PnPEventHandler;
            UNLOAD_PROTOCOL_HANDLER UnloadHandler;
        //
        // MajorNdisVersion must be set to 0x05 
        // with any of the following members.
        //
            CO_SEND_COMPLETE_HANDLER CoSendCompleteHandler;
            CO_STATUS_HANDLER CoStatusHandler;
            CO_RECEIVE_PACKET_HANDLER CoReceivePacketHandler;
            CO_AF_REGISTER_NOTIFY_HANDLER CoAfRegisterNotifyHandler;
        } NDIS_PROTOCOL_CHARACTERISTICS, *PNDIS_PROTOCOL_CHARACTERISTICS;

The driver should initialize this structure with zeros before setting up 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 drivers developed for NDIS V4.0. NDIS no longer supports V3.0 protocols.
MinorNdisVersion
Specifies the minor NDIS version. The current value is 0x00.
Reserved
This member is reserved for system use.
OpenAdapterCompleteHandler
Specifies the entry point of the caller's ProtocolOpenAdapterComplete function.
CloseAdapterCompleteHandler
Specifies the entry point of the caller's ProtocolCloseAdapterComplete function.
SendCompleteHandler
Specifies the entry point of the caller's ProtocolSendComplete function, if any.
TransferDataCompleteHandler
Specifies the entry point of the caller's ProtocolTransferDataComplete function, if any.
ResetCompleteHandler
Specifies the entry point of the caller's ProtocolResetComplete function.
RequestCompleteHandler
Specifies the entry point of the caller's ProtocolRequestComplete function.
ReceiveHandler
Specifies the entry point of the caller's ProtocolReceive function, if any.
ReceiveCompleteHandler
Specifies the entry point of the caller's ProtocolReceiveComplete function.
StatusHandler
Specifies the entry point of the caller's ProtocolStatus function, if any.
StatusCompleteHandler
Specifies the entry point of the caller's ProtocolStatusComplete function.
Name
An NDIS_STRING type containing a caller-initialized counted string, in the system-default character set, naming the driver. For Windows 2000 and later drivers, this string contains Unicode characters. That is, for Windows 2000 and later, NDIS defines the NDIS_STRING type as a UNICODE_STRING type. This string must match that specified in the registry (under Services) when the protocol was installed.

NdisRegisterProtocol converts the supplied string to upper case, so a protocol driver writer cannot assume that changing the case of an already registered protocol name creates a unique name for the driver.
ReceivePacketHandler
Specifies the entry point of the caller's ProtocolReceivePacket function, if any, or NULL. Protocols that bind to any NIC driver that supports multipacket receive indications should supply a ProtocolReceivePacket function to enhance their performance. However, a protocol that binds itself exclusively to connection-oriented miniports also can set this member to NULL.
BindAdapterHandler
Specifies the entry point of the caller's ProtocolBindAdapter function. Callers that set the value in the MajorNdisVersion member to 0x05 or 0x04 must supply a ProtocolBindAdapter function and support Plug and Play. NDIS intermediate drivers also must supply a ProtocolBindAdapter function, which allows those intermediate drivers to call NdisIMRegisterLayeredMiniport and to defer full driver initialization until underlying NIC drivers have initialized.
UnbindAdapterHandler
Specifies the entry point of the caller's ProtocolUnbindAdapter function. NDIS drivers that supply a ProtocolBindAdapter function also must supply a ProtocolUnbindAdapter function.
PnPEventHandler
Specifies the entry point of the caller's ProtocolPnPEvent function, if any.
UnloadHandler
Specifies the entry point of the caller's ProtocolUnbind function, if any, or NULL.
CoSendCompleteHandler
Specifies the entry point of the caller's ProtocolCoSendComplete function, which a connection-oriented client or call manager must supply. A connection-oriented client supplies a ProtocolSendComplete function if it also binds itself to connectionless miniports.
CoStatusHandlerCoStatusHandler
Specifies the entry point of the caller's ProtocolCoStatus function, which a connection-oriented client or call manager must supply. A connection-oriented client supplies a ProtocolStatus function if it also binds itself to connectionless miniports.
CoReceivePacketHandler
Specifies the entry point of the caller's ProtocolCoReceivePacket function, which a connection-oriented client or call manager must supply. A connection-oriented client supplies a ProtocolReceivePacket function and/or ProtocolReceive and ProtocolTransferDataComplete functions if it also binds itself to connectionless miniports.
CoAfRegisterNotifyHandler
Specifies the entry point of the caller's ProtocolAfRegisterNotify function, which a connection-oriented client must supply.

[in] CharacteristicsLength

Specifies the size in bytes of the structure at ProtocolCharacteristics. If the build directive -DNDIS50=1 or -DNDIS40=1 is specified in the sources file ahead of #includeNdis.h , the sizeof(NDIS_PROTOCOL_CHARACTERISTICS) is automatically set to the appropriate value. If neither directive is specified, NDIS assumes the V3.0 characteristics structure is being used.

The values set in the MajorNdisVersion and MinorNdisVersion members of the characteristics structure must be consistent with the build directive, or they must be 0x03 and 0x00, respectively.

Return value

None

Remarks

A protocol driver must specify an MajorNdisVersion of 0x05 (the current version) or 0x04. NDIS no longer supports V.30 protocols and therefore does not load a protocol that specifies an MajorNdisVersion of 0x03.

All protocols must be Plug and Play (PnP) capable. A protocol must therefore specify entry points for BindAdapterHandler and UnbindAdapterHandler. NDIS does not load a protocol that specifies NULL for these handlers.

For the best possible performance, any protocol that will layer itself above a connectionless NIC driver that supports multipacket receives should provide a ProtocolReceivePacket function. Such a protocol driver also must provide a ProtocolReceive function. Any connectionless NIC driver that supports multipacket sends is also likely to indicate multipacket receives.

All connection-oriented protocols, whether clients or call managers, must register a ProtocolCoReceivePacket function. Client protocols that also bind themselves to connectionless NIC drivers provide ProtocolReceivePacket and ProtocolReceive functions as well. Connection-oriented protocols must register additional connection-oriented entry points with NDIS by calling either NdisClOpenAddressFamily for clients or NdisCmRegisterAddressFamily for call managers from their ProtocolBindAdapter functions.

After a successful call to NdisRegisterProtocol, a driver cannot alter the set of ProtocolXxx functions it supplied.

A successfully registered driver should save the handle returned at NdisProtocolHandle. It is a required parameter to other NdisXxx functions that the driver calls subsequently.

After a successful call to NdisRegisterProtocol, the DriverEntry function of a PnP-aware or connection-oriented protocol returns control because such a driver's ProtocolBindAdapter function will be called subsequently one or more times to set up bindings to underlying NIC(s). Otherwise, the protocol driver can call NdisOpenAdapter to set up a binding to the underlying NIC driver or to layer itself above any NDIS driver that registered a set of NDIS MiniportXxx functions.

Target platform: Universal
Version: Not supported for NDIS 6.0 drivers in Windows Vista. Use NdisRegisterProtocolDriverinstead. Supported for NDIS 5.1 drivers in Windows Vista and Windows XP.

Requirements

Requirement	Value
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	PASSIVE_LEVEL