FLOWSPEC

[This is preliminary documentation and subject to change.]

The FLOWSPEC structure provides quality of service parameters to the GQOS SP. This allows GQOS-aware applications to invoke, modify, or remove quality of service settings for a given flow.

typedef struct _flowspec {
    uint32        TokenRate;            /* In Bytes/sec            */
    uint32        TokenBucketSize;      /* In Bytes                */
    uint32        PeakBandwidth;        /* In Bytes/sec            */
    uint32        Latency;              /* In microseconds         */
    uint32        DelayVariation;       /* In microseconds         */
    SERVICETYPE   ServiceType;          /* Guaranteed, Predictive, */
                                        /*   Best Effort, etc.     */
   uint32         MaxSduSize            /* In Bytes                */
   uint32         MinimumPolicedSize    /* In Bytes                */
} FLOWSPEC, *PFLOWSPEC,  FAR * LPFLOWSPEC;

Members

TokenRate

Specifies the permitted rate at which data can be transmitted over the life of the flow. TokenRate is similar to other token bucket models seen in such WAN technologies as Frame Relay, in which the token is analogous to a credit. If such tokens are not used immediately, they accrue to allow data transmission up to a certain periodic limit (PeakBandwidth, in the case of GQOS). Accrual of credits is limited, however, to a specified amount (TokenBucketSize). Limiting total credits (tokens) avoids situations where, for example, flows that are inactive for some time flood the available bandwidth with their large amount of accrued tokens. Because flows may accrue transmission credits over time (at their TokenRate value) only up to the maximum of their TokenBucketSize, and because they are limited in "burst transmissions" to their PeakBandwidth, traffic control and network-device resource integrity are maintained. Traffic control is maintained because flows cannot send too much data at once, and network-device resource integrity is maintained because such devices are spared from high traffic bursts.

With this model, applications can transmit data only when sufficient credits are available. If sufficient credit amounts are not available, the application must either wait or discard the traffic (based on the value of QOS_OBJECT_SD_MODE). Therefore it is important that applications base their TokenRate requests on reasonable expectations for transmission requirements. For example, in video applications the TokenRate is typically set to the average bit rate peak to peak.

If the TokenRate member is set to -1, limits on the transmission rate (the token bucket model) will not be put into effect. TokenRate is expressed in bytes per second.

TokenBucketSize

The maximum amount of credits a given direction of a flow can accrue, regardless of time. In video applications, TokenBucketSize will likely be the largest average frame size. In constant rate applications, TokenBucketSize should be set to allow for small variations. TokenBucketSize is expressed in bytes.

PeakBandwidth

The upper limit on time-based transmission permission for a given flow, sometimes considered a burst limit. PeakBandwidth restricts flows that may have accrued a significant amount of transmission credits, or tokens from overburdening network resources with one-time or cyclical data bursts, by enforcing a per-second data transmission ceiling. Some intermediate systems can take advantage of this information, resulting in more efficient resource allocation. PeakBandwidth is expressed in bytes per second.

Latency

Maximum acceptable delay between transmission of a bit by the sender and its receipt by one or more intended receivers. The precise interpretation of this number depends on the level of guarantee specified in the QOS request. Latency is expressed in microseconds.

DelayVariation

Difference between the maximum and minimum possible delay a packet will experience. Applications use DelayVariation to determine the amount of buffer space needed at the receiving end of the flow, in order to restore the original data transmission pattern. DelayVariation is expressed in microseconds.

ServiceType

Specifies the level of service to negotiate for the flow. This member can be one of the following defined service types.

Value	Meaning
SERVICETYPE_NOTRAFFIC	Indicates that no traffic will be transmitted in the specified direction. On duplex capable media, this value signals underlying software to set up unidirectional connections only.
SERVICETYPE_BESTEFFORT	Specifies that GQOS should use FLOWSPEC as a service quality guideline, and makes reasonable efforts to maintain the level of service requested, without making any guarantees on packet delivery.
SERVICETYPE_CONTROLLEDLOAD	Provides an end-to-end quality of service that closely approximates transmission quality provided to by best-effort service, as expected under unloaded conditions from the associated network components along the data path. Applications that use SERVICETYPE_CONTROLLEDLOAD may therefore assume the following: The network will deliver a very high percentage of transmitted packets to their intended receivers; in other words, packet loss will closely approximate the basic packet error rate of the transmission medium. Transmission delay for a very high percentage of the delivered packets will not greatly exceed the minimum transit delay experienced by any successfully delivered packet.
SERVICETYPE_GUARANTEED	Initiates a queuing algorithm within the service provider (such as GQOS on any Windows NT client) that isolates a given flow from the effects of other flows (as much as possible). This isolation guarantees the ability to transmit data at TokenRate for the duration of the connection; however, if the corresponding end-node transmits data faster than TokenRate, the network may delay or discard the excess traffic. If TokenRate is not exceeded over time, Latency is also guaranteed. SERVICETYPE_GUARANTEED is designed for applications that may require a deterministic quality of service but would not benefit from better service (such as real-time control systems).

Other defined ServiceType values provide information that can be useful for determining the result of errors or getting information about network service availability. Note that nodes throughout the network use and pass information through what becomes the FLOWSPEC, allowing for such communication to occur between network devices such as routers or WAN adapters, and end nodes, either due to timeouts or due to intentional use of PATH and RESV messages. Such ServiceType values include the following:

Value	Meaning
SERVICETYPE_NETWORK UNAVAILABLE	Used by a service provider to indicate a loss of service in the sending or receiving direction.
SERVICETYPE_GENERAL_INFORMATION	Specifies that all service types are supported for a flow.
SERVICETYPE_NOCHANGE	Indicates that the quality of service in the transmission using this ServiceType value is not changed. SERVICETYPE_NOCHANGE can be used when requesting a change in the quality of service for one direction only, or when requesting a change only within the ProviderSpecific parameters of a QOS specification, and not in the SendingFlowspec or ReceivingFlowspec.
SERVICETYPE_IMMEDIATE_TRAFFIC_CONTROL	Can be combined, using bit-wise OR, with one of the other defined ServiceType values to request the service provider to activate traffic control concurrently with provision of the FLOWSPEC, as opposed to sending with best-effort until RESV messages are received.

MaxSduSize

Specifies the maximum packet size permitted or used in the traffic flow. MaxSduSize is expressed in bytes.

MinimumPolicedSize

Specifies the minimum packet size for which the requested quality of service will be provided. MinimumPolicedSize is expressed in bytes.

QuickInfo

  Windows NT: Requires version 5.0 or later.
  Windows: Requires Windows 98.
  Windows CE: Unsupported.
  Header: Declared in rsvp.h.