NDIS_GET_PACKET_MEDIA_SPECIFIC_INFO (Compact 2013)

3/26/2014

This macro returns the MediaSpecificInformation pointer and the SizeMediaSpecificInfo value from the out-of-band data block associated with a given packet descriptor.

Syntax

VOID NDIS_GET_PACKET_MEDIA_SPECIFIC_INFO(
  PNDIS_PACKET _Packet,
  PPVOID _pMediaSpecificInfo,
  PUINT _pSizeMediaSpecificInfo
);

Parameters

• _Packet
  Points to a packet descriptor

• _pMediaSpecificInfo
  Points to a caller supplied variable that this macro sets to the MediaSpecificInformation pointer. The returned address gives the caller access to any buffered out-of-band information, such as packet priority, associated with the specified net packet indicated or to be transmitted.

• _pSizeMediaSpecificInfo
  Points to a caller-supplied variable that this macro sets to the SizeMediaSpecificInfovalue, which specifies the size in bytes of the buffer at MediaSpecificInformation.

Return Value

None

Remarks

NDIS_GET_PACKET_MEDIA_SPECIFIC_INFO returns a NULL pointer at pMediaSpecificInfo and zero (0) at pSizeMediaSpecificInfo if there is no media-specific information in the NDIS_PACKET_OOB_DATA block associated with the given packet descriptor.

Depending on the medium, a network adapter miniport might set these members with NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO331f4dfc-7249-4ac7-9f79-8fffdd366200 in the out-of-band data blocks associated with the packet descriptors it allocates for receive indications.

Depending on the medium of the underlying driver to which it is bound, a protocol might set MediaSpecificInformation and SizeMediaSpecificInfo in the out-of-band blocks associated with the packet descriptors it allocates for sends.

In either case, while a higher-level protocol is consuming a receive indication or a lower-level miniport is processing a send, that driver must have exclusive access to the buffer at MediaSpecificInformation. This restriction implies the following:

• A miniport cannot access the buffer it set up with media-specific information when NdisMIndicateReceivePacket returns control if NDIS_STATUS_PENDING is set in the Status member of the associated out-of-band block. The driver can use NDIS_GET_PACKET_STATUS8c365145-6da9-4adb-800f-d16c43583c99 to determine whether each packet in the packet array it indicated has this status set or was returned with NDIS_STATUS_SUCCESS.
• A protocol driver cannot access the media-specific information buffer it set up for a send, nor anything else in the out-of-band data block associated with a packet descriptor it passes to NdisSendPackets or NdisSend, until the packet descriptor is returned to its ProtocolSendComplete function.
  Because NDIS queues send packets and resubmits them if the MiniportSend function returns NDIS_STATUS_RESOURCES or if the MiniportSendPackets function sets NDIS_STATUS_RESOURCES for the Status of a packet in a submitted array, the final status of each packet in a send array is volatile until that packet was returned to ProtocolSendComplete.

A protocol driver can call NdisGetReceivedPacket followed by NDIS_GET_ORIGINAL_PACKET to obtain this information from the NDIS_PACKET_OOB_DATA block associated with a packet descriptor when its ProtocolReceive function is given an indication. However, these calls are superfluous if the protocol is bound to an underlying driver that does not supply out-of-band information with its indications.

The NDIS_GET_PACKET_MEDIA_SPECIFIC_INFO macro is defined as follows.

#define NDIS_GET_PACKET_MEDIA_SPECIFIC_INFO(_Packet,                    \
                                            _pMediaSpecificInfo,        \
                                            _pSizeMediaSpecificInfo)    \
{                                                                       \
    if (!((_Packet)->Private.NdisPacketFlags & fPACKET_ALLOCATED_BY_NDIS) ||\
        !((_Packet)->Private.NdisPacketFlags & fPACKET_CONTAINS_MEDIA_SPECIFIC_INFO))\
    {                                                                   \
        *(_pMediaSpecificInfo) = NULL;                                  \
        *(_pSizeMediaSpecificInfo) = 0;                                 \
    }                                                                   \
    else                                                                \
    {                                                                   \
        *(_pMediaSpecificInfo) =((PNDIS_PACKET_OOB_DATA)((PUCHAR)(_Packet) +\
                    (_Packet)->Private.NdisPacketOobOffset))->MediaSpecificInformation;\
        *(_pSizeMediaSpecificInfo) = ((PNDIS_PACKET_OOB_DATA)((PUCHAR)(_Packet) +\
                    (_Packet)->Private.NdisPacketOobOffset))->SizeMediaSpecificInfo;\
    }                                                                   \
}

Requirements

See Also

Reference

NDIS 5.x Legacy Network Driver Macros
MediaSpecificInformation
MiniportHandleInterrupt
MiniportSend
MiniportSendPackets
NDIS_GET_ORIGINAL_PACKET
NDIS_GET_PACKET_STATUS
NDIS_OOB_DATA_FROM_PACKET
NDIS_PACKET_OOB_DATA
NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO
NdisAllocatePacket
NdisGetReceivedPacket
NdisMIndicateReceivePacket
NdisSend
NdisSendPackets
ProtocolReceive
ProtocolReceivePacket
ProtocolSendComplete
NDIS 5.x Legacy Reference