Internet Draft






Internet Draft                                                 R. Braden
Expiration: December 1997                                            ISI
File: draft-ietf-rsvp-rapi-00.txt                             D. Hoffman
                                                        Sun Microsystems



           RAPI -- An RSVP Application Programming Interface

                               Version 5



                             June 16, 1997

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: December 1997                [Page 1]




Internet Draft                  RAPI v.5                       June 1997


   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: December 1997                [Page 2]




Internet Draft                  RAPI v.5                       June 1997


   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 txt _session()
      call to define an "API session" for sending a single simplex data
      flow and/or receiving such a data flow.  The txt _sender() call
      may then be used to register as a data sender, and/or the
      txt _reserve() call may be used to make a QoS reservation as a
      data receiver.The txt _sender and/or txt _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: December 1997                [Page 3]




Internet Draft                  RAPI v.5                       June 1997


      txt _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 txt _reserve(0) represent null calls in that diagram.

      Note that a single API session, defined by a single txt _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 txt _session and
      txt _sender separately for each of these flows.

      The txt _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 txt _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 txt _dispatch().  This drives the API to
           execute the upcall routine if appropriate.










Braden, Hoffman        Expiration: December 1997                [Page 4]




Internet Draft                  RAPI v.5                       June 1997


                              RAPI State Diagram

                                  +---------+
                                  | Closed  |<-----+
                                  +---------+      |
                                       |           |
                                 txt _session      |
                                       |           |
                              +----+   |      txt _release
                   PATH_EVENT |    V   V           |
                              |   +---------+      |
                              +---|         |------+
                                  | Session |
                       +----------|         |----------+
                 txt _sender      +---------+    txt _reserve
                       |           ^       ^           |
      txt _sender or   |           |       |           |   txt _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: December 1997                [Page 5]




Internet Draft                  RAPI v.5                       June 1997


      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: December 1997                [Page 6]




Internet Draft                  RAPI v.5                       June 1997


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,
        the call returns an opaque but non-zero session handle for use
        in subsequent calls related to this API session.  If the call
        fails synchronously, it returns zero (NULL_SID) and stores a
        RAPI error code into an integer variable pointed to by the
        "errnop" parameter.

        After a successful rapi_session call has been made, the
        application may receive upcalls of type RAPI_PATH_EVENT for the
        API session.

        unsigned int rapi_session(

             struct sockaddr *Dest,      /* Session: (Dst addr, port) */
             int         Protid,         /* Protocol Id               */
             int         flags,          /* flags                     */
             int         (*Event_rtn)(), /* Address of upcall routine */
             void        *Event_arg,     /* App argument to upcall    */
             int         *errnop         /* Place to return error code*/
             )


        The parameters are as follows.

        o    "Dest"

             This required parameter points to a sockaddr structure
             defining the destination IP (V4 or V6) address and a port
             number to which data will be sent.  The "Dest" and "Protid"
             parameters define an RSVP session.  If the "Protid"
             specifies UDP or TCP transport, the port corresponds to the
             appropriate transport port number.

        o    "Protid"

             The IP protocol ID for the session.  If it is omitted
             (i.e., zero), 17 (UDP) is assumed.

        o    "flags"




Braden, Hoffman        Expiration: December 1997                [Page 7]




