NdisSetPacketCancelId (Windows CE 5.0)
NdisSetPacketCancelId marks a packet with a cancellation identifier that a driver can later use to cancel the pending transmission of the packet.
VOID NdisSetPacketCancelId(PNDIS_PACKETPacket,ULONG_PTRCancelId);
Parameters
- Packet
[in] Points to an NDIS_PACKET structure that is the descriptor for a packet. - CancelId
[in] A cancellation identifier.
Return Values
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
OS Versions: Windows CE .NET 4.0 and later.
Header: Ndis.h.
See Also
MiniportCancelSendPackets | NdisAllocatePacket | NdisAllocatePacketPool | NdisAllocatePacketPoolEx | NdisCancelSendPackets | NdisGeneratePartialCancelId | NdisGetPacketCancelId | NDIS_PACKET | NdisMSendComplete | NdisMWanSendComplete | ProtocolSendComplete
Send Feedback on this topic to the authors