Terminating QOS

In the previous section, you learned how to invoke QOS on a socket. Next we'll examine the termination of QOS guarantees. Each of the following events causes a termination of RSVP and Traffic Control processing for a socket:

• Closing a socket via the closesocket function
• Shutting down a socket via the shutdown function
• Calling WSAConnect with a null peer address
• Calling WSAIoctl and SIO_SET_QOS with the SERVICETYPE_NOTRAFFIC or the SERVICE_TYPE_BESTEFFORT service type

Except for the second item in the list, these events are self-explanatory. Remember that the shutdown function can signal the cessation of either sending or receiving data, which will result in the termination of the flow of data for only that direction. In other words, if shutdown is called with SD_SEND, QOS will still be in effect for data being received.

Provider-Specific Objects

The provider-specific objects covered in this section are passed as part of the ProviderSpecific field of the QOS structure. Either they return QOS information to your application via the FD_QOS event or you can pass them along with the other QOS parameters to a WSAIoctl call with the SIO_SET_QOS option to refine the behavior of QOS.

Every provider-specific object contains a QOS_OBJECT_HDR structure as its first member. This structure identifies the type of the provider-specific object. This is necessary because these provider objects are most commonly returned within the QOS structure after a call to SIO_GET_QOS. Using the QOS_OBJECT_HDR, your application can identify each object and decode its significance. The object header is defined as

 typedef struct { ULONG ObjectType; ULONG ObjectLength; } QOS_OBJECT_HDR, *LPQOS_OBJECT_HDR; 

ObjectType identifies the type of preset provider-specific object, while ObjectLength tells how long the entire object is, including the object header and the provider-specific object. An object type can be one of the flags listed in Table 12-3.

Table 12-3. Object types

Provider Object	Object Structure
QOS_OBJECT_PRIORITY	QOS_PRIORITY
QOS_OBJECT_SD_MODE	QOS_SD_MODE
QOS_OBJECT_TRAFFIC_CLASS	QOS_TRAFFIC_CLASS
QOS_OBJECT_DESTADDR	QOS_DESTADDR
QOS_OBJECT_SHAPER_QUEUE_DROP_MODE	QOS_SHAPER_QUEUE_LIMIT_DROP_MODE
QOS_OBJECT_SHAPER_QUEUE_LIMIT	QOS_SHAPER_QUEUE_LIMIT
RSVP_OBJECT_STATUS_INFO	RSVP_STATUS_INFO
RSVP_OBJECT_RESERVE_INFO	RSVP_RESERVE_INFO
RSVP_OBJECT_ADSPEC	RSVP_ADSPEC
RSVP_OBJECT_POLICY_INFO	RSVP_POLICY_INFO
QOS_OBJECT_END_OF_LIST	None. No more objects.

QOS priority

QOS priority defines the absolute priority of the flow. The priority levels themselves range from 0 to 7, lowest to highest. The QOS_PRIORITY structure is defined as

 typedef struct _QOS_PRIORITY { QOS_OBJECT_HDR ObjectHdr; UCHAR SendPriority UCHAR SendFlags; UCHAR ReceivePriority; UCHAR Unused; } QOS_PRIORITY, *LPQOS_PRIORITY; 

These priority values determine the local priority (internal to the sending host computer) of the corresponding flow's traffic relative to traffic from other flows. The default priority for a flow is 3. This priority is used in combination with the ServiceType parameter of FLOWSPEC to determine the priority that should be applied to the flow internal to the Packet Scheduler. SendFlags and ReceivePriority are not currently used but might be used in the future.

QOS shape discard mode

This QOS object defines how the Packet Shaper element of Traffic Control processes the data of a given flow. This property most often comes into play when dealing with flows that do not conform to the parameters given in FLOWSPEC. That is, if an application is sending data at a rate faster than what is specified in the TokenRate field of the sending FLOWSPEC, it is considered nonconforming. This object defines how the local system handles this occurrence. The QOS_SD_MODE structure is defined as

 typedef struct _QOS_SD_MODE { QOS_OBJECT_HDR ObjectHdr; ULONG ShapeDiscardMode; } QOS_SD_MODE, *LPQOS_SD_MODE; 

The ShapeDiscardMode field can be one of the values specified in Table 12-4.

You might be wondering why you would want to use the TC_NONCONF_DISCARD mode when it might result in the dropping of data before it even gets sent on the wire. One such use is in sending audio or video data. In most cases, the FLOWSPEC structure is set up to reflect the sending of a packet whose size is equal to one frame of video or a small segment of audio. If for some reason the packet does not conform, is it better for an application to wait until it does conform (as is the case with TC_NONCONF_SHAPE), or should the application drop the packet altogether and move on to the next one? For time-critical data such as video, it is often better to drop the frame and move on.

