QOSSetFlow 函数 (qos2.h)

项目
08/25/2023

QOSSetFlow 函数由应用程序调用，以请求 QOS 子系统确定应用程序的数据包的优先级并更改流流量。此函数还用于通知 QoS 子系统流发生更改：例如，如果流速率已更改以解释网络拥塞，或者 QoS 优先级值需要调整以通过单个永久性套接字连接传输或流式传输不同类型的内容。

语法

ExternC BOOL QOSSetFlow(
  [in]            HANDLE       QOSHandle,
  [in]            QOS_FLOWID   FlowId,
  [in]            QOS_SET_FLOW Operation,
  [in]            ULONG        Size,
  [in]            PVOID        Buffer,
                  DWORD        Flags,
  [out, optional] LPOVERLAPPED Overlapped
);

parameters

[in] QOSHandle

QOSCreateHandle 返回的 QOS 子系统的句柄。

[in] FlowId

流标识符。 QOS_FLOWID是无符号 32 位整数。

[in] Operation

一个QOS_SET_FLOW枚举类型，用于标识将在流中更改的内容。此参数指定 Buffer 将包含的结构。

值	含义
QOSSetTrafficType 0	流的流量类型将更改。缓冲区将包含指向QOS_TRAFFIC_TYPE常量的指针。
QOSSetOutgoingRate 1	流速将更改。缓冲区将包含指向QOS_FLOWRATE_OUTGOING结构的指针。
QOSSetOutgoingDSCPValue 2	Windows 7、Windows Server 2008 R2 及更高版本：传出 DSCP 值将更改。缓冲区将包含指向定义任意 DSCP 值的 DWORD 值的指针。注意此设置要求调用应用程序是管理员或网络配置操作员组的成员。

[in] Size

Buffer 参数的大小（以字节为单位）。

[in] Buffer

指向 由 Operation 参数的值指定的结构的指针。

Flags

保留供将来使用。此参数必须设置为 0。

[out, optional] Overlapped

指向用于异步输出的 OVERLAPPED 结构的指针。如果未异步调用此函数，则必须将其设置为 NULL 。

返回值

如果该函数成功，则返回值为非零值。

如果函数失败，返回值为 0。要获得更多的错误信息，请调用 GetLastError。一些可能的错误代码随之而来。

返回代码	说明
ERROR_ACCESS_DISABLED_BY_POLICY	QoS 子系统当前由策略配置为不允许在此主机和目标主机之间的网络路径上执行此操作。例如，默认策略阻止 qWAVE 试验运行到链接外目标。
ERROR_IO_PENDING	已成功收到更新流请求。在重叠完成期间将返回结果。
ERROR_ACCESS_DENIED	调用应用程序对请求的操作没有足够的权限。
ERROR_INVALID_HANDLE	QOSHandle 参数无效。
ERROR_INVALID_PARAMETER	FlowId 参数无效。
ERROR_NETWORK_BUSY	请求的流属性在此路径上不可用。
ERROR_NOT_FOUND	找不到指定的 FlowId 参数。
ERROR_NOT_ENOUGH_MEMORY	内存分配失败。
ERROR_NOT_SUPPORTED	要执行的操作需要 QoS 子系统没有的信息。目前不支持在此网络上获取此信息。例如，无法在目标主机处于非链接的网络路径上获取带宽估算。
ERROR_NO_SYSTEM_RESOURCES	资源不足，无法执行该操作。
ERROR_IO_DEVICE	由于出现 I/O 设备错误，因此无法执行该请求。
ERROR_DEVICE_REINITIALIZATION_NEEDED	由于硬件错误，指示的设备需要重新初始化。应用程序应清理并再次调用 QOSCreateHandle 。
ERROR_ADAP_HDW_ERR	网络适配器硬件出错。
ERROR_HOST_UNREACHABLE	无法访问网络位置。
ERROR_RETRY	目前有关网络状况的数据不足，无法回答查询。这通常是一种暂时性状态，qWAVE 在确定网络状态之前会等待更多数据，因此存在谨慎态度。
ERROR_UNEXP_NET_ERR	与远程主机的网络连接失败。

注解

如果尚未调用 QOSStartTrackingClient ，则调用 QOSSetFlow 将导致 QOS 子系统执行以下操作。

了解端到端网络路径是否支持优先顺序。
通过网络试验跟踪端到端网络特征。这些实验不会对网络施加任何值得注意的压力。

如果 QOSSetFlow 返回 ERROR_NETWORK_BUSY 则指定的流速没有足够的带宽，并且无法授予网络优先级。应用程序仍然可以传输数据流，但流不会收到优先级标记。理想情况下，如果带宽不足，应用程序不会尝试以请求的速率进行流式传输。如果返回 ERROR_NETWORK_BUSY ，可以使用以下安全策略：

使用 QOSNotifyFlow 查询 QoS 子系统，以确定当前的可用带宽，并在网络支持的情况下以接收的较低速率开始流式传输。如果网络支持，则优先级较低。
使用 QOSNotifyFlow 请求通知，当最初所需的带宽量可用时。收到通知时，使用新的带宽请求调用 QOSSetFlow ，并在支持的情况下再次以新的速率发送优先级。

可以选择异步调用此函数。

示例

以下代码片段演示如何在应用程序中使用 QOSSetFlow。输入参数 QOSHandle、 FlowId、 FlowId、 QOSSetOutgoingRate 和 size of (QoSOutgoingFlowrate) 之前必须由应用程序中的其他 QoS 函数和计算进行初始化。

显示参数初始化的其他 QoS 函数示例包括 QOSCreateHandle、 QOSAddSocketToFlow 和 QOSQueryFlow。

有关完整的示例代码列表，请参阅 Windows SDK。 SDK 文件夹：Samples\NetDs\GQos\Qos2

if( QOSSetFlow( QOSHandle,
        FlowId,
        QOSSetOutgoingRate,           // Operation 
        sizeof(QoSOutgoingFlowrate),  // Size
        &QoSOutgoingFlowrate,         // Buffer
        0,                            // Flags (Must be set to 0 with QoS Version 1.0)
        NULL)                         // Overlapped
        == 0 )
{
    if( ERROR_INVALID_PARAMETER == GetLastError())
    {
        std::cerr << __FILE__ <<" Line: " << __LINE__ ;
        std::cerr << " - QOSSetFlow failed. Exception code: "; 
        std::cerr << GetLastError() << " - Invalid parameter"; 
        std::cerr << std::endl;
    }
    else
    {
        std::cerr << __FILE__ <<" Line: " << __LINE__ ;
        std::cerr << " - QOSSetFlow failed. Exception code: "; 
        std::cerr << GetLastError() << std::endl;
    }
    
}
else
{
    std::cout << "QOSSetFlow set outgoing flowrate bandwidth to "; 
    std::cout << QoSOutgoingFlowrate.Bandwidth;
    std::cerr << std::endl;
}

要求


最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	qos2.h (包括 Qos2.h)
Library	Qwave.lib
DLL	Qwave.dll

请参阅

质量 Windows 音频/视频体验 (qWAVE)

通过

QOSSetFlow 函数 (qos2.h)

语法

parameters

返回值

注解

示例

要求

请参阅

反馈

其他资源