INTERNET-DRAFT Bob Lindell Expiration: August 1999 ISI File: draft-lindell-rsvp-scrapi-02.txt SCRAPI - A Simple 'Bare Bones' API for RSVP February 26, 1999 Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. 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.' The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. 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: August 1999 [Page 1]
INTERNET-DRAFT SCRAPI v.2 February 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. To provide simplicity, event upcalls to the application do not exist in SCRAPI. Because of the design choice, it may be difficult to use SCRAPI for applications which negotiate QoS with the network. Applications requiring this type of functionality should use the standard RAPI interface. There are three main functions included in this API, one which is used by the sender side, one to be used at the receiving end, and a function 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. Error reporting is handled in two distinct forms. The first is an aggregated error model that is unique to SCRAPI. SCRAPI includes a tri-valued error model with error states of 'red', 'yellow', or 'green'. This model gives feedback to an application on the status of reservations at an given time. The exact description of each error state will be described below. Second, it is possible to get an error number and corresponding error description after executing a SCRAPI sender, receiver, or close function. This is similar to the errno Lindell Expiration: August 1999 [Page 2]
INTERNET-DRAFT SCRAPI v.2 February 1998 support in Unix. These error codes are of limited use, since they only provide feedback on an immediate failure of a request. This is most likely due to invalid arguments or some general system error. A timeout errno is returned if a timer expires on the sender or receiver calls. A timeout error does not abort the request, it is merely an indication that the timer has expired. Applications can abort a request following a timeout by closing the flow. There is support for applications which have polling based event loops using a system call such as select. Analogous functions to the RAPI interface for supporting this functionality is provided in SCRAPI. The remaining functions in the API are utility functions to ease the development of an interface which supports IPv4 and IPv6. These are documented in Appendix 1. These functions are not viewed as part of the SCRAPI API, but rather a collection of useful address manipulation functions which should be provided in system libraries. In the future, these functions will be removed in favor of system supplied functionality. The objective of these extensions was 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. 2. Functional Description The basic abstraction for the SCRAPI API is a flow. A flow is defined in terms of three parameters: the destination address, a protocol number, and the source address. This triple is used for the sender, receiver, status, and close operations in SCRAPI. Applications which use SCRAPI get a simplied service model. The average bandwidth specified by the sender is currently used for the integrated services controlled load [4] or guaranteed service [3] token bucket rate (r). The peak token bucket rate (p) is set to positive infinity and token bucket depth (b) is set to twice the average bandwidth. Minimum policed unit (m) and maximum packet size (M) 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 Lindell Expiration: August 1999 [Page 3]
INTERNET-DRAFT SCRAPI v.2 February 1998 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 data rate (R) is set to the maximum of all senders and the slack term (S) is set to zero. If blocking is requested, the receiver blocks until the receipt of a CONFIRM event. If any RSVP errors occur during a blocking sender or receiver API call, the call will unblock. Internal to SCRAPI, there is support for both IPv6 Flow Labels and the Generalized Port Identifier (GPI) [5]. These are not visible at the API. It is assumed that applications would continue to use port numbers to specify flows and that SCRAPI internally would convert these port numbers to either a Flow Label or a GPI value using system supplied functionality. A state diagram of the SCRAPI reservation API, for a given data flow, is shown in Figure 1. A sender call subscripted with zero designates a sender call with the bandwidth set to zero. Similarly, a receiver call subscripted with zero designates a receiver call with the reservation flag set to FALSE. Lindell Expiration: August 1999 [Page 4]
INTERNET-DRAFT SCRAPI v.2 February 1998 +---------+ +----------| 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_close or scrapi_close scrapi_close or scrapi_sender(0) | scrapi_receiver(0) | V | | +---------+ | +---------------------->| Closed |<----------------------+ +---------+ Figure 1: SCRAPI API State Diagram 3. The Simplified Error Model of SCRAPI 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: August 1999 [Page 5]
INTERNET-DRAFT SCRAPI v.2 February 1998 A state diagram of the SCRAPI error model, for a given data flow, is shown in Figure 2. A close operation takes the model from any state back to the red state. This was intentionally omitted to increase the clarity of the diagram. There are a number of difficulties in providing a simple, robust, aggregated error model based on RSVP signaling information. These issues are highlighted below as either 'long term' or 'short term' stability issues. If the model provides 'long term' stability, it will eventually report the currect status. There should be no terminal states of the model that cause the reported status to remain fixed without the ability to transition to a new state if conditions change. If the model has 'short term' stability, it attempts to damp rapid oscillations between states. There are a few obstacles to 'long term' stability is the current error reporting model for RSVP. Once an error message has been received, it is not always possible to determine when an error condition has cleared. If an application possessed global knowledge about refresh rates and link reliability assumptions along a path, the solution would be to wait until enough time has expired to assume that the lack of any subsequent error message is an indication that an error has cleared. Unfortunately, this information about refresh rates at any given point in the path is unknown to applications. The solution in SCRAPI is an attempt to match error messages with the receipt of other messages that could be used to indicate the clearing of a given error. For example, a CONFIRM message received subsequent to a RESV ERROR message might indicate that the error condition has cleared. For unicast, path errors can be paired with the complementary RESV message to transition the error model between red and green. With multicast, an application could be receiving refreshes of a PATH ERROR message from one branch of the multicast tree and RESV messages from another branch. Should the error state of this model be red or green? RSVP CONFIRM messages are not delivered reliably. SCRAPI should probably include a reliability model for confirmations so that the error model does not get stuck in a non-green state due to the loss of a CONFIRM message. This can be implemented by making repeated requests for a CONFIRM message from the API. There are also 'short term' stability issues that have not been adequately addressed in SCRAPI. In the multicast example above, an application could be receiving mixture of path errors and RESV messages for the same flow. Since the error messages will continue to refresh, this may cause oscillatory behavior of the error model. Similarly, RESV errors can be received soon after a confirmation due to the merging rules for RSVP. In both of these cases, it might be useful to add some Lindell Expiration: August 1999 [Page 6]
INTERNET-DRAFT SCRAPI v.2 February 1998 delay to state transitions in the error model. It is anticipated that improvements to the design and implementation of this error model will occur as we gain a better understanding of of the use of RSVP with applications. +---------+ +----------| Red |----------+ scrapi_sender +---------+ scrapi_receiver | | V V +---------+ +---------+ +-------| Yellow |<-----+ +----->| Yellow |-------+ | +---------+ | | +---------+ | | | | | | | | |scrapi_receiver(0) | | | | | | | | | | | | scrapi_sender(0)| | | | | | | | | scrapi_receiver | | scrapi_sender | | | +---------+ | | | +--------->| Yellow |<---------+ | | +---------+ | | | | RESV RESV or CONFIRM | CONFIRM | | | | | V | | +---------+ | +---------------------->| Green |<----------------------+ +--------->| |<---------+ | +---------+ | | | | | | PATH RESV | | ERROR ERROR | RESV | | CONFIRM | V V | | +---------+ +---------+ | +---| Red | | Red |---+ +---------+ +---------+ Figure 2: SCRAPI Error Model State Diagram Lindell Expiration: August 1999 [Page 7]
INTERNET-DRAFT SCRAPI v.2 February 1998 4. A Comparison to RAPI In this section, a brief comparison of SCRAPI and RAPI are provided in outline form. o SCRAPI is entirely flow based, there is no concept of a session. Calls to RAPI session operations are internally hidden by the sender, receiver, and close operations. o The SCRAPI sender command is simplified by not requiring sender templates or flow specifications. These are constructed internally based on a single bandwidth parameter provided. A RAPI based application has more control over specifying the contents of sender templates and flow specifications. o The SCRAPI receiver command is simplified by not requiring filter or flow specifications. These are constructed internally based on the sender templates and flow specifications received in a PATH message. In addition, the receiver command may be called prior to the receipt of any PATH messages without causing an error. A RAPI based application has more control over specifying the contents of filter and flow specifications, including making a reservation for an amount different than the senders flow specification. o A default SCRAPI callback function is defined to process RSVP messages. It supports automatic responses to PATH messages given prior information from a receiver call. It also maintains state for the simplified SCRAPI error model described in the previous section. A RAPI based application can define an arbitrary callback function which might implement a complex error model and contain functionality to perform QoS negotiation. 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. Lindell Expiration: August 1999 [Page 8]
INTERNET-DRAFT SCRAPI v.2 February 1998 5. Application Programming Interface Definition The section describes the functions of the SCRAPI API. It includes the error reporting capabilities and the asynchronous event support. 5.1. Reservation API Description Function Name: scrapi_sender Syntax: int scrapi_sender( const struct sockaddr *destination, int protocol, const struct sockaddr *source, double bw, unsigned long msecs ); Description: SCRAPI call for a data sender. The destination address, protocol number, and the source address of the data flow are supplied as the first three arguments. The source address may be wild, but a non-wild port must be provided. The bw parameter is the average bandwidth of the flow in bytes/sec. 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 address, protocol number, and source address). A value of 0 for the bw parameter unregisters a sender for this data flow. Return Values: TRUE if successful, FALSE otherwise. Unsuccessful operations will set an appropriate error code. Also See: scrapi_errno, scrapi_get_status Lindell Expiration: August 1999 [Page 9]
INTERNET-DRAFT SCRAPI v.2 February 1998 Function Name: scrapi_receiver Syntax: int scrapi_receiver( const struct sockaddr *destination, int protocol, const struct sockaddr *source, int reserve, scrapi_service service, scrapi_style style, unsigned long msecs ); Description: SCRAPI call for a data receiver. The destination address, protocol number, and the source address of the data flow are supplied as the first three arguments. The source address can be set to NULL to choose any source. In addition, the source address can be specified with a wild port number of 0 to match a source address regardless of port number. Wild port number requests take precedence over any source requests. The reserve parameter should be set to TRUE or FALSE to turn on and off a reservation for that data flow respectively. The service parameter specifies the service, currently either Controlled Load or Guaranteed. 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 including removing a reservation request. Return Values: TRUE if successful, FALSE otherwise. Unsuccessful operations will set an appropriate error code. Also See: scrapi_errno, scrapi_get_status Lindell Expiration: August 1999 [Page 10]
INTERNET-DRAFT SCRAPI v.2 February 1998 Function Name: scrapi_close Syntax: int scrapi_close( const struct sockaddr *destination, int protocol, const struct sockaddr *source ); Description: SCRAPI call to close a flow for sending and receiving. If the destination address is set to NULL, all flows will be closed and the other parameter values will be ignored. If the source address is set to NULL, the close applies to all possible sources. Return Values: TRUE if successful, FALSE otherwise. Unsuccessful operations will set an appropriate error code. Also See: scrapi_errno, scrapi_get_status 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. 5.2. Error Handling API Description Lindell Expiration: August 1999 [Page 11]
INTERNET-DRAFT SCRAPI v.2 February 1998 The section describes the error reporting functions of the SCRAPI API. Function Name: scrapi_get_status Syntax: scrapi_status scrapi_get_status( const struct sockaddr *destination, int protocol, const struct sockaddr *source ); 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. If the source address is set to NULL, a yellow status indicates that the flow is valid but no reservation operation(s) as a sender or receiver has completed successfully. Once a single reservation completion has been detected for either a sender or receiver, the flow has a green status. If the source address is not set to NULL, the status applies only to the receiver for the specified source. Thus, if an application is both a sender and receiver for a the given flow, any relevant sender status information is ignored. Return Values: scrapi_status_red, scrapi_status_yellow, or scrapi_status_green. Lindell Expiration: August 1999 [Page 12]
INTERNET-DRAFT SCRAPI v.2 February 1998 Function Name: scrapi_errno Syntax: int scrapi_errno( const struct sockaddr *destination, int protocol, const struct sockaddr *source ); Description: Set to the errno value of the last SCRAPI call for a given flow. Must be called with identical arguments given in a preceding SCRAPI function. Since failed SCRAPI functions may not have created a flow, or caused the closure of a flow, the errno may be transitory and should be observed immediately after the failure. Also See: scrapi_perror, scrapi_errlist Function Name: scrapi_perror Syntax: void scrapi_perror( const struct sockaddr *destination, int protocol, const struct sockaddr *source, const char *string ); Description: SCRAPI call to print an error message analogous to the perror() library call. Also See: scrapi_errno, scrapi_errlist Lindell Expiration: August 1999 [Page 13]
INTERNET-DRAFT SCRAPI v.2 February 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. Also See: scrapi_errno, scrapi_perror 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. Lindell Expiration: August 1999 [Page 14]
INTERNET-DRAFT SCRAPI v.2 February 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. 5.3. Asynchronous Event Loop API Description The section describes the asynchronous event functions of the SCRAPI API. Function Name: scrapi_poll_list Syntax: void scrapi_poll_list( fdset *set ); Description: SCRAPI call to get all API file descriptors to use in a subsequent select call. 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. 6. Application Code Templates This section provides examples, presented as code templates, to aid programmers in augmenting networking applications with SCRAPI calls. Lindell Expiration: August 1999 [Page 15]
INTERNET-DRAFT SCRAPI v.2 February 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. 6.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. 6.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: August 1999 [Page 16]
INTERNET-DRAFT SCRAPI v.2 February 1998 #include <scrapi.h> #define SAP(x) ((struct sockaddr *) (x)) void main(int argc, char *argv[]) { int fd,len; int timeout = 10000; /* wait for at most 10 seconds */ double bw = 1000; /* Average bandwidth 1Kbytes/sec */ struct SOCKADDR destination,source; scrapi_status status; char *hostname = 'receive-hostname'; unsigned short port = 1111; /* translate host name or address */ if (!scrapi_sockaddr_parse(SAP(&destination),hostname, htons(port))) { fprintf(stderr,'Could not parse host address'); exit(1); } /* open, bind, and connect */ /* fd = socket(...); */ len = sizeof(source); if (getsockname(fd,SAP(&source),&len) == -1) { perror('getsockname'); exit(1); } /* make an RSVP based reservation */ if (!scrapi_sender(SAP(&destination),IPPROTO_TCP,SAP(&source), bw,0,timeout)) scrapi_perror(SAP(&destination),IPPROTO_TCP,SAP(&source), 'RSVP unable to reserve bandwidth'); status = scrapi_get_status(SAP(&destination),IPPROTO_TCP,NULL); /* run test */ if (status == scrapi_status_green) { status = scrapi_get_status(SAP(&destination),IPPROTO_TCP, NULL); if (status != scrapi_status_green) fprintf(stderr, 'RSVP reservation lost during test!'); } scrapi_close(NULL,0,0); } Lindell Expiration: August 1999 [Page 17]
INTERNET-DRAFT SCRAPI v.2 February 1998 6.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. #include <scrapi.h> #define SAP(x) ((struct sockaddr *) (x)) 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,SAP(&destination),&len) == -1) { perror('getsockname'); exit(1); } /* make an RSVP based reservation */ if (!scrapi_receiver(SAP(&destination),IPPROTO_TCP,NULL,1, scrapi_service_cl,scrapi_style_distinct,timeout)) scrapi_perror(SAP(&destination),IPPROTO_TCP,NULL, 'RSVP unable to reserve bandwidth'); /* run test */ scrapi_close(NULL,0,0); } 6.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: August 1999 [Page 18]
INTERNET-DRAFT SCRAPI v.2 February 1998 #include <tcl.h> #include <tk.h> #include <scrapi.h> #define SAP(x) ((struct sockaddr *) (x)) void callback(ClientData data, int mask) { if (!scrapi_dispatch()) Tk_DeleteFileHandler(data); } void main(int argc, char *argv[]) { int i,fd,len; fd_set set; struct SOCKADDR destination,source; double bw = 1000; /* Average bandwidth 1Kbytes/sec */ char *hostname = 'receive-hostname'; unsigned short port = 1111; /* translate host name or address */ if (!scrapi_sockaddr_parse(SAP(&destination),hostname, htons(port))) { fprintf(stderr,'Could not parse host address'); exit(1); } len = sizeof(source); if (getsockname(fd,SAP(&source),&len) == -1) { perror('getsockname'); exit(1); } /* make an RSVP based reservation */ if (!scrapi_sender(SAP(&destination),IPPROTO_UDP,SAP(&source), bw,0,0)) scrapi_perror(SAP(&destination),IPPROTO_UDP,SAP(&source), 'RSVP unable to reserve bandwidth'); if (!scrapi_receiver(SAP(&destination),IPPROTO_UDP,SAP(&source), 1,scrapi_service_cl,scrapi_style_distinct,0)) scrapi_perror(SAP(&destination),IPPROTO_UDP,SAP(&source), 'RSVP unable to reserve bandwidth'); scrapi_poll_list(&set); for (i = 0;i < FD_SETSIZE; i++) { if (!FD_ISSET(i,&set)) Lindell Expiration: August 1999 [Page 19]
INTERNET-DRAFT SCRAPI v.2 February 1998 continue; Tk_CreateFileHandler((ClientData) i,TK_READABLE, callback,(ClientData) i); } /* send data */ scrapi_close(NULL,0,0); } 7. Conclusion 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. 8. Security Considerations Security considerations are not discussed in this memo. 9. Acknowledgements The author would like to thank Steve Berson for helping to define this API. I would also like to thank Bob Braden for his help in improving the definition of the API and corresponding documentation. 10. 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. Lindell Expiration: August 1999 [Page 20]
INTERNET-DRAFT SCRAPI v.2 February 1998 [4] Wroclawski, J., Specification of the Controlled Load Quality of Service, RFC 2211, September 1997. [5] Berger, L., O'Malley, T., RSVP Extensions for IPSEC Data Flows, RFC 2207, September 1997. 11. Author's Address Bob Lindell USC Information Sciences Institute 4676 Admiralty Way Marina del Rey, CA 90292 12. Appendix 1: Address Manipulation API Description These are utility functions to ease the development of an interface which supports IPv4 and IPv6. These are not viewed as part of the SCRAPI API, but rather a collection of useful address manipulation functions which should be provided in system libraries. In the future, these functions will be removed in favor of system supplied functionality. 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. Lindell Expiration: August 1999 [Page 21]
INTERNET-DRAFT SCRAPI v.2 February 1998 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. Function Name: scrapi_sockaddr_get_addr Syntax: int scrapi_sockaddr_get_addr( const struct sockaddr *address, char *addr ); Description: Store the address field of the sockaddr structure to a network order binary representation of an address which starts at the memory location specified. Return Values: TRUE if successful, FALSE otherwise. Lindell Expiration: August 1999 [Page 22]
INTERNET-DRAFT SCRAPI v.2 February 1998 Function Name: scrapi_sockaddr_set_addr Syntax: int scrapi_sockaddr_set_addr( struct sockaddr *address, char *addr ); Description: Load the address field of the sockaddr structure from a network order binary representation of an address which starts at the memory location specified. Return Values: TRUE if successful, FALSE otherwise. 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. Lindell Expiration: August 1999 [Page 23]
INTERNET-DRAFT SCRAPI v.2 February 1998 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. Function Name: scrapi_sockaddr_length Syntax: int scrapi_sockaddr_length( struct sockaddr *address ); Description: Return the length of a struct sockaddr for the given address family. Return Values: The length if successful, 0 otherwise. Lindell Expiration: August 1999 [Page 24]
INTERNET-DRAFT SCRAPI v.2 February 1998 Table of Contents 1. Introduction ................................................... 2 2. Functional Description ......................................... 3 3. The Simplified Error Model of SCRAPI ........................... 5 4. A Comparison to RAPI ........................................... 8 5. Application Programming Interface Definition ................... 9 5.1. Reservation API Description .................................. 9 5.2. Error Handling API Description ............................... 11 5.3. Asynchronous Event Loop API Description ...................... 15 6. Application Code Templates ..................................... 15 6.1. Unicast Performance Measurement Application .................. 16 6.1.1. Sender Application ......................................... 16 6.1.2. Receiver Application ....................................... 18 6.2. Multicast Multimedia Application ............................. 18 7. Conclusion ..................................................... 20 8. Security Considerations ........................................ 20 9. Acknowledgements ............................................... 20 10. References .................................................... 20 11. Author's Address .............................................. 21 12. Appendix 1: Address Manipulation API Description .............. 21 Lindell Expiration: August 1999 [Page 25]