Développer Réduire

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

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

Status [out]

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.

NdisProtocolHandle [out]

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

ProtocolCharacteristics [in]

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.

CharacteristicsLength [in]

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.

Requirements

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.

Header

Ndis.h (include Ndis.h)

IRQL

PASSIVE_LEVEL

See also

ANSI_STRING
DriverEntry of NDIS Protocol Drivers
NdisClOpenAddressFamily
NdisCmRegisterAddressFamily
NdisDeregisterProtocol
NdisIMRegisterLayeredMiniport
NdisInitializeString
NdisInitUnicodeString
NdisMCmRegisterAddressFamily
NdisOpenAdapter
NdisZeroMemory
ProtocolBindAdapter
ProtocolCloseAdapterComplete
ProtocolCoAfRegisterNotify
ProtocolCoReceivePacket
ProtocolCoSendComplete
ProtocolCoStatus
ProtocolOpenAdapterComplete
ProtocolPnPEvent
ProtocolReceive
ProtocolReceiveComplete
ProtocolReceivePacket
ProtocolRequestComplete
ProtocolResetComplete
ProtocolSendComplete
ProtocolStatus
ProtocolStatusComplete
ProtocolTransferDataComplete
ProtocolUnbindAdapter
UNICODE_STRING

 

 

Send comments about this topic to Microsoft

Afficher:
© 2015 Microsoft