idnits 2.17.1 draft-ietf-iptel-cpl-03.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: ---------------------------------------------------------------------------- ** 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 : ---------------------------------------------------------------------------- ** There are 22 instances of too long lines in the document, the longest one being 27 characters in excess of 72. ** There are 2 instances of lines with control characters in the document. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 356: '...t-present, which MAY occur anywhere in...' RFC 2119 keyword, line 360: '...otherwise, which MUST be the last outp...' RFC 2119 keyword, line 393: '...invoked. Servers MAY define additional...' RFC 2119 keyword, line 397: '...ay. Additional subfield values MAY be...' RFC 2119 keyword, line 402: '...ignalling protocol. Servers MAY define...' (61 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 383 has weird spacing: '...main-of sub...' -- 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 (October 25, 2000) is 8583 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Missing reference section? '1' on line 2564 looks like a reference -- Missing reference section? '2' on line 2568 looks like a reference -- Missing reference section? '3' on line 2572 looks like a reference -- Missing reference section? '4' on line 2577 looks like a reference -- Missing reference section? '5' on line 2581 looks like a reference -- Missing reference section? '6' on line 2585 looks like a reference -- Missing reference section? '7' on line 2589 looks like a reference -- Missing reference section? '8' on line 2595 looks like a reference -- Missing reference section? '9' on line 2599 looks like a reference -- Missing reference section? '10' on line 2603 looks like a reference -- Missing reference section? '11' on line 2607 looks like a reference -- Missing reference section? '12' on line 2611 looks like a reference -- Missing reference section? '13' on line 2615 looks like a reference -- Missing reference section? '14' on line 2619 looks like a reference -- Missing reference section? '15' on line 2622 looks like a reference -- Missing reference section? '16' on line 2628 looks like a reference -- Missing reference section? '17' on line 2632 looks like a reference -- Missing reference section? '18' on line 2637 looks like a reference -- Missing reference section? '19' on line 2641 looks like a reference -- Missing reference section? '20' on line 2644 looks like a reference -- Missing reference section? '21' on line 2648 looks like a reference -- Missing reference section? '22' on line 2654 looks like a reference -- Missing reference section? '23' on line 2659 looks like a reference Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 25 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Engineering Task Force IPTEL WG 3 Internet Draft Lennox/Schulzrinne 4 draft-ietf-iptel-cpl-03.txt Columbia University 5 October 25, 2000 6 Expires: April, 2001 8 CPL: A Language for User Control of Internet Telephony Services 10 STATUS OF THIS MEMO 12 This document is an Internet-Draft and is in full conformance with 13 all provisions of Section 10 of RFC2026. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 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 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt 28 To view the list Internet-Draft Shadow Directories, see 29 http://www.ietf.org/shadow.html. 31 Abstract 33 The Call Processing Language (CPL) is a language that can be used to 34 describe and control Internet telephony services. It is designed to 35 be implementable on either network servers or user agent servers. It 36 is meant to be simple, extensible, easily edited by graphical 37 clients, and independent of operating system or signalling protocol. 38 It is suitable for running on a server where users may not be allowed 39 to execute arbitrary programs, as it has no variables, loops, or 40 ability to run external programs. 42 This document is a product of the IP Telephony (IPTEL) working group 43 of the Internet Engineering Task Force. Comments are solicited and 44 should be addressed to the working group's mailing list at 45 iptel@lists.research.bell-labs.com and/or the authors. 47 1 Introduction 49 The Call Processing Language (CPL) is a language that can be used to 50 describe and control Internet telephony services. It is not tied to 51 any particular signalling architecture or protocol; it is anticipated 52 that it will be used with both SIP [1] and H.323 [2]. 54 The CPL is powerful enough to describe a large number of services and 55 features, but it is limited in power so that it can run safely in 56 Internet telephony servers. The intention is to make it impossible 57 for users to do anything more complex (and dangerous) than describing 58 Internet telephony services. The language is not Turing-complete, and 59 provides no way to write loops or recursion. 61 The CPL is also designed to be easily created and edited by graphical 62 tools. It is based on XML [3], so parsing it is easy and many 63 parsers for it are publicly available. The structure of the language 64 maps closely to its behavior, so an editor can understand any valid 65 script, even ones written by hand. The language is also designed so 66 that a server can easily confirm scripts' validity at the time they 67 are delivered to it, rather that discovering them while a call is 68 being processed. 70 Implementations of the CPL are expected to take place both in 71 Internet telephony servers and in advanced clients; both can usefully 72 process and direct users' calls. This document primarily addresses 73 the usage in servers. A mechanism will be needed to transport scripts 74 between clients and servers; this document does not describe such a 75 mechanism, but related documents will. 77 The framework and requirements for the CPL architecture are described 78 in RFC 2824, "Call Processing Language Framework and Requirements" 79 [4]. 81 1.1 Conventions of this document 83 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 84 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 85 and "OPTIONAL" are to be interpreted as described in RFC 2119 [5] and 86 indicate requirement levels for compliant CPL implementations. 88 In examples, non-XML strings such as -action1, -action2, and so 89 forth, are sometimes used. These represent further parts of the 90 script which are not relevant to the example in question. 92 Some paragraphs are indented, like this; they give 93 motivations of design choices, or questions for future 94 discussion in the development of the CPL, and are not 95 essential to the specification of the language. 97 2 Structure of CPL scripts 99 2.1 High-level structure 101 A CPL script consists of two types of information: ancillary 102 information about the script, and call processing actions. 104 A call processing action is a structured tree that describes the 105 decisions and actions a telephony signalling server performs on a 106 call set-up event. There are two types of call processing actions: 107 top-level actions are actions that are triggered by signalling events 108 that arrive at the server. Two top-level action names are defined: 109 incoming, the action performed when a call arrives whose destination 110 is the owner of the script; and outgoing, the action performed when a 111 call arrives whose originator is the owner of the script. Sub-actions 112 are actions which can be called from other actions. The CPL forbids 113 sub-actions from being called recursively: see section 9. 115 Ancillary information is information which is necessary for a server 116 to correctly process a script, but which does not directly describe 117 any actions. Currently, no ancillary information is defined, but the 118 section is reserved for use by extensions. 120 2.2 Abstract structure of a call processing action 122 Abstractly, a call processing action is described by a collection of 123 nodes, which describe actions that can be performed or choices which 124 can be made. A node may have several parameters, which specify the 125 precise behavior of the node; they usually also have outputs, which 126 depend on the result of the condition or action. 128 For a graphical representation of a CPL action, see Figure 1. Nodes 129 and outputs can be thought of informally as boxes and arrows; the CPL 130 is designed so that actions can be conveniently edited graphically 131 using this representation. Nodes are arranged in a tree, starting at 132 a single root node; outputs of nodes are connected to additional 133 nodes. When an action is run, the action or condition described by 134 the top-level node is performed; based on the result of that node, 135 the server follows one of the node's outputs, and that action or 136 condition is performed; this process continues until a node with no 137 specified outputs is reached. Because the graph is acyclic, this will 138 occur after a bounded and predictable number of nodes are visited. 140 If an output to a node is not specified, it indicates that the CPL 141 server should perform a node- or protocol-specific action. Some nodes 142 have specific default actions associated with them; for others, the 143 default action is implicit in the underlying signalling protocol, or 144 can be configured by the administrator of the server. For further 145 details on this, see section 11. 147 _________________ ___________________ ________ busy 148 | Address-switch | | location | | proxy |--------\ 149 Call --->| field: origin | ->| url: sip:jones@ |--->|timeout:| timeout| 150 | subfield: host | / | example.com | | 10s |--------| 151 |-----------------|/ |___________________| | | failure| 152 | subdomain-of: | |________|--------| 153 | example.com | | 154 |-----------------| _____________________________________________/ 155 | otherwise | /.......................................... 156 | |\|. Voicemail . 157 |_________________| \. ____________________ . 158 ->| location | __________ . 159 . | url: sip:jones@ | | redirect | . 160 . | voicemail. |--->| | . 161 . | example.com | |__________| . 162 . |____________________| . 163 .......................................... 165 Figure 1: Sample CPL Action: Graphical Version 167 2.3 Location model 169 For flexibility, one piece of information necessary for the function 170 of a CPL is not given as node parameters: the set of locations to 171 which a call is to be directed. Instead, this set of locations is 172 stored as an implicit global variable throughout the execution of a 173 processing action (and its sub-actions). This allows locations to be 174 retrieved from external sources, filtered, and so forth, without 175 requiring general language support for such actions (which could harm 176 the simplicity and tractability of understanding the language). The 177 specific actions which add, retrieve, or filter location sets are 178 given in section 6. 180 For the incoming top-level processing action, the location set is 181 initialized to the empty set. For the outgoing action, it is 182 initialized to the destination address of the call. 184 2.4 XML structure 186 Syntactically, CPL scripts are represented by XML documents. XML is 187 thoroughly specified by [3], and implementors of this specification 188 should be familiar with that document, but as a brief overview, XML 189 consists of a hierarchical structure of tags; each tag can have a 190 number of attributes. It is visually and structurally very similar to 191 HTML [6], as both languages are simplifications of the earlier and 192 larger standard SGML [7]. 194 See Figure 2 for the XML document corresponding to the graphical 195 representation of the CPL script in Figure 1. Both nodes and outputs 196 in the CPL are represented by XML tags; parameters are represented by 197 XML tag attributes. Typically, node tags contain output tags, and 198 vice-versa (with one exception; see section 6.1). 200 The connection between the output of a node and another node is 201 represented by enclosing the tag representing the pointed-to node 202 inside the tag for the outer node's output. Convergence (several 203 outputs pointing to a single node) is represented by sub-actions, 204 discussed further in section 9. 206 The higher-level structure of a CPL script is represented by tags 207 corresponding to each piece of meta-information, sub-actions, and 208 top-level actions, in order. This higher-level information is all 209 enclosed in a special tag cpl, the outermost tag of the XML document. 211 A complete Document Type Declaration for the CPL is provided in 212 Appendix C. The remainder of the main sections of this document 213 describe the semantics of the CPL, while giving its syntax 214 informally. For the formal syntax, please see the appendix. 216 3 Document information 218 This section gives meta-information about CPL scripts. 220 3.1 CPL Document Identifiers for XML 222 A CPL script list which appears as a top-level XML document is 223 identified with the formal public identifier "-//IETF//DTD RFCxxxx 224 CPL 1.0//EN". If this document is published as an RFC, "xxxx" will be 225 replaced by the RFC number. 227 A CPL embedded as a fragment within another XML document is 228 identified with the XML namespace identifier 229 230 232 233 234 235 236 237 239 240 241
242 243 244 245 246 247 248 249
250 251 252 253 254 255 257 Figure 2: Sample CPL Script: XML Version 259 "http://www.ietf.org/internet-drafts/draft-ietf-iptel-cpl-03.txt". 260 If this document is published as an RFC, the namespace identifier 261 will be "http://www.rfc-editor.org/rfc/rfcxxxx.txt", where xxxx is 262 the RFC number. 264 Note that the URIs specifying XML namespaces are only 265 globally unique names; they do not have to reference any 266 particular actual object. The URI of a canonical source of 267 this specification meets the requirement of being globally 268 unique, and is also useful to document the format. 270 3.2 MIME Registration 272 As an XML type, CPL's MIME registration conforms with "XML Media 273 Types" [8] as well as RFC 2048 [9]. 275 MIME media type name: application 277 MIME subtype name: cpl+xml 279 Mandatory parameters: none 281 Optional parameters: charset 282 As for application/xml in "XML Media Types." 284 Encoding considerations: As for application/xml in "XML Media 285 Types." 287 Security considerations: See section 14, and section 10 of "XML 288 Media Types." 290 Interoperability considerations: Different CPL servers may use 291 incompatible address types. However, all potential 292 interoperability issues should be resolvable at the time a 293 script is uploaded; there should be no interoperability 294 issues which cannot be detected until runtime. 296 Published specification: This document. 298 Applications which use this media type: None publicly released 299 at this time, as far as the authors are aware. 301 Additional information: 303 Magic number: None 305 File extension: .cpl or .xml 307 Macintosh file type code: "TEXT" 309 Person and e-mail address for further information: 310 Jonathan Lennox 311 Henning Schulzrinne 313 Intended usage: COMMON 315 Author/Change Controller: The IETF. 317 4 Script structure: overview 319 As mentioned, a CPL script consists of ancillary information, 320 subactions, and top-level actions. The full syntax of the cpl node is 321 given in Figure 3. 323 Tag: cpl 324 Parameters: none 325 Sub-tags: ancillary See section 10 326 subaction See section 9 327 outgoing Top-level actions to take on this user's 328 outgoing calls 329 incoming Top-level actions to take on this user's 330 incoming calls 332 Figure 3: Syntax of the top-level cpl tag 334 Call processing actions, both top-level actions and sub-actions, 335 consist of nodes and outputs. Nodes and outputs are both described by 336 XML tags. There are four categories of CPL nodes: switches , which 337 represent choices a CPL script can make; location modifiers , which 338 add or remove locations from the location set; signalling actions , 339 which cause signalling events in the underlying protocol; and non- 340 signalling actions, which take an action but do not effect the 341 underlying protocol. 343 5 Switches 345 Switches represent choices a CPL script can make, based on either 346 attributes of the original call request or items independent of the 347 call. 349 All switches are arranged as a list of conditions that can match a 350 variable. Each condition corresponds to a node output; the output 351 points to the next node to execute if the condition was true. The 352 conditions are tried in the order they are presented in the script; 353 the output corresponding to the first node to match is taken. 355 There are two special switch outputs that apply to every switch type. 356 The output not-present, which MAY occur anywhere in the list of 357 outputs, is true if the variable the switch was to match was not 358 present in the original call setup request. (In this document, this 359 is sometimes described by saying that the information is "absent".) 360 The output otherwise, which MUST be the last output specified if it 361 is present, matches if no other condition matched. 363 If no condition matches and no otherwise output was present in the 364 script, the default script action is taken. See section 11 for more 365 information on this. 367 5.1 Address switches 369 Address switches allow a CPL script to make decisions based on one of 370 the addresses present in the original call request. They are 371 summarized in Figure 4. 373 Node: address-switch 374 Outputs: address Specific addresses to match 375 Parameters: field origin, destination, or original-destination 376 subfield address-type, user, host, port, tel, or display, 377 ( 378 also: password and alias-type) 380 Output: address 381 Parameters: is exact match 382 contains substring match (for display only) 383 subdomain-of sub-domain match (for host, tel only) 385 Figure 4: Syntax of the address-switch node 387 Address switches have two node parameters: field, and subfield. The 388 mandatory field parameter allows the script to specify which address 389 is to be considered for the switch: either the call's origin address 390 (field "origin"), its current destination address (field 391 "destination"), or its original destination (field "original- 392 destination"), the destination the call had before any earlier 393 forwarding was invoked. Servers MAY define additional field values. 395 The optional subfield specifies what part of the address is to be 396 considered. The possible subfield values are: address-type, user, 397 host, port, tel, and display. Additional subfield values MAY be 398 defined for protocol-specific values. (The subfield password is 399 defined for SIP in Section 5.1.1; the subfield alias-type is defined 400 for H.323 in Appendix B.1.) If no subfield is specified, the 401 "entire" address is matched; the precise meaning of this is defined 402 for each underlying signalling protocol. Servers MAY define 403 additional subfield values. 405 The subfields are defined as follows: 407 address-type This indicates the type of the underlying address; 408 i.e., the URI scheme, if the address can be represented by 409 a URI. The types specifically discussed by this document 410 are sip, tel, and h323. The address type is not case- 411 sensitive. It has a value for all defined address types. 413 user This subfield of the address indicates, for e-mail style 414 addresses, the user part of the address. For telephone 415 number style address, it includes the subscriber number. 416 This subfield is case-sensitive; it may be absent. 418 host This subfield of the address indicates the Internet host 419 name or IP address corresponding to the address, in host 420 name, IPv4, or IPv6 format. For host names only, subdomain 421 matching is supported with the subdomain-of match operator. 422 It is not case sensitive, and may be absent. 424 port This subfield indicates the TCP or UDP port number of the 425 address, numerically in decimal format. It is not case 426 sensitive, as it MUST only contain decimal digits. It may 427 be absent; however, for address types with default ports, 428 an absent port matches the default port number. 430 tel This subfield indicates a telephone subscriber number, if 431 the address contains such a number. It is not case 432 sensitive (the telephone numbers may contain the symbols 433 `A' `B' `C' and `D'), and may be absent. It may be matched 434 using the subdomain-of match operator. Punctuation and 435 separator characters in telephone numbers are discarded. 437 display This subfield indicates a "display name" or user-visible 438 name corresponding to an address. It is a Unicode string, 439 and is matched using the case-insensitive algorithm 440 described in section 5.2. The contains operator may be 441 applied to it. It may be absent. 443 For any completely unknown subfield, the server MAY reject the script 444 at the time it is submitted with an indication of the problem; if a 445 script with an unknown subfield is executed, the server MUST consider 446 the not-present output to be the valid one. 448 The address output tag may take exactly one of three possible 449 parameters, indicating the kind of matching allowed. 451 is An output with this match operator is followed if the 452 subfield being matched in the address-switch exactly 453 matches the argument of the operator. It may be used for 454 any subfield, or for the entire address if no subfield was 455 specified. 457 subdomain-of This match operator applies only for the subfields 458 host and tel. In the former case, it matches if the 459 hostname being matched is a subdomain of the domain given 460 in the argument of the match operator; thus, subdomain- 461 of="example.com" would match the hostnames "example.com", 462 "research.example.com", and 463 "zaphod.sales.internal.example.com". IP addresses may be 464 given as arguments to this operator; however, they only 465 match exactly. In the case of the tel subfield, the output 466 matches if the telephone number being matched has a prefix 467 that matches the argument of the match operator; 468 subdomain-of="1212555" would match the telephone number "1 469 212 555 1212." 471 contains This match operator applies only for the subfield 472 display. The output matches if the display name being 473 matched contains the argument of the match as a substring. 475 5.1.1 Usage of address-switch with SIP 477 For SIP, the origin address corresponds to the address in the From 478 header; destination corresponds to the Request-URI; and original- 479 destination corresponds to the To header. 481 The display subfield of an address is the display-name part of the 482 address, if it is present. Because of SIP's syntax, the destination 483 address field will never have a display subfield. 485 The address-type subfield of an address is the URI scheme of that 486 address. Other address fields depend on that address-type. 488 For sip URLs, the user, host, and port subfields correspond to the 489 "user," "host," and "port" elements of the URI syntax. The tel 490 subfield is defined to be the "user" part of the URI if and only if 491 the "user=phone" parameter is given to the URI. An additional 492 subfield, password is defined to correspond to the "password" element 493 of the SIP URI, and is case-sensitive. However, use of this field is 494 NOT RECOMMENDED for general security reasons. 496 For tel URLs, the tel and user subfields are the subscriber name; in 497 the former case, visual separators are stripped. The host and port 498 subfields are both not present. 500 For h323 URLs, subfields MAY be set according to the scheme described 501 in Appendix B. 503 For other URI schemes, only the address-type subfield is defined by 504 this specification; servers MAY set other pre-defined subfields, or 505 MAY support additional subfields. 507 If no subfield is specified for addresses in SIP messages, the string 508 matched is the URI part of the address. For "sip" URLs, all 509 parameters are stripped; for other URLs, the URL is used verbatim. 511 5.2 String switches 513 String switches allow a CPL script to make decisions based on free- 514 form strings present in a call request. They are summarized in Figure 515 5. 517 Node: string-switch 518 Outputs: string Specific string to match 519 Parameters: field subject, organization, user-agent, 520 language, or display 522 Output: string 523 Parameters: is exact match 524 contains substring match 526 Figure 5: Syntax of the string-switch node 528 String switches have one node parameter: field. The mandatory field 529 parameter specifies which string is to be matched. 531 String switches are dependent on the call signalling protocol being 532 used. 534 Five fields are defined, listed below. The value of each of these 535 fields, except as specified, is a free-form Unicode string with no 536 other structure defined. 538 subject The subject of the call. 540 organization The organization of the originator of the call. 542 user-agent The name of the program or device with which the call 543 request was made. 545 language The languages in which the originator of the call 546 wishes to receive responses. This contains a list of RFC 547 1766 [10] language tags, separated by commas. 549 Note that matching based on contains is likely to be 550 much more useful than matching based on is, for this 551 field. 553 display Free-form text associated with the call, intended to be 554 displayed to the recipient, with no other semantics defined 555 by the signalling protocol. 557 Strings are matched as case-insensitive Unicode strings, in the 558 following manner. First, strings are canonicalized to the 559 "Compatibility Composition" (KC) form, as specified in Unicode 560 Technical Report 15 [11]. Then, strings are compared using locale- 561 insensitive caseless mapping, as specified in Unicode Technical 562 Report 21 [12]. 564 Code to perform the first step, in Java and Perl, is 565 available; see the links from Annex E of UTR 15 [11]. The 566 case-insensitive string comparison in the Java standard 567 class libraries already performs the second step; other 568 Unicode-aware libraries should be similar. 570 The output tags of string matching are named string, and have a 571 mandatory argument, one of is or contains, indicating whole-string 572 match or substring match, respectively. 574 5.2.1 Usage of string-switch with SIP 576 For SIP, the fields subject, organization, and user-agent correspond 577 to the SIP header fields with the same name. These are used verbatim 578 as they appear in the message. 580 The field language corresponds to the SIP Accept-Language header. It 581 is converted to a list of comma-separated languages as described 582 above. 584 The field display is not used, and is never present. 586 5.3 Time switches 588 Time switches allow a CPL script to make decisions based the time 589 and/or date the script is being executed. They are summarized in 590 Figure 6. 592 Time switches are independent of the underlying signalling protocol. 594 Time switches are based on a large subset of how recurring intervals 595 Node: time-switch 596 Outputs: time Specific time to match 597 Parameters: tzid RFC 2445 Time Zone Identifier 598 tzurl RFC 2445 Time Zone URL 600 Output: time 601 Parameters: dtstart Start of interval (RFC 2445 DATE-TIME) 602 dtend End of interval (RFC 2445 DATE-TIME) 603 duration Length of interval (RFC 2445 DURATION) 604 freq Frequency of recurrence (one of "daily", 605 "weekly", "monthly", or "yearly") 606 interval How often the recurrence repeats 607 until Bound of recurrence (RFC 2445 DATE-TIME) 608 byday List of days of the week 609 bymonthday List of days of the month 610 byyearday List of days of the year 611 byweekno List of weeks of the year 612 bymonth List of months of the year 613 wkst First day of workweek 615 Figure 6: Syntax of the time-switch node 617 of time are specified in the Internet Calendaring and Scheduling Core 618 Object Specification (iCal COS), RFC 2445 [13]. 620 This allows CPLs to be generated automatically from 621 calendar books. It also allows us to re-use the extensive 622 existing work specifying time intervals. 624 The subset was designed with the goal that a time-switch 625 can be evaluated -- an instant can be determined to fall 626 within an interval, or not -- in constant (O(1)) time. 628 An algorithm to whether an instant falls within a given recurrence is 629 given in Appendix A. 631 The time-switch tag takes two optional parameters, tzid and tzurl, 632 both of which are defined in RFC 2445 (sections 4.8.3.1 and 4.8.3.5 633 respectively). The TZID is the identifying label by which a time zone 634 definition is referenced. If it begins with a forward slash 635 (solidus), it references a to-be-defined global time zone registry; 636 otherwise it is locally-defined at the server. The TZURL gives a 637 network location from which an up-to-date VTIMEZONE definition for 638 the timezone can be retrieved. 640 While TZID labels that do not begin with a forward slash are locally 641 defined, it is RECOMMENDED that servers support at least the naming 642 scheme used by Olson Time Zone database [14]. Examples of timezone 643 databases that use the Olson scheme are the zoneinfo files on most 644 Unix-like systems, and the standard Java TimeZone class. 646 If a script is uploaded with a tzid and tzurl which the CPL server 647 does not recognize or cannot resolve, it SHOULD diagnose and reject 648 this at script upload time. If neither tzid nor tzurl are present, 649 all non-UTC times within this time switch should be interpreted as 650 being "floating" times, i.e. that they are specified in the local 651 timezone of the CPL server. 653 Because of daylight-savings-time changes over the course of 654 a year, it is necessary to specify time switches in a given 655 timezone. UTC offsets are not sufficient, or a time-of-day 656 routing rule which held between 9 am and 5 pm in the 657 eastern United States would start holding between 8 am and 658 4 pm at the end of October. 660 Authors of CPL servers should be careful to handle correctly the 661 intervals when local time is discontinuous, at the beginning or end 662 of daylight-savings time. Note especially that some times may occur 663 more than once when clocks are set back. The algorithm in Appendix A 664 is believed to handle this correctly. 666 Time nodes specify a list of periods during which their output should 667 be taken. They have two required parameters: dtstart, which specifies 668 the beginning of the first period of the list, and exactly one of 669 dtend or duration, which specify the ending time or the duration of 670 the period, respectively. The dtstart and dtend parameters are 671 formatted as iCal COS DATE-TIME values, as specified in section 4.3.5 672 of RFC 2445 [13]. Because time zones are specified in the top-level 673 time-switch tag, only forms 1 or 2 (floating or UTC times) can be 674 used. The duration parameter is given as an iCal COS DURATION 675 parameter, as specified in section 4.3.6 of RFC 2445. Both the 676 DATE-TIME and the DURATION syntaxes are subsets of the corresponding 677 syntaxes from ISO 8601 [15]. 679 For a recurring interval, the duration parameter MUST be less than 680 twenty-four hours. For non-recurring intervals, durations of any 681 length are permitted. 683 If no other parameters are specified, a time node indicates only a 684 single period of time. More complicated sets periods intervals are 685 constructed as recurrences. A recurrence is specified by including 686 the freq parameter, which indicates the type of recurrence rule. No 687 parameters other than dtstart, dtend, and duration SHOULD be 688 specified unless freq is present. 690 The freq parameter takes one of the following values: daily, to 691 specify repeating periods based on an interval of a day or more; 692 weekly, to specify repeating periods based on an interval of a week 693 or more; monthly, to specify repeating periods based on an interval 694 of a month or more; and yearly, to specify repeating periods based on 695 an interval of a year or more. These values are not case-sensitive. 697 The values secondly, minutely, and hourly are present in 698 iCal, but were removed from CPL. 700 The interval parameter contains a positive integer representing how 701 often the recurrence rule repeats. The default value is "1", meaning 702 every second for a secondly rule, or every minute for a minutely 703 rule, every hour for an hourly rule, every day for a daily rule, 704 every week for a weekly rule, every month for a monthly rule and 705 every year for a yearly rule. 707 The until parameter defines an iCal COS DATE or DATE-TIME value which 708 bounds the recurrence rule in an inclusive manner. If the value 709 specified by until is synchronized with the specified recurrence, 710 this date or date-time becomes the last instance of the recurrence. 711 If specified as a date-time value, then it MUST be specified in an 712 UTC time format. If not present, the recurrence is considered to 713 repeat forever. 715 iCal also defines a count parameter, which allows an 716 alternate method of specifying a bound to a recurrence. 717 This bound has been removed from CPL. Translating from full 718 iCal recurrences to CPL recurrences requires that the count 719 parameter be converted to an until parameter, which can be 720 done by enumerating the recurrence and determining its 721 final date. 723 The byday parameter specifies a comma-separated list of days of the 724 week. MO indicates Monday; TU indicates Tuesday; WE indicates 725 Wednesday; TH indicates Thursday; FR indicates Friday; SA indicates 726 Saturday; SU indicates Sunday. These values are not case-sensitive. 728 Each byday value can also be preceded by a positive (+n) or negative 729 (-n) integer. If present, this indicates the nth occurrence of the 730 specific day within the monthly or yearly recurrence. For example, 731 within a monthly rule, +1MO (or simply 1MO) represents the first 732 Monday within the month, whereas -1MO represents the last Monday of 733 the month. If an integer modifier is not present, it means all days 734 of this type within the specified frequency. For example, within a 735 monthly rule, MO represents all Mondays within the month. 737 The bymonthday parameter specifies a comma-separated list of days of 738 the month. Valid values are 1 to 31 or -31 to -1. For example, -10 739 represents the tenth to the last day of the month. 741 The byyearday parameter specifies a comma-separated list of days of 742 the year. Valid values are 1 to 366 or -366 to -1. For example, -1 743 represents the last day of the year (December 31st) and -306 744 represents the 306th to the last day of the year (March 1st). 746 The byweekno parameter specifies a comma-separated list of ordinals 747 specifying weeks of the year. Valid values are 1 to 53 or -53 to -1. 748 This corresponds to weeks according to week numbering as defined in 749 ISO 8601 [15]. A week is defined as a seven day period, starting on 750 the day of the week defined to be the week start (see wkst). Week 751 number one of the calendar year is the first week which contains at 752 least four (4) days in that calendar year. This parameter is only 753 valid for yearly rules. For example, 3 represents the third week of 754 the year. 756 Note: Assuming a Monday week start, week 53 can only occur 757 when Thursday is January 1 or if it is a leap year and 758 Wednesday is January 1. 760 The bymonth parameter specifies a comma-separated list of months of 761 the year. Valid values are 1 to 12. 763 The wkst parameter specifies the day on which the workweek starts. 764 Valid values are MO, TU, WE, TH, FR, SA and SU. This is significant 765 when a weekly recurrence has an interval greater than 1, and a byday 766 parameter is specified. This is also significant in a yearly 767 recurrence when a byweekno parameter is specified. The default value 768 is MO, following ISO 8601 [15]. 770 iCal also includes the Byxxx parameters bysecond, byminute, 771 byhour, and bysetpos, which have been removed from CPL. 773 If byxxx parameter values are found which are beyond the available 774 scope (ie, bymonthday="30" in February), they are simply ignored. 776 Byxxx parameters modify the recurrence in some manner. Byxxx rule 777 parts for a period of time which is the same or greater than the 778 frequency generally reduce or limit the number of occurrences of the 779 recurrence generated. For example, freq="daily" bymonth="1" reduces 780 the number of recurrence instances from all days (if the bymonth 781 parameter is not present) to all days in January. Byxxx parameters 782 for a period of time less than the frequency generally increase or 783 expand the number of occurrences of the recurrence. For example, 784 freq="yearly" bymonth="1,2" increases the number of days within the 785 yearly recurrence set from 1 (if bymonth parameter is not present) to 786 2. 788 If multiple Byxxx parameters are specified, then after evaluating the 789 specified freq and interval parameters, the Byxxx parameters are 790 applied to the current set of evaluated occurrences in the following 791 order: bymonth, byweekno, byyearday, bymonthday, and byday; then 792 until is evaluated. 794 Here is an example of evaluating multiple Byxxx parameters. 796