Table 12-4. QOS shape discard mode flags

Flag	Description
TC_NONCONF_BORROW	The flow receives the resources remaining after all higher-priority flows have been serviced. Flows of this type are not subjected to either the Shaper or the Sequencer. If a value for TokenRate is specified, packets can be nonconforming and will be demoted to less than best-effort priority.
TC_NONCONF_SHAPE	A value for TokenRate must be specified. Nonconforming packets will be retained in the Packet Shaper until they become conforming.
TC_NONCONF_DISCARD	A value for TokenRate must be specified. Nonconforming packets will be discarded.

QOS traffic class

The QOS_TRAFFIC_CLASS structure can carry an 802.1p traffic class parameter provided to the host by a Layer 2 network device. The structure is defined as

 typedef struct _QOS_TRAFFIC_CLASS { QOS_OBJECT_HDR ObjectHdr; ULONG TrafficClass; } QOS_TRAFFIC_CLASS, *LPQOS_TRAFFIC_CLASS; 

Hosts stamp the MAC headers of corresponding transmitted packets with the TrafficClass value specified in the structure. Despite the structure's inclusion in Qos.h, applications are not allowed to set their own priority.

QOS destination address

The QOS_DESTADDR structure is used to specify the destination address for a connectionless sending socket without using a WSAConnect call. No RSVP PATH or RESV messages will be sent until the destination address of a connectionless socket is known. The destination address can be set with the SIO_SET_QOS ioctl command. The structure is defined as

 typedef struct _QOS_DESTADDR { QOS_OBJECT_HDR ObjectHdr; const struct sockaddr *SocketAddress; ULONG SocketAddressLength; } QOS_DESTADDR, *LPQOS_DESTADDR; 

The SocketAddress field references the SOCKADDR structure that defines the endpoint's address for the given protocol. SocketAddressLength is simply the size of the SOCKADDR structure.

QOS shaper queue limit drop mode

This structure defines any overriding of the default schema used to drop packets when a flow's shaper queue limit is reached. Remember that the Traffic Shaper module of Traffic Control can be configured to discard any excess data pending if the currently queued data does not conform to the FLOWSPEC structure. The structure is defined as

 typedef struct _QOS_SHAPER_QUEUE_LIMIT_DROP_MODE { QOS_OBJECT_HDR ObjectHdr; ULONG DropMode; } QOS_SHAPER_QUEUE_LIMIT_DROP_MODE, *LPQOS_SHAPER_QUEUE_LIMIT_DROP_MODE; 

The two possible values for DropMode are described in Table 12-5.

Table 12-5. Shaper queue limit drop modes

Flag	Meaning
QOS_SHAPER_DROP_FROM_HEAD	Drop packets from the head of the queue (the default behavior).
QOS_SHAPER_DROP_INCOMING	Drop any incoming packets once the queue limit is reached.

QOS shaper queue limit

The shaper queue limit structure allows the default per-flow limit on the shaper queue size to be overridden. The structure is defined as

 typedef struct _QOS_SHAPER_QUEUE_LIMIT { QOS_OBJECT_HDR ObjectHdr; ULONG QueueSizeLimit; } QOS_SHAPER_QUEUE_LIMIT, *LPQOS_SHAPER_QUEUE_LIMIT; 

QueueSizeLimit is the size of the shaper queue in bytes. Setting a larger shaper queue size can prevent data from being dropped by allowing data to be queued without running out of buffer space.

RSVP status info

The RSVP status info object is used to return RSVP-specific error and status information. The structure is defined as

 typedef struct _RSVP_STATUS_INFO { QOS_OBJECT_HDR     ObjectHdr; ULONG StatusCode; ULONG ExtendedStatus1; ULONG ExtendedStatus2; } RSVP_STATUS_INFO, *LPRSVP_STATUS_INFO; 

The StatusCode field is the RSVP message returned. The possible codes are described in Table 12-6. The other two fields, ExtendedStatus1 and ExtendedStatus2, are reserved for provider-specific information.

Table 12-6. RSVP status info codes

Flag	Meaning
WSA_QOS_RECEIVERS	At least one RESV message has arrived.
WSA_QOS_SENDERS	At least one PATH message has arrived.
WSA_NO_QOS_RECEIVERS	There are no receivers.
WSA_NO_QOS_SENDERS	There are no senders.
WSA_QOS_REQUEST_CONFIRMED	The reserve has been confirmed.
WSA_QOS_ADMISSION_FAILURE	Request failed due to lack of resources.
WSA_QOS_POLICY_FAILURE	Request rejected for administrative reasons or bad credentials.
WSA_QOS_BAD_STYLE	Unknown or conflicting style.
WSA_QOS_BAD_OBJECT	There is a problem with some part of the RSVP_FILTERSPEC structure or the provider-specific buffer in general. (This object will be discussed shortly.)
WSA_QOS_TRAFFIC_CTRL_ERROR	There is a problem with some part of the FLOWSPEC structure.
WSA_QOS_GENERIC_ERROR	General error.
ERROR_IO_PENDING	Overlapped operation is canceled.

