[Search] [txt|ps|pdf|bibtex] [Tracker] [Email] [Nits]

Versions: 00 01 02                                                      
INTERNET-DRAFT                                               Bob Lindell
Expiration: February 1999                                            ISI
File: draft-lindell-rsvp-scrapi-00.txt


              SCRAPI - A Simple "Bare Bones" API for RSVP

                               Version 1

                             August 7, 1998




                          Status of this 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 view the entire list of current Internet-Drafts, please
     check the "1id-abstracts.txt" listing contained in the
     Internet-Drafts Shadow Directories on ftp.is.co.za (Africa),
     ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern
     Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East
     Coast), or ftp.isi.edu (US West Coast).



                                Abstract



     This document describes SCRAPI, a simple 'bare bones' API for
     RSVP.  The goal of this API is to produce an interface which
     simplifies the augmentation of applications with RSVP support.





Lindell                Expiration: February 1999                [Page 1]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998


1.  Introduction


This document describes SCRAPI, a simple "Bare Bones" API for RSVP [1].
The goal of this API is produce an interface which simplifies the
augmentation of applications with RSVP support.  The main features of
SCRAPI are:


     o    Allow the addition of RSVP support to applications by adding a
          few lines of code.


     o    Provide a portable interface which can be used with any
          vendor's RAPI implementation.


     o    Avoid the introduction of RSVP specific data types and
          definitions.


     o    Support IPv4 and IPv6 in a transparent manner.


SCRAPI is layered on top of RAPI [2], an existing RSVP API, to provide
portability across vendor implementations.  Currently, SCRAPI has been
tested only with the ISI implementation of RAPI.

There are three main routines included in this API, one which is used by
the sender side, one to be used at the receiving end, and a routine to
finalize the entire API at the end of execution.  This simple API should
be easy to insert into networking applications which require RSVP
support.

The remaining routines in the API are utility functions to ease the
development of an interface which supports IPv4 and IPv6.  The objective
is to provide enough functionality so that applications would not need
to code explicitly for either IPv4 or IPv6, or use messy compilation
conditionals to develop an interface to support both address families.
As an example, a single data type for addresses is provided that is
large enough to hold addresses from either address family.   In
addition, parsing an address string or performing a host name resolution
for both address families is provided.

To provide simplicity, event upcalls to the application do not exist in
SCRAPI.  For this reason, it would be difficult to use SCRAPI for
applications which negotiate QoS with the network.  Applications
requiring this type of functionality should use the standard RAPI



Lindell                Expiration: February 1999                [Page 2]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998


interface.


2.  Functional Description


Applications which use SCRAPI get a simplied service model.  The average
bandwidth specified by the sender is currently translated into the
integrated services controlled load [4] or guaranteed service [3] with
the given average bandwidth.  The peak bandwidth and token bucket depth
are set to twice the average bandwidth.  Minimum policed unit and
maximum packet size are set to 64 bytes and the largest MTU of all IP
interfaces on the host.

Sender and receiver side API calls can block, if requested, until a
reservation request has completed.  The notion of completion can be
difficult to define for multicast flows.  We will define completion in
the content of SCRAPI calls to refer to either partial or full
completion of the reservation request.

A sender sources PATH messages using the Tspec described above.  If
blocking is requested with a non-zero timeout value, the sender blocks
until the receipt of a single RESV event from any sender.  If the
specified flow is unicast, the call blocks until the reservation has
completed.  If the flow is multicast, then at least one receiver has a
reservation in place when the call unblocks.

A receiver waits for a PATH event from the sender, and if requested,
makes a reservation in response using the sender's Tspec and Adspec for
guaranteed service.  For guaranteed service, the slack term is set to
zero.  If blocking is requested, the receiver blocks until the receipt
of a CONFIRM event.  For a multicast flow, a CONFIRM event can be a
unreliable indication that a reservation has been successful.

If any RSVP errors occur during a blocking sender or receiver API call,
the call will unblock and return an error code.

A state diagram of the SCRAPI reservation API, for a given data flow, is
shown in Figure 1.  A data flow, or RSVP session, is defined as a unique
destination address, port and protocol number.

