NDIS_SET_PACKET_CANCEL_ID function

Article
06/19/2017

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.

NDIS_SET_PACKET_CANCEL_ID marks a packet with a cancellation identifier that a driver can later use to cancel the pending transmission of the packet.

Syntax

VOID NDIS_SET_PACKET_CANCEL_ID(
  _In_ PNDIS_PACKET Packet,
  _In_ ULONG_PTR    CancelId
);

Parameters

Packet [in]
Pointer to an NDIS_PACKET structure that is the descriptor for a packet.
CancelId [in]
A cancellation identifier.

Return value

None

Remarks

A protocol driver or intermediate driver can call the NDIS_SET_PACKET_CANCEL_ID function for each packet that it passes to lower-level drivers for transmission. The NDIS_SET_PACKET_CANCEL_ID function marks the specified packet with a cancellation identifier.

To cancel the pending transmission of a marked packet, a protocol or intermediate driver passes the packet's cancellation ID to NdisCancelSendPackets. The caller of NDIS_SET_PACKET_CANCEL_ID should therefore store the assigned cancellation ID internally so that it can pass it, as necessary, to NdisCancelSendPackets. A driver can also obtain a packet's cancellation ID by calling NDIS_GET_PACKET_CANCEL_ID.

An intermediate driver should not modify the cancellation ID of packets that it passes to a lower-level driver. However, an intermediate driver can set a cancellation ID for packets that it originates.

Before assigning cancellation IDs to packets, a driver should call NdisGeneratePartialCancelId to obtain the high-order byte of each cancellation ID that it assigns. This ensures that the driver does not duplicate cancellation IDs assigned by other drivers in the system. NdisGeneratePartialCancelId is typically called once from the DriverEntry routine; however, a protocol or intermediate driver can obtain more than one partial cancellation identifier by calling NdisGeneratePartialCancelId more than once.

A protocol driver or intermediate driver might assign cancellation IDs to packets as follows:

The driver could mark all packets sent over a connection with the same cancellation identifier.
The driver could mark each packet with a unique cancellation identifier.
The driver could mark all packets within a subgroup of packets (for example, packets sent on behalf of a single client) with a unique identifier.

If a driver marks all packets with the same cancellation identifier, it can cancel all pending packet transmissions from an adapter with a single call to NdisCancelSendPackets. If a driver marks each packet with a unique cancellation identifier, it can cancel the pending transmission of individual packets from an adapter by calling NdisCancelSendPackets once for each packet. If a driver marks all packets within a subgroup of packets with a unique identifier, it can cancel all pending transmissions of packets within that subgroup with a single call to NdisCancelSendPackets.

After aborting the pending transmission of a packet, the underlying miniport driver calls the NdisMSendComplete, NdisMCoSendComplete, or NdisMWanSendComplete function to return the packet descriptor and a completion status of NDIS_STATUS_ABORTED to the protocol or intermediate driver that requested the transmission. NDIS, in turn, calls the protocol or intermediate driver's ProtocolSendComplete or ProtocolCoSendComplete function.

In its ProtocolSendComplete or ProtocolCoSendComplete function, a protocol driver can call NDIS_SET_PACKET_CANCEL_ID with CancelId set to NULL. This prevents the packet from inadvertently being used again with a stale cancellation ID.

Requirements

Target platform	Desktop
Version	Available in Windows XP and later versions of the Windows operating systems.
Header	Ndis.h (include Ndis.h)
IRQL	<= DISPATCH_LEVEL