NdisRegisterProtocol

NdisRegisterProtocol

VOID
   NdisRegisterProtocol(
       OUT PNDIS_STATUS Status,
       OUT PNDIS_HANDLE NdisProtocolHandle,
       IN PNDIS_PROTOCOL_CHARACTERISTICS ProtocolCharacteristics,
       IN UINT CharacteristicsLength
       );

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

Parameters

Status

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

NdisProtocolHandle

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

ProtocolCharacteristics

Points 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

// with any of the following members.

//

RECEIVE_PACKET_HANDLER ReceivePacketHandler;

BIND_HANDLER BindAdapterHandler;

UNBIND_HANDLER UnbindAdapterHandler;

TRANSLATE_HANDLER TranslateHandler;

UNLOAD_PROTOCOL_HANDLER UnloadHandler;

} 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 0x04, although the NDIS library continues to support existing drivers developed for NDIS V3.0.

This member must be set to 0x04 if the caller if the caller is an NDIS intermediate driver or if the caller sets entry points in any members following Name.

MinorNdisVersion

Specifies the minor NDIS version. The current value is 0x00, although NDIS continues to support existing drivers.

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.

TransferDataCompleteHandler

Specifies the entry point of the caller’s ProtocolTransferDataComplete function.

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.

ReceiveCompleteHandler

Specifies the entry point of the caller’s ProtocolReceiveComplete function.

StatusHandler

Specifies the entry point of the caller’s ProtocolStatus function.

StatusCompleteHandler

Specifies the entry point of the caller’s ProtocolStatusComplete function.

Name

Specifies a pointer to a buffered, caller-initialized counted string, in the system-default character set, naming the driver. For Windows NT drivers, this string contains Unicode characters.

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 driver that supports multipacket receive indications should supply a ProtocolReceivePacket function to enhance their performance.

BindAdapterHandler

Specifies the entry point of the caller’s ProtocolBindAdapter function, if any, or NULL. NDIS intermediate drivers usually supply a ProtocolBindAdapter function, which both makes them PnP-ready and allows the intermediate 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, if any, or NULL. NDIS drivers that supply a ProtocolBindAdapter function also must supply a ProtocolUnbindAdapter function.

TranslateHandler

Specifies the entry point of the caller’s ProtocolTranslate function, if any, or NULL. Such a function currently is not called, and this member is reserved for future use by PnP-aware protocols.

UnloadHandler

Set to NULL by Windows NT protocol drivers.

CharacteristicsLength

Specifies the size in bytes of the structure at ProtocolCharacteristics. If the build directive NDIS40 is specified in the sources ahead of #include ndis.h, this value is supplied automatically.

Comments

The value supplied at CharacteristicsLength must be at least the sizeof(NDISXX_PROTOCOL_CHARACTERISTICS) designated by the supplied MajorNdisVersion in this structure.

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

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 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 upper-edge (MiniportXxx) functions.

Callers of NdisRegisterProtocol run at IRQL PASSIVE_LEVEL.