This structure specifies out-of-band information associated with a packet descriptor, used by drivers whose media supplies, requires, or accepts out-of-band information, such as packet priorities, and by drivers that support multipacket receives and/or sends.
| Header file: | Ndis.h |
| Windows CE versions: | 2.0 and later |
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;
Protocols can set this time stamp before passing an array of packet descriptor pointers to the NdisSendPackets function or a packet descriptor pointer to the NdisSend function.
The MiniportSendPackets or MiniportSend functions of underlying drivers can retrieve the value of this time stamp to determine when the specified packet(s) should be transmitted over the network. Usually, only the lowest-level underlying driver retrieves this time stamp.
NIC drivers and, possibly, intermediate drivers that export only a set of MiniportXXX functions set this time stamp before indicating receive packet(s).
The ProtocolReceivePacket functions of drivers bound above such a miniport can retrieve the value of this time stamp 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 NdisQueryReceiveInformation to retrieve this time stamp.
NIC drivers and, possibly, intermediate drivers that export only a set of MiniportXXX functions set this time stamp 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 time stamp to determine when the specified packet(s) were received. If the ProtocolReceive function is given an indication and the underlying driver sets this time stamp, ProtocolReceive can call NdisQueryReceiveInformation to retrieve this time stamp.
Lower-level drivers set this member for subsequent receive indication(s) according to the medium that 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.
A driver must set this member if it supplies out-of-band information with a packet to be sent or indicated.
Either type of driver can retrieve the address of the out-of-band 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 NdisQueryReceiveInformation to retrieve the virtual range of this buffer.
Only lower-level drivers and NDIS set this member.
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 descriptor(s). It 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.
A miniport can set this member in its MiniportSendPackets function to complete an incoming send immediately, to notify NDIS that it completes the request asynchronously, or to request that NDIS requeue some or all of the incoming packet array and resubmit those packet descriptor(s) to MiniportSendPackets later.
A protocol cannot retrieve this value to determine the completion status of a send on return from its call to the NdisSendPackets or the NdisSend function.
Every packet descriptor allocated with the NdisAllocatePacket function has one of these structures associated with it. Only drivers that support multipacket sends and/or receives and drivers that supply out-of-band 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 an NIC driver makes the greatest performance gains by supporting multipacket transfers. Any protocol that binds itself to or above such an underlying NIC driver should also 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 an 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.
All time stamps set in these structures 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 the NdisGetCurrentSystemTime function when they set these time stamps with the NDIS_SET_PACKET_TIME_XXX macros. Still higher-level drivers or system components can convert these time stamps into locale-specific values more meaningful to the user.
Any out-of-band 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 that they send and require NIC drivers to specify a packet priority with each receive packet that they indicate. Such an 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.