Win32 API 日本語リファレンス
ホームNetworking.WinSock › FLOWSPEC

FLOWSPEC

構造体
サイズx64: 32 バイト / x86: 32 バイト

サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。

フィールド

フィールドサイズx64x86説明
TokenRateDWORD4+0+0

フローの存続期間中にデータを送信できる、許可された転送レートを指定します。TokenRate メンバーは、フレームリレーなどの WAN テクノロジーで見られる他のトークンバケットモデルと似ており、トークンはクレジット (与信) に相当します。こうしたトークンは、すぐに使用されない場合は蓄積され、一定の周期的な上限 (Windows 2000 のサービス品質の場合は PeakBandwidth) までのデータ送信を可能にします。ただし、クレジットの蓄積は指定された量 (TokenBucketSize) までに制限されます。合計クレジット (トークン) を制限することで、たとえばしばらく非アクティブであったフローが、大量に蓄積したトークンによって利用可能な帯域幅を占有してしまうといった状況を回避できます。フローは時間の経過とともに (TokenRate の値で) 送信クレジットを蓄積できますが、その上限は TokenBucketSize までであり、またバースト送信は PeakBandwidth に制限されるため、トラフィック制御とネットワークデバイスのリソースの健全性が維持されます。フローが一度に大量のデータを送信できないため トラフィック制御 が維持され、またそうしたデバイスが高いトラフィックバーストにさらされずに済むため、ネットワークデバイスのリソースの健全性が維持されます。

このモデルでは、アプリケーションは十分なクレジットが利用可能な場合にのみデータを送信できます。十分なクレジットが利用できない場合、アプリケーションは待機するか、トラフィックを破棄しなければなりません ( QOS_SD_MODE の値に基づきます)。したがって、アプリケーションは送信要件に対する妥当な見積もりに基づいて TokenRate を要求することが重要です。たとえばビデオアプリケーションでは、TokenRate は通常、ピークからピークまでの平均ビットレートに設定されます。

受信側でのみ TokenRateQOS_NOT_SPECIFIED に設定した場合、TokenRate には最大転送単位 (MTU) が使用され、送信レートの制限 (トークンバケットモデル) は有効になりません。このように、TokenRate はバイト/秒で表されます。

TokenRate メンバーに 0 を設定することはできません。また、送信側の FLOWSPEC において既定値 (つまり QOS_NOT_SPECIFIED) として設定することもできません。

TokenBucketSizeDWORD4+4+4フローの特定の方向が時間に関係なく蓄積できるクレジットの最大量をバイト単位で指定します。ビデオアプリケーションでは、TokenBucketSize は通常、最も大きい平均フレームサイズになります。一定レートのアプリケーションでは、TokenBucketSize は小さな変動を許容できる値に設定してください。
PeakBandwidthDWORD4+8+8指定したフローに対する、時間ベースの送信許可の上限をバイト/秒で指定します。PeakBandwidth メンバーは、1 秒あたりのデータ送信の上限を強制することで、多量の送信クレジット (トークン) を蓄積したフローが、一時的または周期的なデータバーストによってネットワークリソースに過大な負荷をかけることを防ぎます。一部の中間システムはこの情報を活用でき、より効率的なリソース割り当てが可能になります。
LatencyDWORD4+12+12送信側がビットを送信してから、対象となる 1 つ以上の受信側がそれを受け取るまでに許容される最大の遅延をマイクロ秒単位で指定します。この値の正確な解釈は、QOS 要求で指定された保証のレベルによって異なります。
DelayVariationDWORD4+16+16パケットが受ける可能性のある遅延の最大値と最小値の差をマイクロ秒単位で指定します。アプリケーションは DelayVariation を使用して、フローの受信側で必要となるバッファー領域の量を決定します。このバッファー領域の情報は、元のデータ送信パターンを復元するために使用できます。
ServiceTypeDWORD4+20+20

フローに対してネゴシエートするサービスのレベルを指定します。ServiceType メンバーには、次に定義されたサービスの種類のいずれかを指定できます。

