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]