NdisSetPacketCancelId (Windows Embedded CE 6.0)

1/6/2010

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

Syntax

VOID NdisSetPacketCancelId(
  PNDIS_PACKET Packet,
  ULONG_PTR CancelId
); 

Parameters

• Packet
  [in] Points 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 NdisSetPacketCancelId function for each packet that it passes to lower-level drivers for transmission. The NdisSetPacketCancelId 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 NdisSetPacketCancelId 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 NdisGetPacketCancelId.

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 once from the Initialization of NDIS Protocol Drivers routines; 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 NdisSetPacketCancelId with CancelId set to NULL. This prevents the packet from inadvertently being used again with a stale cancellation identifier.

Requirements

See Also

Reference

NDIS Library Functions
MiniportCancelSendPackets
NdisAllocatePacket
NdisAllocatePacketPool
NdisAllocatePacketPoolEx
NdisCancelSendPackets
NdisGeneratePartialCancelId
NdisGetPacketCancelId
NDIS_PACKET
NdisMSendComplete
NdisMWanSendComplete
ProtocolSendComplete