idnits 2.17.1 draft-ietf-rsvp-rapi-00.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-19) 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 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 a Security Considerations 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 an Authors' Addresses Section. ** There are 5 instances of too long lines in the document, the longest one being 190 characters in excess of 72. ** There are 2 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.) -- The document date (June 16, 1997) is 9804 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) No issues found here. Summary: 11 errors (**), 0 flaws (~~), 1 warning (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Draft R. Braden 3 Expiration: December 1997 ISI 4 File: draft-ietf-rsvp-rapi-00.txt D. Hoffman 5 Sun Microsystems 7 RAPI -- An RSVP Application Programming Interface 9 Version 5 11 June 16, 1997 13 Status of Memo 15 This document is an Internet-Draft. Internet-Drafts are working 16 documents of the Internet Engineering Task Force (IETF), its areas, 17 and its working groups. Note that other groups may also distribute 18 working documents as Internet-Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 To learn the current status of any Internet-Draft, please check the 26 "1id-abstracts.txt" listing contained in the Internet- Drafts Shadow 27 Directories on ds.internic.net (US East Coast), nic.nordu.net 28 (Europe), ftp.isi.edu (US West Coast), or munnari.oz.au (Pacific 29 Rim). 31 Abstract 33 This memo describes version 5 of RAPI, a specific API (application 34 programming interface) for RSVP. The RAPI interface is one 35 realization of the generic API contained in the RSVP Functional 36 Specification document, and it is being published for information 37 only. The RAPI interface is based upon a client library, whose calls 38 are described here. 40 1. Introduction 42 An Internet application uses some "API" ( Application Programming 43 Interface) in order to request enhanced quality-of-service (QoS). A 44 local RSVP control program will then use the RSVP protocol to 45 propagate the QoS request through the routers along path(s) for the 46 data flow. Each router may accept or deny the request, depending 47 upon its available resources. In the case of failure, the local RSVP 48 control program will return the decision to the requesting 49 application via the API. 51 This document describes a particular RSVP API implementation known as 52 "RAPI". RAPI is based on a client library linked with the 53 application. This document describes the calls to that library. 54 There is at least one other documented API for RSVP, based on 55 sockets. 57 The following diagram shows RAPI's implementation model. RSVP is 58 implemented on a host by a user-level daemon program. The procedures 59 of the RSVP client library module interact with the local RSVP daemon 60 program through a Unix-domain socket. RAPI refers to the interface 61 between the application and the RSVP client library. 63 H O S T . R O U T E R 64 (RAPI) . 65 v . 66 _____________v . 67 | |_______ . 68 | x RSVP | . 69 | x Client| . 70 | Application x Lib | ____________ . _____________ 71 | x rtns | | | . | | 72 | x_______| | RSVP | . | RSVP | 73 | | | | Daemon | . | Daemon | 74 |_____________| | |____________| . |_____________| 75 | | | . | . | | | 76 USER | | | . | . | | | 77 ===========|======|========|===V====|=====. | | | 78 KERNEL | |_<____>_| . |___<_____>___| | |__> 79 | UNIX Pipe . RSVP messages | RSVP 80 | . . | 81 | _____V______ . _____V______ 82 | | | . | | 83 | | Packet | . | Packet | 84 += DATA====> | Classifier | =DATA==> | Classifier | ==> 85 |& Scheduler | . |& Scheduler | 86 | (if any) | . | | 87 |____________| . |____________| 89 1.1 Reservation Model 91 RSVP performs the signaling necessary to make a resource 92 reservation for a simplex data flow sent to a unicast or multicast 93 destination address. Although RSVP distinguishes senders from 94 receivers, the same application may act in both roles. 96 RSVP assigns QoS to an specific multipoint-to-multipoint data flow 97 known as a "session". A session is defined by a particular 98 transport protocol, IP destination address, and destination port. 99 In order to receive data packets for a particular multicast 100 session, a host must have joined the corresponding IP multicast 101 group using the setsockopt call IP_ADD_MEMBERSHIP. 103 A data source, or "sender", is defined by an IP source address and 104 a source port. A given session may have multiple senders S1, S2, 105 ... Sn, and if the destination is a multicast address, multiple 106 "receivers" R1, R2, ... Rm. In the current version of RSVP, the 107 ports used by RSVP for defining sessions and senders are 108 restricted to be TCP/UDP port numbers. 110 Under RSVP, QoS requests are made by the data receivers. A QoS 111 request contains a "flowspec" together with a "filter spec". The 112 flowspec includes an "Rspec", which defines the desired QoS and is 113 used to control the packet scheduling mechanism in the router or 114 host, and also a "Tspec", which defines the traffic expected by 115 the receiver. The filter spec controls packet classification to 116 determine which sender(s)' data packets receive the corresponding 117 QoS. 119 The detailed manner in which reservations from different receivers 120 are shared in the Internet is controlled by a reservation 121 parameter known as the "reservation style". The RSVP Functional 122 Specification contains a definition and explanation of the 123 different reservation styles. 125 1.2 API Outline 127 Using the RAPI interface, an application uses the txt _session() 128 call to define an "API session" for sending a single simplex data 129 flow and/or receiving such a data flow. The txt _sender() call 130 may then be used to register as a data sender, and/or the 131 txt _reserve() call may be used to make a QoS reservation as a 132 data receiver.The txt _sender and/or txt _reserve calls may be 133 repeated with different parameters to dynamically modify the state 134 at any time or they can be issued in null forms that retract the 135 corresponding registration. The application can call 136 txt _release() to close the session and delete all of its resource 137 reservations. The relationship among the RAPI library calls is 138 summarized by the RAPI state diagram shown below. Rapi_sender(0) 139 and txt _reserve(0) represent null calls in that diagram. 141 Note that a single API session, defined by a single txt _session 142 call, can define only one sender at a time. More than one API 143 session may be established for the same RSVP session. For 144 example, suppose an application sends multiple UDP data flows, 145 distinguished by source port. It will call txt _session and 146 txt _sender separately for each of these flows. 148 The txt _session call allows the application to specify an " 149 upcall" (or "callback") routine that will be invoked to signal 150 RSVP state change and error events. There are five types of 151 upcalls. 153 o PATH_EVENT and RESV_EVENT upcalls signal the arrival or 154 change of path state and reservation state, respectively, and 155 deliver the relevant state information to the application. 157 o PATH_ERROR and RESV_ERROR upcalls signal the corresponding 158 errors. 160 o PATH_CONFIRM upcalls signal the arrival of a CONFIRM message. 162 The upcall routine is invoked indirectly (and synchronously) by 163 the application, using the following mechanism. 165 o The application issues the RAPI library call txt _getfd() to 166 learn the file descriptor of the Unix socket used by the API. 168 o The application detects read events on this file descriptor, 169 either passing it directly in a select call or passing it to 170 the notifier of another library (such as XLib, tk/tcl, RPC, 171 etc.). 173 o When a read event on the file descriptor is signaled, the 174 application calls txt _dispatch(). This drives the API to 175 execute the upcall routine if appropriate. 177 RAPI State Diagram 179 +---------+ 180 | Closed |<-----+ 181 +---------+ | 182 | | 183 txt _session | 184 | | 185 +----+ | txt _release 186 PATH_EVENT | V V | 187 | +---------+ | 188 +---| |------+ 189 | Session | 190 +----------| |----------+ 191 txt _sender +---------+ txt _reserve 192 | ^ ^ | 193 txt _sender or | | | | txt _reserve or 194 PATH_EVENT or | rapi_sender(0) | | PATH_EVENT or 195 RESV_EVENT or | | | | CONFIRM_EVENT 196 PATH_ERROR | | | | or RESV_ERROR 197 +----+ | | rapi_reserve(0) | +----+ 198 | V V | | V V | 199 | +---------+ | | +---------+ | 200 +---| |------+ +------| |---+ 201 | Send | | Rcv | 202 +-------| |<-----+ +----->| |-------+ 203 | +---------+ | | +---------+ | 204 | | | | | | 205 | | rapi_reserve(0) | | | 206 | | | | | | 207 | | | rapi_sender(0) | | 208 | | | | | | 209 | rapi_reserve | | rapi_sender | 210 | | +---------+ | | 211 | +--------->| |<---------+ | 212 | | SendRcv | | 213 | rapi_sender or +---| | | 214 | rapi_reserve or | +---------+ | 215 | PATH_EVENT or | ^ | | 216 | RESV_EVENT or +----+ | | 217 | CONFIRM_EVENT | | 218 | or PATH_ERROR | | 219 | or RESV_ERROR | | 220 | rapi_release rapi_release 221 rapi_release V | 222 | +--------+ | 223 +----------------------->| Closed |<----------------------+ 224 +--------+ 226 A synchronous error in a RAPI library routine returns an 227 appropriate error code. Asynchronous RSVP errors are delivered to 228 the application via the RAPI upcall routine. Text messages for 229 synchronous and asynchronous error codes will be found in the file 230 "rapi_err.h". 232 The first rapi_session() call in a particular instance of the RAPI 233 library opens a Unix-domain RAPI socket to the RSVP daemon and 234 passes the session registration request across it. If the 235 application (or the daemon) crashes without properly closing the 236 RAPI socket, the other side will be notified to perform a cleanup. 237 In particular, if the user process terminates without explicitly 238 closing the RAPI session, the daemon will delete the corresponding 239 reservation state from the routers. 241 2. CLIENT LIBRARY SERVICES 243 The RSVP API provides the client library calls defined in this 244 section. To use these calls, the application should include the file 245 "rapi_lib.h" and "rsvp_intserv.h". 247 A. Create a Session 249 The rapi_session call creates an API session. If it succeeds, 250 the call returns an opaque but non-zero session handle for use 251 in subsequent calls related to this API session. If the call 252 fails synchronously, it returns zero (NULL_SID) and stores a 253 RAPI error code into an integer variable pointed to by the 254 "errnop" parameter. 256 After a successful rapi_session call has been made, the 257 application may receive upcalls of type RAPI_PATH_EVENT for the 258 API session. 260 unsigned int rapi_session( 262 struct sockaddr *Dest, /* Session: (Dst addr, port) */ 263 int Protid, /* Protocol Id */ 264 int flags, /* flags */ 265 int (*Event_rtn)(), /* Address of upcall routine */ 266 void *Event_arg, /* App argument to upcall */ 267 int *errnop /* Place to return error code*/ 268 ) 270 The parameters are as follows. 272 o "Dest" 274 This required parameter points to a sockaddr structure 275 defining the destination IP (V4 or V6) address and a port 276 number to which data will be sent. The "Dest" and "Protid" 277 parameters define an RSVP session. If the "Protid" 278 specifies UDP or TCP transport, the port corresponds to the 279 appropriate transport port number. 281 o "Protid" 283 The IP protocol ID for the session. If it is omitted 284 (i.e., zero), 17 (UDP) is assumed. 286 o "flags" 287 RAPI_GPI_SESSION (0x40) -- If set, this flag requests that 288 this API session be defined in the GPI format used by the 289 IPSEC extension of RSVP. If this flag is set, the port 290 number included in "Dest" is considered "virtual" (see the 291 IPSEC specification for details), and any sender template 292 and filter specifications must be in GPI format. 294 RAPI_USE_INTSERV (0X10) -- If set, IntServ formats are 295 used in upcalls; otherwise, the Simplified format is used 296 (see Section 4 below). 298 o "Event_rtn" 300 This parameter is a pointer to an upcall routine that will 301 be invoked to notify the application of RSVP errors and 302 state change events. The parameter may be NULL if there is 303 no such routine. 305 o "Event_arg" 307 This optional parameter points to an argument that will be 308 passed in any invocation of the upcall routine. 310 o "errnop" 312 The address of an integer into which a RAPI error code will 313 be returned. 315 An application can have multiple API sessions registered for the 316 same or different RSVP sessions at the same time. There can be 317 at most one sender associated with each API session; however, an 318 application can announce multiple senders for a given RSVP 319 session by announcing each sender in a separate API session. 321 Two API sessions for the same RSVP session, if they are 322 receiving data, are assumed to have joined the same multicast 323 group and will receive the same data packets. At present, if 324 two or more such sessions issue "rapi_reserve" calls, their 325 reservation parameters must agree or the results will be 326 undefined. There is no check for such a conflict. 327 Furthermore, the code does not disallow multiple API sessions 328 for the same sender (defined by the host interface and the local 329 UDP port) within the same RSVP session, i.e., for the same data 330 flow. If these API sessions are created by different 331 application processes on the local host, the data packets they 332 send will be merged but their sender declarations will not be. 334 B. Specify Sender Parameters 335 An application must issue a rapi_sender call if it intends to 336 send a flow of data for which receivers may make reservations. 337 This call defines, redefines, or deletes the parameters of that 338 flow. A rapi_sender call may be issued more than once for the 339 same API session; the most recent one takes precedence. 341 If there is a synchronous error, rapi_sender() returns a RAPI 342 error code; otherwise, it returns zero. Once a successful 343 rapi_sender call has been made, the application may receive 344 upcalls of type RAPI_RESV_EVENT or RAPI_PATH_ERROR. 346 int rapi_sender( 347 int Sid, /* Session ID */ 348 int flags, /* Flags */ 349 struct sockaddr *LHost, /* Local Host */ 350 rapi_filter_t *SenderTemplate, /* Sender template */ 351 rapi_tspec_t *SenderTspec, /* Sender Tspec */ 352 rapi_adspec_t *SenderAdspec, /* Sender Adspec */ 353 rapi_policy_t *SenderPolicy, /* Sender policy data */ 354 int TTL; /* Multicast data TTL */ 355 ) 357 The parameters are as follows. 359 o "Sid" 361 This required parameter must be a session ID returned by a 362 successful rapi_session call. 364 o "flags" 366 No flags are currently defined for this call. 368 o "LHost" 370 This optional parameter may point to a sockaddr structure 371 specifying the IP source address and the UDP source port 372 from which data will be sent, or it may be NULL. 374 If the IP source address is INADDR_ANY, the API will use 375 the default IP (V4 or V6) address of the local host. This 376 is sufficient unless the host is multihomed. The port 377 number may be zero if the protocol for the session does not 378 have ports. 380 A NULL "LHost" parameter indicates that the application 381 wishes to withdraw its registration as a sender. In this 382 case, the following parameters will all be ignored. 384 o "SenderTemplate" 386 This optional parameter may be a pointer to a RAPI filter 387 spec structure (see Section 4) specifying the format of 388 data packets to be sent, or it may be NULL. 390 If this parameter is omitted (NULL), a sender template will 391 be created internally from the "Dest" and "LHost" 392 parameters. If a "SenderTemplate" parameter is present, 393 the "LHost" parameter will be ignored. 395 This parameter is required in order to declare the sender 396 template for a session using IPSEC, i.e., a session created 397 with the RAP_GPI_SESSION flag set. 399 o "SenderTspec" 401 This required parameter is a pointer to a Tspec that 402 defines the traffic that this sender will create. 404 o "SenderAdspec" 406 This optional parameter may point to a RAPI Adspec 407 structure (see Section 4), or it may be NULL. 409 o "SenderPolicy" 411 This optional parameter may be a pointer to a sender policy 412 data structure, or it may be NULL. 414 o "TTL" 416 This parameter specifies the IP TTL (Time-to-Live) value 417 with which multicast data will be sent. It allows RSVP to 418 send its control messages with the same TTL scope as the 419 data packets. 421 C. Make, Modify, or Delete a Reservation 423 The rapi_reserve procedure is called to make, modify, or delete 424 a resource reservation for a session. The call may be repeated 425 with different parameters, allowing the application to modify or 426 remove the reservation; the latest call will take precedence. 427 Depending upon the parameters, each call may or may not result 428 in new Admission Control calls, which could fail asynchronously. 430 If there is a synchronous error in this call, rapi_reserve() 431 returns a RAPI error code; otherwise, it returns zero. Once 432 this call has been successful, the application may receive an 433 upcall of type RAPI_RESV_ERROR or RAPI_RESV_CONFIRM. 435 An admission control failure (e.g., refusal of the QoS request) 436 will be reported asynchronously by an upcall of type 437 RAPI_RESV_ERROR. A " No Path State" error code indicates that 438 RSVP state from one or more of the senders specified in 439 "filter_list" has not (yet) propagated all the way to the 440 receiver; it may also indicate that one or more of the specified 441 senders has closed its API and that its RSVP state has been 442 deleted from the routers. 444 int rapi_reserve( 446 int Sid, /* Session ID */ 447 int flags, 448 struct sockaddr *RHost, /* Receive host addr*/ 449 int StyleId, /* Style ID */ 450 rapi_stylex_t *Style_Ext, /* Style extension */ 451 rapi_policy_t *Rcvr_Policy, /* Receiver policy */ 453 int FilterSpecNo, /* # of filter specs */ 454 rapi_filter_t *FilterSpec_list, /* List of filt specs*/ 455 int FlowspecNo, /* # of flowspecs */ 456 rapi_flowspec_t *Flowspec_list /* List of flowspecs*/ 457 ) 459 The parameters are as follows: 461 o "Sid" 463 This required parameter must be a session ID returned by a 464 successful rapi_session call. 466 o "flags" 467 Setting the RAPI_REQ_CONFIRM flag will request confirmation 468 of the reservation, by means of a confirmation upcall (type 469 RAPI_RESV_CONFIRM). 471 o "RHost" 473 This optional parameter may be used to define the interface 474 address on which data will be received. It is useful for a 475 multi-homed host. If it is omitted or the host address is 476 INADDR_ANY, the default interface will be assumed. 478 o "StyleId" 480 This required parameter specifies the reservation style id 481 (values defined below). 483 o "Style_Ext" 485 This optional parameter is a pointer to a style-dependent 486 extension to the parameter list, if any. 488 o "Rcvr_Policy" 490 This optional parameter is a pointer to a policy data 491 structure, or it is NULL. 493 o "FilterSpec_list", "FilterSpecNo" 495 The "FilterSpec_list" parameter is a pointer to an area 496 containing a sequential vector of RAPI filter spec objects. 497 The number of objexts in this vector is specified in 498 "FilterSpecNo". If "FilterSpecNo" is zero, the 499 "FilterSpec_list" parameter will be ignored. 501 o "Flowspec_list", "FlowspecNo" 503 The "Flowspec_list" parameter is a pointer to an area 504 containing a sequential vector of RAPI flow spec objects. 505 The number of objects in this vector is specified in 506 "FlowspecNo". If "FlowspecNo" is zero, the "Flowspec_list" 507 parameter will be ignored. 509 If FlowspecNo is zero, the rapi_reserve call will remove the 510 current reservation(s) for the specified session, and 511 FilterSpec_list and Flowspec_list will be ignored. Otherwise, 512 the parameters depend upon the style, as follows. 514 o Wildcard Filter (WF) 515 Use "StyleId" = RAPI_RSTYLE_WILDCARD. The "Flowspec_list" 516 parameter may be empty (to delete the reservation) or else 517 point to a single flowspec. The "FilterSpec_list" 518 parameter may be empty or it may point to a single filter 519 spec containing appropriate wildcard(s). 521 o Fixed Filter (FF) 523 Use "StyleId" = RAPI_RSTYLE_FIXED. "FilterSpecNo" must 524 equal "FlowspecNo". Entries in "Flowspec_list" and 525 "FilterSpec_list" parameters will correspond in pairs. 527 o Shared Explicit (SE) 529 Use "StyleId" = RAPI_RSTYLE_SE. The "Flowspec_list" 530 parameter should point to a single flowspec. The " 531 FilterSpec_list" parameter may point to a list of any 532 length. 534 D. Remove a Session 536 The rapi_release call removes the reservation, if any, and the 537 state corresponding to a given session handle. This call will 538 be made implicitly if the application terminates without closing 539 its RSVP sessions. If the session handle is invalid, the call 540 returns a corresponding RAPI error code; otherwise, it returns 541 zero. 543 int { 544 7777777777777778 r99a99p99i99_99r99e99l99e99a99s99e99}99(9999u99n99s99i99g99n99e99d9999i99n99t9999S99i99d9999)77777777777777778.fi 546 E. Get File Descriptor 548 The rapi_getfd call may be used by the application to obtain the 549 file descriptor associated with the Unix socket connected to the 550 RSVP daemon, after a rapi_session() call has completed 551 successfully and before rapi_release() is called. When a socket 552 read event is signaled on this file descriptor, the application 553 should call rapi_dispatch(), described below. 555 int {777r99a99p99i99_99g99e99t7777d} ( unsigned int Sid ) 557 If Sid is illegal or undefined, this call returns -1; otherwise, 558 it returns the file descriptor. 560 F. Dispatch API Event 562 The application should call this routine whenever a read event 563 is signaled on the file descriptor returned by rapi_getfd(). 564 Rapi_dispatch() may be called at any time, but it will generally 565 have no effect unless there is a pending event associated with 566 the Unix pipe. Calling this routine may result in one or more 567 upcalls to the application from any of the open API sessions 568 known to this instance of the library. 570 int rapi_dispatch( ) 572 If this call encounters an error, rapi_dispatch() returns a RAPI 573 error code; otherwise, it returns zero, 575 G. RAPI Version 577 int rapi_version( ) 579 This call returns a single integer that defines the version of 580 the interface. The returned value is composed of a major number 581 and a minor number, encoded as 100*major + minor. This call may 582 be used by an application to adapt to different versions. 584 The API described in this document has major version number 5. 586 H. Upcalls 588 An upcall (invoked by a call to rapi_dispatch()) executes the 589 procedure whose address was specified by the "Event_rtn" in the 590 rapi_register call. 592 event_upcall( 594 unsigned int Sid, /* Session ID */ 595 int EventType, /* Event type */ 597 int Style, /* Resv style */ 598 int ErrorCode, /* (error event): err code */ 599 int ErrorValue, /* (error event): err value*/ 600 struct sockaddr *ErrorNode, /* Node that detected error*/ 601 unsigned char ErrorFlags, 603 int FilterSpecNo, /* # of filter specs in list*/ 604 rapi_filter_t *FilterSpec_list, 605 int FlowspecNo, /* # of flowspecs in list */ 606 rapi_spec_t *Flowspec_list, 607 int AdspecNo, /* # of ADSPECs in list */ 608 rapi_adspec_t *Adspec_list, 609 void *Event_arg /* Supplied by application */ 611 The following parameters are used in the upcall: 613 o "Sid" 615 This parameter must be a session ID returned by a 616 successful rapi_register call. 618 o "EventType" 620 Upcall event types. 622 o "Style" 624 This parameter contains the style of the reservation; it is 625 non-zero only for a RAPI_RESV_EVENT or RAPI_RESV_ERROR 626 upcall. 628 o "ErrorCode, ErrorValue" 629 These values encode the error cause, and they are set only 630 for a RAPI_PATH_ERROR or RAPI_RESV_ERROR event. ErrorCode 631 values are defined in "rapi_lib.h" and corresponding text 632 strings are defined in "rapi_err.h". 634 o "ErrorNode" 636 This is the IP (V4 or V6) address of the node that detected 637 the error, and it is set only for a RAPI_PATH_ERROR or 638 RAPI_RESV_ERROR event. 640 o "ErrorFlags" 642 These error flags are set only for a RAPI_PATH_ERROR or 643 RAPI_RESV_ERROR event. 645 RAPI_ERRF_InPlace (0x01) -- The reservation failed, but 646 another reservation (presumably smaller) reservation is 647 still in place on the same interface. 649 RAPI_ERRF_NotGuilty (0x02) -- The reservation failed, but 650 the request from this client was merged with a larger 651 reservation upstream, so this client's reservation might 652 not have caused the failure. 654 o "FilterSpec_list", "FilterSpecNo" 656 The "FilterSpec_list" parameter is a pointer to a malloc'd 657 area containing a sequential vector of RAPI filter spec or 658 sender template objects. The number of objexts in this 659 vector is specified in "FilterSpecNo". If "FilterSpecNo" 660 is zero, the "FilterSpec_list" parameter will be NULL. 662 o "Flowspec_list", "FlowspecNo" 664 The "Flowspec_list" parameter is a pointer to an area 665 containing a sequential vector of RAPI flowspec or Tspec 666 objects. The number of objects in this vector is specified 667 in "FlowspecNo". If "FlowspecNo" is zero, the 668 "Flowspec_list" parameter will be NULL. 670 o "Adspec_list", "AdspecNo" 672 The "Adspec_list" parameter is a pointer to an area 673 containing a sequential vector of RAPI adspec objects. The 674 number of objects in this vector is specified in 675 "AdspecNo". If "AdspecNo" is zero, the "Adspec_list" 676 parameter will be NULL. 678 o "Event_arg" 680 This is the value supplied in the rapi_register call. 682 When the application's upcall procedure returns, the API will 683 free any areas pointed to by "Flowspec_list" or 684 "FilterSpec_list"; the application must copy any values it wants 685 to save. 687 The specific parameters depend upon "EventType", which may have 688 one of the following values. 690 o RAPI_PATH_EVENT 692 A path event indicates that RSVP sender ("Path") state from 693 a remote node has arrived or changed at the local node. A 694 RAPI_PATH_EVENT upcall containing the complete current list 695 of senders (or possibly no senders, after a path teardown) 696 in the path state for the specified session will be 697 triggered whenever the path state changes. 699 "FilterSpec_list", "Flowspec_list", and "Adspec_list" will 700 be of equal length, and corresponding entries will contain 701 sender templates, sender Tspecs, and Adspecs, respectively, 702 for all senders known at this node. In general, a missing 703 object will be indicated by an empty RAPI object. 705 RAPI_PATH_EVENT upcalls are enabled by the initial 706 rapi_session call. 708 o RAPI_RESV_EVENT 710 A reservation event upcall indicates that reservation state 711 has arrived or changed at the node, implying (but not 712 assuring) that reservations have been established or 713 deleted along the entire data path to one or more 714 receivers. RAPI_RESV_EVENT upcalls containing the current 715 reservation state for the API session will be triggered 716 whenever the reservation state changes. 718 "Flowspec_list" will either contain one flowspec object or 719 be empty (if the state has been torn down), and 720 "FilterSpec_list" will contain zero or more corresponding 721 filter spec objects. "Adspec_list" will be empty. 723 RAPI_RESV_EVENT upcalls are enabled by a rapi_sender call; 724 the sender template from the latter call will match the 725 filter spec returned in a reservation event upcall. 727 o RAPI_PATH_ERROR 729 A path error upcall indicates that an asynchronous error 730 has been found in the sender information specified in a 731 rapi_sender call. 733 The "ErrorCode" and "ErrorValue" parameters will specify 734 the error. "FilterSpec_list" and "Flowspec_list" will each 735 contain one object, the sender template and corresponding 736 sender Tspec (if any) in error, while "Adspec_list" will be 737 empty. If there is no sender Tspec, the object in 738 "Flowspec_list" will be an empty RAPI object. The 739 "Adspec_list" will be empty. 741 Path Error upcalls are enabled by a rapi_sender call, and 742 the sender Tspec in that call will match the sender Tspec 743 returned in a subsequent path error upcall. 745 o RAPI_RESV_ERROR 747 A reservation error upcall indicates that an asynchronous 748 reservation error has occurred. 750 The "ErrorCode" and "ErrorValue" parameters will specify 751 the error. "Flowspec_list" will contain one flowspec, 752 while "FilterSpec_list" may contain zero or more 753 corresponding filter specs. "Adspec_list" will be empty. 755 o RAPI_RESV_CONFIRM 757 A confirmation upcall indicates that a reservation has been 758 made at least up to an intermediate merge point, and 759 probably (but not necessarily) all the way to at least one 760 sender. A confirmation upcall is enabled by a rapi_reserve 761 call with the RAPI_REQ_CONFIRM flag set, and at most one 762 confirmation upcall will result from each such call. 764 The parameters of a confirmation upcall are the same as 765 those for a reservation event upcall. 767 The accompanying table summarizes the upcalls; here n is a non- 768 negative integer. 770 Upcall Enabled by FilterSpecNo FlowspecNo AdspecNo 772 Path event rapi_session n n n 774 Path error rapi_sender 1 1 0 776 Resv event rapi_sender 1 or 0 1 or 0 0 778 Resv error rapi_reserve n 1 0 780 Confirm rapi_reserve 1 1 0 782 Table 1: Summary of Upcall Types 784 3. RAPI FORMATTING ROUTINES 786 For convenience of applications, RAPI includes standard routines for 787 displaying the contents of a RAPI flowspec object or Tspec object. 788 To use these routines, include the file "rapi_lib.h". 790 A. Format a Flowspec 792 The rapi_fmt_flowspec() call formats a given RAPI flowspec into 793 a buffer of given address and size. The output is truncated if 794 the size is too small. 796 void rapi_fmt_flowspec( 798 rapi_flowspec_t *specp, /* Addr of RAPI flowspec*/ 799 char *buffer, /* Addr of buffer */ 800 int length /* Length of buffer */ 801 ) 803 B. Format a Tspec 805 The rapi_fmt_tspec() call formats a given RAPI Tspec into a 806 buffer of given address and size. The output is truncated if 807 the size is too small. 809 void rapi_fmt_tspec( 811 rapi_tspec_t *tspecp, /* Addr of RAPI Tspec */ 812 char *buffer, /* Addr of buffer */ 813 int length /* Length of buffer */ 814 ) 816 C. Format an Adspec 818 The rapi_fmt_adspec() call formats a given RAPI Adspec into a 819 buffer of given address and size. The output is truncated if 820 the size is too small. 822 void rapi_fmt_adspec( 824 rapi_adspec_t *adspecp, /* Addr of RAPI Adspec */ 825 char *buffer, /* Addr of buffer */ 826 int length /* Length of buffer */ 827 ) 829 D. Format a Filter Spec 831 The rapi_fmt_filtspec() call formats a given RAPI Filter Spec 832 into a buffer of given address and size. The output is 833 truncated if the size is too small. 835 void rapi_fmt_filtspec( 837 rapi_filter_t *filtp, /* Addr of RAPI Filt Spec*/ 838 char *buffer, /* Addr of buffer */ 839 int length /* Length of buffer */ 840 ) 842 4. RAPI OBJECTS 844 Flowspecs, filter specs, sender templates, and sender Tspecs are 845 encoded as variable-length RAPI objects. 847 Every RAPI object begins with a header consisting of two words, the 848 total length of the object in bytes and the type, respectively. An 849 empty object consists only of a header, with type zero and length 8 850 bytes. 852 Integrated services data structures are defined in: draft-ietf- 853 intserv-rsvp-01.txt. 855 o Flowspecs 857 There are two formats for RAPI flowspecs. For more details, see 858 "rapi_lib.h" and "rsvp_intserv.h". 860 - RAPI_FLOWSTYPE_Simplified 862 This is a "simplified" format. It consists of a simple 863 list of parameters needed for either Guaranteed or 864 Controlled Load service, using the service type 865 QOS_GUARANTEED or QOS_CNTR_LOAD, respectively. The RAPI 866 client library routines will map this format to/from an 867 appropriate Integrated Services data structure. 869 - RAPI_FLOWSTYPE_Intserv 871 This flowspec must be a fully formatted Integrated Services 872 flowspec data structure. 874 o Sender Tspecs 876 There are two formats for RAPI Sender Tspecs. For more details, 877 see "rapi_lib.h" and "rsvp_intserv.h". 879 - RAPI_TSPECTYPE_Simplified 881 This is a "simplified" format, consisting of a simple list 882 of parameters with the service type QOS_TSPEC. The RAPI 883 client library routines will map this format to/from an 884 appropriate Integrated Services data structure. 886 - RAPI_TSPECTYPE_Intserv 888 This flowspec must be a fully formatted Integrated Services 889 Tspec data structure. 891 o Adspecs 893 There are two formats for RAPI Adspecs. For more details, see 894 "rapi_lib.h" and "rsvp_intserv.h". 896 - RAPI_ADSTYPE_Simplified 898 This is a "simplified" format, consisting of a list of 899 Adspec parameters for all possible services. The RAPI 900 client library routines will map this format to/from an 901 appropriate Integrated Services data structure. 903 - RAPI_ADSTYPE_Intserv 905 This flowspec must be a fully formatted Integrated Services 906 Tspec data structure. 908 In an upcall, a flowspec, sender Tspec, or Adspec is by default 909 delivered in simplified format; however, if the RAPI_USE_INTSERV 910 flag is set in the rapi_session call, then the IntServ format is 911 used in upcalls. 913 o Filter Specs and Sender Templates 915 There are two formats for these objects. 917 - RAPI_FILTERFORM_BASE (RAPI_FILTERFORM_BASE6) 919 This object consists of only a socket address structure, 920 defining the IP (V4 or V6) address and port. 922 - RAPI_FILTERFORM_GPI (RAPI_FILTERFORM_GPI6) 924 This object consists of only an address structure, defining 925 the IP (V4 or V6) address and a 32-bit Generalized Port 926 Identifier. It is recommended for all IPSEC applications. 927 Other non-TCP/non-UDP transports may also utilize this 928 format in the future. 930 o Policy Data Objects 932 (Not yet supported) 934 APPENDIX A. Implementation 936 This section contains some general remarks on the implementation of 937 this API that is distributed with the ISI release of RSVP code. 939 A.1 Protocols 941 There are three protocol interfaces involved in invoking RSVP via 942 the API. 944 1. Procedure Call Interface to Application 946 The term "RAPI" (RSVP API) is used for the procedure call 947 interface to applications, and for the data structures 948 ("objects") used in that interface. This document is 949 primarily concerned with the RAPI interface. This interface 950 is realized by procedures included in the library routine 951 librsvp.a, which is compiled from rapi_lib.c and rapi_fmt.c. 953 2. Application - Daemon Protocol 955 The term "API" is used in the code for the local protocol 956 across the Unix socket between the librsvp.a routines and the 957 RSVP daemon rsvpd. This protocol generally use RSVP object 958 bodies but RAPI object framing. 960 3. RSVP Protocol 962 The RSVP protocol is used in the Internet between RSVP daemon 963 programs. 965 The code is organized to make these three interfaces logically 966 independent, so they can be changed independently. Each of these 967 three protocol interfaces has an independent version number, 968 defined in rapi_lib.h, rsvp_api.h, and rsvp.h for RAPI, API, and 969 RSVP, respectively. 971 The RAPI call library librsvp.a includes routines that convert 972 objects between RAPI and API formats. Similarly, the file 973 rsvp_api.c included in the RSVP daemon includes routines that 974 convert between the API representation and the RSVP 975 representation. In some cases, these conversion procedures are 976 identity transformations (i.e., pure copies); however, they 977 provide the structure to allow any of the three interfaces to be 978 changed in the future. 980 There are two different object framing conventions. RAPI and API 981 objects have a two-word header -- a total length in bytes and a 982 format code -- and a body. RSVP objects have a one-word header. 983 In general, objects in the API interface (i.e., across the Unix 984 socket) carry the two-word RAPI object header, but their body is 985 that of the corresponding RSVP object. Therefore, the API<->RSVP 986 conversion in rsvp_api.c simply maps the framing convention. 988 In the RAPI interface, the application is given some choice of 989 data formats. For example, QoS control objects (i.e., flowspecs, 990 Tspecs, and Adspecs) can be represented in either the RSVP (really 991 Int-Serv) format, which has complex packing, or in the more 992 convenient Simplified format. The RAPI library routines map 993 between Simplified format and Int-Serv format, which is used 994 across the API. 996 A.2 RAPI Sessions 998 Each instance of the RAPI library routines keeps a local (to the 999 application process) table of open RAPI sessions; the index into 1000 this table is the session handle (a_sid) used locally. The RSVP 1001 daemon keeps its own table of RAPI sessions. From the daemon's 1002 viewpoint, a RAPI session is defined by the triple: (fd, pid, 1003 a_sid), where fd is the file descriptor for the Unix socket, pid 1004 is the Unix process id, and a_sid is an application session id 1005 received over fd from pid. 1007 APPENDIX B. Implementation Restrictions 1009 This Appendix summarizes the features of the interface that have not 1010 been implemented in the latest (4.1a6) release of the ISI reference 1011 implementation of RSVP. 1013 o The RAPI_FILTERFORM_GPI and RAPI_FILTERFORM_GPI objects and the 1014 session flag RAPI_GPI_SESSION are implemented in RAPI and the 1015 API, but the IPSEC extensions are not yet fully implemented in 1016 RSVP. 1018 o The "SenderAdspec", and "SenderPolicy" parameters in a 1019 rapi_sender call are not implemented. 1021 o The "Style_Ext" and "Rcvr_Policy" parameters in a rapi_reserve 1022 call are not implemented. 1024 APPENDIX C. CHANGES 1026 This document describes major version 5 of RAPI. This version has 1027 the following differences from previous versions: 1029 o The "Legacy" format has been removed. 1031 o The rapi_fmt_filtspec() routine has been added. 1033 o The two session flags RAPI_GPI_SESSION and RAPI_USE_INTSERV have 1034 been defined. 1036 o The ErrorNode parameter in an upcall has been changed from a 1037 sockaddr to a pointer to a sockaddr structure, to accommodate 1038 IPv6. 1040 o IPv4-specific Socket structures sockaddr_in have been changed to 1041 the more general form sockaddr, to accomodate IPv6. The calling 1042 application should supply the appropriate form, sockaddr_in or 1043 sockaddr_in6, and cast it into a sockaddr for the call.