idnits 2.17.1 draft-ietf-iptel-cpl-05.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 26 instances of too long lines in the document, the longest one being 21 characters in excess of 72. ** There are 2 instances of lines with control characters in the document. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. ** 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 353: '...-present", which MAY occur anywhere in...' RFC 2119 keyword, line 357: '...therwise", which MUST be the last outp...' RFC 2119 keyword, line 388: '...invoked. Servers MAY define additional...' RFC 2119 keyword, line 392: '...play". Additional subfield values MAY...' RFC 2119 keyword, line 397: '...ignalling protocol. Servers MAY define...' (74 more instances...) 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 (November 21, 2001) is 8192 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 2834 looks like a reference -- Missing reference section? '2' on line 2838 looks like a reference -- Missing reference section? '3' on line 2842 looks like a reference -- Missing reference section? '4' on line 2847 looks like a reference -- Missing reference section? '5' on line 2851 looks like a reference -- Missing reference section? '6' on line 2855 looks like a reference -- Missing reference section? '7' on line 2859 looks like a reference -- Missing reference section? '8' on line 2865 looks like a reference -- Missing reference section? '9' on line 2868 looks like a reference -- Missing reference section? '10' on line 2872 looks like a reference -- Missing reference section? '11' on line 2877 looks like a reference -- Missing reference section? '12' on line 2881 looks like a reference -- Missing reference section? '13' on line 2885 looks like a reference -- Missing reference section? '14' on line 2889 looks like a reference -- Missing reference section? '15' on line 2892 looks like a reference -- Missing reference section? '16' on line 2898 looks like a reference -- Missing reference section? '17' on line 2902 looks like a reference -- Missing reference section? '18' on line 2906 looks like a reference -- Missing reference section? '19' on line 2911 looks like a reference -- Missing reference section? '20' on line 2915 looks like a reference -- Missing reference section? '21' on line 2918 looks like a reference -- Missing reference section? '22' on line 2922 looks like a reference -- Missing reference section? '23' on line 2928 looks like a reference -- Missing reference section? '24' on line 2932 looks like a reference Summary: 6 errors (**), 0 flaws (~~), 2 warnings (==), 26 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-05.txt Columbia University 5 November 21, 2001 6 Expires: May, 2002 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 Some paragraphs are indented, like this; they give 89 motivations of design choices, or questions for future 90 discussion in the development of the CPL, and are not 91 essential to the specification of the language. 93 2 Structure of CPL Scripts 94 2.1 High-level Structure 96 A CPL script consists of two types of information: ancillary 97 information about the script, and call processing actions. 99 A call processing action is a structured tree that describes the 100 operations and decisions a telephony signalling server performs on a 101 call set-up event. There are two types of call processing actions: 102 top-level actions and subactions. Top-level actions are actions that 103 are triggered by signalling events that arrive at the server. Two 104 top-level action names are defined: "incoming", the action performed 105 when a call arrives whose destination is the owner of the script; and 106 "outgoing", the action performed when a call arrives whose originator 107 is the owner of the script. Subactions are actions which can be 108 called from other actions. The CPL forbids subactions from being 109 called recursively: see Section 9. 111 Ancillary information is information which is necessary for a server 112 to correctly process a script, but which does not directly describe 113 any operations or decisions. Currently, no ancillary information is 114 defined, but the section is reserved for use by extensions. 116 2.2 Abstract Structure of a Call Processing Action 118 Abstractly, a call processing action is described by a collection of 119 nodes, which describe operations that can be performed or decisions 120 which can be made. A node may have several parameters, which specify 121 the precise behavior of the node; they usually also have outputs, 122 which depend on the result of the decision or action. 124 For a graphical representation of a CPL action, see Figure 1. Nodes 125 and outputs can be thought of informally as boxes and arrows; the CPL 126 is designed so that actions can be conveniently edited graphically 127 using this representation. Nodes are arranged in a tree, starting at 128 a single root node; outputs of nodes are connected to additional 129 nodes. When an action is run, the action or decision described by the 130 action's top-level node is performed; based on the result of that 131 node, the server follows one of the node's outputs, and the 132 subsequent node it points to is performed; this process continues 133 until a node with no specified outputs is reached. Because the graph 134 is acyclic, this will occur after a bounded and predictable number of 135 nodes are visited. 137 If an output to a node does not point to another node, it indicates 138 that the CPL server should perform a node- or protocol-specific 139 action. Some nodes have specific default behavior associated with 140 them; for others, the default behavior is implicit in the underlying 141 signalling protocol, or can be configured by the administrator of the 142 server. For further details on this, see Section 11. 144 _________________ ___________________ ________ busy 145 | Address-switch | | location | | proxy |--------\ 146 Call --->| field: origin | ->| url: sip:jones@ |--->|timeout:| timeout| 147 | subfield: host | / | example.com | | 10s |--------| 148 |-----------------|/ |___________________| | | failure| 149 | subdomain-of: | |________|--------| 150 | example.com | | 151 |-----------------| _____________________________________________/ 152 | otherwise | /.......................................... 153 | |\|. Voicemail . 154 |_________________| \. ____________________ . 155 ->| location | __________ . 156 . | url: sip:jones@ | | redirect | . 157 . | voicemail. |--->| | . 158 . | example.com | |__________| . 159 . |____________________| . 160 .......................................... 162 Figure 1: Sample CPL Action: Graphical Version 164 2.3 Location Model 166 For flexibility, one piece of information necessary for the function 167 of a CPL is not given as node parameters: the set of locations to 168 which a call is to be directed. Instead, this set of locations is 169 stored as an implicit global variable throughout the execution of a 170 processing action (and its subactions). This allows locations to be 171 retrieved from external sources, filtered, and so forth, without 172 requiring general language support for such operations (which could 173 harm the simplicity and tractability of understanding the language). 174 The specific operations which add, retrieve, or filter location sets 175 are given in Section 6. 177 For the incoming top-level call processing action, the location set 178 is initialized to the empty set. For the outgoing action, it is 179 initialized to the destination address of the call. 181 2.4 XML Structure 182 Syntactically, CPL scripts are represented by XML documents. XML is 183 thoroughly specified by [3], and implementors of this specification 184 should be familiar with that document, but as a brief overview, XML 185 consists of a hierarchical structure of tags; each tag can have a 186 number of attributes. It is visually and structurally very similar to 187 HTML [6], as both languages are simplifications of the earlier and 188 larger standard SGML [7]. 190 See Figure 2 for the XML document corresponding to the graphical 191 representation of the CPL script in Figure 1. Both nodes and outputs 192 in the CPL are represented by XML tags; parameters are represented by 193 XML tag attributes. Typically, node tags contain output tags, and 194 vice-versa (with a few exceptions: see Sections 6.1, 6.3, 8.1, and 195 8.2). 197 The connection between the output of a node and another node is 198 represented by enclosing the tag representing the pointed-to node 199 inside the tag for the outer node's output. Convergence (several 200 outputs pointing to a single node) is represented by subactions, 201 discussed further in Section 9. 203 The higher-level structure of a CPL script is represented by tags 204 corresponding to each piece of ancillary information, subactions, and 205 top-level actions, in order. This higher-level information is all 206 enclosed in a special tag "cpl", the outermost tag of the XML 207 document. 209 A complete Document Type Declaration for the CPL is provided in 210 Appendix C. The remainder of the main sections of this document 211 describe the semantics of the CPL, while giving its syntax 212 informally. For the formal syntax, please see the appendix. 214 3 Document Information 216 This section gives information describing how CPL scripts are 217 identified. 219 3.1 CPL Document Identifiers for XML 221 A CPL script list which appears as a top-level XML document is 222 identified with the formal public identifier "-//IETF//DTD RFCxxxx 223 CPL 1.0//EN". 225 A CPL embedded as a fragment within another XML document is 226 identified with the XML namespace identifier "http://www.rfc- 227 editor.org/rfc/rfcxxxx.txt". 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 [Note to RFC editor: please replace "xxxx" above with the 260 number of this RFC.] 262 Note that the URIs specifying XML namespaces are only 263 globally unique names; they do not have to reference any 264 particular actual object. The URI of a canonical source of 265 this specification meets the requirement of being globally 266 unique, and is also useful to document the format. 268 3.2 MIME Registration 270 As an XML type, CPL's MIME registration conforms with "XML Media 271 Types," RFC 3023 [8]. 273 MIME media type name: application 275 MIME subtype name: cpl+xml 277 Mandatory parameters: none 279 Optional parameters: charset 280 As for application/xml in RFC 3023. 282 Encoding considerations: As for application/xml in RFC 3023. 284 Security considerations: See Section 14, and Section 10 of RFC 285 3023. 287 Interoperability considerations: Different CPL servers may use 288 incompatible address types. However, all potential 289 interoperability issues should be resolvable at the time a 290 script is uploaded; there should be no interoperability 291 issues which cannot be detected until runtime. 293 Published specification: This document. 295 Applications which use this media type: None publicly released 296 at this time, as far as the authors are aware. 298 Additional information: 300 Magic number: None 302 File extension: .cpl or .xml 304 Macintosh file type code: "TEXT" 306 Person and e-mail address for further information: 307 Jonathan Lennox 308 Henning Schulzrinne 310 Intended usage: COMMON 312 Author/Change Controller: The IETF. 314 4 Script Structure: Overview 316 As mentioned, a CPL script consists of ancillary information, 317 subactions, and top-level actions. The full syntax of the "cpl" node 318 is given in Figure 3. 320 Tag: "cpl" 321 Parameters: None 322 Sub-tags: "ancillary" See Section 10 323 "subaction" See Section 9 324 "outgoing" Top-level actions to take on this user's 325 outgoing calls 326 "incoming" Top-level actions to take on this user's 327 incoming calls 329 Figure 3: Syntax of the top-level "cpl" tag 331 Call processing actions, both top-level actions and sub-actions, 332 consist of a tree of nodes and outputs. Nodes and outputs are both 333 described by XML tags. There are four categories of CPL nodes: 334 switches, which represent choices a CPL script can make; location 335 modifiers, which add or remove locations from the location set; 336 signalling operations, which cause signalling events in the 337 underlying protocol; and non-signalling operations, which trigger 338 behavior which does not effect the underlying protocol. 340 5 Switches 342 Switches represent choices a CPL script can make, based on either 343 attributes of the original call request or items independent of the 344 call. 346 All switches are arranged as a list of conditions that can match a 347 variable. Each condition corresponds to a node output; the output 348 points to the next node to execute if the condition was true. The 349 conditions are tried in the order they are presented in the script; 350 the output corresponding to the first node to match is taken. 352 There are two special switch outputs that apply to every switch type. 353 The output "not-present", which MAY occur anywhere in the list of 354 outputs, is true if the variable the switch was to match was not 355 present in the original call setup request. (In this document, this 356 is sometimes described by saying that the information is "absent".) 357 The output "otherwise", which MUST be the last output specified if it 358 is present, matches if no other condition matched. 360 If no condition matches and no "otherwise" output was present in the 361 script, the default script behavior is taken. See Section 11 for more 362 information on this. 364 5.1 Address Switches 365 Address switches allow a CPL script to make decisions based on one of 366 the addresses present in the original call request. They are 367 summarized in Figure 4. 369 Node: "address-switch" 370 Outputs: "address" Specific addresses to match 371 Parameters: "field" "origin", "destination", or "original-destination" 372 "subfield" "address-type", "user", "host", "port", "tel", or "display" 373 (also: "password" and "alias-type") 375 Output: "address" 376 Parameters: "is" exact match 377 "contains" substring match (for "display" only) 378 "subdomain-of" sub-domain match (for "host", "tel" only) 380 Figure 4: Syntax of the "address-switch" node 382 Address switches have two node parameters: "field", and "subfield". 383 The mandatory "field" parameter allows the script to specify which 384 address is to be considered for the switch: either the call's origin 385 address (field "origin"), its current destination address (field 386 "destination"), or its original destination (field "original- 387 destination"), the destination the call had before any earlier 388 forwarding was invoked. Servers MAY define additional field values. 390 The optional "subfield" specifies what part of the address is to be 391 considered. The possible subfield values are: "address-type", "user", 392 "host", "port", "tel", and "display". Additional subfield values MAY 393 be defined for protocol-specific values. (The subfield "password" is 394 defined for SIP in Section 5.1.1; the subfield "alias-type" is 395 defined for H.323 in Appendix B.1.) If no subfield is specified, the 396 "entire" address is matched; the precise meaning of this is defined 397 for each underlying signalling protocol. Servers MAY define 398 additional subfield values. 400 The subfields are defined as follows: 402 address-type This indicates the type of the underlying address; 403 i.e., the URI scheme, if the address can be represented by 404 a URI. The types specifically discussed by this document 405 are "sip", "tel", and "h323". The address type is not 406 case-sensitive. It has a value for all defined address 407 types. 409 user This subfield of the address indicates, for e-mail style 410 addresses, the user part of the address. For telephone 411 number style address, it includes the subscriber number. 412 This subfield is case-sensitive; it may be absent. 414 host This subfield of the address indicates the Internet host 415 name or IP address corresponding to the address, in host 416 name, IPv4, or IPv6 [9] textual representation format. 417 Host names are compared as strings. IP addresses are 418 compared numerically. (In particular, the presence or 419 location of an IPv6 :: omitted-zero-bits block is not 420 significant for matching purposes.) Host names are never 421 equal to IP addresses -- no DNS resolution is performed. 422 IPv4 addresses are never equal to IPv6 addresses, even if 423 the IPv6 address is a v4-in-v6 embedding. 425 For host names only, subdomain matching is supported with 426 the "subdomain-of" match operator. The "subdomain-of" 427 operator ignores leading dots in the hostname or match 428 pattern, if any. This subfield is not case sensitive, and 429 may be absent. 431 port This subfield indicates the TCP or UDP port number of the 432 address, numerically in decimal format. It is not case 433 sensitive, as it MUST only contain decimal digits. Leading 434 zeros are ignored. This subfield may be absent; however, 435 for address types with default ports, an absent port 436 matches the default port number. 438 tel This subfield indicates a telephone subscriber number, if 439 the address contains such a number. It is not case 440 sensitive (the telephone numbers may contain the symbols 441 `A' `B' `C' and `D'), and may be absent. It may be matched 442 using the "subdomain-of" match operator. Punctuation and 443 separator characters in telephone numbers are discarded. 445 display This subfield indicates a "display name" or user-visible 446 name corresponding to an address. It is a Unicode string, 447 and is matched using the case-insensitive algorithm 448 described in Section 5.2. The "contains" operator may be 449 applied to it. It may be absent. 451 For any completely unknown subfield, the server MAY reject the script 452 at the time it is submitted with an indication of the problem; if a 453 script with an unknown subfield is executed, the server MUST consider 454 the "not-present" output to be the valid one. 456 The "address" output tag may take exactly one of three possible 457 parameters, indicating the kind of matching allowed. 459 is An output with this match operator is followed if the 460 subfield being matched in the "address-switch" exactly 461 matches the argument of the operator. It may be used for 462 any subfield, or for the entire address if no subfield was 463 specified. 465 subdomain-of This match operator applies only for the subfields 466 "host" and "tel". In the former case, it matches if the 467 hostname being matched is a subdomain of the domain given 468 in the argument of the match operator; thus, subdomain- 469 of="example.com" would match the hostnames "example.com", 470 "research.example.com", and 471 "zaphod.sales.internal.example.com". IP addresses may be 472 given as arguments to this operator; however, they only 473 match exactly. In the case of the "tel" subfield, the 474 output matches if the telephone number being matched has a 475 prefix that matches the argument of the match operator; 476 subdomain-of="1212555" would match the telephone number "1 477 212 555 1212." 479 contains This match operator applies only for the subfield 480 "display". The output matches if the display name being 481 matched contains the argument of the match as a substring. 483 5.1.1 Usage of "address-switch" with SIP 485 For SIP, the "origin" address corresponds to the address in the 486 "From" header; "destination" corresponds to the "Request-URI"; and 487 "original-destination" corresponds to the "To" header. 489 The "display" subfield of an address is the display-name part of the 490 address, if it is present. Because of SIP's syntax, the "destination" 491 address field will never have a "display" subfield. 493 The "address-type" subfield of an address is the URI scheme of that 494 address. Other address fields depend on that "address-type". 496 For sip URLs, the "user", "host", and "port" subfields correspond to 497 the "user," "host," and "port" elements of the URI syntax. The "tel" 498 subfield is defined to be the "user" part of the URI, with visual 499 separators stripped, if and only if the "user=phone" parameter is 500 given to the URI. An additional subfield, "password" is defined to 501 correspond to the "password" element of the SIP URI, and is case- 502 sensitive. However, use of this field is NOT RECOMMENDED for general 503 security reasons. 505 For tel URLs, the "tel" and "user" subfields are the subscriber name; 506 in the former case, visual separators are stripped. The "host" and 507 "port" subfields are both not present. 509 For h323 URLs, subfields MAY be set according to the scheme described 510 in Appendix B. 512 For other URI schemes, only the "address-type" subfield is defined by 513 this specification; servers MAY set other pre-defined subfields, or 514 MAY support additional subfields. 516 If no subfield is specified for addresses in SIP messages, the string 517 matched is the URI part of the address. For "is" matches, standard 518 SIP URI matching rules are used; for "contains" matches, the URI is 519 used verbatim. 521 5.2 String Switches 523 String switches allow a CPL script to make decisions based on free- 524 form strings present in a call request. They are summarized in Figure 525 5. 527 Node: "string-switch" 528 Outputs: "string" Specific string to match 529 Parameters: "field" "subject", "organization", "user-agent", 530 or "display" 532 Output: "string" 533 Parameters: "is" exact match 534 "contains" substring match 536 Figure 5: Syntax of the "string-switch" node 538 String switches have one node parameter: "field". The mandatory 539 "field" parameter specifies which string is to be matched. 541 String switches are dependent on the call signalling protocol being 542 used. 544 Five fields are defined, listed below. The value of each of these 545 fields, except as specified, is a free-form Unicode string with no 546 other structure defined. 548 "subject" The subject of the call. 550 "organization" The organization of the originator of the call. 552 "user-agent" The name of the program or device with which the 553 call request was made. 555 "display" Free-form text associated with the call, intended to 556 be displayed to the recipient, with no other semantics 557 defined by the signalling protocol. 559 Strings are matched as case-insensitive Unicode strings, in the 560 following manner. First, strings are canonicalized to the 561 "Compatibility Composition" (KC) form, as specified in Unicode 562 Technical Report 15 [10]. Then, strings are compared using locale- 563 insensitive caseless mapping, as specified in Unicode Technical 564 Report 21 [11]. 566 Code to perform the first step, in Java and Perl, is 567 available; see the links from Annex E of UTR 15 [10]. The 568 case-insensitive string comparison in the Java standard 569 class libraries already performs the second step; other 570 Unicode-aware libraries should be similar. 572 The output tags of string matching are named "string", and have a 573 mandatory argument, one of "is" or "contains", indicating whole- 574 string match or substring match, respectively. 576 5.2.1 Usage of "string-switch" with SIP 578 For SIP, the fields "subject", "organization", and "user-agent" 579 correspond to the SIP header fields with the same name. These are 580 used verbatim as they appear in the message. 582 The field "display" is not used, and is never present. 584 5.3 Language Switches 586 Language switches allow a CPL script to make decisions based on the 587 languages in which the originator of the call wishes to communicate. 588 They are summarized in Figure 6. 590 Language switches take no parameters. 592 The "language" outputs take one parameter, "matches". The value of 593 one of these parameters is a language-tag, as defined in RFC 3066 594 [12]. The caller may have specified a set of language-ranges, also as 595 defined in RFC 3066. The CPL server checks each language-tag 596 Node: "language-switch" 597 Outputs: "language" Specific string to match 598 Parameters: None 600 Output: "language" 601 Parameters: "matches" Match if the given language matches a 602 language-range of the call. 604 Figure 6: Syntax of the "language-switch" node 606 specified by the script against the language-ranges specified in the 607 request. 609 See RFC 3066 for the details of how language-ranges match language- 610 tags. Briefly, a language-range matches a language-tag if it exactly 611 equals the tag, or if it exactly equals a prefix of the tag such that 612 the first character following the prefix is "-". 614 The special language-range "*" is ignored for the purpose of 615 matching. Languages with a "q" value of 0 are also ignored. 617 This switch MAY be not-present. 619 5.3.1 Usage of "language-switch" with SIP 621 The language-ranges for the "language-switch" switch are obtained 622 from the SIP "Accept-Language" header field. The switch is not- 623 present if the initial SIP request did not contain this header field. 625 Note that because of CPL's first-match semantics in 626 switches, "q" values other than 0 of the "Accept-Language" 627 header fields are ignored. 629 5.4 Time Switches 631 Time switches allow a CPL script to make decisions based on the time 632 and/or date the script is being executed. They are summarized in 633 Figure 7. 635 Time switches are independent of the underlying signalling protocol. 637 Time switches are based closely on the specification of recurring 638 intervals of time in the Internet Calendaring and Scheduling Core 639 Node: "time-switch" 640 Outputs: "time" Specific time to match 641 Parameters: "tzid" RFC 2445 Time Zone Identifier 642 "tzurl" RFC 2445 Time Zone URL 644 Output: "time" 645 Parameters: "dtstart" Start of interval (RFC 2445 DATE-TIME) 646 "dtend" End of interval (RFC 2445 DATE-TIME) 647 "duration" Length of interval (RFC 2445 DURATION) 648 "freq" Frequency of recurrence (one of "secondly", 649 "minutely", "hourly", "daily", 650 "weekly", "monthly", or "yearly") 651 "interval" How often the recurrence repeats 652 "until" Bound of recurrence (RFC 2445 DATE-TIME) 653 "count" Number of occurences of recurrence 654 "bysecond" List of seconds within a minute 655 "byminute" List of minutes within an hour 656 "byhour" List of hours of the day 657 "byday" List of days of the week 658 "bymonthday" List of days of the month 659 "byyearday" List of days of the year 660 "byweekno" List of weeks of the year 661 "bymonth" List of months of the year 662 "wkst" First day of the workweek 663 "bysetpos" List of values within set of events specified 665 Figure 7: Syntax of the "time-switch" node 667 Object Specification (iCalendar COS), RFC 2445 [13]. 669 This allows CPLs to be generated automatically from 670 calendar books. It also allows us to re-use the extensive 671 existing work specifying time intervals. 673 If future standards-track documents are published that obsolete RFC 674 2445, any changes or clarifications those documents make to 675 recurrence handling apply to CPL time-switches as well. 677 An algorithm to whether an instant falls within a given recurrence is 678 given in Appendix A. 680 The "time-switch" tag takes two optional parameters, "tzid" and 681 "tzurl", both of which are defined in RFC 2445 (Sections 4.8.3.1 and 682 4.8.3.5 respectively). The TZID is the identifying label by which a 683 time zone definition is referenced. If it begins with a forward slash 684 (solidus), it references a to-be-defined global time zone registry; 685 otherwise it is locally-defined at the server. The TZURL gives a 686 network location from which an up-to-date VTIMEZONE definition for 687 the timezone can be retrieved. 689 While TZID labels that do not begin with a forward slash are locally 690 defined, it is RECOMMENDED that servers support at least the naming 691 scheme used by Olson Time Zone database [14]. Examples of timezone 692 databases that use the Olson scheme are the zoneinfo files on most 693 Unix-like systems, and the standard Java TimeZone class. 695 Servers SHOULD resolve TZID and TZURL references to time zone 696 definitions at the time the script is uploaded. They MAY periodically 697 refresh these resolutions to obtain the most up-to-date definition of 698 a time zone. If a TZURL becomes invalid, servers SHOULD remember the 699 most recent valid data retrieved from the URL. 701 If a script is uploaded with a "tzid" and "tzurl" which the CPL 702 server does not recognize or cannot resolve, it SHOULD diagnose and 703 reject this at script upload time. If neither "tzid" nor "tzurl" are 704 present, all non-UTC times within this time switch should be 705 interpreted as being "floating" times, i.e. that they are specified 706 in the local timezone of the CPL server. 708 Because of daylight-savings-time changes over the course of 709 a year, it is necessary to specify time switches in a given 710 timezone. UTC offsets are not sufficient, or a time-of-day 711 routing rule which held between 9 am and 5 pm in the 712 eastern United States would start holding between 8 am and 713 4 pm at the end of October. 715 Authors of CPL servers should be careful to handle correctly the 716 intervals when local time is discontinuous, at the beginning or end 717 of daylight-savings time. Note especially that some times may occur 718 more than once when clocks are set back. The algorithm in Appendix A 719 is believed to handle this correctly. 721 Time nodes specify a list of periods during which their output should 722 be taken. They have two required parameters: "dtstart", which 723 specifies the beginning of the first period of the list, and exactly 724 one of "dtend" or "duration", which specify the ending time or the 725 duration of the period, respectively. The "dtstart" and "dtend" 726 parameters are formatted as iCalendar COS DATE-TIME values, as 727 specified in Section 4.3.5 of RFC 2445 [13]. Because time zones are 728 specified in the top-level "time-switch" tag, only forms 1 or 2 729 (floating or UTC times) can be used. The "duration" parameter is 730 given as an iCalendar COS DURATION parameter, as specified in section 731 4.3.6 of RFC 2445. Both the DATE-TIME and the DURATION syntaxes are 732 subsets of the corresponding syntaxes from ISO 8601 [15]. 734 For a recurring interval, the "duration" parameter MUST be small 735 enough such that subsequent intervals do not overlap. 737 For non-recurring intervals, durations of any positive length are 738 permitted. Zero-length and negative-length durations are not allowed. 740 If no other parameters are specified, a time node indicates only a 741 single period of time. More complicated sets periods intervals are 742 constructed as recurrences. A recurrence is specified by including 743 the "freq" parameter, which indicates the type of recurrence rule. No 744 parameters other than "dtstart", "dtend", and "duration" SHOULD be 745 specified unless "freq" is present, though CPL servers SHOULD accept 746 scripts with such parameters present, and ignore the other 747 parameters. 749 The "freq" parameter takes one of the following values: "secondly", 750 to specify repeating periods based on an interval of a second or 751 more; "minutely", to specify repeating periods based on an interval 752 of a minute or more; "hourly", to specify repeating periods based on 753 an interval of an hour or more; 755 "daily", to specify repeating periods based on an interval of a day 756 or more; "weekly", to specify repeating periods based on an interval 757 of a week or more; "monthly", to specify repeating periods based on 758 an interval of a month or more; and "yearly", to specify repeating 759 periods based on an interval of a year or more. These values are not 760 case-sensitive. 762 The "interval" parameter contains a positive integer representing how 763 often the recurrence rule repeats. The default value is "1", meaning 764 every day for a "daily" rule, every week for a "weekly" rule, every 765 month for a "monthly" rule and every year for a "yearly" rule. 767 The "until" parameter defines an iCalendar COS DATE or DATE-TIME 768 value which bounds the recurrence rule in an inclusive manner. If the 769 value specified by "until" is synchronized with the specified 770 recurrence, this date or date-time becomes the last instance of the 771 recurrence. If specified as a date-time value, then it MUST be 772 specified in an UTC time format. If not present, and the "count" 773 parameter is not also present, the recurrence is considered to repeat 774 forever. 776 The "count" parameter defines the number of occurrences at which to 777 range-bound the recurrence. The "dtstart" parameter counts as the 778 first occurrence. The "until" and "count" parameters MUST NOT occur 779 in the same "time" output. 781 The "bysecond" parameter specifies a comma-separated list of seconds 782 within a minute. Valid values are 0 to 59. The "byminute" parameter 783 specifies a comma-separated list of minutes within an hour. Valid 784 values are 0 to 59. The "byhour" parameter specifies a comma- 785 separated list of hours of the day. Valid values are 0 to 23. 787 The "byday" parameter specifies a comma-separated list of days of the 788 week. "MO" indicates Monday; "TU" indicates Tuesday; "WE" indicates 789 Wednesday; "TH" indicates Thursday; "FR" indicates Friday; "SA" 790 indicates Saturday; "SU" indicates Sunday. These values are not 791 case-sensitive. 793 Each "byday" value can also be preceded by a positive (+n) or 794 negative (-n) integer. If present, this indicates the nth occurrence 795 of the specific day within the "monthly" or "yearly" recurrence. For 796 example, within a "monthly" rule, +1MO (or simply 1MO) represents the 797 first Monday within the month, whereas -1MO represents the last 798 Monday of the month. If an integer modifier is not present, it means 799 all days of this type within the specified frequency. For example, 800 within a "monthly" rule, MO represents all Mondays within the month. 802 The "bymonthday" parameter specifies a comma-separated list of days 803 of the month. Valid values are 1 to 31 or -31 to -1. For example, -10 804 represents the tenth to the last day of the month. 806 The "byyearday" parameter specifies a comma-separated list of days of 807 the year. Valid values are 1 to 366 or -366 to -1. For example, -1 808 represents the last day of the year (December 31st) and -306 809 represents the 306th to the last day of the year (March 1st). 811 The "byweekno" parameter specifies a comma-separated list of ordinals 812 specifying weeks of the year. Valid values are 1 to 53 or -53 to -1. 813 This corresponds to weeks according to week numbering as defined in 814 ISO 8601 [15]. A week is defined as a seven day period, starting on 815 the day of the week defined to be the week start (see "wkst"). Week 816 number one of the calendar year is the first week which contains at 817 least four (4) days in that calendar year. This parameter is only 818 valid for "yearly" rules. For example, 3 represents the third week of 819 the year. 821 Note: Assuming a Monday week start, week 53 can only occur 822 when Thursday is January 1 or if it is a leap year and 823 Wednesday is January 1. 825 The "bymonth" parameter specifies a comma-separated list of months of 826 the year. Valid values are 1 to 12. 828 The "wkst" parameter specifies the day on which the workweek starts. 829 Valid values are "MO", "TU", "WE", "TH", "FR", "SA" and "SU". This is 830 significant when a "weekly" recurrence has an interval greater than 831 1, and a "byday" parameter is specified. This is also significant in 832 a "yearly" recurrence when a "byweekno" parameter is specified. The 833 default value is "MO", following ISO 8601 [15]. 835 The "bysetpos" parameter specifies a comma-separated list of values 836 which corresponds to the nth occurrence within the set of events 837 specified by the rule. Valid values are 1 to 366 or -366 to -1. It 838 MUST only be used in conjunction with another byxxx parameter. For 839 example "the last work day of the month" could be represented as: 841