rsvpapi.txt

radius协议源码÷The Radius Stack will connect to a Radius Server. This stack implementation is built upo

Internet Draft                                                 R. Braden
Expiration:  February 1999                                           ISI
File: draft-ietf-rsvp-rapi-01.ps                              D. Hoffman
                                                        Sun Microsystems



           RAPI -- An RSVP Application Programming Interface

                               Version 5



                            August 11, 1998

Status of Memo

   This document is an Internet-Draft.  Internet-Drafts are working
   documents of the Internet Engineering Task Force (IETF), its areas,
   and its working groups.  Note that other groups may also distribute
   working documents as Internet-Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   To learn the current status of any Internet-Draft, please check the
   "1id-abstracts.txt" listing contained in the Internet- Drafts Shadow
   Directories on ds.internic.net (US East Coast), nic.nordu.net
   (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific
   Rim).

Abstract

   This memo describes version 5 of RAPI, a specific API (application
   programming interface) for RSVP.  The RAPI interface is one
   realization of the generic API contained in the RSVP Functional
   Specification document, and it is being published for information
   only.  The RAPI interface is based upon a client library, whose calls
   are described here.

1. Introduction

   An Internet application uses some "API" ( Application Programming
   Interface) in order to request enhanced quality-of-service (QoS).  A
   local RSVP control program will then use the RSVP protocol to
   propagate the QoS request through the routers along path(s) for the



Braden, Hoffman        Expiration:  February 1999               [Page 1]




Internet Draft                  RAPI v.5                     August 1998


   data flow.  Each router may accept or deny the request, depending
   upon its available resources.  In the case of failure, the local RSVP
   control program will return the decision to the requesting
   application via the API.

   This document describes a particular RSVP API implementation known as
   "RAPI".  RAPI is based on a client library linked with the
   application.  This document describes the calls to that library.
   There is at least one other documented API for RSVP, based on
   sockets.

   The following diagram shows RAPI's implementation model.  RSVP is
   implemented on a host by a user-level daemon program.  The procedures
   of the RSVP client library module interact with the local RSVP daemon
   program through a Unix-domain socket.  RAPI refers to the interface
   between the application and the RSVP client library.


                            H O S T           .      R O U T E R
                (RAPI)                        .
                  v                           .
     _____________v                           .
    |             |_______                    .
    |             x RSVP  |                   .
    |             x Client|                   .
    | Application x Lib   |   ____________    .      _____________
    |             x  rtns |  |            |   .     |             |
    |             x_______|  |    RSVP    |   .     |    RSVP     |
    |             |   |      |   Daemon   |   .     |   Daemon    |
    |_____________|   |      |____________|   .     |_____________|
               |      |        |   .    |     .       |    |    |
      USER     |      |        |   .    |     .       |    |    |
    ===========|======|========|===V====|=====.       |    |    |
      KERNEL   |      |_<____>_|   .    |___<_____>___|    |    |__>
               |       UNIX Pipe   .      RSVP messages    |    RSVP
               |                   .          .            |
               |              _____V______    .       _____V______
               |             |            |   .      |            |
               |             | Packet     |   .      |  Packet    |
               += DATA====>  | Classifier | =DATA==> | Classifier | ==>
                             |& Scheduler |   .      |& Scheduler |
                             |  (if any)  |   .      |            |
                             |____________|   .      |____________|








Braden, Hoffman        Expiration:  February 1999               [Page 2]




Internet Draft                  RAPI v.5                     August 1998


   1.1 Reservation Model

      RSVP performs the signaling necessary to make a resource
      reservation for a simplex data flow sent to a unicast or multicast
      destination address.  Although RSVP distinguishes senders from
      receivers, the same application may act in both roles.

      RSVP assigns QoS to an specific multipoint-to-multipoint data flow
      known as a "session".  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 using the setsockopt call IP_ADD_MEMBERSHIP.

      A data source, or "sender", is defined by an IP source address and
      a source port.  A given session may have multiple senders S1, S2,
      ... Sn, and if the destination is a multicast address, multiple
      "receivers" R1, R2, ... Rm.  In the current version of RSVP, the
      ports used by RSVP for defining sessions and senders are
      restricted to be TCP/UDP port numbers.

      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 sender(s)' 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 contains a definition and explanation of the
      different reservation styles.


   1.2 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 and/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



Braden, Hoffman        Expiration:  February 1999               [Page 3]




