NdisQueryReceiveInformation

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.