Internet Draft                  RAPI v.5                       June 1997


             RAPI_GPI_SESSION (0x40) -- If set, this flag requests that
             this API session be defined in the GPI format used by the
             IPSEC extension of RSVP.  If this flag is set, the port
             number included in "Dest" is considered "virtual" (see the
             IPSEC specification for details), and any sender template
             and filter specifications must be in GPI format.

             RAPI_USE_INTSERV (0X10)  -- If set, IntServ formats are
             used in upcalls; otherwise, the Simplified format is used
             (see Section 4 below).

        o    "Event_rtn"

             This parameter is a pointer to an upcall routine that will
             be invoked to notify the application of RSVP errors and
             state change events.  The parameter may be NULL if there is
             no such routine.

        o    "Event_arg"

             This optional parameter points to an argument that will be
             passed in any invocation of the upcall routine.

        o    "errnop"

             The address of an integer into which a RAPI error code will
             be returned.

        An application can have multiple API sessions registered for the
        same or different RSVP sessions at the same time.  There can be
        at most one sender associated with each API session; however, an
        application can announce multiple senders for a given RSVP
        session by announcing each sender in a separate API session.

        Two API sessions for the same RSVP session, if they are
        receiving data, are assumed to have joined the same multicast
        group and will receive the same data packets.  At present, if
        two or more such sessions issue "rapi_reserve" calls, their
        reservation parameters must agree or the results will be
        undefined.   There is no check for such a conflict.
        Furthermore, the code does not disallow multiple API sessions
        for the same sender (defined by the host interface and the local
        UDP port) within the same RSVP session, i.e., for the same data
        flow.  If these API sessions are created by different
        application processes on the local host, the data packets they
        send will be merged but their sender declarations will not be.

   B.   Specify Sender Parameters



Braden, Hoffman        Expiration: December 1997                [Page 8]




Internet Draft                  RAPI v.5                       June 1997


        An application must issue a rapi_sender call if it intends to
        send a flow of data for which receivers may make reservations.
        This call defines, redefines, or deletes the parameters of that
        flow.  A rapi_sender call may be issued more than once for the
        same API session; the most recent one takes precedence.

        If there is a synchronous error, rapi_sender() returns a RAPI
        error code; otherwise, it returns zero.  Once a successful
        rapi_sender call has been made, the application may receive
        upcalls of type RAPI_RESV_EVENT or RAPI_PATH_ERROR.

        int rapi_sender(
               int              Sid,            /* Session ID         */
               int              flags,          /* Flags              */
               struct sockaddr *LHost,          /* Local Host         */
               rapi_filter_t   *SenderTemplate, /* Sender template    */
               rapi_tspec_t    *SenderTspec,    /* Sender Tspec       */
               rapi_adspec_t   *SenderAdspec,   /* Sender Adspec      */
               rapi_policy_t   *SenderPolicy,   /* Sender policy data */
               int              TTL;            /* Multicast data TTL */
             )


        The parameters are as follows.

        o    "Sid"

             This required parameter must be a session ID returned by a
             successful rapi_session call.

        o    "flags"

             No flags are currently defined for this call.

        o    "LHost"

             This optional parameter may point to a sockaddr structure
             specifying the IP source address and the UDP source port
             from which data will be sent, or it may be NULL.

             If the IP source address is INADDR_ANY, the API will use
             the default IP (V4 or V6) address of the local host.  This
             is sufficient unless the host is multihomed.  The port
             number may be zero if the protocol for the session does not
             have ports.

             A NULL "LHost" parameter indicates that the application
             wishes to withdraw its registration as a sender.  In this



Braden, Hoffman        Expiration: December 1997                [Page 9]




Internet Draft                  RAPI v.5                       June 1997


             case, the following parameters will all be ignored.

        o    "SenderTemplate"

             This optional parameter may be a pointer to a RAPI filter
             spec structure (see Section 4) specifying the format of
             data packets to be sent, or it may be NULL.

             If this parameter is omitted (NULL), a sender template will
             be created internally from the "Dest" and "LHost"
             parameters.  If a "SenderTemplate" parameter is present,
             the "LHost" parameter will be ignored.

             This parameter is required in order to declare the sender
             template for a session using IPSEC, i.e., a session created
             with the RAP_GPI_SESSION flag set.

        o    "SenderTspec"

             This required parameter is a pointer to a Tspec that
             defines the traffic that this sender will create.

        o    "SenderAdspec"

             This optional parameter may point to a  RAPI Adspec
             structure (see Section 4), or it may be NULL.

        o    "SenderPolicy"

             This optional parameter may be a pointer to a sender policy
             data structure, or it may be NULL.

        o    "TTL"

             This parameter specifies the IP TTL (Time-to-Live) value
             with which multicast data will be sent.  It allows RSVP to
             send its control messages with the same TTL scope as the
             data packets.













