NDIS_SET_PACKET_CANCEL_ID (Compact 2013)

Artikel
07/31/2017

3/26/2014

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

Syntax

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 Value

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 the initialization of NDIS protocol drivers. However, a protocol or intermediate driver can obtain more than one partial cancellation identifier by calling NdisGeneratePartialCancelId multiple times.

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 in 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 one time for each packet. If a driver marks all packets in 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 _cIdset 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

Header

ndis.h

Freigeben über

NDIS_SET_PACKET_CANCEL_ID (Compact 2013)

Syntax

Parameters

Return Value

Remarks

Requirements

See Also

Reference

Zusätzliche Ressourcen