NDIS_PACKET_OOB_DATA (Windows Embedded CE 6.0)

Article
01/05/2012

1/6/2010

This structure contains out-of-band (OOB) information associated with a packet descriptor that is used by drivers whose media supplies, requires, or accepts OOB information, such as information for an asynchronous transfer mode (ATM) NIC. In addition, it is used by drivers that support multipacket receives and/or sends.

Syntax

typedef struct _NDIS_PACKET_OOB_DATA {
  union {
    ULONGLONG TimeToSend;
    ULONGLONG TimeSent;
  };
    ULONGLONG TimeReceived;
    UINT HeaderSize;
    UINT SizeMediaSpecificInfo;
    PVOID MediaSpecificInformation;
    NDIS_STATUS Status;
} NDIS_PACKET_OOB_DATA, *PNDIS_PACKET_OOB_DATA;

Members

TimeToSend
Specifies the time, in system time units, at which a given packet should be transmitted over the network.

Protocols can set this timestamp before passing an array of packet descriptor pointers to NdisSendPackets or a packet descriptor pointer to NdisSend.

The MiniportSendPackets or MiniportSend function of underlying drivers can retrieve the value of this timestamp to determine when the given packets should be transmitted over the network. Usually, only the lowest-level underlying driver retrieves this timestamp.

TimeSent
Specifies the time, in system time units, at which a received packet was transmitted over the network from a remote node.

NIC drivers and, possibly, intermediate drivers that export only a set of MiniportXXX functions set this timestamp before indicating receive packets.

The ProtocolReceivePacket functions of drivers bound above such a miniport can retrieve the value of this timestamp to determine when any particular packet was transmitted from the remote node. If the ProtocolReceive function is given an indication and the underlying driver sets this timestamp, ProtocolReceive can call NdisGetReceivedPacket and NDIS_GET_ORIGINAL_PACKET to retrieve the packet that contains this timestamp.

TimeReceived
Specifies the time, in system time units, at which a given packet from a remote node on the network was received on the NIC.

NIC drivers and, possibly, intermediate drivers that export only a set of MiniportXXX functions set this timestamp before calling NdisMIndicateReceivePacket with a packet array, which can have one or more pointers to packet descriptors.

The ProtocolReceivePacket functions of drivers bound above any such miniport can retrieve the value of this timestamp to determine when the given packets were received. If the ProtocolReceive function is given an indication and the underlying driver sets this timestamp, ProtocolReceive can call NdisGetReceivedPacket and NDIS_GET_ORIGINAL_PACKET to retrieve the packet that contains this timestamp.

HeaderSize
Specifies the size, in bytes, of the medium-specific header contained in the buffer mapped by the initial buffer descriptor chained to the packet descriptor.

Lower-level drivers set this member for subsequent receive indications according to the medium each driver's MiniportInitialize function elected to support.

The ProtocolReceivePacket functions of drivers bound above such a miniport can retrieve the value of this member to determine how to process the medium-specific net packet.

SizeMediaSpecificInfo
Specifies the size, in bytes, of the buffer at MediaSpecificInformation.

A driver must set this member if it supplies OOB information with a packet to be sent or indicated.

MediaSpecificInformation
Specifies the address of a driver-allocated buffer. This buffer contains any OOB data, such as information for an ATM NIC that accompanies the net packet specified with the packet descriptor. The OOB data has been set up either by the allocating protocol for a send or by the allocating miniport for a receive indication.

Either type of driver can retrieve the address of the OOB data buffer and its size to determine how to process or interpret the send or receive specified with the incoming packet descriptor. If the ProtocolReceive function is given an indication and the underlying driver supplies this information, ProtocolReceive can call NdisGetReceivedPacket and NDIS_GET_ORIGINAL_PACKET to retrieve the packet that contains the virtual range of this buffer.

Status
Specifies the status of the packet descriptor and the ownership of all driver-allocated resources specified with the packet descriptor.

Only lower-level drivers and NDIS set this member.

In the receive path, a miniport can set this member before it calls NdisMIndicateReceivePacket to indicate how soon it needs to regain ownership of its allocated resources specified in the associated packet descriptors. A serialized miniport can retrieve this value on return from NdisMIndicateReceivePacket to determine whether the resources specified with the packet descriptor for its indication can be prepared for reuse immediately.

In the send path, a serialized miniport can set this member in its MiniportSendPackets function to complete an incoming send immediately, to notify NDIS that it will complete the request asynchronously, or to request that NDIS requeue some or all of the incoming packet array and resubmit those packet descriptors to MiniportSendPackets later.

A protocol cannot retrieve this value to determine the completion status of a send on return from its call to NdisSendPackets or NdisSend.

A deserialized or connection-oriented miniport cannot complete a multipacket send synchronously or request (by setting the Status member) that NDIS requeue some or all of an incoming packet array. Instead, a deserialized or connection-oriented miniport must queue internally the entire incoming packet array if it cannot send the data immediately and must always complete a multipacket send asynchronously with NdisMSendComplete for each packet in the array.

Remarks

Every packet descriptor allocated with NdisAllocatePacket has an associated NDIS_PACKET_OOB_DATA block. Only drivers that support multipacket sends and/or receives and drivers that supply OOB information, such as packet priority, with each network packet to be transferred use the OOB block. Nevertheless, every NDIS driver that allocates packet descriptors for transfers between bound drivers must allocate those packet descriptors with NdisAllocatePacket from the packet pool that each such NDIS driver usually allocates when it initializes.

In general, drivers of high-capacity busmaster DMA NICs are most likely to support multipacket receives and sends because such a NIC driver makes the greatest performance gains by supporting multipacket transfers. Any protocol that binds itself to, or above, such an underlying NIC driver also should support multipacket sends and receives for maximum performance.

If such a protocol also binds itself above another NIC driver without multipacket transfer support, NDIS handles multipacket sends and single-packet receives in a manner transparent to both drivers by always calling the protocol's ProtocolReceive function and by calling that NIC driver's MiniportSend function with a single packet per call. Similarly, if a protocol that does not support multipacket transfers binds itself above a NIC driver that does, NDIS handles multipacket receive indications and single packet sends in a manner transparent to both drivers, although the MiniportSendPackets function of the underlying NIC driver is given only a single send request per call to NdisSend from such a protocol.

Using Timestamps

All timestamps set in the NDIS_PACKET_OOB_DATA blocks associated with packet descriptors are expressed in system time units as the number of 100-nanosecond intervals since 12:00 A.M. January 1, 1601.

NDIS drivers can call NdisGetCurrentSystemTime when they set these timestamps with the NDIS_SET_PACKET_TIME_XXX macros. Still higher-level drivers or system components can convert these timestamps into locale-specific values more meaningful to the end user.

Supplying OOB Information with Packets

Any OOB information specified in the SizeMediaSpecificInfo and MediaSpecificInformation members is medium-type-specific. For example, some types of media require protocols to specify a packet priority for each packet they send and require NIC drivers to specify a packet priority with each receive packet they indicate. Such a NIC driver must call NdisMIndicateReceivePacket to fulfill the requirements of these types of media.

While NDIS provides support for a range of priority values from 0 through 7, some media support only two levels of priority. For these types of media, NDIS drivers should map values 0 through 3 to the medium-specific normal priority value (usually 0 for such media types) and values 4 through 7 to the medium-specific high-priority value (usually one for such media types).

For additional information about the structure of individual records within the buffer at MediaSpecificInformation, see MediaSpecificInformation.

Requirements

Header	ndis.h
Windows Embedded CE	Windows CE .NET 4.0 and later