Braden, Hoffman        Expiration: December 1997               [Page 10]




Internet Draft                  RAPI v.5                       June 1997


   C.   Make, Modify, or Delete a Reservation

        The rapi_reserve procedure is called to make, modify, or delete
        a resource reservation for a session.  The call may be repeated
        with different parameters, allowing the application to modify or
        remove the reservation; the latest call will take precedence.
        Depending upon the parameters, each call may or may not result
        in new Admission Control calls, which could fail asynchronously.

        If there is a synchronous error in this call, rapi_reserve()
        returns a RAPI error code; otherwise, it returns zero.  Once
        this call has been successful, the application may receive an
        upcall of type RAPI_RESV_ERROR or RAPI_RESV_CONFIRM.

        An admission control failure (e.g., refusal of the QoS request)
        will be reported asynchronously by an upcall of type
        RAPI_RESV_ERROR.  A " No Path State" error code indicates that
        RSVP state from one or more of the senders specified in
        "filter_list" has not (yet) propagated all the way to the
        receiver; it may also indicate that one or more of the specified
        senders has closed its API and that its RSVP state has been
        deleted from the routers.

        int rapi_reserve(

               int              Sid,           /* Session ID       */
               int              flags,
               struct sockaddr *RHost,         /* Receive host addr*/
               int              StyleId,       /* Style ID         */
               rapi_stylex_t   *Style_Ext,     /* Style extension  */
               rapi_policy_t   *Rcvr_Policy,   /* Receiver policy  */

               int              FilterSpecNo,    /* # of filter specs */
               rapi_filter_t   *FilterSpec_list, /* List of filt specs*/
               int              FlowspecNo,      /* # of flowspecs   */
               rapi_flowspec_t *Flowspec_list    /* List of flowspecs*/
               )


        The parameters are as follows:

        o    "Sid"

             This required parameter must be a session ID returned by a
             successful rapi_session call.

        o    "flags"




Braden, Hoffman        Expiration: December 1997               [Page 11]




Internet Draft                  RAPI v.5                       June 1997


             Setting the RAPI_REQ_CONFIRM flag will request confirmation
             of the reservation, by means of a confirmation upcall (type
             RAPI_RESV_CONFIRM).

        o    "RHost"

             This optional parameter may be used to define the interface
             address on which data will be received.  It is useful for a
             multi-homed host.  If it is omitted or the host address is
             INADDR_ANY, the default interface will be assumed.

        o    "StyleId"

             This required parameter specifies the reservation style id
             (values defined below).

        o    "Style_Ext"

             This optional parameter is a pointer to a style-dependent
             extension to the parameter list, if any.

        o    "Rcvr_Policy"

             This optional parameter is a pointer to a policy data
             structure, or it is NULL.

        o    "FilterSpec_list", "FilterSpecNo"

             The "FilterSpec_list" parameter is a pointer to an area
             containing a sequential vector of RAPI filter spec objects.
             The number of objexts in this vector is specified in
             "FilterSpecNo".  If "FilterSpecNo" is zero, the
             "FilterSpec_list" parameter will be ignored.

        o    "Flowspec_list", "FlowspecNo"

             The "Flowspec_list" parameter is a pointer to an area
             containing a sequential vector of RAPI flow spec objects.
             The number of objects in this vector is specified in
             "FlowspecNo".  If "FlowspecNo" is zero, the "Flowspec_list"
             parameter will be ignored.

        If FlowspecNo is zero, the rapi_reserve call will remove the
        current reservation(s) for the specified session, and
        FilterSpec_list and Flowspec_list will be ignored.  Otherwise,
        the parameters depend upon the style, as follows.

        o    Wildcard Filter (WF)



Braden, Hoffman        Expiration: December 1997               [Page 12]




