Share via

MediaSpecificInformation

  • Article

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

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 NIC medium requires that drivers specify per-packet priority, while its driver uses Ethernet emulation to communicate with bound protocols.

    A bound protocol can determine whether the underlying NIC 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 NIC 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, including 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 Making 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, along 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 retaining 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 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 of the packet descriptors 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 retain 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 with 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 due to 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, so 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/or 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 with the packet descriptor.

Requirements

OS Versions: Windows CE .NET 4.0 and later.
Header: Ndis.h.

See Also

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

 Last updated on Tuesday, May 18, 2004

© 1992-2003 Microsoft Corporation. All rights reserved.