SCRAPI provides a simple error status reporting on a per flow basis.
Status can be in a "red", "yellow", or "green" state.  The red state
indicates that either the flow does not exist or is currently in an
error state.  Yellow state indicates that the reservation requests are
pending, whereas green indicates that at least one request has
completed.




Lindell                Expiration: February 1999                [Page 3]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998


In the next section, the SCRAPI application programming interface is
defined.  In subsequent sections, usage examples are offered as
templates for programmers who are attempting to embed SCRAPI calls into
existing applications.


                             +---------+
                  +----------| Closed  |----------+
            scrapi_sender    +---------+    scrapi_receiver
                  |                               |
  scrapi_sender   |                               |   scrapi_receiver
         +----+   |                               |   +----+
         |    V   V                               V   V    |
         |   +---------+                     +---------+   |
         +---|         |                     |         |---+
             |  Send   |                     |   Rcv   |
     +-------|         |<-----+       +----->|         |-------+
     |       +---------+      |       |      +---------+       |
     |            |           |       |           |            |
     |            |scrapi_receiver(0) |           |            |
     |            |           |       |           |            |
     |            |           |   scrapi_sender(0)|            |
     |            |           |       |           |            |
     |      scrapi_receiver   |       |     scrapi_sender      |
     |            |          +---------+          |            |
     |            +--------->|         |<---------+            |
     |                       | SendRcv |                       |
     |  scrapi_sender or +---|         |                       |
     |  scrapi_receiver  |   +---------+                       |
     |                   |    ^   |                            |
     |                   +----+   |                            |
     |                            |                            |
  scrapi_release            scrapi_release           scrapi_release
  scrapi_sender(0)                |              scrapi_receiver(0)
     |                            V                            |
     |                        +--------+                       |
     +----------------------->| Closed |<----------------------+
                              +--------+


                   Figure 1: SCRAPI API State Diagram



3.  Application Programming Interface Definition






Lindell                Expiration: February 1999                [Page 4]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998


3.1.  Reservation API Description


Function Name: scrapi_sender

Syntax:        int scrapi_sender(

                       const struct sockaddr *destination,
                       int protocol,
                       const struct sockaddr *source,
                       scrapi_service service,
                       double bw,
                       int ttl,
                       unsigned long msecs

               );

Description:   SCRAPI call for a data sender.  The destination address
               and protocol number of the data flow are supplied as the
               first two arguments.  The source address of the data flow
               can be specified, or set to NULL to choose the system
               default.  The service parameter specifies the service,
               currently either Controlled Load or Guaranteed.  The bw
               parameter is the average bandwidth of the flow in
               bytes/sec.  The ttl of the packets can be specified or
               set to 0 to choose the system default.  If msecs is
               greater than 0, the call to scrapi_sender blocks msecs
               milliseconds to receive a reservation event from at least
               one recipient.  The call will also unblock prematurely if
               any errors are detected during this period.  This
               function can be called repeatedly by an application to
               modify any parameters associated with this data flow
               (same destination and protocol values).  A value of 0 for
               the bw parameter unregisters the data flow.


Return Values: TRUE if successful, FALSE otherwise.  Unsuccessful
               operations set scrapi_errno to an appropriate error code.

Also See:      scrapi_errno, scrapi_get_status











Lindell                Expiration: February 1999                [Page 5]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998



Function Name: scrapi_receiver

Syntax:        int scrapi_receiver(

                       const struct sockaddr *destination,
                       int protocol,
                       const struct sockaddr *source,
                       int reserve,
                       scrapi_style style,
                       unsigned long msecs

               );

Description:   SCRAPI call for a data receiver.  The destination address
               and protocol number of the data flow are supplied as the
               first two arguments.  The source address of the data flow
               can be specified or can be set to NULL to choose any
               source.  In addition, the source address can be specified
               with a port number of 0 to match a source address
               regardless of port number.  The reserve parameter should
               be set to TRUE or FALSE to turn on and off a reservation
               for that data flow respectively.  The style parameter
               specifies whether the reservation is shared among
               multiple senders.  If msecs is greater than 0, the call
               to scrapi_receiver blocks msecs milliseconds to receive a
               reservation confirmation event.  The call will also
               unblock prematurely if any errors are detected during
               this period.  This function can be called repeatedly by
               an application to modify any parameters associated with
               this data flow (same destination and protocol values).