Typically, an application receives an FD_QOS event and calls SIO_GET_QOS to obtain a QOS structure containing an RSVP_STATUS_INFO object when an RSVP message is received. For example, for a QOS-enabled UDP-based receiver, an FD_QOS event containing a WSA_QOS_SENDERS message is generated to indicate that someone has requested the QOS service to send data to the receiver.

RSVP reserve info

The RSVP reserve info object is used for storing RSVP-specific information for fine-tuning interactions via the Winsock 2 QOS APIs and the provider-specific buffer. A RSVP_RESERVE_INFO object overrides the default reservation style and is used by a QOS receiver. The object is defined as

 typedef struct _RSVP_RESERVE_INFO { QOS_OBJECT_HDR ObjectHdr; ULONG Style; ULONG ConfirmRequest; ULONG NumPolicyElements; LPRSVP_POLICY PolicyElementList; ULONG NumFlowDesc; LPFLOWDESCRIPTOR FlowDescList; } RSVP_RESERVE_INFO, *LPRSVP_RESERVE_INFO; 

The Style field specifies the filter type that should be applied to this receiver. Table 12-7 lists the filter types available and the default filter types used by different types of receivers. Each filter style will be discussed in greater detail shortly. If the ConfirmRequest field is nonzero, notification will be sent once the RESV request has been received for receiving applications. NumPolicyElements is related to the PolicyElementList field. It contains the number of RSVP_POLICY objects that are contained in the PolicyElementList field. (We define RSVP_POLICY a little bit later in this chapter.) Let's take a look at the different filter styles and the characteristics of each.

RSVP_DEFAULT_STYLE

This flag tells the QOS service provider to use the default style. Table 12-7 lists the default styles for the different possible receivers. Unicast receivers use fixed filter, whereas wildcard is for multicast receivers. UDP receivers that call WSAConnect also use fixed filter.

Table 12-7. Default filter styles

Filter Style	Default Users
Fixed filter	Unicast receivers Connected UDP receivers
Wildcard	Multicast receivers Unconnected UDP receivers
Shared explicit	None

RSVP_FIXED_FILTER_STYLE

Normally this style establishes a single flow with QOS guarantees between the receiver and a single source. This is the case for a unicast receiver and connected UDP receivers: NumFlowDesc is set to 1, and FlowDescList contains the sender's address. However, it is also possible to set up a multiple fixed filter style that allows a receiver to reserve mutually exclusive flows from multiple, explicitly identified sources. For example, if your receiver intends to receive data from three senders and needs guaranteed bandwidth of 20 Kbps for each, use the multiple fixed filter style. In this example, NumFlowDesc would be set to 3, while FlowDescList would contain three addresses, one for each FLOWSPEC. It is also possible to assign varying levels of QOS to each sender; they do not all have to be equal. Note that unicast receivers and connected UDP receivers cannot use multiple fixed filters. Figure 12-1 shows the relationship between FLOWDESCRIPTOR and RSVP_FILTERSPEC structures.

Figure 12-1. Multiple fixed filter style

RSVP_WILDCARD_STYLE

Multicast receivers and unconnected UDP receivers use the wildcard style. To use this style for TCP connections or for connected UDP receivers, set NumFlowDesc to 0 and FlowDescList to NULL. This is the default filter style for unconnected UDP receivers and multicast applications because the sender's address is unknown.

RSVP_SHARED_EXPLICIT_STYLE

This style is somewhat similar to multiple fixed filter style except that network resources, instead of being allocated for each sender, are shared among all senders. In this case, NumFlowDesc is 1 and FlowDescList contains the list of sender addresses. Figure 12-2 illustrates this style.

Figure 12-2. Shared explicit style

We've introduced the last two fields, NumFlowDesc and FlowDescList, in our discussion of RSVP styles. How you use these two fields depends on the style. NumFlowDesc defines the number of FLOWDESCRIPTOR objects in the FlowDescList field. This structure is defined as

 typedef struct _FLOWDESCRIPTOR { FLOWSPEC FlowSpec; ULONG NumFilters; LPRSVP_FILTERSPEC FilterList; } FLOWDESCRIPTOR, *LPFLOWDESCRIPTOR; 