Internet Draft                  RAPI v.5                     August 1998


      rapi_release() to close the session and delete all of its resource
      reservations.  The relationship among the RAPI library calls is
      summarized by the RAPI state diagram shown below.  Rapi_sender(0)
      and rapi_reserve(0) 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 change and error events.  There are five types of
      upcalls.

      o    PATH_EVENT and RESV_EVENT upcalls signal the arrival or
           change of path state and reservation state, respectively, and
           deliver the relevant state information to the application.

      o    PATH_ERROR and RESV_ERROR upcalls signal the corresponding
           errors.

      o    PATH_CONFIRM upcalls signal the arrival of a CONFIRM message.

      The upcall routine is invoked indirectly (and synchronously) by
      the application, using the following mechanism.

      o    The application issues the RAPI library call rapi_getfd() to
           learn the file descriptor of the Unix socket used by the API.

      o    The application detects read events on this file descriptor,
           either passing it directly in a select call or passing it to
           the notifier of another library (such as XLib, tk/tcl, RPC,
           etc.).

      o    When a read event on the file descriptor is signaled, the
           application calls rapi_dispatch().  This drives the API to
           execute the upcall routine if appropriate.











Braden, Hoffman        Expiration:  February 1999               [Page 4]




Internet Draft                  RAPI v.5                     August 1998


                              RAPI State Diagram

                                  +---------+
                                  | Closed  |<-----+
                                  +---------+      |
                                       |           |
                                 rapi_session      |
                                       |           |
                              +----+   |      rapi_release
                   PATH_EVENT |    V   V           |
                              |   +---------+      |
                              +---|         |------+
                                  | Session |
                       +----------|         |----------+
                 rapi_sender      +---------+    rapi_reserve
                       |           ^       ^           |
      rapi_sender or   |           |       |           |   rapi_reserve or
      PATH_EVENT or    | rapi_sender(0)    |           |   PATH_EVENT or
      RESV_EVENT or    |           |       |           |   CONFIRM_EVENT
      PATH_ERROR       |           |       |           |   or RESV_ERROR
              +----+   |           |  rapi_reserve(0)  |   +----+
              |    V   V           |       |           V   V    |
              |   +---------+      |       |      +---------+   |
              +---|         |------+       +------|         |---+
                  |  Send   |                     |   Rcv   |
          +-------|         |<-----+       +----->|         |-------+
          |       +---------+      |       |      +---------+       |
          |            |           |       |           |            |
          |            | rapi_reserve(0)   |           |            |
          |            |           |       |           |            |
          |            |           |  rapi_sender(0)   |            |
          |            |           |       |           |            |
          |     rapi_reserve       |       |      rapi_sender       |
          |            |          +---------+          |            |
          |            +--------->|         |<---------+            |
          |                       | SendRcv |                       |
          |    rapi_sender or +---|         |                       |
          |   rapi_reserve or |   +---------+                       |
          |     PATH_EVENT or |    ^   |                            |
          |     RESV_EVENT or +----+   |                            |
          |     CONFIRM_EVENT          |                            |
          |     or PATH_ERROR          |                            |
          |     or RESV_ERROR          |                            |
          |                      rapi_release              rapi_release
        rapi_release                   V                            |
          |                        +--------+                       |
          +----------------------->| Closed |<----------------------+
                                   +--------+



Braden, Hoffman        Expiration:  February 1999               [Page 5]




Internet Draft                  RAPI v.5                     August 1998


      A synchronous error in a RAPI library routine returns an
      appropriate error code.  Asynchronous RSVP errors are delivered to
      the application via the RAPI upcall routine.  Text messages for
      synchronous and asynchronous error codes will be found in the file
      "rapi_err.h".

      The first rapi_session() call in a particular instance of the RAPI
      library opens a Unix-domain RAPI socket to the RSVP daemon and
      passes the session registration request across it.  If the
      application (or the daemon) crashes without properly closing the
      RAPI socket, the other side will be notified to perform a cleanup.
      In particular, if the user process terminates without explicitly
      closing the RAPI session, the daemon will delete the corresponding
      reservation state from the routers.





































Braden, Hoffman        Expiration:  February 1999               [Page 6]




Internet Draft                  RAPI v.5                     August 1998


2. CLIENT LIBRARY SERVICES

   The RSVP API provides the client library calls defined in this
   section.  To use these calls, the application should include the file
   "rapi_lib.h" and "rsvp_intserv.h".

   A.   Create a Session

        The rapi_session call creates an API session.  If it succeeds,