Return Values: TRUE if successful, FALSE otherwise.  Unsuccessful
               operations set scrapi_errno to an appropriate error code.

Also See:      scrapi_errno, scrapi_get_status















Lindell                Expiration: February 1999                [Page 6]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998



Function Name: scrapi_close

Syntax:        int scrapi_close(

                       const struct sockaddr *destination,
                       int protocol

               );

Description:   SCRAPI call to close either a sender or receiver flow.
               If the destination address is set to NULL, all flows will
               be closed and the protocol parameter value will be
               ignored.

Return Values: TRUE if successful, FALSE otherwise.  Unsuccessful
               operations set scrapi_errno to an appropriate error code.


Enum Name:     scrapi_service

               1.   scrapi_service_cl

               2.   scrapi_service_gs

Description:   Enumerated types for specificing the desired service.
               Currently, Integrated Services Controlled Load and
               Guaranteed are supported.


Enum Name:     scrapi_style

               1.   scrapi_style_shared

               2.   scrapi_style_distinct

Description:   Enumerated types for specificing the reservation style.
               Currently, shared (wildcard) and distinct styles are
               supported.












Lindell                Expiration: February 1999                [Page 7]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998



Enum Name:     scrapi_status

               1.   scrapi_status_red

               2.   scrapi_status_yellow

               3.   scrapi_status_green

Description:   Enumerated types for status condition of a flow.  The
               meaning of these values is described in the
               scrapi_status() function description.


3.2.  Asynchronous Event Loop API Description


Function Name: scrapi_getfd

Syntax:        int scrapi_getfd(

                       const struct sockaddr *destination,
                       int protocol

               );

Description:   SCRAPI call to get the API file descriptor to use in a
               subsequent select() call.

Return Values: A file descriptor value if successful, -1 otherwise.


Function Name: scrapi_dispatch

Syntax:        int scrapi_dispatch();

Description:   SCRAPI call to poll the API for new events.

Return Values: TRUE if successful, FALSE if RSVP support is no longer
               available.


3.3.  Error Handling API Description








Lindell                Expiration: February 1999                [Page 8]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998



Function Name: scrapi_get_status

Syntax:        scrapi_status scrapi_get_status(

                       const struct sockaddr *destination,
                       int protocol

               );

Description:   SCRAPI call to get the status of a flow.  If the status
               is red, either the flow was never defined or the flow is
               currently in an error state.  A yellow status indicates
               that the flow is valid but no reservation operation(s) at
               the sender or receiver end has completed successfully.
               Once a single operation on either the sender or receiver
               end has completed successfully, the flow has a green
               status.

Return Values: scrapi_stat_red, scrapi_stat_yellow, or
               scrapi_stat_green.


Variable Name: scrapi_errno

Syntax:        extern int scrapi_errno;

Description:   Set to the return value of the last RAPI call made within
               the SCRAPI library.

Also See:      scrapi_errlist


Function Name: scrapi_perror

Syntax:        void scrapi_perror(

                       const char *string

               );

Description:   SCRAPI call to print an error message analogous to the
               perror() library call.








Lindell                Expiration: February 1999                [Page 9]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998



Function Name: scrapi_errlist

Syntax:        const char * scrapi_errlist(

                       int errno

               );

Description:   SCRAPI call to get an error message string for a given
               errno.

Return Values: An error message string.


Function Name: scrapi_stderr

Syntax:        void scrapi_stderr(

                       FILE *file

               );

Description:   Set the file pointer to be used by the SCRAPI library for
               standard error.  If it is set to NULL, no messages are
               printed.  The default value is stderr.


Function Name: scrapi_debug

Syntax:        void scrapi_debug(

                       FILE *file

               );

Description:   Set the file pointer to be used by the SCRAPI library for
               debugging information.  If it is set to NULL, no messages
               are printed.  Debug messages include the logging of all
               asynchronous RSVP events.  The default value is NULL.


3.4.  Address Manipulation API Description








Lindell                Expiration: February 1999               [Page 10]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998



Macro Name:    SOCKADDR

Description:   A struct sockaddr data type that is large enough for both
               IPv4 and IPv6 addresses.


