idnits 2.17.1 draft-lindell-rsvp-scrapi-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. 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 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? ** 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 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 5 instances of too long lines in the document, the longest one being 1 character in excess of 72. 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.) -- The document date (February 26, 1999) is 9190 days in the past. Is this intentional? -- 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: 7 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: August 1999 ISI 4 File: draft-lindell-rsvp-scrapi-02.txt 6 SCRAPI - A Simple 'Bare Bones' API for RSVP 8 February 26, 1999 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance 13 with all provisions of Section 10 of RFC2026. 15 Internet-Drafts are working documents of the Internet 16 Engineering Task Force (IETF), its areas, and its working 17 groups. Note that other groups may also distribute working 18 documents as Internet-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 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt 29 The list of Internet-Draft Shadow Directories can be accessed 30 at http://www.ietf.org/shadow.html. 32 Abstract 34 This document describes SCRAPI, a simple 'bare bones' API for 35 RSVP. The goal of this API is to produce an interface which 36 simplifies the augmentation of applications with RSVP support. 38 1. Introduction 40 This document describes SCRAPI, a simple 'Bare Bones' API for RSVP [1]. 41 The goal of this API is produce an interface which simplifies the 42 augmentation of applications with RSVP support. The main features of 43 SCRAPI are: 45 o Allow the addition of RSVP support to applications by adding a 46 few lines of code. 48 o Provide a portable interface which can be used with any 49 vendor's RAPI implementation. 51 o Avoid the introduction of RSVP specific data types and 52 definitions. 54 o Support IPv4 and IPv6 in a transparent manner. 56 SCRAPI is layered on top of RAPI [2], an existing RSVP API, to provide 57 portability across vendor implementations. Currently, SCRAPI has been 58 tested only with the ISI implementation of RAPI. 60 To provide simplicity, event upcalls to the application do not exist in 61 SCRAPI. Because of the design choice, it may be difficult to use SCRAPI 62 for applications which negotiate QoS with the network. Applications 63 requiring this type of functionality should use the standard RAPI 64 interface. 66 There are three main functions included in this API, one which is used 67 by the sender side, one to be used at the receiving end, and a function 68 to finalize the entire API at the end of execution. This simple API 69 should be easy to insert into networking applications which require RSVP 70 support. 72 Error reporting is handled in two distinct forms. The first is an 73 aggregated error model that is unique to SCRAPI. SCRAPI includes a 74 tri-valued error model with error states of 'red', 'yellow', or 'green'. 75 This model gives feedback to an application on the status of 76 reservations at an given time. The exact description of each error 77 state will be described below. Second, it is possible to get an error 78 number and corresponding error description after executing a SCRAPI 79 sender, receiver, or close function. This is similar to the errno 80 support in Unix. These error codes are of limited use, since they only 81 provide feedback on an immediate failure of a request. This is most 82 likely due to invalid arguments or some general system error. A timeout 83 errno is returned if a timer expires on the sender or receiver calls. A 84 timeout error does not abort the request, it is merely an indication 85 that the timer has expired. Applications can abort a request following 86 a timeout by closing the flow. 88 There is support for applications which have polling based event loops 89 using a system call such as select. Analogous functions to the RAPI 90 interface for supporting this functionality is provided in SCRAPI. 92 The remaining functions in the API are utility functions to ease the 93 development of an interface which supports IPv4 and IPv6. These are 94 documented in Appendix 1. These functions are not viewed as part of the 95 SCRAPI API, but rather a collection of useful address manipulation 96 functions which should be provided in system libraries. In the future, 97 these functions will be removed in favor of system supplied 98 functionality. The objective of these extensions was to provide enough 99 functionality so that applications would not need to code explicitly for 100 either IPv4 or IPv6, or use messy compilation conditionals to develop an 101 interface to support both address families. As an example, a single 102 data type for addresses is provided that is large enough to hold 103 addresses from either address family. In addition, parsing an address 104 string or performing a host name resolution for both address families is 105 provided. 107 2. Functional Description 109 The basic abstraction for the SCRAPI API is a flow. A flow is defined 110 in terms of three parameters: the destination address, a protocol 111 number, and the source address. This triple is used for the sender, 112 receiver, status, and close operations in SCRAPI. 114 Applications which use SCRAPI get a simplied service model. The average 115 bandwidth specified by the sender is currently used for the integrated 116 services controlled load [4] or guaranteed service [3] token bucket rate 117 (r). The peak token bucket rate (p) is set to positive infinity and 118 token bucket depth (b) is set to twice the average bandwidth. Minimum 119 policed unit (m) and maximum packet size (M) are set to 64 bytes and the 120 largest MTU of all IP interfaces on the host. 122 Sender and receiver side API calls can block, if requested, until a 123 reservation request has completed. The notion of completion can be 124 difficult to define for multicast flows. We will define completion in 125 the content of SCRAPI calls to refer to either partial or full 126 completion of the reservation request. 128 A sender sources PATH messages using the Tspec described above. If 129 blocking is requested with a non-zero timeout value, the sender blocks 130 until the receipt of a single RESV event from any sender. If the 131 specified flow is unicast, the call blocks until the reservation has 132 completed. If the flow is multicast, then at least one receiver has a 133 reservation in place when the call unblocks. 135 A receiver waits for a PATH event from the sender, and if requested, 136 makes a reservation in response using the sender's Tspec and Adspec for 137 guaranteed service. For guaranteed service, the data rate (R) is set to 138 the maximum of all senders and the slack term (S) is set to zero. If 139 blocking is requested, the receiver blocks until the receipt of a 140 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 There are a number of difficulties in providing a simple, robust, 208 aggregated error model based on RSVP signaling information. These 209 issues are highlighted below as either 'long term' or 'short term' 210 stability issues. If the model provides 'long term' stability, it will 211 eventually report the currect status. There should be no terminal 212 states of the model that cause the reported status to remain fixed 213 without the ability to transition to a new state if conditions change. 214 If the model has 'short term' stability, it attempts to damp rapid 215 oscillations between states. 217 There are a few obstacles to 'long term' stability is the current error 218 reporting model for RSVP. Once an error message has been received, it 219 is not always possible to determine when an error condition has cleared. 220 If an application possessed global knowledge about refresh rates and 221 link reliability assumptions along a path, the solution would be to wait 222 until enough time has expired to assume that the lack of any subsequent 223 error message is an indication that an error has cleared. 224 Unfortunately, this information about refresh rates at any given point 225 in the path is unknown to applications. The solution in SCRAPI is an 226 attempt to match error messages with the receipt of other messages that 227 could be used to indicate the clearing of a given error. For example, a 228 CONFIRM message received subsequent to a RESV ERROR message might 229 indicate that the error condition has cleared. 231 For unicast, path errors can be paired with the complementary RESV 232 message to transition the error model between red and green. With 233 multicast, an application could be receiving refreshes of a PATH ERROR 234 message from one branch of the multicast tree and RESV messages from 235 another branch. Should the error state of this model be red or green? 237 RSVP CONFIRM messages are not delivered reliably. SCRAPI should 238 probably include a reliability model for confirmations so that the error 239 model does not get stuck in a non-green state due to the loss of a 240 CONFIRM message. This can be implemented by making repeated requests 241 for a CONFIRM message from the API. 243 There are also 'short term' stability issues that have not been 244 adequately addressed in SCRAPI. In the multicast example above, an 245 application could be receiving mixture of path errors and RESV messages 246 for the same flow. Since the error messages will continue to refresh, 247 this may cause oscillatory behavior of the error model. Similarly, RESV 248 errors can be received soon after a confirmation due to the merging 249 rules for RSVP. In both of these cases, it might be useful to add some 250 delay to state transitions in the error model. 252 It is anticipated that improvements to the design and implementation of 253 this error model will occur as we gain a better understanding of of the 254 use of RSVP with applications. 256 +---------+ 257 +----------| Red |----------+ 258 scrapi_sender +---------+ scrapi_receiver 259 | | 260 V V 261 +---------+ +---------+ 262 +-------| Yellow |<-----+ +----->| Yellow |-------+ 263 | +---------+ | | +---------+ | 264 | | | | | | 265 | |scrapi_receiver(0) | | | 266 | | | | | | 267 | | | scrapi_sender(0)| | 268 | | | | | | 269 | scrapi_receiver | | scrapi_sender | 270 | | +---------+ | | 271 | +--------->| Yellow |<---------+ | 272 | +---------+ | 273 | | | 274 RESV RESV or CONFIRM 275 | CONFIRM | 276 | | | 277 | V | 278 | +---------+ | 279 +---------------------->| Green |<----------------------+ 280 +--------->| |<---------+ 281 | +---------+ | 282 | | | | 283 | PATH RESV | 284 | ERROR ERROR | 285 RESV | | CONFIRM 286 | V V | 287 | +---------+ +---------+ | 288 +---| Red | | Red |---+ 289 +---------+ +---------+ 291 Figure 2: SCRAPI Error Model State Diagram 293 4. A Comparison to RAPI 295 In this section, a brief comparison of SCRAPI and RAPI are provided in 296 outline form. 298 o SCRAPI is entirely flow based, there is no concept of a 299 session. Calls to RAPI session operations are internally 300 hidden by the sender, receiver, and close operations. 302 o The SCRAPI sender command is simplified by not requiring 303 sender templates or flow specifications. These are 304 constructed internally based on a single bandwidth parameter 305 provided. A RAPI based application has more control over 306 specifying the contents of sender templates and flow 307 specifications. 309 o The SCRAPI receiver command is simplified by not requiring 310 filter or flow specifications. These are constructed 311 internally based on the sender templates and flow 312 specifications received in a PATH message. In addition, the 313 receiver command may be called prior to the receipt of any 314 PATH messages without causing an error. A RAPI based 315 application has more control over specifying the contents of 316 filter and flow specifications, including making a reservation 317 for an amount different than the senders flow specification. 319 o A default SCRAPI callback function is defined to process RSVP 320 messages. It supports automatic responses to PATH messages 321 given prior information from a receiver call. It also 322 maintains state for the simplified SCRAPI error model 323 described in the previous section. A RAPI based application 324 can define an arbitrary callback function which might 325 implement a complex error model and contain functionality to 326 perform QoS negotiation. 328 In the next section, the SCRAPI application programming interface 329 is defined. In subsequent sections, usage examples are offered as 330 templates for programmers who are attempting to embed SCRAPI calls 331 into existing applications. 333 5. Application Programming Interface Definition 335 The section describes the functions of the SCRAPI API. It includes the 336 error reporting capabilities and the asynchronous event support. 338 5.1. Reservation API Description 340 Function Name: scrapi_sender 342 Syntax: int scrapi_sender( 344 const struct sockaddr *destination, 345 int protocol, 346 const struct sockaddr *source, 347 double bw, 348 unsigned long msecs 350 ); 352 Description: SCRAPI call for a data sender. The destination address, 353 protocol number, and the source address of the data flow 354 are supplied as the first three arguments. The source 355 address may be wild, but a non-wild port must be 356 provided. The bw parameter is the average bandwidth of 357 the flow in bytes/sec. If msecs is greater than 0, the 358 call to scrapi_sender blocks msecs milliseconds to 359 receive a reservation event from at least one recipient. 360 The call will also unblock prematurely if any errors are 361 detected during this period. This function can be called 362 repeatedly by an application to modify any parameters 363 associated with this data flow (same destination address, 364 protocol number, and source address). A value of 0 for 365 the bw parameter unregisters a sender for this data flow. 367 Return Values: TRUE if successful, FALSE otherwise. Unsuccessful 368 operations will set an appropriate error code. 370 Also See: scrapi_errno, scrapi_get_status 371 Function Name: scrapi_receiver 373 Syntax: int scrapi_receiver( 375 const struct sockaddr *destination, 376 int protocol, 377 const struct sockaddr *source, 378 int reserve, 379 scrapi_service service, 380 scrapi_style style, 381 unsigned long msecs 383 ); 385 Description: SCRAPI call for a data receiver. The destination 386 address, protocol number, and the source address of the 387 data flow are supplied as the first three arguments. The 388 source address can be set to NULL to choose any source. 389 In addition, the source address can be specified with a 390 wild port number of 0 to match a source address 391 regardless of port number. Wild port number requests 392 take precedence over any source requests. The reserve 393 parameter should be set to TRUE or FALSE to turn on and 394 off a reservation for that data flow respectively. The 395 service parameter specifies the service, currently either 396 Controlled Load or Guaranteed. The style parameter 397 specifies whether the reservation is shared among 398 multiple senders. If msecs is greater than 0, the call 399 to scrapi_receiver blocks msecs milliseconds to receive a 400 reservation confirmation event. The call will also 401 unblock prematurely if any errors are detected during 402 this period. This function can be called repeatedly by 403 an application to modify any parameters associated with 404 this data flow including removing a reservation request. 406 Return Values: TRUE if successful, FALSE otherwise. Unsuccessful 407 operations will set an appropriate error code. 409 Also See: scrapi_errno, scrapi_get_status 410 Function Name: scrapi_close 412 Syntax: int scrapi_close( 414 const struct sockaddr *destination, 415 int protocol, 416 const struct sockaddr *source 418 ); 420 Description: SCRAPI call to close a flow for sending and receiving. 421 If the destination address is set to NULL, all flows will 422 be closed and the other parameter values will be ignored. 423 If the source address is set to NULL, the close applies 424 to all possible sources. 426 Return Values: TRUE if successful, FALSE otherwise. Unsuccessful 427 operations will set an appropriate error code. 429 Also See: scrapi_errno, scrapi_get_status 431 Enum Name: scrapi_service 433 1. scrapi_service_cl 435 2. scrapi_service_gs 437 Description: Enumerated types for specificing the desired service. 438 Currently, Integrated Services Controlled Load and 439 Guaranteed are supported. 441 Enum Name: scrapi_style 443 1. scrapi_style_shared 445 2. scrapi_style_distinct 447 Description: Enumerated types for specificing the reservation style. 448 Currently, shared (wildcard) and distinct styles are 449 supported. 451 5.2. Error Handling API Description 452 The section describes the error reporting functions of the SCRAPI API. 454 Function Name: scrapi_get_status 456 Syntax: scrapi_status scrapi_get_status( 458 const struct sockaddr *destination, 459 int protocol, 460 const struct sockaddr *source 462 ); 464 Description: SCRAPI call to get the status of a flow. If the status 465 is red, either the flow was never defined or the flow is 466 currently in an error state. If the source address is 467 set to NULL, a yellow status indicates that the flow is 468 valid but no reservation operation(s) as a sender or 469 receiver has completed successfully. Once a single 470 reservation completion has been detected for either a 471 sender or receiver, the flow has a green status. If the 472 source address is not set to NULL, the status applies 473 only to the receiver for the specified source. Thus, if 474 an application is both a sender and receiver for a the 475 given flow, any relevant sender status information is 476 ignored. 478 Return Values: scrapi_status_red, scrapi_status_yellow, or 479 scrapi_status_green. 481 Function Name: scrapi_errno 483 Syntax: int scrapi_errno( 485 const struct sockaddr *destination, 486 int protocol, 487 const struct sockaddr *source 489 ); 491 Description: Set to the errno value of the last SCRAPI call for a 492 given flow. Must be called with identical arguments 493 given in a preceding SCRAPI function. Since failed 494 SCRAPI functions may not have created a flow, or caused 495 the closure of a flow, the errno may be transitory and 496 should be observed immediately after the failure. 498 Also See: scrapi_perror, scrapi_errlist 500 Function Name: scrapi_perror 502 Syntax: void scrapi_perror( 504 const struct sockaddr *destination, 505 int protocol, 506 const struct sockaddr *source, 507 const char *string 509 ); 511 Description: SCRAPI call to print an error message analogous to the 512 perror() library call. 514 Also See: scrapi_errno, scrapi_errlist 515 Function Name: scrapi_errlist 517 Syntax: const char * scrapi_errlist( 519 int errno 521 ); 523 Description: SCRAPI call to get an error message string for a given 524 errno. 526 Return Values: An error message string. 528 Also See: scrapi_errno, scrapi_perror 530 Function Name: scrapi_stderr 532 Syntax: void scrapi_stderr( 534 FILE *file 536 ); 538 Description: Set the file pointer to be used by the SCRAPI library for 539 standard error. If it is set to NULL, no messages are 540 printed. The default value is stderr. 542 Function Name: scrapi_debug 544 Syntax: void scrapi_debug( 546 FILE *file 548 ); 550 Description: Set the file pointer to be used by the SCRAPI library for 551 debugging information. If it is set to NULL, no messages 552 are printed. Debug messages include the logging of all 553 asynchronous RSVP events. The default value is NULL. 555 Enum Name: scrapi_status 557 1. scrapi_status_red 559 2. scrapi_status_yellow 561 3. scrapi_status_green 563 Description: Enumerated types for status condition of a flow. The 564 meaning of these values is described in the 565 scrapi_status() function description. 567 5.3. Asynchronous Event Loop API Description 569 The section describes the asynchronous event functions of the SCRAPI 570 API. 572 Function Name: scrapi_poll_list 574 Syntax: void scrapi_poll_list( 576 fdset *set 578 ); 580 Description: SCRAPI call to get all API file descriptors to use in a 581 subsequent select call. 583 Function Name: scrapi_dispatch 585 Syntax: int scrapi_dispatch(); 587 Description: SCRAPI call to poll the API for new events. 589 Return Values: TRUE if successful, FALSE if RSVP support is no longer 590 available. 592 6. Application Code Templates 594 This section provides examples, presented as code templates, to aid 595 programmers in augmenting networking applications with SCRAPI calls. 597 One example contains two simplex applications which attempt to wait for 598 a reservation to be put in place before sending data on the network. 599 The other example is a full duplex multimedia type application which 600 sends and receives data without waiting for completion of the 601 reservation. 603 6.1. Unicast Performance Measurement Application 605 The following example was derived from a network performance tool. It 606 attempts to put in place a unicast reservation before measuring network 607 performance. Waiting is accomplished using the timeout option in the 608 sender and receiver calls. 610 6.1.1. Sender Application 612 This sender application opens a TCP connection to the 'receive-hostname' 613 on port 1111 and attempts to reserve 1000 bytes/sec of average 614 bandwidth. After waiting at most 10 seconds for a reservation to be put 615 in place, this application streams data to the receiver to measure 616 network performance and then closes the connection. 618 #include 620 #define SAP(x) ((struct sockaddr *) (x)) 622 void 623 main(int argc, char *argv[]) 624 { 625 int fd,len; 626 int timeout = 10000; /* wait for at most 10 seconds */ 627 double bw = 1000; /* Average bandwidth 1Kbytes/sec */ 628 struct SOCKADDR destination,source; 629 scrapi_status status; 631 char *hostname = 'receive-hostname'; 632 unsigned short port = 1111; 634 /* translate host name or address */ 635 if (!scrapi_sockaddr_parse(SAP(&destination),hostname, 636 htons(port))) { 637 fprintf(stderr,'Could not parse host address'); 638 exit(1); 639 } 640 /* open, bind, and connect */ 641 /* fd = socket(...); */ 642 len = sizeof(source); 643 if (getsockname(fd,SAP(&source),&len) == -1) { 644 perror('getsockname'); 645 exit(1); 646 } 648 /* make an RSVP based reservation */ 649 if (!scrapi_sender(SAP(&destination),IPPROTO_TCP,SAP(&source), 650 bw,0,timeout)) 651 scrapi_perror(SAP(&destination),IPPROTO_TCP,SAP(&source), 652 'RSVP unable to reserve bandwidth'); 653 status = scrapi_get_status(SAP(&destination),IPPROTO_TCP,NULL); 655 /* run test */ 656 if (status == scrapi_status_green) { 657 status = scrapi_get_status(SAP(&destination),IPPROTO_TCP, 658 NULL); 659 if (status != scrapi_status_green) 660 fprintf(stderr, 661 'RSVP reservation lost during test!'); 662 } 663 scrapi_close(NULL,0,0); 664 } 665 6.1.2. Receiver Application 667 This receiver application accepts a TCP connection and attempts to make 668 a reservation. After waiting at most 10 seconds for a reservation to be 669 put in place, this application consumes data from the sender to measure 670 network performance and then closes the connection. 672 #include 674 #define SAP(x) ((struct sockaddr *) (x)) 676 void 677 main(int argc, char *argv[]) 678 { 679 int fd,len,timeout = 10000; /* wait for at most 10 seconds */ 680 struct SOCKADDR destination; 682 /* open, bind, and listen for connection */ 683 /* fd = accept(...); */ 684 len = sizeof(destination); 685 if (getsockname(fd,SAP(&destination),&len) == -1) { 686 perror('getsockname'); 687 exit(1); 688 } 690 /* make an RSVP based reservation */ 691 if (!scrapi_receiver(SAP(&destination),IPPROTO_TCP,NULL,1, 692 scrapi_service_cl,scrapi_style_distinct,timeout)) 693 scrapi_perror(SAP(&destination),IPPROTO_TCP,NULL, 694 'RSVP unable to reserve bandwidth'); 696 /* run test */ 697 scrapi_close(NULL,0,0); 698 } 700 6.2. Multicast Multimedia Application 702 This example highlights the inclusion of the SCRAPI API into a Tcl/Tk 703 event loop of a multimedia application. This is a full duplex 704 application that is sending and receiving data on the same address. 705 This application does not wait for completion status from the 706 reservation calls. 708 #include 709 #include 710 #include 712 #define SAP(x) ((struct sockaddr *) (x)) 714 void 715 callback(ClientData data, int mask) 716 { 717 if (!scrapi_dispatch()) 718 Tk_DeleteFileHandler(data); 719 } 721 void 722 main(int argc, char *argv[]) 723 { 724 int i,fd,len; 725 fd_set set; 726 struct SOCKADDR destination,source; 727 double bw = 1000; /* Average bandwidth 1Kbytes/sec */ 728 char *hostname = 'receive-hostname'; 729 unsigned short port = 1111; 731 /* translate host name or address */ 732 if (!scrapi_sockaddr_parse(SAP(&destination),hostname, 733 htons(port))) { 734 fprintf(stderr,'Could not parse host address'); 735 exit(1); 736 } 737 len = sizeof(source); 738 if (getsockname(fd,SAP(&source),&len) == -1) { 739 perror('getsockname'); 740 exit(1); 741 } 743 /* make an RSVP based reservation */ 744 if (!scrapi_sender(SAP(&destination),IPPROTO_UDP,SAP(&source), 745 bw,0,0)) 746 scrapi_perror(SAP(&destination),IPPROTO_UDP,SAP(&source), 747 'RSVP unable to reserve bandwidth'); 748 if (!scrapi_receiver(SAP(&destination),IPPROTO_UDP,SAP(&source), 749 1,scrapi_service_cl,scrapi_style_distinct,0)) 750 scrapi_perror(SAP(&destination),IPPROTO_UDP,SAP(&source), 751 'RSVP unable to reserve bandwidth'); 752 scrapi_poll_list(&set); 753 for (i = 0;i < FD_SETSIZE; i++) { 754 if (!FD_ISSET(i,&set)) 755 continue; 756 Tk_CreateFileHandler((ClientData) i,TK_READABLE, 757 callback,(ClientData) i); 758 } 760 /* send data */ 761 scrapi_close(NULL,0,0); 762 } 764 7. Conclusion 766 The SCRAPI interface provides a simple method to add RSVP support to 767 many network applications. It supports both IPv4 and IPv6 and attempts 768 to simplify user developed code to support both address families. 769 Coding examples are provided to give additional guidance on the usage of 770 this API. 772 8. Security Considerations 774 Security considerations are not discussed in this memo. 776 9. Acknowledgements 778 The author would like to thank Steve Berson for helping to define this 779 API. I would also like to thank Bob Braden for his help in improving 780 the definition of the API and corresponding documentation. 782 10. References 784 [1] Braden, R., Ed., et. al., Resource Reservation Protocol (RSVP) - 785 Version 1 Functional Specification, RFC 2205, September 1997. 787 [2] Braden, R., Hoffman, D., RAPI -- An RSVP Application Programming 788 Interface Version 5, Work In Progress, November 1997. 790 [3] Shenker, S., Partridge, C., Guerin, R., Specification of Guaranteed 791 Quality of Service, RFC 2212, September 1997. 793 [4] Wroclawski, J., Specification of the Controlled Load Quality of 794 Service, RFC 2211, September 1997. 796 [5] Berger, L., O'Malley, T., RSVP Extensions for IPSEC Data Flows, RFC 797 2207, September 1997. 799 11. Author's Address 801 Bob Lindell 802 USC Information Sciences Institute 803 4676 Admiralty Way 804 Marina del Rey, CA 90292 806 12. Appendix 1: Address Manipulation API Description 808 These are utility functions to ease the development of an interface 809 which supports IPv4 and IPv6. These are not viewed as part of the 810 SCRAPI API, but rather a collection of useful address manipulation 811 functions which should be provided in system libraries. In the future, 812 these functions will be removed in favor of system supplied 813 functionality. 815 Macro Name: SOCKADDR 817 Description: A struct sockaddr data type that is large enough for both 818 IPv4 and IPv6 addresses. 820 Function Name: scrapi_sockaddr_multicast 822 Syntax: int scrapi_sockaddr_multicast( 824 const struct sockaddr *address 826 ); 828 Description: Determine if an address is multicast or unicast. 830 Return Values: TRUE if multicast, FALSE otherwise. 832 Function Name: scrapi_sockaddr_parse 834 Syntax: int scrapi_sockaddr_parse( 836 struct sockaddr *address 837 const char *name, 838 unsigned short port 840 ); 842 Description: Perform a host name lookup or parse an address and 843 initialize a struct sockaddr structure. 845 Return Values: TRUE if parsed, FALSE otherwise. 847 Function Name: scrapi_sockaddr_print 849 Syntax: const char * scrapi_sockaddr_print( 851 const struct sockaddr *address 853 ); 855 Description: Pretty print an address. 857 Return Values: A valid string if printable, NULL otherwise. 859 Function Name: scrapi_sockaddr_get_addr 861 Syntax: int scrapi_sockaddr_get_addr( 863 const struct sockaddr *address, 864 char *addr 866 ); 868 Description: Store the address field of the sockaddr structure to a 869 network order binary representation of an address which 870 starts at the memory location specified. 872 Return Values: TRUE if successful, FALSE otherwise. 874 Function Name: scrapi_sockaddr_set_addr 876 Syntax: int scrapi_sockaddr_set_addr( 878 struct sockaddr *address, 879 char *addr 881 ); 883 Description: Load the address field of the sockaddr structure from a 884 network order binary representation of an address which 885 starts at the memory location specified. 887 Return Values: TRUE if successful, FALSE otherwise. 889 Function Name: scrapi_sockaddr_get_port 891 Syntax: unsigned short scrapi_sockaddr_get_port( 893 const struct sockaddr *address 895 ); 897 Description: Get the port number. 899 Return Values: The port number if successful, 0 otherwise. 901 Function Name: scrapi_sockaddr_set_port 903 Syntax: int scrapi_sockaddr_set_port( 905 struct sockaddr *address, 906 unsigned short port 908 ); 910 Description: Set the port number. 912 Return Values: TRUE if successful, FALSE otherwise. 914 Function Name: scrapi_sockaddr_any 916 Syntax: int scrapi_sockaddr_any( 918 struct sockaddr *address, 919 int family 921 ); 923 Description: Initialize a struct sockaddr to the wildcard address and 924 port number for the given address family. 926 Return Values: TRUE if successful, FALSE otherwise. 928 Function Name: scrapi_sockaddr_length 930 Syntax: int scrapi_sockaddr_length( 932 struct sockaddr *address 934 ); 936 Description: Return the length of a struct sockaddr for the given 937 address family. 939 Return Values: The length if successful, 0 otherwise. 941 Table of Contents 943 1. Introduction ................................................... 2 944 2. Functional Description ......................................... 3 945 3. The Simplified Error Model of SCRAPI ........................... 5 946 4. A Comparison to RAPI ........................................... 8 947 5. Application Programming Interface Definition ................... 9 948 5.1. Reservation API Description .................................. 9 949 5.2. Error Handling API Description ............................... 11 950 5.3. Asynchronous Event Loop API Description ...................... 15 951 6. Application Code Templates ..................................... 15 952 6.1. Unicast Performance Measurement Application .................. 16 953 6.1.1. Sender Application ......................................... 16 954 6.1.2. Receiver Application ....................................... 18 955 6.2. Multicast Multimedia Application ............................. 18 956 7. Conclusion ..................................................... 20 957 8. Security Considerations ........................................ 20 958 9. Acknowledgements ............................................... 20 959 10. References .................................................... 20 960 11. Author's Address .............................................. 21 961 12. Appendix 1: Address Manipulation API Description .............. 21