Internet Draft                  RAPI v.5                       June 1997


             Use "StyleId" = RAPI_RSTYLE_WILDCARD.  The "Flowspec_list"
             parameter may be empty (to delete the reservation) or else
             point to a single flowspec.  The "FilterSpec_list"
             parameter may be empty or it may point to a single filter
             spec containing appropriate wildcard(s).

        o    Fixed Filter (FF)

             Use "StyleId" = RAPI_RSTYLE_FIXED.  "FilterSpecNo" must
             equal "FlowspecNo".  Entries in "Flowspec_list" and
             "FilterSpec_list" parameters will correspond in pairs.

        o    Shared Explicit (SE)

             Use "StyleId" = RAPI_RSTYLE_SE.  The "Flowspec_list"
             parameter should point to a single flowspec.  The "
             FilterSpec_list" parameter may point to a list of any
             length.

































Braden, Hoffman        Expiration: December 1997               [Page 13]




Internet Draft                  RAPI v.5                       June 1997


   D.   Remove a Session

        The rapi_release call removes the reservation, if any, and the
        state corresponding to a given session handle.  This call will
        be made implicitly if the application terminates without closing
        its RSVP sessions.  If the session handle is invalid, the call
        returns a corresponding RAPI error code; otherwise, it returns
        zero.

           int {
7777777777777778        r99a99p99i99_99r99e99l99e99a99s99e99}99(9999u99n99s99i99g99n99e99d9999i99n99t9999S99i99d9999)77777777777777778.fi

   E.   Get File Descriptor

        The rapi_getfd call may be used by the application to obtain the
        file descriptor associated with the Unix socket connected to the
        RSVP daemon, after a rapi_session() call has completed
        successfully and before rapi_release() is called.  When a socket
        read event is signaled on this file descriptor, the application
        should call rapi_dispatch(), described below.

           int {777r99a99p99i99_99g99e99t7777d} ( unsigned int Sid )

        If Sid is illegal or undefined, this call returns -1; otherwise,
        it returns the file descriptor.

   F.   Dispatch API Event

        The application should call this routine whenever a read event
        is signaled on the file descriptor returned by rapi_getfd().
        Rapi_dispatch() may be called at any time, but it will generally
        have no effect unless there is a pending event associated with
        the Unix pipe.  Calling this routine may result in one or more
        upcalls to the application from any of the open API sessions
        known to this instance of the library.

        int rapi_dispatch( )

        If this call encounters an error, rapi_dispatch() returns a RAPI
        error code; otherwise, it returns zero,

   G.   RAPI Version

        int rapi_version( )

        This call returns a single integer that defines the version of
        the interface.  The returned value is composed of a major number
        and a minor number, encoded as 100*major + minor.  This call may



Braden, Hoffman        Expiration: December 1997               [Page 14]




