rsvpapi.txt

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

Braden, Hoffman        Expiration:  February 1999              [Page 13]




Internet Draft                  RAPI v.5                     August 1998


   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:  February 1999              [Page 14]




Internet Draft                  RAPI v.5                     August 1998


        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_session() 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_session() 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:  February 1999              [Page 15]




Internet Draft                  RAPI v.5                     August 1998


             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:  February 1999              [Page 16]




Internet Draft                  RAPI v.5                     August 1998


        o    "Event_arg"

             This is the value supplied in the rapi_session() 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:  February 1999              [Page 17]




Internet Draft                  RAPI v.5                     August 1998


        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:  February 1999              [Page 18]




Internet Draft                  RAPI v.5                     August 1998


        Upcall           Enabled by    FilterSpecNo  FlowspecNo   AdspecNo

        Path event       rapi_session       n             n        n or 0

        Path error       rapi_sender        1             1           0

        Resv event       rapi_sender        n           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