意味
SERVICETYPE_NOTRAFFIC
指定した方向にトラフィックが送信されないことを示します。全二重に対応したメディアでは、この値は下位のソフトウェアに対して単方向の接続のみを設定するよう指示します。このサービスの種類は TC API では有効ではありません。
SERVICETYPE_BESTEFFORT
RSVP SP では何も処理が行われません。ただし、トラフィック制御は BESTEFFORT フローを作成し、そのフロー上のトラフィックは他の BESTEFFORT トラフィックと同様にトラフィック制御によって処理されます。
SERVICETYPE_CONTROLLEDLOAD
データパス上の関連するネットワークコンポーネントが非負荷状態にあるときに期待される、ベストエフォートサービスの伝送品質にきわめて近いエンドツーエンドの QOS を提供します。

したがって、SERVICETYPE_CONTROLLEDLOAD を使用するアプリケーションは、次のことを前提にできます。

  • ネットワークは、送信されたパケットのきわめて高い割合を対象の受信側に配信します。言い換えると、パケット損失は伝送メディア本来のパケットエラー率にきわめて近くなります。
  • 配信されたパケットのきわめて高い割合について、伝送遅延が、正常に配信されたパケットの最小伝送遅延を大きく上回ることはありません。
SERVICETYPE_GUARANTEED
フローのトラフィックが指定されたトラフィックパラメーターの範囲内に収まっている限り、データグラムが保証された配信時間内に到着し、キューのオーバーフローによって破棄されないことを保証します。このサービスは、データグラムが送信元から送信された後、一定の時間までに必ず到着するという確実な保証を必要とするアプリケーションを対象としています。
SERVICETYPE_QUALITATIVE
アプリケーションが BESTEFFORT よりも良好な伝送を必要としているものの、その伝送要件を定量化できないことを示します。SERVICETYPE_QUALITATIVE を使用するアプリケーションは、アプリケーション識別子ポリシーオブジェクトを提供できます。アプリケーション識別ポリシーオブジェクトにより、ネットワーク上のポリシーサーバーはアプリケーションを識別し、それに応じて要求に適切なサービス品質を割り当てられるようになります。アプリケーション識別の詳細については、IETF インターネットドラフト draft-ietf-rap-rsvp-appid-00.txt、またはアプリケーション識別に関する Microsoft のホワイトペーパーを参照してください。トラフィック制御は、この種類のフローをローカルコンピューター上の BESTEFFORT トラフィックと同じ優先度で扱います。ただし、アプリケーションプログラマーは、 QOS_TRAFFIC_CLASS QOS オブジェクトを使用して対象のフローのレイヤー 2 設定を変更することで、そうしたフローの優先度を引き上げることができます。
SERVICETYPE_NETWORK_UNAVAILBLE
ネットワークの変更を通知するために使用されます。
SERVICETYPE_NETWORK_CONTROL
制御パケット (RSVP シグナリングメッセージなど) の送信にのみ使用されます。この ServiceType は最も高い優先度を持ちます。
SERVICETYPE_GENERAL_INFORMATION
フローに対してすべてのサービスの種類がサポートされることを指定します。送信側でのみ使用できます。
SERVICETYPE_NOCHANGE
この ServiceType の値を使用する伝送において、サービス品質が変更されないことを示します。SERVICETYPE_NOCHANGE は、一方向のみのサービス品質の変更を要求する場合や、SendingFlowspecReceivingFlowspec ではなく QOS 仕様の ProviderSpecific パラメーター内でのみ変更を要求する場合に使用できます。
SERVICETYPE_NONCONFORMING
非準拠のトラフィックを示すために使用されます。
SERVICE_NO_TRAFFIC_CONTROL
指定した方向でトラフィック制御を呼び出さないことを示します。
SERVICE_NO_QOS_SIGNALING
指定した方向で RSVP シグナリングを抑制します。

次の一覧は、ServiceType の設定の相対的な優先度を示しています。

SERVICETYPE_NETWORK_CONTROL

SERVICETYPE_GUARANTEED

SERVICETYPE_CONTROLLED_LOAD

SERVICETYPE_BESTEFFORT