Function Name: scrapi_sockaddr_multicast

Syntax:        int scrapi_sockaddr_multicast(

                       const struct sockaddr *address

               );

Description:   Determine if an address is multicast or unicast.

Return Values: TRUE if multicast, FALSE otherwise.


Function Name: scrapi_sockaddr_parse

Syntax:        int scrapi_sockaddr_parse(

                       struct sockaddr *address
                       const char *name,
                       unsigned short port

               );

Description:   Perform a host name lookup or parse an address and
               initialize a struct sockaddr structure.

Return Values: TRUE if parsed, FALSE otherwise.


Function Name: scrapi_sockaddr_print

Syntax:        const char * scrapi_sockaddr_print(

                       const struct sockaddr *address

               );

Description:   Pretty print an address.

Return Values: A valid string if printable, NULL otherwise.




Lindell                Expiration: February 1999               [Page 11]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998



Function Name: scrapi_sockaddr_get_port

Syntax:        unsigned short scrapi_sockaddr_get_port(

                       const struct sockaddr *address

               );

Description:   Get the port number.

Return Values: The port number if successful, 0 otherwise.


Function Name: scrapi_sockaddr_set_port

Syntax:        int scrapi_sockaddr_set_port(

                       struct sockaddr *address,
                       unsigned short port

               );

Description:   Set the port number.

Return Values: TRUE if successful, FALSE otherwise.


Function Name: scrapi_sockaddr_any

Syntax:        int scrapi_sockaddr_any(

                       struct sockaddr *address,
                       int family

               );

Description:   Initialize a struct sockaddr to the wildcard address and
               port number for the given address family.

Return Values: TRUE if successful, FALSE otherwise.


4.  Application Code Templates


This section provides examples, presented as code templates, to aid
programmers in augmenting networking applications with SCRAPI calls.



Lindell                Expiration: February 1999               [Page 12]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998


One example contains two simplex applications which attempt to wait for
a reservation to be put in place before sending data on the network.
The other example is a full duplex multimedia type application which
sends and receives data without waiting for completion of the
reservation.


4.1.  Unicast Performance Measurement Application


The following example was derived from a network performance tool.  It
attempts to put in place a unicast reservation before measuring network
performance.  Waiting is accomplished using the timeout option in the
sender and receiver calls.


4.1.1.  Sender Application


This sender application opens a TCP connection to the "receive-hostname"
on port 1111 and attempts to reserve 1000 bytes/sec of average
bandwidth.  After waiting at most 10 seconds for a reservation to be put
in place, this application streams data to the receiver to measure
network performance and then closes the connection.



























Lindell                Expiration: February 1999               [Page 13]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998



#include <scrapi.h>

void
main(int argc, char *argv[])
{
        int timeout = 10000;        /* wait for at most 10 seconds */
        double bw = 1000;           /* Average bandwidth 1Kbytes/sec */
        struct SOCKADDR destination;
        char *hostname = "receive-hostname";
        unsigned short port = 1111;

        /* translate host name or address */
        if (!scrapi_sockaddr_parse((struct sockaddr *) &destination,
                        hostname,htons(port))) {
                fprintf(stderr,"Could not parse host address");
                exit(1);
        }

        /* make an RSVP based reservation */
        if (!scrapi_sender((struct sockaddr *) &destination,IPPROTO_TCP,
                        NULL,scrapi_service_cl,bw,0,timeout))
                scrapi_perror("RSVP unable to reserve bandwidth");

        /* run test */
        scrapi_close(NULL,0);
}



4.1.2.  Receiver Application


This receiver application accepts a TCP connection and attempts to make
a reservation.  After waiting at most 10 seconds for a reservation to be
put in place, this application consumes data from the sender to measure
network performance and then closes the connection.














Lindell                Expiration: February 1999               [Page 14]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998



#include <scrapi.h>
#include <errno.h>

void
main(int argc, char *argv[])
{
        int fd,len,timeout = 10000;        /* wait for at most 10 seconds */
        struct SOCKADDR destination;

        /* open, bind, and listen for connection */
        /* fd = accept(...); */
        len = sizeof(destination);
        if (getsockname(fd,(struct sockaddr *) &destination,&len) == -1) {
                perror("getsockname");
                exit(1);
        }

        /* make an RSVP based reservation */
        if (!scrapi_receiver((struct sockaddr *) &destination,IPPROTO_TCP,
                        NULL,1,scrapi_style_distinct,timeout))
                scrapi_perror("RSVP unable to reserve bandwidth");

        /* run test */
        scrapi_close(NULL,0);
}



