QOSQueryFlow function (qos2.h)

The QOSQueryFlow function requests information about a specific flow added to the QoS subsystem. This function may be called asynchronously.


ExternC BOOL QOSQueryFlow(
  [in]            HANDLE         QOSHandle,
  [in]            QOS_FLOWID     FlowId,
  [in]            QOS_QUERY_FLOW Operation,
  [in, out]       PULONG         Size,
  [out]           PVOID          Buffer,
  [in, optional]  DWORD          Flags,
  [out, optional] LPOVERLAPPED   Overlapped


[in] QOSHandle

Handle to the QOS subsystem returned by QOSCreateHandle.

[in] FlowId

Specifies a flow identifier. A QOS_FLOWID is an unsigned 32-bit integer.

[in] Operation

Specifies which type of flow information is being queried. This parameter specifies what structure the Buffer will contain.

Value Meaning
Buffer will contain a QOS_FLOW_FUNDAMENTALS structure.
Buffer will contain a QOS_PACKET_PRIORITY structure.
Buffer will contain a UINT64 value that indicates the flow rate specified when requesting the contract, in bits per second.

[in, out] Size

Indicates the size of the Buffer parameter, in bytes.

On function return, if successful, this parameter will specify the number of bytes copied into Buffer.

If this call fails with ERROR_INSUFFICIENT_BUFFER, this parameter will indicate the minimum required Buffer size in order to successfully complete this operation.

[out] Buffer

Pointer to the structure specified by the value of the Operation parameter.

[in, optional] Flags

Flags pertaining to the data being returned.

Value Meaning
The QOS subsystem will only return fresh, not cached, data. If fresh data is unavailable, it will try to obtain such data, at the expense of possibly taking more time. If this is not possible, the call will fail with the error code ERROR_RETRY.

This flag is only applicable when the Operation parameter is set to QOSQueryFlowFundamentals.

[out, optional] Overlapped

Pointer to an OVERLAPPED structure used for asynchronous output. This must be set to NULL if this function is not being called asynchronously.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is 0. To get extended error information, call GetLastError. Some possible error codes follow.

Return code Description
The QoS subsystem is currently configured by policy to not allow this operation on the network path between this host and the destination host. For example, the default policy prevents qWAVE experiments from running to off-link destinations.
The request to the QOS subsystem timed out before enough useful information could be gathered.
The buffer length as specified by the Size parameter is not sufficient for the queried data. The Size parameter now contains the minimum required size.
The QOSHandle parameter is invalid.
The FlowId parameter or Buffer size is insufficient.
Invalid FlowId specified.
Indicates that a memory allocation failed.
The operation being performed requires information that the QoS subsystem does not have. Obtaining this information on this network is currently not supported. For example, bandwidth estimations cannot be obtained on a network path where the destination host is off-link.
There are insufficient resources to carry out the operation.
The request could not be performed because of an I/O device error.
Indicates that the update flow request was successfully initiated.
The indicated device requires reinitialization due to hardware errors. The application should clean up and call QOSCreateHandle again.
A network adapter hardware error occurred.
The network location cannot be reached.
The is no valid data to be returned.
There is currently insufficient data about networking conditions to answer the query. This is typically a transient state where qWAVE has erred on the side of caution as it awaits more data before ascertaining the state of the network.


Minimum supported client Windows Vista [desktop apps only]
Minimum supported server Windows Server 2008 [desktop apps only]
Target Platform Windows
Header qos2.h (include Qos2.h)
Library Qwave.lib
DLL Qwave.dll

See also

Quality Windows Audio/Video Experience (qWAVE)