This object is used to define the types of filters per FLOWSPEC given by FlowSpec. Again, the NumFilters field contains the number of RSVP_FILTERSPEC objects present in the FilterList array. The RSVP_FILTERSPEC object is defined as

 typedef struct _RSVP_FILTERSPEC { FilterType Type; union { RSVP_FILTERSPEC_V4 FilterSpecV4; RSVP_FILTERSPEC_V6 FilterSpecV6; RSVP_FILTERSPEC_V6_FLOW FilterSpecV6Flow; RSVP_FILTERSPEC_V4_GPI FilterSpecV4Gpi; RSVP_FILTERSPEC_V6_GPI FilterSpecV6Gpi; }; } RSVP_FILTERSPEC, *LPRSVP_FILTERSPEC; 

The first field, Type, is a simple enumeration of the following values:

 typedef enum { FILTERSPECV4 = 1, FILTERSPECV6, FILTERSPECV6_FLOW, FILTERSPECV4_GPI, FILTERSPECV6_GPI, FILTERSPEC_END } FilterType; 

This enumeration specifies the object present in the union. Each of these filter specs is defined below.

 typedef struct _RSVP_FILTERSPEC_V4 { IN_ADDR_IPV4 Address; USHORT Unused; USHORT Port; } RSVP_FILTERSPEC_V4, *LPRSVP_FILTERSPEC_V4; typedef struct _RSVP_FILTERSPEC_V6 { IN_ADDR_IPV6 Address; USHORT UnUsed; USHORT Port; } RSVP_FILTERSPEC_V6, *LPRSVP_FILTERSPEC_V6; typedef struct _RSVP_FILTERSPEC_V6_FLOW { IN_ADDR_IPV6 Address; UCHAR UnUsed; UCHAR FlowLabel[3]; } RSVP_FILTERSPEC_V6_FLOW, *LPRSVP_FILTERSPEC_V6_FLOW; typedef struct _RSVP_FILTERSPEC_V4_GPI { IN_ADDR_IPV4 Address; ULONG GeneralPortId; } RSVP_FILTERSPEC_V4_GPI, *LPRSVP_FILTERSPEC_V4_GPI; typedef struct _RSVP_FILTERSPEC_V6_GPI { IN_ADDR_IPV6 Address; ULONG GeneralPortId; } RSVP_FILTERSPEC_V6_GPI, *LPRSVP_FILTERSPEC_V6_GPI; 

RSVP Adspec

The RSVP_ADSPEC object defines the information carried in the RSVP Adspec. This RSVP object typically indicates which service types are available (controlled load or guaranteed), whether a non-RSVP hop has been encountered by the PATH message, and the minimum MTU along the path. The structure is defined as

 typedef struct _RSVP_ADSPEC { QOS_OBJECT_HDR ObjectHdr; AD_GENERAL_PARAMS GeneralParams; ULONG NumberOfServices; CONTROL_SERVICE Services[1]; } RSVP_ADSPEC, *LPRSVP_ADSPEC; 

The first field of interest is GeneralParams, which is a structure of type AD_GENERAL_PARAMS. This structure is exactly as it sounds—it defines some general characterization parameters. The definition of this object is

 typedef struct _AD_GENERAL_PARAMS { ULONG IntServAwareHopCount; ULONG PathBandwidthEstimate; ULONG MinimumLatency; ULONG PathMTU; ULONG Flags; } AD_GENERAL_PARAMS, *LPAD_GENERAL_PARAMS; 

The IntServAwareHopCount is the number of hops that conform to Integrated Services (IntServ) requirements. PathBandwidthEstimate is the minimum bandwidth available from sender to receiver. MinimumLatency is the sum of minimum latencies, in microseconds, of the packet forwarding processes in the routers. PathMTU is the maximum transmission unit—end-to-end—that will not incur any fragmentation. The Flags field is not currently used.

RSVP policy info

The last provider object we'll take a look at is the RSVP policy info. This object is rather nebulous—it contains any number of policy elements from RSVP that are not defined. The structure is defined as

 typedef struct _RSVP_POLICY_INFO { QOS_OBJECT_HDR ObjectHdr; ULONG NumPolicyElement; RSVP_POLICY PolicyElement[1]; } RSVP_POLICY_INFO, *LPRSVP_POLICY_INFO; 

The NumPolicyElement field gives the number of RSVP_POLICY structures present in the PolicyElement array. This structure is defined as

 typedef struct _RSVP_POLICY { USHORT Len; USHORT Type; UCHAR Info[4]; } RSVP_POLICY, *LPRSVP_POLICY; 

The RSVP_POLICY structure is data transported by RSVP on behalf of the policy component and is not particularly relevant to our needs.