SERVICETYPE_QUALITATIVE

非準拠のトラフィック

簡単な例を挙げると、あるネットワークデバイスがリソースの制約を受けており、上記の ServiceType 設定のいずれかからパケットを 1 つ選んで送信しなければならない場合、まず SERVICETYPE_NETWORKCONTROL のパケットを送信し、その ServiceType で送信を要するパケットがなければ ServiceTypeSERVICETYPE_GUARANTEED のパケットを送信する、というように動作します。

MaxSduSizeDWORD4+24+24トラフィックフローで許可される、または使用されるパケットの最大サイズをバイト単位で指定します。
MinimumPolicedSizeDWORD4+28+28要求されたサービス品質が提供されるパケットの最小サイズをバイト単位で指定します。このサイズより小さいパケットは、トラフィック制御によって MinimumPolicedSize として扱われます。FLOWSPEC 構造体を RSVP と組み合わせて使用する場合、MinimumPolicedSize の値を 0 にすることはできません。ただし、FLOWSPEC 構造体を特に TC API と共に使用する場合は、MinimumPolicedSize に 0 を設定できます。

公式ドキュメント

FLOWSPEC 構造体は、 RSVP SP にサービス品質 (QOS) のパラメーターを提供します。これにより、QOS 対応のアプリケーションは、指定したフローに対して QOS 設定の適用、変更、または削除を行えます。 FLOWSPEC の一部のメンバーには既定値を設定できます。詳細については「解説」を参照してください。

解説(Remarks)

FLOWSPEC 構造体の多くのメンバーは、QOS_NOT_SPECIFIED を設定することで既定値にできます。既定値を設定できるメンバーは、その FLOWSPEC が受信側の FLOWSPEC か、送信側の FLOWSPEC かによって異なる点に注意してください。

トラフィック制御で FLOWSPEC を使用する際には、次のようないくつかの考慮事項があります。

受信側の FLOWSPEC では、ServiceType を除く多くの設定を既定値にできますが、次の点を考慮してください。 次の一覧は、受信側の FLOWSPEC で対応する値を既定値に設定した場合に適用される値を示しています。

ServiceType の値が SERVICETYPE_GUARANTEED に設定されている場合は、次の内容も適用されます。

送信側の FLOWSPEC では、ServiceTypeTokenRate を除くすべてを既定値にできます。次の一覧は、送信側の FLOWSPEC で対応する値を既定値に設定した場合に適用される値を示しています。

トラフィック制御: 次の ServiceType は、特にトラフィック制御を直接扱う場合には無効です。自分がトラフィック制御を直接扱っているかどうか (つまり、次の ServiceType が自分の状況に該当するかどうかを気にする必要があるかどうか) がわからない場合は、おそらく扱っていません。

SERVICE_NO_TRAFFIC_CONTROL
SERVICE_NO_QOS_SIGNALING
SERVICETYPE_GENERAL_INFORMATION
SERVICETYPE_NETWORK_UNAVAILABLE
SERVICETYPE_NOCHANGE
SERVICETYPE_NOTRAFFIC
出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での定義

#include <windows.h>

// FLOWSPEC  (x64 32 / x86 32 バイト)
typedef struct FLOWSPEC {
    DWORD TokenRate;
    DWORD TokenBucketSize;
    DWORD PeakBandwidth;
    DWORD Latency;
    DWORD DelayVariation;
    DWORD ServiceType;
    DWORD MaxSduSize;
    DWORD MinimumPolicedSize;
} FLOWSPEC;
using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
public struct FLOWSPEC
{
    public uint TokenRate;
    public uint TokenBucketSize;
    public uint PeakBandwidth;
    public uint Latency;
    public uint DelayVariation;
    public uint ServiceType;
    public uint MaxSduSize;
    public uint MinimumPolicedSize;
}
Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, CharSet:=CharSet.Unicode)>
Public Structure FLOWSPEC
    Public TokenRate As UInteger
    Public TokenBucketSize As UInteger
    Public PeakBandwidth As UInteger
    Public Latency As UInteger
    Public DelayVariation As UInteger
    Public ServiceType As UInteger
    Public MaxSduSize As UInteger
    Public MinimumPolicedSize As UInteger
