idnits 2.17.1 draft-lindell-rsvp-scrapi-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-26) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. ** The document is more than 15 pages and seems to lack a Table of Contents. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Abstract section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 536 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- Couldn't find a document date in the document -- date freshness check skipped. -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Possible downref: Non-RFC (?) normative reference: ref. '2' Summary: 11 errors (**), 0 flaws (~~), 1 warning (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT Bob Lindell 3 Expiration: May 1999 ISI 4 File: draft-lindell-rsvp-scrapi-01.txt 6 SCRAPI - A Simple "Bare Bones" API for RSVP 8 Version 2 10 November 17, 1998 12 Status of this Memo 14 This document is an Internet-Draft. Internet-Drafts are 15 working documents of the Internet Engineering Task Force 16 (IETF), its areas, and its working groups. Note that other 17 groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six 21 months and may be updated, replaced, or obsoleted by other 22 documents at any time. It is inappropriate to use Internet- 23 Drafts as reference material or to cite them other than as 24 "work in progress." 26 To view the entire list of current Internet-Drafts, please 27 check the "1id-abstracts.txt" listing contained in the 28 Internet-Drafts Shadow Directories on ftp.is.co.za (Africa), 29 ftp.nordu.net (Northern Europe), ftp.nis.garr.it (Southern 30 Europe), munnari.oz.au (Pacific Rim), ftp.ietf.org (US East 31 Coast), or ftp.isi.edu (US West Coast). 33 Abstract 35 This document describes SCRAPI, a simple "bare bones" API for 36 RSVP. The goal of this API is to produce an interface which 37 simplifies the augmentation of applications with RSVP support. 39 1. Introduction 41 This document describes SCRAPI, a simple "Bare Bones" API for RSVP [1]. 42 The goal of this API is produce an interface which simplifies the 43 augmentation of applications with RSVP support. The main features of 44 SCRAPI are: 46 o Allow the addition of RSVP support to applications by adding a 47 few lines of code. 49 o Provide a portable interface which can be used with any 50 vendor's RAPI implementation. 52 o Avoid the introduction of RSVP specific data types and 53 definitions. 55 o Support IPv4 and IPv6 in a transparent manner. 57 SCRAPI is layered on top of RAPI [2], an existing RSVP API, to provide 58 portability across vendor implementations. Currently, SCRAPI has been 59 tested only with the ISI implementation of RAPI. 61 To provide simplicity, event upcalls to the application do not exist in 62 SCRAPI. Because of the design choice, it may be difficult to use SCRAPI 63 for applications which negotiate QoS with the network. Applications 64 requiring this type of functionality should use the standard RAPI 65 interface. 67 There are three main functions included in this API, one which is used 68 by the sender side, one to be used at the receiving end, and a function 69 to finalize the entire API at the end of execution. This simple API 70 should be easy to insert into networking applications which require RSVP 71 support. 73 Error reporting is handled in two distinct forms. The first is an 74 aggregated error model that is unique to SCRAPI. SCRAPI includes a 75 tri-valued error model with error states of "red", "yellow", or "green". 76 This model gives feedback to an application on the status of 77 reservations at an given time. The exact description of each error 78 state will be described below. Second, it is possible to get an error 79 number and corresponding error description after executing a SCRAPI 80 sender, receiver, or close function. This is similar to the errno 81 support in Unix. These error codes are of limited use, since they only 82 provide feedback on an immediate failure of a request. This is most 83 likely due to invalid arguments or some general system error. A timeout 84 errno is returned if a timer expires on the sender or receiver calls. A 85 timeout error does not abort the request, it is merely an indication 86 that the timer has expired. Applications can abort a request following 87 a timeout by closing the flow. 89 There is support for applications which have polling based event loops 90 using a system call such as select. Analogous functions to the RAPI 91 interface for supporting this functionality is provided in SCRAPI. 93 The remaining functions in the API are utility functions to ease the 94 development of an interface which supports IPv4 and IPv6. These are 95 documented in Appendix 1. These functions are not viewed as part of the 96 SCRAPI API, but rather a collection of useful address manipulation 97 functions which should be provided in system libraries. In the future, 98 these functions will be removed in favor of system supplied 99 functionality. The objective of these extensions was to provide enough 100 functionality so that applications would not need to code explicitly for 101 either IPv4 or IPv6, or use messy compilation conditionals to develop an 102 interface to support both address families. As an example, a single 103 data type for addresses is provided that is large enough to hold 104 addresses from either address family. In addition, parsing an address 105 string or performing a host name resolution for both address families is 106 provided. 108 2. Functional Description 110 The basic abstraction for the SCRAPI API is a flow. A flow is defined 111 in terms of three parameters: the destination address, a protocol 112 number, and the source address. This triple is used for the sender, 113 receiver, status, and close operations in SCRAPI. 115 Applications which use SCRAPI get a simplied service model. The average 116 bandwidth specified by the sender is currently translated into the 117 integrated services controlled load [4] or guaranteed service [3] with 118 the given average bandwidth. The peak bandwidth and token bucket depth 119 are set to twice the average bandwidth. Minimum policed unit and 120 maximum packet size are set to 64 bytes and the largest MTU of all IP 121 interfaces on the host. 123 Sender and receiver side API calls can block, if requested, until a 124 reservation request has completed. The notion of completion can be 125 difficult to define for multicast flows. We will define completion in 126 the content of SCRAPI calls to refer to either partial or full 127 completion of the reservation request. 129 A sender sources PATH messages using the Tspec described above. If 130 blocking is requested with a non-zero timeout value, the sender blocks 131 until the receipt of a single RESV event from any sender. If the 132 specified flow is unicast, the call blocks until the reservation has 133 completed. If the flow is multicast, then at least one receiver has a 134 reservation in place when the call unblocks. 136 A receiver waits for a PATH event from the sender, and if requested, 137 makes a reservation in response using the sender's Tspec and Adspec for 138 guaranteed service. For guaranteed service, the slack term is set to 139 zero. If blocking is requested, the receiver blocks until the receipt 140 of a CONFIRM event. 142 If any RSVP errors occur during a blocking sender or receiver API call, 143 the call will unblock. 145 Internal to SCRAPI, there is support for both IPv6 Flow Labels and the 146 Generalized Port Identifier (GPI) [5]. These are not visible at the 147 API. It is assumed that applications would continue to use port numbers 148 to specify flows and that SCRAPI internally would convert these port 149 numbers to either a Flow Label or a GPI value using system supplied 150 functionality. 152 A state diagram of the SCRAPI reservation API, for a given data flow, is 153 shown in Figure 1. A sender call subscripted with zero designates a 154 sender call with the bandwidth set to zero. Similarly, a receiver call 155 subscripted with zero designates a receiver call with the reservation 156 flag set to FALSE. 158 +---------+ 159 +----------| Closed |----------+ 160 scrapi_sender +---------+ scrapi_receiver 161 | | 162 scrapi_sender | | scrapi_receiver 163 +----+ | | +----+ 164 | V V V V | 165 | +---------+ +---------+ | 166 +---| | | |---+ 167 | Send | | Rcv | 168 +-------| |<-----+ +----->| |-------+ 169 | +---------+ | | +---------+ | 170 | | | | | | 171 | |scrapi_receiver(0) | | | 172 | | | | | | 173 | | | scrapi_sender(0)| | 174 | | | | | | 175 | scrapi_receiver | | scrapi_sender | 176 | | +---------+ | | 177 | +--------->| |<---------+ | 178 | | SendRcv | | 179 | scrapi_sender or +---| | | 180 | scrapi_receiver | +---------+ | 181 | | ^ | | 182 | +----+ | | 183 | | | 184 scrapi_close or scrapi_close scrapi_close or 185 scrapi_sender(0) | scrapi_receiver(0) 186 | V | 187 | +---------+ | 188 +---------------------->| Closed |<----------------------+ 189 +---------+ 191 Figure 1: SCRAPI API State Diagram 193 3. The Simplified Error Model of SCRAPI 195 SCRAPI provides a simple error status reporting on a per flow basis. 196 Status can be in a "red", "yellow", or "green" state. The red state 197 indicates that either the flow does not exist or is currently in an 198 error state. Yellow state indicates that the reservation requests are 199 pending, whereas green indicates that at least one request has 200 completed. 202 A state diagram of the SCRAPI error model, for a given data flow, is 203 shown in Figure 2. A close operation takes the model from any state 204 back to the red state. This was intentionally omitted to increase the 205 clarity of the diagram. 207 RSVP error reporting to an application is inherently ambiguous. Once an 208 error message has been received, it is not always possible to determine 209 when an error condition has cleared. With global knowledge, a solution 210 would be to wait until enough time has expired relative to the refresh 211 rates, and link reliability assumptions along a path, to assume that the 212 lack of any subsequent error message is an indication that an error has 213 cleared. Unfortunately, this information about refresh rates at any 214 given point in the path is unknown to applications. The solution in 215 SCRAPI is an attempt to match error messages with the receipt of other 216 messages that could be used to indicate the clearing of a given error. 217 For example, a CONFIRM message received subsequent to a RESV ERROR 218 message might indicate that the error condition has cleared. A side 219 effect of the solution is that error message refreshing will cause 220 oscillatory behavior of the error model. Also, the error model may get 221 stuck in a error state unless a complementary message is received to 222 clear the error. 224 Multicast only makes the problem worse. An application could be 225 receiving refreshes of a PATH ERROR message from one branch of the 226 multicast tree and RESV messages from another branch. Should the error 227 state of this model be red or green? If we choose green, which is not 228 entirely correct, it will oscillate into the red state when refreshes of 229 the PATH ERROR are received. 231 RSVP CONFIRM messages are not delivered reliably. SCRAPI should 232 probably include a reliability model for confirmations so that the error 233 model does not get stuck in a non-green state due to the loss of a 234 CONFIRM message. In addition, for a multicast flow, a CONFIRM message 235 can be a unreliable indication that a reservation has been successful. 237 +---------+ 238 +----------| Red |----------+ 239 scrapi_sender +---------+ scrapi_receiver 240 | | 241 V V 242 +---------+ +---------+ 243 +-------| Yellow |<-----+ +----->| Yellow |-------+ 244 | +---------+ | | +---------+ | 245 | | | | | | 246 | |scrapi_receiver(0) | | | 247 | | | | | | 248 | | | scrapi_sender(0)| | 249 | | | | | | 250 | scrapi_receiver | | scrapi_sender | 251 | | +---------+ | | 252 | +--------->| Yellow |<---------+ | 253 | +---------+ | 254 | | | 255 RESV RESV or CONFIRM 256 | CONFIRM | 257 | | | 258 | V | 259 | +---------+ | 260 +---------------------->| Green |<----------------------+ 261 +--------->| |<---------+ 262 | +---------+ | 263 | | | | 264 | PATH RESV | 265 | ERROR ERROR | 266 RESV | | CONFIRM 267 | V V | 268 | +---------+ +---------+ | 269 +---| Red | | Red |---+ 270 +---------+ +---------+ 272 Figure 2: SCRAPI Error Model State Diagram 274 4. A Comparison to RAPI 276 In this section, a brief comparison of SCRAPI and RAPI are provided in 277 outline form. 279 o SCRAPI is entirely flow based, there is no concept of a 280 session. Calls to RAPI session operations are internally 281 hidden by the sender, receiver, and close operations. 283 o The SCRAPI sender command is simplified by not requiring 284 sender templates or flow specifications. These are 285 constructed internally based on a single bandwidth parameter 286 provided. A RAPI based application has more control over 287 specifying the contents of sender templates and flow 288 specifications. 290 o The SCRAPI receiver command is simplified by not requiring 291 filter or flow specifications. These are constructed 292 internally based on the sender templates and flow 293 specifications received in a PATH message. In addition, the 294 receiver command may be called prior to the receipt of any 295 PATH messages without causing an error. A RAPI based 296 application has more control over specifying the contents of 297 filter and flow specifications, including making a reservation 298 for an amount different than the senders flow specification. 300 o A default SCRAPI callback function is defined to process RSVP 301 messages. It supports automatic responses to PATH messages 302 given prior information from a receiver call. It also 303 maintains state for the simplified SCRAPI error model 304 described in the previous section. A RAPI based application 305 can define an arbitrary callback function which might 306 implement a complex error model and contain functionality to 307 perform QoS negotiation. 309 In the next section, the SCRAPI application programming interface 310 is defined. In subsequent sections, usage examples are offered as 311 templates for programmers who are attempting to embed SCRAPI calls 312 into existing applications. 314 5. Application Programming Interface Definition 316 The section describes the functions of the SCRAPI API. It includes the 317 error reporting capabilities and the asynchronous event support. 319 5.1. Reservation API Description 321 Function Name: scrapi_sender 323 Syntax: int scrapi_sender( 325 const struct sockaddr *destination, 326 int protocol, 327 const struct sockaddr *source, 328 double bw, 329 int ttl, 330 unsigned long msecs 332 ); 334 Description: SCRAPI call for a data sender. The destination address, 335 protocol number, and the source address of the data flow 336 are supplied as the first three arguments. The source 337 address may be wild, but a non-wild port must be 338 provided. The bw parameter is the average bandwidth of 339 the flow in bytes/sec. The ttl of the packets can be 340 specified or set to 0 to choose the system default. If 341 msecs is greater than 0, the call to scrapi_sender blocks 342 msecs milliseconds to receive a reservation event from at 343 least one recipient. The call will also unblock 344 prematurely if any errors are detected during this 345 period. This function can be called repeatedly by an 346 application to modify any parameters associated with this 347 data flow (same destination address, protocol number, and 348 source address). A value of 0 for the bw parameter 349 unregisters a sender for this data flow. 351 Return Values: TRUE if successful, FALSE otherwise. Unsuccessful 352 operations will set an appropriate error code. 354 Also See: scrapi_errno, scrapi_get_status 355 Function Name: scrapi_receiver 357 Syntax: int scrapi_receiver( 359 const struct sockaddr *destination, 360 int protocol, 361 const struct sockaddr *source, 362 int reserve, 363 scrapi_service service, 364 scrapi_style style, 365 unsigned long msecs 367 ); 369 Description: SCRAPI call for a data receiver. The destination 370 address, protocol number, and the source address of the 371 data flow are supplied as the first three arguments. The 372 source address can be set to NULL to choose any source. 373 In addition, the source address can be specified with a 374 wild port number of 0 to match a source address 375 regardless of port number. Wild port number requests 376 take precedence over any source requests. The reserve 377 parameter should be set to TRUE or FALSE to turn on and 378 off a reservation for that data flow respectively. The 379 service parameter specifies the service, currently either 380 Controlled Load or Guaranteed. The style parameter 381 specifies whether the reservation is shared among 382 multiple senders. If msecs is greater than 0, the call 383 to scrapi_receiver blocks msecs milliseconds to receive a 384 reservation confirmation event. The call will also 385 unblock prematurely if any errors are detected during 386 this period. This function can be called repeatedly by 387 an application to modify any parameters associated with 388 this data flow including removing a reservation request. 390 Return Values: TRUE if successful, FALSE otherwise. Unsuccessful 391 operations will set an appropriate error code. 393 Also See: scrapi_errno, scrapi_get_status 394 Function Name: scrapi_close 396 Syntax: int scrapi_close( 398 const struct sockaddr *destination, 399 int protocol, 400 const struct sockaddr *source 402 ); 404 Description: SCRAPI call to close a flow for sending and receiving. 405 If the destination address is set to NULL, all flows will 406 be closed and the other parameter values will be ignored. 407 If the source address is set to NULL, the close applies 408 to all possible sources. 410 Return Values: TRUE if successful, FALSE otherwise. Unsuccessful 411 operations will set an appropriate error code. 413 Also See: scrapi_errno, scrapi_get_status 415 Enum Name: scrapi_service 417 1. scrapi_service_cl 419 2. scrapi_service_gs 421 Description: Enumerated types for specificing the desired service. 422 Currently, Integrated Services Controlled Load and 423 Guaranteed are supported. 425 Enum Name: scrapi_style 427 1. scrapi_style_shared 429 2. scrapi_style_distinct 431 Description: Enumerated types for specificing the reservation style. 432 Currently, shared (wildcard) and distinct styles are 433 supported. 435 5.2. Error Handling API Description 436 The section describes the error reporting functions of the SCRAPI API. 438 Function Name: scrapi_get_status 440 Syntax: scrapi_status scrapi_get_status( 442 const struct sockaddr *destination, 443 int protocol, 444 const struct sockaddr *source 446 ); 448 Description: SCRAPI call to get the status of a flow. If the status 449 is red, either the flow was never defined or the flow is 450 currently in an error state. If the source address is 451 set to NULL, a yellow status indicates that the flow is 452 valid but no reservation operation(s) as a sender or 453 receiver has completed successfully. Once a single 454 reservation completion has been detected for either a 455 sender or receiver, the flow has a green status. If the 456 source address is not set to NULL, the status applies 457 only to the receiver for the specified source. Thus, if 458 an application is both a sender and receiver for a the 459 given flow, any relevant sender status information is 460 ignored. 462 Return Values: scrapi_status_red, scrapi_status_yellow, or 463 scrapi_status_green. 465 Function Name: scrapi_errno 467 Syntax: int scrapi_errno( 469 const struct sockaddr *destination, 470 int protocol, 471 const struct sockaddr *source 473 ); 475 Description: Set to the errno value of the last SCRAPI call for a 476 given flow. Must be called with identical arguments 477 given in a preceding SCRAPI function. Since failed 478 SCRAPI functions may not have created a flow, or caused 479 the closure of a flow, the errno may be transitory and 480 should be observed immediately after the failure. 482 Also See: scrapi_perror, scrapi_errlist 484 Function Name: scrapi_perror 486 Syntax: void scrapi_perror( 488 const struct sockaddr *destination, 489 int protocol, 490 const struct sockaddr *source, 491 const char *string 493 ); 495 Description: SCRAPI call to print an error message analogous to the 496 perror() library call. 498 Also See: scrapi_errno, scrapi_errlist 499 Function Name: scrapi_errlist 501 Syntax: const char * scrapi_errlist( 503 int errno 505 ); 507 Description: SCRAPI call to get an error message string for a given 508 errno. 510 Return Values: An error message string. 512 Also See: scrapi_errno, scrapi_perror 514 Function Name: scrapi_stderr 516 Syntax: void scrapi_stderr( 518 FILE *file 520 ); 522 Description: Set the file pointer to be used by the SCRAPI library for 523 standard error. If it is set to NULL, no messages are 524 printed. The default value is stderr. 526 Function Name: scrapi_debug 528 Syntax: void scrapi_debug( 530 FILE *file 532 ); 534 Description: Set the file pointer to be used by the SCRAPI library for 535 debugging information. If it is set to NULL, no messages 536 are printed. Debug messages include the logging of all 537 asynchronous RSVP events. The default value is NULL. 539 Enum Name: scrapi_status 541 1. scrapi_status_red 543 2. scrapi_status_yellow 545 3. scrapi_status_green 547 Description: Enumerated types for status condition of a flow. The 548 meaning of these values is described in the 549 scrapi_status() function description. 551 5.3. Asynchronous Event Loop API Description 553 The section describes the asynchronous event functions of the SCRAPI 554 API. 556 Function Name: scrapi_poll_list 558 Syntax: void scrapi_poll_list( 560 fdset *set 562 ); 564 Description: SCRAPI call to get all API file descriptors to use in a 565 subsequent select call. 567 Function Name: scrapi_dispatch 569 Syntax: int scrapi_dispatch(); 571 Description: SCRAPI call to poll the API for new events. 573 Return Values: TRUE if successful, FALSE if RSVP support is no longer 574 available. 576 6. Application Code Templates 578 This section provides examples, presented as code templates, to aid 579 programmers in augmenting networking applications with SCRAPI calls. 581 One example contains two simplex applications which attempt to wait for 582 a reservation to be put in place before sending data on the network. 583 The other example is a full duplex multimedia type application which 584 sends and receives data without waiting for completion of the 585 reservation. 587 6.1. Unicast Performance Measurement Application 589 The following example was derived from a network performance tool. It 590 attempts to put in place a unicast reservation before measuring network 591 performance. Waiting is accomplished using the timeout option in the 592 sender and receiver calls. 594 6.1.1. Sender Application 596 This sender application opens a TCP connection to the "receive-hostname" 597 on port 1111 and attempts to reserve 1000 bytes/sec of average 598 bandwidth. After waiting at most 10 seconds for a reservation to be put 599 in place, this application streams data to the receiver to measure 600 network performance and then closes the connection. 602 #include 604 #define SAP(x) ((struct sockaddr *) (x)) 606 void 607 main(int argc, char *argv[]) 608 { 609 int fd,len; 610 int timeout = 10000; /* wait for at most 10 seconds */ 611 double bw = 1000; /* Average bandwidth 1Kbytes/sec */ 612 struct SOCKADDR destination,source; 613 scrapi_status status; 615 char *hostname = "receive-hostname"; 616 unsigned short port = 1111; 618 /* translate host name or address */ 619 if (!scrapi_sockaddr_parse(SAP(&destination),hostname, 620 htons(port))) { 621 fprintf(stderr,"Could not parse host address"); 622 exit(1); 623 } 624 /* open, bind, and connect */ 625 /* fd = socket(...); */ 626 len = sizeof(source); 627 if (getsockname(fd,SAP(&source),&len) == -1) { 628 perror("getsockname"); 629 exit(1); 630 } 632 /* make an RSVP based reservation */ 633 if (!scrapi_sender(SAP(&destination),IPPROTO_TCP,SAP(&source), 634 bw,0,timeout)) 635 scrapi_perror(SAP(&destination),IPPROTO_TCP,SAP(&source), 636 "RSVP unable to reserve bandwidth"); 637 status = scrapi_get_status(SAP(&destination),IPPROTO_TCP,NULL); 639 /* run test */ 640 if (status == scrapi_status_green) { 641 status = scrapi_get_status(SAP(&destination),IPPROTO_TCP, 642 NULL); 643 if (status != scrapi_status_green) 644 fprintf(stderr, 645 "RSVP reservation lost during test!"); 646 } 647 scrapi_close(NULL,0,0); 648 } 649 6.1.2. Receiver Application 651 This receiver application accepts a TCP connection and attempts to make 652 a reservation. After waiting at most 10 seconds for a reservation to be 653 put in place, this application consumes data from the sender to measure 654 network performance and then closes the connection. 656 #include 658 #define SAP(x) ((struct sockaddr *) (x)) 660 void 661 main(int argc, char *argv[]) 662 { 663 int fd,len,timeout = 10000; /* wait for at most 10 seconds */ 664 struct SOCKADDR destination; 666 /* open, bind, and listen for connection */ 667 /* fd = accept(...); */ 668 len = sizeof(destination); 669 if (getsockname(fd,SAP(&destination),&len) == -1) { 670 perror("getsockname"); 671 exit(1); 672 } 674 /* make an RSVP based reservation */ 675 if (!scrapi_receiver(SAP(&destination),IPPROTO_TCP,NULL,1, 676 scrapi_service_cl,scrapi_style_distinct,timeout)) 677 scrapi_perror(SAP(&destination),IPPROTO_TCP,NULL, 678 "RSVP unable to reserve bandwidth"); 680 /* run test */ 681 scrapi_close(NULL,0,0); 682 } 684 6.2. Multicast Multimedia Application 686 This example highlights the inclusion of the SCRAPI API into a Tcl/Tk 687 event loop of a multimedia application. This is a full duplex 688 application that is sending and receiving data on the same address. 689 This application does not wait for completion status from the 690 reservation calls. 692 #include 693 #include 694 #include 696 #define SAP(x) ((struct sockaddr *) (x)) 698 void 699 callback(ClientData data, int mask) 700 { 701 if (!scrapi_dispatch()) 702 Tk_DeleteFileHandler(data); 703 } 705 void 706 main(int argc, char *argv[]) 707 { 708 int i,fd,len; 709 fd_set set; 710 struct SOCKADDR destination,source; 711 double bw = 1000; /* Average bandwidth 1Kbytes/sec */ 712 char *hostname = "receive-hostname"; 713 unsigned short port = 1111; 715 /* translate host name or address */ 716 if (!scrapi_sockaddr_parse(SAP(&destination),hostname, 717 htons(port))) { 718 fprintf(stderr,"Could not parse host address"); 719 exit(1); 720 } 721 len = sizeof(source); 722 if (getsockname(fd,SAP(&source),&len) == -1) { 723 perror("getsockname"); 724 exit(1); 725 } 727 /* make an RSVP based reservation */ 728 if (!scrapi_sender(SAP(&destination),IPPROTO_UDP,SAP(&source), 729 bw,0,0)) 730 scrapi_perror(SAP(&destination),IPPROTO_UDP,SAP(&source), 731 "RSVP unable to reserve bandwidth"); 732 if (!scrapi_receiver(SAP(&destination),IPPROTO_UDP,SAP(&source), 733 1,scrapi_service_cl,scrapi_style_distinct,0)) 734 scrapi_perror(SAP(&destination),IPPROTO_UDP,SAP(&source), 735 "RSVP unable to reserve bandwidth"); 736 scrapi_poll_list(&set); 737 for (i = 0;i < FD_SETSIZE; i++) { 738 if (!FD_ISSET(i,&set)) 739 continue; 740 Tk_CreateFileHandler((ClientData) i,TK_READABLE, 741 callback,(ClientData) i); 742 } 744 /* send data */ 745 scrapi_close(NULL,0,0); 746 } 748 7. Conclusion 750 The SCRAPI interface provides a simple method to add RSVP support to 751 many network applications. It supports both IPv4 and IPv6 and attempts 752 to simplify user developed code to support both address families. 753 Coding examples are provided to give additional guidance on the usage of 754 this API. 756 8. Security Considerations 758 Security considerations are not discussed in this memo. 760 9. Acknowledgements 762 The author would like to thank Steve Berson for helping to define this 763 API. I would also like to thank Bob Braden for his help in improving 764 the definition of the API and corresponding documentation. 766 10. References 768 [1] Braden, R., Ed., et. al., Resource Reservation Protocol (RSVP) - 769 Version 1 Functional Specification, RFC 2205, September 1997. 771 [2] Braden, R., Hoffman, D., RAPI -- An RSVP Application Programming 772 Interface Version 5, Work In Progress, November 1997. 774 [3] Shenker, S., Partridge, C., Guerin, R., Specification of Guaranteed 775 Quality of Service, RFC 2212, September 1997. 777 [4] Wroclawski, J., Specification of the Controlled Load Quality of 778 Service, RFC 2211, September 1997. 780 [5] Berger, L., O'Malley, T., RSVP Extensions for IPSEC Data Flows, RFC 781 2207, September 1997. 783 11. Author's Address 785 Bob Lindell 786 USC Information Sciences Institute 787 4676 Admiralty Way 788 Marina del Rey, CA 90292 790 12. Appendix 1: Address Manipulation API Description 792 These are utility functions to ease the development of an interface 793 which supports IPv4 and IPv6. These are not viewed as part of the 794 SCRAPI API, but rather a collection of useful address manipulation 795 functions which should be provided in system libraries. In the future, 796 these functions will be removed in favor of system supplied 797 functionality. 799 Macro Name: SOCKADDR 801 Description: A struct sockaddr data type that is large enough for both 802 IPv4 and IPv6 addresses. 804 Function Name: scrapi_sockaddr_multicast 806 Syntax: int scrapi_sockaddr_multicast( 808 const struct sockaddr *address 810 ); 812 Description: Determine if an address is multicast or unicast. 814 Return Values: TRUE if multicast, FALSE otherwise. 816 Function Name: scrapi_sockaddr_parse 818 Syntax: int scrapi_sockaddr_parse( 820 struct sockaddr *address 821 const char *name, 822 unsigned short port 824 ); 826 Description: Perform a host name lookup or parse an address and 827 initialize a struct sockaddr structure. 829 Return Values: TRUE if parsed, FALSE otherwise. 831 Function Name: scrapi_sockaddr_print 833 Syntax: const char * scrapi_sockaddr_print( 835 const struct sockaddr *address 837 ); 839 Description: Pretty print an address. 841 Return Values: A valid string if printable, NULL otherwise. 843 Function Name: scrapi_sockaddr_get_addr 845 Syntax: int scrapi_sockaddr_get_addr( 847 const struct sockaddr *address, 848 char *addr 850 ); 852 Description: Store the address field of the sockaddr structure to a 853 network order binary representation of an address which 854 starts at the memory location specified. 856 Return Values: TRUE if successful, FALSE otherwise. 858 Function Name: scrapi_sockaddr_set_addr 860 Syntax: int scrapi_sockaddr_set_addr( 862 struct sockaddr *address, 863 char *addr 865 ); 867 Description: Load the address field of the sockaddr structure from a 868 network order binary representation of an address which 869 starts at the memory location specified. 871 Return Values: TRUE if successful, FALSE otherwise. 873 Function Name: scrapi_sockaddr_get_port 875 Syntax: unsigned short scrapi_sockaddr_get_port( 877 const struct sockaddr *address 879 ); 881 Description: Get the port number. 883 Return Values: The port number if successful, 0 otherwise. 885 Function Name: scrapi_sockaddr_set_port 887 Syntax: int scrapi_sockaddr_set_port( 889 struct sockaddr *address, 890 unsigned short port 892 ); 894 Description: Set the port number. 896 Return Values: TRUE if successful, FALSE otherwise. 898 Function Name: scrapi_sockaddr_any 900 Syntax: int scrapi_sockaddr_any( 902 struct sockaddr *address, 903 int family 905 ); 907 Description: Initialize a struct sockaddr to the wildcard address and 908 port number for the given address family. 910 Return Values: TRUE if successful, FALSE otherwise. 912 Function Name: scrapi_sockaddr_length 914 Syntax: int scrapi_sockaddr_length( 916 struct sockaddr *address 918 ); 920 Description: Return the length of a struct sockaddr for the given 921 address family. 923 Return Values: The length if successful, 0 otherwise. 925 Table of Contents 927 1. Introduction ................................................... 2 928 2. Functional Description ......................................... 3 929 3. The Simplified Error Model of SCRAPI ........................... 5 930 4. A Comparison to RAPI ........................................... 7 931 5. Application Programming Interface Definition ................... 8 932 5.1. Reservation API Description .................................. 9 933 5.2. Error Handling API Description ............................... 11 934 5.3. Asynchronous Event Loop API Description ...................... 15 935 6. Application Code Templates ..................................... 15 936 6.1. Unicast Performance Measurement Application .................. 16 937 6.1.1. Sender Application ......................................... 16 938 6.1.2. Receiver Application ....................................... 18 939 6.2. Multicast Multimedia Application ............................. 18 940 7. Conclusion ..................................................... 20 941 8. Security Considerations ........................................ 20 942 9. Acknowledgements ............................................... 20 943 10. References .................................................... 20 944 11. Author's Address .............................................. 21 945 12. Appendix 1: Address Manipulation API Description .............. 21