4.2.  Multicast Multimedia Application


This example highlights the inclusion of the SCRAPI API into a Tcl/Tk
event loop of a multimedia application.  This is a full duplex
application that is sending and receiving data on the same address.
This application does not wait for completion status from the
reservation calls.














Lindell                Expiration: February 1999               [Page 15]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998



#include <tcl.h>
#include <tk.h>
#include <scrapi.h>

void
callback(ClientData data, int mask)
{
        if (!scrapi_dispatch())
                Tk_DeleteFileHandler(data);
}

void
main(int argc, char *argv[])
{
        int fd;
        struct SOCKADDR destination;
        double bw = 1000;                /* Average bandwidth 1Kbytes/sec */
        char *hostname = "receive-hostname";
        unsigned short port = 1111;

        /* translate host name or address */
        if (!scrapi_sockaddr_parse((struct sockaddr *) &destination,
                        hostname,htons(port))) {
                fprintf(stderr,"Could not parse host address");
                exit(1);
        }

        /* make an RSVP based reservation */
        if (!scrapi_sender((struct sockaddr *) &destination,IPPROTO_UDP,
                        NULL,scrapi_service_cl,bw,0,0))
                scrapi_perror("RSVP unable to reserve bandwidth");
        if (!scrapi_receiver((struct sockaddr *) &destination,IPPROTO_UDP,
                        NULL,1,scrapi_style_distinct,0))
                scrapi_perror("RSVP unable to reserve bandwidth");
        fd = scrapi_getfd((struct sockaddr *) &destination,IPPROTO_UDP);
        Tk_CreateFileHandler((ClientData) fd,TK_READABLE,callback,
                (ClientData) fd);

        /* send data */
        scrapi_close(NULL,0);
}



5.  Conclusion





Lindell                Expiration: February 1999               [Page 16]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998


The SCRAPI interface provides a simple method to add RSVP support to
many network applications.  It supports both IPv4 and IPv6 and attempts
to simplify user developed code to support both address families.
Coding examples are provided to give additional guidance on the usage of
this API.


6.  Security Considerations


Security considerations are not discussed in this memo.


7.  Acknowledgements


The author would like to thank Steve Berson for helping to define this
API.


8.  References


[1]  Braden, R., Ed., et. al., Resource Reservation Protocol (RSVP) -
     Version 1 Functional Specification, RFC 2205, September 1997.


[2]  Braden, R., Hoffman, D., RAPI -- An RSVP Application Programming
     Interface Version 5, Work In Progress, November 1997.


[3]  Shenker, S., Partridge, C., Guerin, R., Specification of Guaranteed
     Quality of Service, RFC 2212, September 1997.


[4]  Wroclawski, J., Specification of the Controlled Load Quality of
     Service, RFC 2211, September 1997.


9.  Author's Address


Bob Lindell
USC Information Sciences Institute
4676 Admiralty Way
Marina del Rey, CA 90292





Lindell                Expiration: February 1999               [Page 17]


INTERNET-DRAFT                 SCRAPI v.1                      July 1998





                           Table of Contents



1. Introduction ...................................................    2
2. Functional Description .........................................    3
3. Application Programming Interface Definition ...................    4
3.1. Reservation API Description ..................................    5
3.2. Asynchronous Event Loop API Description ......................    8
3.3. Error Handling API Description ...............................    8
3.4. Address Manipulation API Description .........................   10
4. Application Code Templates .....................................   12
4.1. Unicast Performance Measurement Application ..................   13
4.1.1. Sender Application .........................................   13
4.1.2. Receiver Application .......................................   14
4.2. Multicast Multimedia Application .............................   15
5. Conclusion .....................................................   16
6. Security Considerations ........................................   17
7. Acknowledgements ...............................................   17
8. References .....................................................   17
9. Author's Address ...............................................   17



























Lindell                Expiration: February 1999               [Page 18]