QOSNotifyFlow function (qos2.h)
The QOSNotifyFlow function registers the calling application to receive a notification about changes in network characteristics, such as congestion. Notifications may also be sent when a desired throughput is able to be achieved.
Syntax
ExternC BOOL QOSNotifyFlow(
[in] HANDLE QOSHandle,
[in] QOS_FLOWID FlowId,
[in] QOS_NOTIFY_FLOW Operation,
[in, out, optional] PULONG Size,
[in, out] PVOID Buffer,
DWORD Flags,
[out, optional] LPOVERLAPPED Overlapped
);
Parameters
[in] QOSHandle
Handle to the QOS subsystem returned by QOSCreateHandle.
[in] FlowId
Specifies the flow identifier from which the application wishes to receive notifications. A QOS_FLOWID is an unsigned 32-bit integer.
[in] Operation
A QOS_NOTIFY_FLOW value that indicates what the type of notification being requested.
[in, out, optional] 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.
[in, out] Buffer
Pointer to a UINT64 that indicates the bandwidth at which point a notification will be sent. This parameter is only used if the Operation parameter is set to QOSNotifyAvailable. For the QOSNotifyCongested and QOSNotifyUncongested options, this parameter must be set to NULL on input.
Flags
Reserved for future use. This parameter must be set to 0.
[out, optional] Overlapped
Pointer to an OVERLAPPED structure used for asynchronous output. This must be se to NULL if this function is not being called asynchronously.
Return value
If the function succeeds, a return value of nonzero is sent when the conditions set by the Operation parameter are met.
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. |
|
Indicates that notification request was successfully received. Results will be returned during overlapped completion. |
|
The QOSHandle parameter is invalid. |
|
The FlowId parameter is invalid. |
|
Indicates that a memory allocation failed. |
|
Invalid FlowId specified. |
|
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. |
|
The indicated device requires reinitialization due to hardware errors. The application should clean up and call QOSCreateHandle again. |
|
The QOS subsystem has determined that the operation requested could not be completed on the network path specified. |
|
A network adapter hardware error occurred. |
|
The network location cannot be reached. |
|
The network connection with the remote host failed. |
|
There is already a request for notifications of the same type pending on this flow. |
Remarks
This function may be called asynchronously.
Requirements
Requirement | Value |
---|---|
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 |