End Structure
import ctypes
from ctypes import wintypes

class FLOWSPEC(ctypes.Structure):
    _fields_ = [
        ("TokenRate", wintypes.DWORD),
        ("TokenBucketSize", wintypes.DWORD),
        ("PeakBandwidth", wintypes.DWORD),
        ("Latency", wintypes.DWORD),
        ("DelayVariation", wintypes.DWORD),
        ("ServiceType", wintypes.DWORD),
        ("MaxSduSize", wintypes.DWORD),
        ("MinimumPolicedSize", wintypes.DWORD),
    ]
#[repr(C)]
pub struct FLOWSPEC {
    pub TokenRate: u32,
    pub TokenBucketSize: u32,
    pub PeakBandwidth: u32,
    pub Latency: u32,
    pub DelayVariation: u32,
    pub ServiceType: u32,
    pub MaxSduSize: u32,
    pub MinimumPolicedSize: u32,
}
import "golang.org/x/sys/windows"

type FLOWSPEC struct {
	TokenRate uint32
	TokenBucketSize uint32
	PeakBandwidth uint32
	Latency uint32
	DelayVariation uint32
	ServiceType uint32
	MaxSduSize uint32
	MinimumPolicedSize uint32
}
type
  FLOWSPEC = record
    TokenRate: DWORD;
    TokenBucketSize: DWORD;
    PeakBandwidth: DWORD;
    Latency: DWORD;
    DelayVariation: DWORD;
    ServiceType: DWORD;
    MaxSduSize: DWORD;
    MinimumPolicedSize: DWORD;
  end;
const FLOWSPEC = extern struct {
    TokenRate: u32,
    TokenBucketSize: u32,
    PeakBandwidth: u32,
    Latency: u32,
    DelayVariation: u32,
    ServiceType: u32,
    MaxSduSize: u32,
    MinimumPolicedSize: u32,
};
type
  FLOWSPEC {.bycopy.} = object
    TokenRate: uint32
    TokenBucketSize: uint32
    PeakBandwidth: uint32
    Latency: uint32
    DelayVariation: uint32
    ServiceType: uint32
    MaxSduSize: uint32
    MinimumPolicedSize: uint32
struct FLOWSPEC
{
    uint TokenRate;
    uint TokenBucketSize;
    uint PeakBandwidth;
    uint Latency;
    uint DelayVariation;
    uint ServiceType;
    uint MaxSduSize;
    uint MinimumPolicedSize;
}

HSP用 定義

HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; FLOWSPEC サイズ: 32 バイト(x64)
dim st, 8    ; 4byte整数×8(構造体サイズ 32 / 4 切り上げ)
; TokenRate : DWORD (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; TokenBucketSize : DWORD (+4, 4byte)  st.1 = 値  /  値 = st.1   (lpoke/lpeek も可)
; PeakBandwidth : DWORD (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; Latency : DWORD (+12, 4byte)  st.3 = 値  /  値 = st.3   (lpoke/lpeek も可)
; DelayVariation : DWORD (+16, 4byte)  st.4 = 値  /  値 = st.4   (lpoke/lpeek も可)
; ServiceType : DWORD (+20, 4byte)  st.5 = 値  /  値 = st.5   (lpoke/lpeek も可)
; MaxSduSize : DWORD (+24, 4byte)  st.6 = 値  /  値 = st.6   (lpoke/lpeek も可)
; MinimumPolicedSize : DWORD (+28, 4byte)  st.7 = 値  /  値 = st.7   (lpoke/lpeek も可)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global FLOWSPEC
    #field int TokenRate
    #field int TokenBucketSize
    #field int PeakBandwidth
    #field int Latency
    #field int DelayVariation
    #field int ServiceType
    #field int MaxSduSize
    #field int MinimumPolicedSize
#endstruct

stdim st, FLOWSPEC        ; NSTRUCT 変数を確保
st->TokenRate = 100
mes "TokenRate=" + st->TokenRate