NDIS_SET_PACKET_CANCEL_ID

  • Article

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

ULONG_PTR NDIS_SET_PACKET_CANCEL_ID(
  PNDIS_PACKET _P,
  ULONG_PTR _cId
);

Parameters

  • _P
    Points to an NDIS_PACKET structure that is the descriptor for a packet.
  • _cId
    Cancellation identifier.

Return Values

The return value is the _cId identifier.

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 identifier to NdisCancelSendPackets. The caller of NDIS_SET_PACKET_CANCEL_ID should therefore store the assigned cancellation identifier internally so that it can pass it, as necessary, to NdisCancelSendPackets. A driver can also obtain a packet's cancellation identifier by calling NDIS_GET_PACKET_CANCEL_ID.

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

Before assigning cancellation identifiers to packets, a driver should call NdisGeneratePartialCancelId to obtain the high-order byte of each cancellation identifier that it assigns. This ensures that the driver does not duplicate cancellation identifiers assigned by other drivers in the system. NdisGeneratePartialCancelId is typically called during Initialization of NDIS Protocol Drivers; 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 identifiers 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 calls the NdisMSendComplete 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 function.

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

The NDIS_SET_PACKET_CANCEL_ID macro is defined as follows.

#define NDIS_SET_PACKET_CANCEL_ID(_P, _cId)  NDIS_PER_PACKET_INFO_FROM_PACKET(_P, PacketCancelId) = _cId

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Ndis.h.

See Also

Initialization of NDIS Protocol Drivers | MiniportCancelSendPackets | NDIS_GET_PACKET_CANCEL_ID | NDIS_PACKET | NdisAllocatePacket | NdisAllocatePacketPool | NdisAllocatePacketPoolEx | NdisCancelSendPackets | NdisGeneratePartialCancelId | NdisMSendComplete | NdisMWanSendComplete | ProtocolSendComplete

 Last updated on Tuesday, May 18, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.