MediaSpecificInformation (Compact 2013)

3/26/2014

This structure contains information about the characteristics of the network hardware that is bound to a protocol.

Syntax

typedef struct MediaSpecificInformation {
  UINT NextEntryOffset;
  NDIS_CLASS_ID ClassId;
  UINT Size;
  UCHAR ClassInformation[1];
} MEDIA_SPECIFIC_INFORMATION;

Members

• NextEntryOffset
  Specifies the byte offset to this member in the next record, if any. Zero indicates that this is the last record in the buffer. The values of all remaining members in the last record are also 0. The value of this member must be quad-aligned.

• ClassId
  Specifies the type of the record. Possible values are one of the following:

  Value	Description
  NdisClass802_3Priority	The underlying network adapter medium requires that drivers specify per-packet priority, whereas its driver uses Ethernet emulation to communicate with bound protocols. A bound protocol can determine whether the underlying network adapter miniport's native medium requires prioritized packets with the OID_802_3_MAC_OPTIONS query. If so, the miniport sets the NDIS_802_3_OPTION_PRIORITY flag.
  NdisClassWirelessWanMbxMailbox	The underlying network adapter driver examines the ULONG-sized record at ClassInformation to determine whether the mailbox flag should be set for the associated packet. A value of 1 indicates that the mailbox flag should be set; 0 indicates that it should not.

• Size
  Specifies the number of bytes in the ClassInformation array. This includes any padding necessary to align the NextEntryOffset of the next record on a 4-byte boundary.

• ClassInformation
  Specifies the out-of-band information for this record

Remarks

The NDIS_CLASS_ID type is an NDIS-defined enumeration. Most common classifications for records will be specified as system-defined values. However, a range of values in this enumeration will be available for vendor-defined experimental classes.

Setting Status Before You Make Receive Indications

Only lower-level NDIS drivers use the Status member of this structure for receive indications. Before such a driver calls NdisMIndicateReceivePacket, it sets the Status member with NDIS_SET_PACKET_STATUS for one or more packet descriptors in the array. The following table shows the possible values for Status:

Value	Description
NDIS_STATUS_SUCCESS	Tells NDIS that the driver is relinquishing ownership of the packet about to be indicated with NdisMIndicateReceivePacket until the packet descriptor is returned to its MiniportReturnPacket function. Protocols that receive the indication can use the packet descriptor, together with all buffers mapped by buffer descriptors chained to the packet descriptor and any OOB information supplied with the packet, to copy the indicated net packet data or, possibly, to forward the indicated data to interested clients.
NDIS_STATUS_RESOURCES	Tells NDIS that the driver is keeping ownership of the packet about to be indicated with NdisMIndicateReceivePacket. This packet will be indicated to the ProtocolReceive function of bound protocols.

Setting this status forces bound protocols to return ownership of each such packet descriptor, of any medium-specific buffer in the OOB data block for each packet descriptor, and of the memory mapped by each packet descriptor's respective chained buffer descriptors to the indicating driver more quickly. The protocols must wait for a call to their ProtocolReceiveComplete functions to begin post-processing the data that they copied from indications and forwarding the data to clients.

Getting Status on Return from NdisMIndicateReceivePacket

After a serialized driver has set the Status for some number of packet descriptors and called NdisMIndicateReceivePacket with the array of pointers to the packet descriptors, it must use the NDIS_GET_PACKET_STATUS macro when NdisMIndicateReceivePacket returns control to retrieve the Status set by NDIS.

The returned Status in the NDIS_PACKET_OOB_DATA block determines what the indicating driver does next. The NDIS_PACKET_OOB_DATA block is associated with each packet descriptor that the serialized driver indicated with NDIS_STATUS_SUCCESS.

The following table shows possible values for Status, and describes the resulting action to be taken by the driver:

Status	Description
NDIS_STATUS_SUCCESS	If this value is set on return from a miniport's call to NdisMIndicateReceivePacket, the miniport regains ownership of the following: The packet descriptor The associated OOB data block associated with the packet descriptor and of any media-specific information buffer specified in this block All buffers mapped by buffer descriptors chained to the packet descriptor NDIS guarantees that any packet descriptors for which the indicating driver set NDIS_STATUS_RESOURCES, as already described, will be returned from its call to NdisMIndicateReceivePacket with NDIS_STATUS_SUCCESS. The driver can prepare these descriptors, the OOB block, and media-specific information buffer, if any, for reuse in subsequent receive indications immediately.
NDIS_STATUS_PENDING	If this value is set on return from NdisMIndicateReceivePacket, protocols keep ownership of the packet descriptor, of its associated OOB data block and any buffer specified in this block, and of all buffers mapped by buffer descriptors chained to the packet descriptor until the packet descriptor is returned to the indicating driver's MiniportReturnPacket function.

Setting Status in MiniportSendPackets

Only underlying serialized NDIS drivers that have MiniportSendPackets functions can use the Status member of this structure for packet descriptors specifying sends. Such a driver's MiniportSendPackets function sets the Status member in the OOB data blocks associated with the packet descriptors in the input array as follows:

• If the driver will complete the send operation asynchronously, MiniportSendPackets sets NDIS_STATUS_PENDING in the Status member for the given packet descriptor.
• If the driver cannot process all sends in a given packet array because of current resource constraints, MiniportSendPackets sets NDIS_STATUS_RESOURCES in the Status member for one packet descriptor.
• NDIS queues these packet descriptors internally in the same order for resubmission to MiniportSendPackets when the driver calls NdisMSendResourcesAvailable or NdisMSendComplete, whichever occurs first. NDIS reflects this miniport-set status value to protocols as NDIS_STATUS_PENDING.
• If MiniportSendPackets will complete a given send request before it returns control, it must set the Status member for the given packet descriptor to a driver-determined status value so that NDIS can reflect this status back to the protocol that initiated the send.

Otherwise, such a driver supplies the completion status for each packet when it calls NdisMSendComplete with the packet descriptor. Drivers that have MiniportSend instead of MiniportSendPackets functions return the status for each incoming send packet. Therefore, such a driver never sets the Status member of the OOB data block for a packet descriptor specifying a send.

Protocols cannot determine the completion status for a protocol-allocated packet descriptor from the Status member of the associated OOB block on return from NdisSendPackets or NdisSend. This value can change dynamically as NDIS submits, re-queues, and resubmits send packets to underlying drivers' MiniportSendPackets and MiniportSend functions.

A protocol cannot use any NDIS_GET_PACKET_XXX macro or the NDIS_OOB_DATA_FROM_PACKET macro to access the OOB data block for such a protocol-allocated packet descriptor until its ProtocolSendComplete function is called by using the packet descriptor.

Requirements

Header

ndis.h

See Also

Reference

NDIS 5.x Legacy Structures
MiniportReturnPacket
MiniportSend
MiniportSendPackets
NDIS_GET_PACKET_STATUS
NDIS_OOB_DATA_FROM_PACKET
NDIS_PACKET_OOB_DATA
NdisMIndicateReceivePacket
NdisMSendComplete
NdisMSendResourcesAvailable
NdisSend
NdisSendPackets
OID_802_3_MAC_OPTIONS
ProtocolReceiveComplete
ProtocolReceive
ProtocolSendComplete
NDIS 5.x Legacy Reference