NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO (Compact 2013)

3/26/2014

This macro sets the _MediaSpecificInformation pointer and the _SizeMediaSpecificInfo value in the out-of-band (OOB) data block associated with a specified packet descriptor.

Syntax

VOID NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO(
  PNDIS_PACKET _Packet,
  PVOID _MediaSpecificInfo,
  UINT _SizeMediaSpecificInfo
);

Parameters

• _Packet
  Pointer to a driver-allocated packet descriptor

• _MediaSpecificInfo
  Pointer to a caller-supplied buffer that contains medium-specific information, such as packet priority, to be set in the MediaSpecificInformation member of the NDIS_PACKET_OOB_DATA structure associated with the specified packet descriptor. This parameter cannot be NULL.

• _SizeMediaSpecificInfo
  Specifies the number of bytes of information supplied by the MediaSpecificInformation member. This parameter cannot be zero (0).

Remarks

Depending on the medium, an underlying driver might set these members with this macro in the OOB data blocks associated with the packet descriptors that it allocates for receive indications. When a bound protocol is called with the indication, it uses the NDIS_GET_PACKET_MEDIA_SPECIFIC_INFO macro to access the supplied information.

Depending on the medium of the underlying driver to which it is bound, a protocol might set MediaSpecificInformation and SizeMediaSpecificInfo in the OOB blocks associated with the packet descriptors that it allocates for sends. The underlying driver uses NDIS_GET_PACKET_MEDIA_SPECIFIC_INFO to access the supplied information.

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 that it sets up with out-of-band information when the NdisMIndicateReceivePacket function returns control if NDIS_STATUS_PENDING is set in the Status member of the associated structure. The driver uses NDIS_GET_PACKET_STATUS to determine whether each packet in the packet array that it just indicated has this status set or was returned with NDIS_STATUS_SUCCESS.
• A protocol driver cannot access the buffer that it set up with out-of-band information for a send, or anything else in the structure associated with a packet descriptor that it passes to the NdisSend function, 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 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 the NdisQueryReceiveInformation function to obtain a copy of the NDIS_PACKET_OOB_DATA structure associated with a packet descriptor when its ProtocolReceive function is given an indication. However, this call is superfluous if the protocol is bound to an underlying driver that does not supply out-of-band information with its indications.

The NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO macro is defined as follows.

#define NDIS_SET_PACKET_MEDIA_SPECIFIC_INFO(_Packet,                    \
                                            _MediaSpecificInfo,         \
                                            _SizeMediaSpecificInfo)     \
{                                                                       \
    if ((_Packet)->Private.NdisPacketFlags & fPACKET_ALLOCATED_BY_NDIS) \
    {                                                                   \
        (_Packet)->Private.NdisPacketFlags |= fPACKET_CONTAINS_MEDIA_SPECIFIC_INFO;\
        ((PNDIS_PACKET_OOB_DATA)((PUCHAR)(_Packet) +                    \
                                          (_Packet)->Private.NdisPacketOobOffset))->MediaSpecificInformation = (_MediaSpecificInfo);\
        ((PNDIS_PACKET_OOB_DATA)((PUCHAR)(_Packet) +                    \
                                          (_Packet)->Private.NdisPacketOobOffset))->SizeMediaSpecificInfo = (_SizeMediaSpecificInfo);\
    }                                                                   \
}

Requirements

Header

ndis.h

See Also

Reference

NDIS 5.x Legacy Network Driver Macros
MediaSpecificInformation
MiniportSend
NDIS_GET_PACKET_MEDIA_SPECIFIC_INFO
NDIS_GET_PACKET_STATUS
NdisMIndicateReceivePacket
NDIS_PACKET_OOB_DATA
NdisSend
ProtocolReceive
ProtocolSendComplete
NDIS 5.x Legacy Reference