2.1.1 Registering as an NDIS Protocol Driver
A driver registers its ProtocolXxx functions with NDIS in the context
of its DriverEntry function by calling NdisRegisterProtocol,
defined as follows:
VOID
NdisRegisterProtocol(
OUT PNDIS_STATUS Status,
OUT PNDIS_HANDLE NdisProtocolHandle,
IN PNDIS_PROTOCOL_CHARACTERISTICS
ProtocolCharacteristics,
IN UINT CharacteristicsLength
);
The NdisProtocolHandle returned by this call is opaque to a protocol
driver. The handle must be retained by the protocol driver and provided as an
input parameter in future calls to NDIS, to open an adapter for example.
Before making this call, DriverEntry must do the following:
-
Zero-initialize a structure of type NDIS_PROTOCOL_CHARACTERISTICS, for
instance with a call to NdisZeroMemory. This assures that unused
members for optional entry points are set to NULL. If the structure is not
zeroed, any unused members must be set to NULL before calling NdisRegisterProtocol.
-
Store the addresses of the mandatory ProtocolXxx functions, as well as
any optional ProtocolXxx functions the driver exports, in the
characteristics structure members, as follows:
-
BindAdapterHandler
-
This is an optional function in protocol drivers. A PnP-ready protocol driver
specifies this entry point so it can be called by NDIS at the
ProtocolBindAdapter function when an adapter is available. Specifying this
entry point requires a V4.0 structure at ProtocolCharacteristics.
-
UnbindAdapterHandler
-
This is a required function if the protocol driver registered a
ProtocolBindAdapter function. Specifying this entry point also requires a V4.0
structure at ProtocolCharacteristics.
-
OpenAdapterCompleteHandler
-
This is a required function. If a protocol driver’s call to NdisOpenAdapter
returns NDIS_STATUS_PENDING, ProtocolOpenAdapterComplete is subsequently
called to complete the binding operation.
-
CloseAdapterCompleteHandler
-
This is a required function. If a protocol driver’s call to NdisCloseAdapter
returns NDIS_STATUS_PENDING, ProtocolCloseAdapterComplete is subsequently
called to complete the unbinding operation.
-
ReceiveHandler
-
This is a required function. ProtocolReceive is called with a pointer to a
lookahead buffer. If this buffer contains less than the full, received network
packet, ProtocolReceive calls NdisTransferData with a
protocol-allocated packet descriptor specifiying protocol-allocated buffer(s)
to obtain the remainder of the received packet.
-
ReceiveCompleteHandler
-
This is a required function. ProtocolReceiveComplete is called to indicate
that any received packets previously indicated to ProtocolReceive can now be
postprocessed.
-
TransferCompleteHandler
-
This is a required function unless the protocol binds itself exclusively to
underlying NIC driver(s) that indicate packets with NdisMIndicateReceivePacket.
ProtocolTransferDataComplete is called when a previous call to NdisTransferData
returned NDIS_STATUS_PENDING and the remaining data has been copied into the
protocol-supplied buffers chained to a given packet descriptor.
-
ReceivePacketHandler
-
This is an optional function. A ProtocolReceivePacket function should be
provided if the protocol driver might be bound to a NIC driver that indicates
an array of one or more packets by calling NdisMIndicateReceivePacket.
Specifying this entry point requires a V4.0 structure at ProtocolCharacteristics.
-
SendCompleteHandler
-
This is a required function. ProtocolSendComplete is called for each packet
transmitted with a call to NdisSend that returned NDIS_STATUS_PENDING
as the status of the send operation. If an array of packets is sent,
ProtocolSendComplete is called once for each packet passed to NdisSendPackets,
whether or not it returned pending.
-
ResetCompleteHandler
-
This is a required function. ProtocolResetComplete is called when a
protocol-initiated reset operation, begun with a call to NdisReset that
returned NDIS_STATUS_PENDING, is completed.
-
RequestCompleteHandler
-
This is a required function. ProtocolRequestComplete is called when a
protocol-initiated query or set operation, begun with a call to NdisRequest
that returned NDIS_STATUS_PENDING, is completed.
-
StatusHandler
-
This is a required function. ProtocolStatus is called to handle status changes
indicated by the underlying NDIS driver.
-
StatusCompleteHandler
-
This is a required function. ProtocolStatusComplete is called by NDIS, along
with ProtocolStatus, to report the start and end of an NDIS- or
NIC-driver-initiated reset operation.
A protocol driver should set the ProtocolCharacteristics TranslateHandler
and UnloadHandler members to NULL. The TranslateHandler member
is reserved for future use. NDIS never calls an entry point specified in UnloadHandler
on Windows NT platforms. Instead, the Windows NT I/O Manager calls the Unload
routine that the protocol driver sets in the driver object passed in to the
protocol's DriverEntry function.