Internet Draft                  RAPI v.5                       June 1997


        be used by an application to adapt to different versions.

        The API described in this document has major version number 5.

   H.   Upcalls

        An upcall (invoked by a call to rapi_dispatch()) executes the
        procedure whose address was specified by the "Event_rtn" in the
        rapi_register call.

        event_upcall(

             unsigned int   Sid,           /* Session ID  */
             int            EventType,     /* Event type  */

             int            Style,         /* Resv style  */
             int            ErrorCode,     /* (error event): err code */
             int            ErrorValue,    /* (error event): err value*/
             struct sockaddr *ErrorNode,   /* Node that detected error*/
             unsigned char  ErrorFlags,

             int            FilterSpecNo,  /* # of filter specs in list*/
             rapi_filter_t *FilterSpec_list,
             int            FlowspecNo,    /* # of flowspecs in list  */
             rapi_spec_t   *Flowspec_list,
             int            AdspecNo,      /* # of ADSPECs in list    */
             rapi_adspec_t *Adspec_list,
             void          *Event_arg      /* Supplied by application */


        The following parameters are used in the upcall:

        o    "Sid"

             This parameter must be a session ID returned by a
             successful rapi_register call.

        o    "EventType"

             Upcall event types.

        o    "Style"

             This parameter contains the style of the reservation; it is
             non-zero only for a RAPI_RESV_EVENT or RAPI_RESV_ERROR
             upcall.

        o    "ErrorCode, ErrorValue"



Braden, Hoffman        Expiration: December 1997               [Page 15]




Internet Draft                  RAPI v.5                       June 1997


             These values encode the error cause, and they are set only
             for a RAPI_PATH_ERROR or RAPI_RESV_ERROR event.  ErrorCode
             values are defined in "rapi_lib.h" and corresponding text
             strings are defined in "rapi_err.h".

        o    "ErrorNode"

             This is the IP (V4 or V6) address of the node that detected
             the error, and it is set only for a RAPI_PATH_ERROR or
             RAPI_RESV_ERROR event.

        o    "ErrorFlags"

             These error flags are set only for a RAPI_PATH_ERROR or
             RAPI_RESV_ERROR event.

             RAPI_ERRF_InPlace (0x01) -- The reservation failed, but
             another reservation (presumably smaller) reservation is
             still in place on the same interface.

             RAPI_ERRF_NotGuilty (0x02) --  The reservation failed, but
             the request from this client was merged with a larger
             reservation upstream, so this client's reservation might
             not have caused the failure.

        o    "FilterSpec_list", "FilterSpecNo"

             The "FilterSpec_list" parameter is a pointer to a malloc'd
             area containing a sequential vector of RAPI filter spec or
             sender template objects.  The number of objexts in this
             vector is specified in "FilterSpecNo".  If "FilterSpecNo"
             is zero, the "FilterSpec_list" parameter will be NULL.

        o    "Flowspec_list", "FlowspecNo"

             The "Flowspec_list" parameter is a pointer to an area
             containing a sequential vector of RAPI flowspec or Tspec
             objects.  The number of objects in this vector is specified
             in "FlowspecNo".  If "FlowspecNo" is zero, the
             "Flowspec_list" parameter will be NULL.

        o    "Adspec_list", "AdspecNo"

             The "Adspec_list" parameter is a pointer to an area
             containing a sequential vector of RAPI adspec objects.  The
             number of objects in this vector is specified in
             "AdspecNo".  If "AdspecNo" is zero, the "Adspec_list"
             parameter will be NULL.



Braden, Hoffman        Expiration: December 1997               [Page 16]




Internet Draft                  RAPI v.5                       June 1997


        o    "Event_arg"

             This is the value supplied in the rapi_register call.

        When the application's upcall procedure returns, the API will
        free any areas pointed to by "Flowspec_list" or
        "FilterSpec_list"; the application must copy any values it wants
        to save.

        The specific parameters depend upon "EventType", which may have
        one of the following values.

        o    RAPI_PATH_EVENT

             A path event indicates that RSVP sender ("Path") state from
             a remote node has arrived or changed at the local node.  A
             RAPI_PATH_EVENT upcall containing the complete current list
             of senders (or possibly no senders, after a path teardown)
             in the path state for the specified session will be
             triggered whenever the path state changes.

             "FilterSpec_list", "Flowspec_list", and "Adspec_list" will
             be of equal length, and corresponding entries will contain
             sender templates, sender Tspecs, and Adspecs, respectively,
             for all senders known at this node.  In general, a missing
             object will be indicated by an empty RAPI object.

             RAPI_PATH_EVENT upcalls are enabled by the initial
             rapi_session call.

        o    RAPI_RESV_EVENT

             A reservation event upcall indicates that reservation state
             has arrived or changed at the node, implying (but not
             assuring) that reservations have been established or
             deleted along the entire data path to one or more
             receivers.  RAPI_RESV_EVENT upcalls containing the current
             reservation state for the API session will be triggered
             whenever the reservation state changes.

             "Flowspec_list" will either contain one flowspec object or
             be empty (if the state has been torn down), and
             "FilterSpec_list" will contain zero or more corresponding
             filter spec objects. "Adspec_list" will be empty.

             RAPI_RESV_EVENT upcalls are enabled by a rapi_sender call;
             the sender template from the latter call will match the
             filter spec returned in a reservation event upcall.



Braden, Hoffman        Expiration: December 1997               [Page 17]




Internet Draft                  RAPI v.5                       June 1997


        o    RAPI_PATH_ERROR

             A path error upcall indicates that an asynchronous error
             has been found in the sender information specified in a
             rapi_sender call.

             The "ErrorCode" and "ErrorValue" parameters will specify
             the error.  "FilterSpec_list" and "Flowspec_list" will each
             contain one object, the sender template and corresponding
             sender Tspec (if any) in error, while "Adspec_list" will be
             empty.  If there is no sender Tspec, the object in
             "Flowspec_list" will be an empty RAPI object.  The
             "Adspec_list" will be empty.

             Path Error upcalls are enabled by a rapi_sender call, and
             the sender Tspec in that call will match the sender Tspec
             returned in a subsequent path error upcall.

        o    RAPI_RESV_ERROR

             A reservation error upcall indicates that an asynchronous
             reservation error has occurred.

             The "ErrorCode" and "ErrorValue" parameters will specify
             the error.  "Flowspec_list" will contain one flowspec,
             while "FilterSpec_list" may contain zero or more
             corresponding filter specs.  "Adspec_list" will be empty.

        o    RAPI_RESV_CONFIRM

             A confirmation upcall indicates that a reservation has been
             made at least up to an intermediate merge point, and
             probably (but not necessarily) all the way to at least one
             sender.  A confirmation upcall is enabled by a rapi_reserve
             call with the RAPI_REQ_CONFIRM flag set, and at most one
             confirmation upcall will result from each such call.

             The parameters of a confirmation upcall are the same as
             those for a reservation event upcall.

        The accompanying table summarizes the upcalls; here n is a non-
        negative integer.









Braden, Hoffman        Expiration: December 1997               [Page 18]




Internet Draft                  RAPI v.5                       June 1997


        Upcall           Enabled by    FilterSpecNo  FlowspecNo   AdspecNo

        Path event       rapi_session       n             n           n

        Path error       rapi_sender        1             1           0

        Resv event       rapi_sender      1 or 0        1 or 0        0

        Resv error       rapi_reserve       n             1           0

        Confirm          rapi_reserve       1             1           0

                        Table 1: Summary of Upcall Types


3. RAPI FORMATTING ROUTINES

   For convenience of applications, RAPI includes standard routines for
   displaying the contents of a RAPI flowspec object or Tspec object.
   To use these routines, include the file "rapi_lib.h".

   A.   Format a Flowspec

        The rapi_fmt_flowspec() call formats a given RAPI flowspec into
        a buffer of given address and size.  The output is truncated if
        the size is too small.

        void rapi_fmt_flowspec(

             rapi_flowspec_t  *specp,   /* Addr of RAPI flowspec*/
             char             *buffer,  /* Addr of buffer       */
             int               length   /* Length of buffer     */
             )


   B.   Format a Tspec

        The rapi_fmt_tspec() call formats a given RAPI Tspec into a
        buffer of given address and size.  The output is truncated if
        the size is too small.

        void rapi_fmt_tspec(

             rapi_tspec_t    *tspecp,  /* Addr of RAPI Tspec  */
             char            *buffer,  /* Addr of buffer      */
             int              length   /* Length of buffer    */
             )




Braden, Hoffman        Expiration: December 1997               [Page 19]




Internet Draft                  RAPI v.5                       June 1997


   C.   Format an Adspec

        The rapi_fmt_adspec() call formats a given RAPI Adspec into a
        buffer of given address and size.  The output is truncated if
        the size is too small.

        void rapi_fmt_adspec(

             rapi_adspec_t    *adspecp,  /* Addr of RAPI Adspec */
             char             *buffer,   /* Addr of buffer      */
             int               length    /* Length of buffer    */
             )


   D.   Format a Filter Spec

        The rapi_fmt_filtspec() call formats a given RAPI Filter Spec
        into a buffer of given address and size.  The output is
        truncated if the size is too small.

        void rapi_fmt_filtspec(

             rapi_filter_t    *filtp,    /* Addr of RAPI Filt Spec*/
             char             *buffer,   /* Addr of buffer        */
             int               length    /* Length of buffer      */
             )

























Braden, Hoffman        Expiration: December 1997               [Page 20]




Internet Draft                  RAPI v.5                       June 1997


4. RAPI OBJECTS

   Flowspecs, filter specs, sender templates, and sender Tspecs are
   encoded as variable-length RAPI objects.

   Every RAPI object begins with a header consisting of two words, the
   total length of the object in bytes and the type, respectively.  An
   empty object consists only of a header, with type zero and length 8
   bytes.

   Integrated services data structures are defined in: draft-ietf-
   intserv-rsvp-01.txt.

   o    Flowspecs

        There are two formats for RAPI flowspecs.  For more details, see
        "rapi_lib.h" and "rsvp_intserv.h".

        -    RAPI_FLOWSTYPE_Simplified

             This is a "simplified" format.  It consists of a simple
             list of parameters needed for either Guaranteed or
             Controlled Load service, using the service type
             QOS_GUARANTEED or QOS_CNTR_LOAD, respectively.  The RAPI
             client library routines will map this format to/from an
             appropriate Integrated Services data structure.

        -    RAPI_FLOWSTYPE_Intserv

             This flowspec must be a fully formatted Integrated Services
             flowspec data structure.

   o    Sender Tspecs

        There are two formats for RAPI Sender Tspecs.  For more details,
        see "rapi_lib.h" and "rsvp_intserv.h".

        -    RAPI_TSPECTYPE_Simplified

             This is a "simplified" format, consisting of a simple list
             of parameters with the service type QOS_TSPEC.  The RAPI
             client library routines will map this format to/from an
             appropriate Integrated Services data structure.

        -    RAPI_TSPECTYPE_Intserv

             This flowspec must be a fully formatted Integrated Services
             Tspec data structure.



Braden, Hoffman        Expiration: December 1997               [Page 21]




Internet Draft                  RAPI v.5                       June 1997


   o    Adspecs

        There are two formats for RAPI Adspecs.  For more details, see
        "rapi_lib.h" and "rsvp_intserv.h".

        -    RAPI_ADSTYPE_Simplified

             This is a "simplified" format, consisting of a list of
             Adspec parameters for all possible services.  The RAPI
             client library routines will map this format to/from an
             appropriate Integrated Services data structure.

        -    RAPI_ADSTYPE_Intserv

             This flowspec must be a fully formatted Integrated Services
             Tspec data structure.

        In an upcall, a flowspec, sender Tspec, or Adspec is by default
        delivered in simplified format; however, if the RAPI_USE_INTSERV
        flag is set in the rapi_session call, then the IntServ format is
        used in upcalls.

   o    Filter Specs and Sender Templates

        There are two formats for these objects.

        -    RAPI_FILTERFORM_BASE (RAPI_FILTERFORM_BASE6)

             This object consists of only a socket address structure,
             defining the IP (V4 or V6) address and port.

        -    RAPI_FILTERFORM_GPI (RAPI_FILTERFORM_GPI6)

             This object consists of only an address structure, defining
             the IP (V4 or V6) address and a 32-bit Generalized Port
             Identifier.  It is recommended for all IPSEC applications.
             Other non-TCP/non-UDP transports may also utilize this
             format in the future.

   o    Policy Data Objects

        (Not yet supported)









Braden, Hoffman        Expiration: December 1997               [Page 22]




Internet Draft                  RAPI v.5                       June 1997


APPENDIX A. Implementation

   This section contains some general remarks on the implementation of
   this API that is distributed with the ISI release of RSVP code.

   A.1 Protocols

      There are three protocol interfaces involved in invoking RSVP via
      the API.

      1.   Procedure Call Interface to Application

           The term "RAPI" (RSVP API) is used for the procedure call
           interface to applications, and for the data structures
           ("objects") used in that interface.  This document is
           primarily concerned with the RAPI interface.  This interface
           is realized by procedures included in the library routine
           librsvp.a, which is compiled from rapi_lib.c and rapi_fmt.c.

      2.   Application - Daemon Protocol

           The term "API" is used in the code for the local protocol
           across the Unix socket between the librsvp.a routines and the
           RSVP daemon rsvpd.  This protocol generally use RSVP object
           bodies but RAPI object framing.

      3.   RSVP Protocol

           The RSVP protocol is used in the Internet between RSVP daemon
           programs.

      The code is organized to make these three interfaces logically
      independent, so they can be changed independently.  Each of these
      three protocol interfaces has an independent version number,
      defined in rapi_lib.h, rsvp_api.h, and rsvp.h for RAPI, API, and
      RSVP, respectively.

      The RAPI call library librsvp.a includes routines that convert
      objects between RAPI and API formats.  Similarly, the file
      rsvp_api.c included in the RSVP daemon includes routines that
      convert between the API representation and the RSVP
      representation.  In some cases, these conversion procedures are
      identity transformations (i.e., pure copies); however, they
      provide the structure to allow any of the three interfaces to be
      changed in the future.

      There are two different object framing conventions.  RAPI and API
      objects have a two-word header -- a total length in bytes and a



Braden, Hoffman        Expiration: December 1997               [Page 23]




Internet Draft                  RAPI v.5                       June 1997


      format code -- and a body.  RSVP objects have a one-word header.
      In general, objects in the API interface (i.e., across the Unix
      socket) carry the two-word RAPI object header, but their body is
      that of the corresponding RSVP object.  Therefore, the API<->RSVP
      conversion in rsvp_api.c simply maps the framing convention.

      In the RAPI interface, the application is given some choice of
      data formats.  For example, QoS control objects (i.e., flowspecs,
      Tspecs, and Adspecs) can be represented in either the RSVP (really
      Int-Serv) format, which has complex packing, or in the more
      convenient Simplified format.  The RAPI library routines map
      between Simplified format and Int-Serv format, which is used
      across the API.

   A.2 RAPI Sessions

      Each instance of the RAPI library routines keeps a local (to the
      application process) table of open RAPI sessions; the index into
      this table is the session handle (a_sid) used locally.   The RSVP
      daemon keeps its own table of RAPI sessions.  From the daemon's
      viewpoint, a RAPI session is defined by the triple: (fd, pid,
      a_sid), where fd is the file descriptor for the Unix socket, pid
      is the Unix process id, and a_sid is an application session id
      received over fd from pid.

APPENDIX B. Implementation Restrictions

   This Appendix summarizes the features of the interface that have not
   been implemented in the latest (4.1a6) release of the ISI reference
   implementation of RSVP.

   o    The RAPI_FILTERFORM_GPI and RAPI_FILTERFORM_GPI objects and the
        session flag RAPI_GPI_SESSION are implemented in RAPI and the
        API, but the IPSEC extensions are not yet fully implemented in
        RSVP.

   o    The "SenderAdspec", and "SenderPolicy" parameters in a
        rapi_sender call are not implemented.

   o    The "Style_Ext" and "Rcvr_Policy" parameters in a rapi_reserve
        call are not implemented.










Braden, Hoffman        Expiration: December 1997               [Page 24]




Internet Draft                  RAPI v.5                       June 1997


APPENDIX C. CHANGES

   This document describes major version 5 of RAPI.  This version has
   the following differences from previous versions:

   o    The "Legacy" format has been removed.

   o    The rapi_fmt_filtspec() routine has been added.

   o    The two session flags RAPI_GPI_SESSION and RAPI_USE_INTSERV have
        been defined.

   o    The ErrorNode parameter in an upcall has been changed from a
        sockaddr to a pointer to a sockaddr structure, to accommodate
        IPv6.

   o    IPv4-specific Socket structures sockaddr_in have been changed to
        the more general form sockaddr, to accomodate IPv6.  The calling
        application should supply the appropriate form, sockaddr_in or
        sockaddr_in6, and cast it into a sockaddr for the call.































Braden, Hoffman        Expiration: December 1997               [Page 25]