Previous section.

Resource ReSerVation Protocol API (RAPI)
Copyright © 1998 The Open Group

Overview

Positioning

An Internet application uses some API (Application Programming Interface) in order to request enhanced quality-of-service (QoS). The local implementation then uses the RSVP protocol to propagate the QoS request through the routers along the path(s) for the data flow. Each router may accept or deny the request, depending upon its available resources. In the case of failure, the local implementation will return the decision to the requesting application via the API.

This specification describes a particular RSVP API known as RAPI. Applications use RSVP to obtain consistent QoS for end systems in packet-switched internetworking.

Reservation Model

RSVP is a receiver-oriented signalling protocol that enables applications to request quality of service on an IP network. The types of quality of service applications may request are defined by Integrated Services. RSVP signalling applies to simplex unicast or multicast data flows. Although RSVP distinguishes senders from receivers, the same application may act in both roles.

RSVP assigns QoS to specific IP data flows which can be either multipoint-to-multipoint or point-to-point and are known as sessions. A session is defined by a particular transport protocol, IP destination address, and destination port. In order to receive data packets for a particular multicast session, a host must have joined the corresponding IP multicast group.

A data source, or sender, is defined by an IP source address and a source port or, alternatively, by an IPv6 source address and flowlabel. A given session may have multiple senders S1, S2, ... Sn, and if the destination is a multicast address, multiple receivers R1, R2, ... Rm.

Under RSVP, QoS requests are made by the data receivers. A QoS request contains a flowspec, together with a filter spec. The flowspec includes an Rspec, which defines the desired QoS and is used to control the packet scheduling mechanism in the router or host, and also a Tspec, which defines the traffic expected by the receiver. The filter spec controls packet classification to determine which senders' data packets receive the corresponding QoS.

The detailed manner in which reservations from different receivers are shared in the Internet is controlled by a reservation parameter known as the reservation style. The RSVP Functional Specification (see referenced document RFC 2205) contains a definition and explanation of the different reservation styles.

API Outline

Using the RAPI interface, an application uses the rapi_session() call to define an API session for sending a single simplex data flow and/or receiving such a data flow. The rapi_sender() call may then be used to register as a data sender, and/or the rapi_reserve() call may be used to make a QoS reservation as a data receiver.

The rapi_sender() or rapi_reserve() calls may be repeated with different parameters to dynamically modify the state at any time or they can be issued in null forms that retract the corresponding registration. The application can call rapi_release() to close the session and delete all of its resource reservations. The relationship among the RAPI calls is summarized by the RAPI state diagram shown in RAPI State Diagram . The calls rapi_sender() and rapi_reserve() represent null calls in that diagram.

Note that a single API session, defined by a single rapi_session() call, can define only one sender at a time. More than one API session may be established for the same RSVP session. For example, suppose an application sends multiple UDP data flows, distinguished by source port. It will call rapi_session() and rapi_sender() separately for each of these flows.

The rapi_session() call allows the application to specify an upcall (or callback) routine that will be invoked to signal RSVP state changes and error events. There are five types of event:

Each RAPI implementation must provide and document a mechanism to receive the incoming asynchronous events and call the application upcall function. Those systems which provide either the select() or poll() functions must provide the mechanism described in Use with select() or poll() .

Figure: RAPI State Diagram

A synchronous error in a RAPI routine returns an appropriate error code. Asynchronous RSVP errors are delivered to the application via the RAPI upcall routine.

Error handling is described in Error Handling .

Contents Next section Index