NdisQueryReceiveInformation

NDIS_STATUS
NdisQueryReceiveInformation(
IN NDIS_HANDLE NdisBindingHandle,
IN NDIS_HANDLE MacContext,
OUT PLONGLONG TimeSent OPTIONAL,
OUT PLONGLONG TimeReceived OPTIONAL,
IN PUCHAR Buffer,
IN UINT BufferSize,
OUT PUINT SizeNeeded
);

NdisQueryReceiveInformation returns information from the out-of-band data block associated with a packet descriptor input to the ProtocolReceive function.

Parameters

NdisBindingHandle: Specifies the handle returned by NdisOpenAdapter that identifies the target NIC or the virtual adapter of the next-lower driver to which the caller is bound.
MacContext: Specifies the MacReceiveContext handle input to the caller’s ProtocolReceive function.
TimeSent: Points to a caller-supplied variable in which this function returns the TimeSent timestamp, if any, for the received packet. This parameter can be NULL.
TimeReceived: Points to a caller-supplied variable in which this function returns the TimeReceived timestamp, if any, for the received packet. This parameter can be NULL.
Buffer: Points to a caller-supplied buffer in which this function returns a copy of any medium-specific out-of-band information, such as packet priority, associated with the received packet.
BufferSize: Specifies the size in bytes of the supplied buffer.
SizeNeeded: Points to a caller-supplied variable in which this function returns how large a buffer should be supplied if the given BufferSize is too small.

Return Value

NdisQueryReceiveInformation can return one of the following values:

NDIS_STATUS_SUCCESS: The caller can use the medium-specific information returned at Buffer and/or the value(s) returned at TimeSent and TimeReceived.
NDIS_STATUS_BUFFER_TOO_SHORT: The amount of medium-specific information was too large to fit at Buffer according to the given BufferSize. SizeNeeded is set to the number of bytes of medium-specific information available for the indication.
NDIS_STATUS_NOT_SUPPORTED: The underlying driver does not indicate receives with NdisMIndicateReceivePacket and, therefore, there is no out-of-band information available with the given packet descriptor.

Comments

The ProtocolReceive functions of protocol drivers that do not supply a ProtocolReceivePacket function can call NdisQueryReceiveInformation when such a driver is bound to an underlying driver that supplies medium-specific information, such as packet priority, and timestamps when it indicates receives.

Whenever the underlying driver calls NdisMIndicateReceivePacket with a packet descriptor for which the Status member in the associated NDIS_PACKET_OOB_DATA block is set to NDIS_STATUS_RESOURCES, the ProtocolReceive functions of bound protocols are called once with each packet descriptor, rather than their ProtocolReceivePacket functions. The ProtocolReceive function of such a driver can call NdisQueryReceiveInformation to retrieve a copy of any medium-specific information and optionally the TimeSent and TimeReceived values if either or both of these timestamps were supplied by the indicating driver.

The MacContext handle passed to NdisQueryReceiveInformation is opaque to the caller of NdisQueryReceiveInformation and reserved for use by the underlying driver.

Callers of NdisQueryReceiveInformation run at IRQL <= DISPATCH_LEVEL.