idnits 2.17.1 draft-ietf-iptel-cpl-06.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. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 24 instances of too long lines in the document, the longest one being 7 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 434: '...-present", which MAY occur anywhere in...' RFC 2119 keyword, line 438: '...therwise", which MUST be the last outp...' RFC 2119 keyword, line 445: '... Switches MAY contain no outputs. Th...' RFC 2119 keyword, line 478: '...invoked. Servers MAY define additional...' RFC 2119 keyword, line 482: '...play". Additional subfield values MAY...' (75 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 (January 15, 2002) is 8136 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 2945 looks like a reference -- Missing reference section? '2' on line 2949 looks like a reference -- Missing reference section? '3' on line 2953 looks like a reference -- Missing reference section? '4' on line 2958 looks like a reference -- Missing reference section? '5' on line 2962 looks like a reference -- Missing reference section? '6' on line 2966 looks like a reference -- Missing reference section? '7' on line 2970 looks like a reference -- Missing reference section? '8' on line 2976 looks like a reference -- Missing reference section? '9' on line 2979 looks like a reference -- Missing reference section? '10' on line 2983 looks like a reference -- Missing reference section? '11' on line 2988 looks like a reference -- Missing reference section? '12' on line 2992 looks like a reference -- Missing reference section? '13' on line 2996 looks like a reference -- Missing reference section? '14' on line 3000 looks like a reference -- Missing reference section? '15' on line 3003 looks like a reference -- Missing reference section? '16' on line 3009 looks like a reference -- Missing reference section? '17' on line 3013 looks like a reference -- Missing reference section? '18' on line 3017 looks like a reference -- Missing reference section? '19' on line 3022 looks like a reference -- Missing reference section? '20' on line 3026 looks like a reference -- Missing reference section? '21' on line 3029 looks like a reference -- Missing reference section? '22' on line 3033 looks like a reference -- Missing reference section? '23' on line 3039 looks like a reference Summary: 5 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-06.txt Columbia University 5 January 15, 2002 6 Expires: July, 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 Table of Contents 49 1 Introduction ........................................ 4 50 1.1 Conventions of This Document ........................ 4 51 2 Structure of CPL Scripts ............................ 4 52 2.1 High-level Structure ................................ 5 53 2.2 Abstract Structure of a Call Processing Action ...... 5 54 2.3 Location Model ...................................... 6 55 2.4 XML Structure ....................................... 6 56 3 Document Information ................................ 7 57 3.1 CPL Document Identifiers for XML .................... 7 58 3.2 MIME Registration ................................... 8 59 4 Script Structure: Overview .......................... 9 60 5 Switches ............................................ 10 61 5.1 Address Switches .................................... 11 62 5.1.1 Usage of "address-switch" with SIP .................. 13 63 5.2 String Switches ..................................... 14 64 5.2.1 Usage of "string-switch" with SIP ................... 15 65 5.3 Language Switches ................................... 15 66 5.3.1 Usage of "language-switch" with SIP ................. 16 67 5.4 Time Switches ....................................... 16 68 5.4.1 iCalendar differences and implementation issues ..... 22 69 5.5 Priority Switches ................................... 23 70 5.5.1 Usage of "priority-switch" with SIP ................. 24 71 6 Location Modifiers .................................. 24 72 6.1 Explicit Location ................................... 25 73 6.1.1 Usage of "location" with SIP ........................ 26 74 6.2 Location Lookup ..................................... 26 75 6.2.1 Usage of "lookup" with SIP .......................... 28 76 6.3 Location Removal .................................... 28 77 6.3.1 Usage of "remove-location" with SIP ................. 29 78 7 Signalling Operations ............................... 29 79 7.1 Proxy ............................................... 29 80 7.1.1 Usage of "proxy" with SIP ........................... 32 81 7.2 Redirect ............................................ 32 82 7.2.1 Usage of "redirect" with SIP ........................ 32 83 7.3 Reject .............................................. 33 84 7.3.1 Usage of "reject" with SIP .......................... 33 85 8 Non-signalling Operations ........................... 34 86 8.1 Mail ................................................ 34 87 8.1.1 Suggested Content of Mailed Information ............. 35 88 8.2 Log ................................................. 35 89 9 Subactions .......................................... 36 90 10 Ancillary Information ............................... 37 91 11 Default Behavior .................................... 38 92 12 CPL Extensions ...................................... 39 93 13 Examples ............................................ 40 94 13.1 Example: Call Redirect Unconditional ................ 40 95 13.2 Example: Call Forward Busy/No Answer ................ 40 96 13.3 Example: Call Forward: Redirect and Default ......... 40 97 13.4 Example: Call Screening ............................. 42 98 13.5 Example: Priority and Language Routing .............. 42 99 13.6 Example: Outgoing Call Screening .................... 42 100 13.7 Example: Time-of-day Routing ........................ 43 101 13.8 Example: Location Filtering ......................... 44 102 13.9 Example: Non-signalling Operations .................. 44 103 13.10 Example: Hypothetical Extensions .................... 45 104 13.11 Example: A Complex Example .......................... 45 105 14 Security Considerations ............................. 48 106 15 IANA Considerations ................................. 49 107 16 Acknowledgments ..................................... 49 108 A An Algorithm for Resolving Time Switches ............ 49 109 B Suggested Usage of CPL with H.323 ................... 51 110 B.1 Usage of "address-switch" with H.323 ................ 51 111 B.2 Usage of "string-switch" with H.323 ................. 53 112 B.3 Usage of "language-switch" with H.323 ............... 53 113 B.4 Usage of "priority-switch" with H.323 ............... 53 114 B.5 Usage of "location" with H.323 ...................... 53 115 B.6 Usage of "lookup" with H.323 ........................ 53 116 B.7 Usage of "remove-location" with H.323 ............... 54 117 C The XML DTD for CPL ................................. 54 118 D Changes from Earlier Versions ....................... 60 119 D.1 Changes from Draft -05 .............................. 60 120 D.2 Changes from Draft -04 .............................. 61 121 D.3 Changes from Draft -03 .............................. 62 122 D.4 Changes from Draft -02 .............................. 62 123 D.5 Changes from Draft -01 .............................. 63 124 D.6 Changes from Draft -00 .............................. 65 125 E Authors' Addresses .................................. 66 126 F Bibliography ........................................ 66 128 1 Introduction 130 The Call Processing Language (CPL) is a language that can be used to 131 describe and control Internet telephony services. It is not tied to 132 any particular signalling architecture or protocol; it is anticipated 133 that it will be used with both SIP [1] and H.323 [2]. 135 The CPL is powerful enough to describe a large number of services and 136 features, but it is limited in power so that it can run safely in 137 Internet telephony servers. The intention is to make it impossible 138 for users to do anything more complex (and dangerous) than describing 139 Internet telephony services. The language is not Turing-complete, and 140 provides no way to write loops or recursion. 142 The CPL is also designed to be easily created and edited by graphical 143 tools. It is based on XML [3], so parsing it is easy and many 144 parsers for it are publicly available. The structure of the language 145 maps closely to its behavior, so an editor can understand any valid 146 script, even ones written by hand. The language is also designed so 147 that a server can easily confirm scripts' validity at the time they 148 are delivered to it, rather that discovering them while a call is 149 being processed. 151 Implementations of the CPL are expected to take place both in 152 Internet telephony servers and in advanced clients; both can usefully 153 process and direct users' calls. This document primarily addresses 154 the usage in servers. A mechanism will be needed to transport scripts 155 between clients and servers; this document does not describe such a 156 mechanism, but related documents will. 158 The framework and requirements for the CPL architecture are described 159 in RFC 2824, "Call Processing Language Framework and Requirements" 160 [4]. 162 1.1 Conventions of This Document 164 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 165 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 166 and "OPTIONAL" are to be interpreted as described in RFC 2119 [5] and 167 indicate requirement levels for compliant CPL implementations. 169 Some paragraphs are indented, like this; they give 170 motivations of design choices, or questions for future 171 discussion in the development of the CPL, and are not 172 essential to the specification of the language. 174 2 Structure of CPL Scripts 175 2.1 High-level Structure 177 A CPL script consists of two types of information: ancillary 178 information about the script, and call processing actions. 180 A call processing action is a structured tree that describes the 181 operations and decisions a telephony signalling server performs on a 182 call set-up event. There are two types of call processing actions: 183 top-level actions and subactions. Top-level actions are actions that 184 are triggered by signalling events that arrive at the server. Two 185 top-level action names are defined: "incoming", the action performed 186 when a call arrives whose destination is the owner of the script; and 187 "outgoing", the action performed when a call arrives whose originator 188 is the owner of the script. Subactions are actions which can be 189 called from other actions. The CPL forbids subactions from being 190 called recursively: see Section 9. 192 Ancillary information is information which is necessary for a server 193 to correctly process a script, but which does not directly describe 194 any operations or decisions. Currently, no ancillary information is 195 defined, but the section is reserved for use by extensions. 197 2.2 Abstract Structure of a Call Processing Action 199 Abstractly, a call processing action is described by a collection of 200 nodes, which describe operations that can be performed or decisions 201 which can be made. A node may have several parameters, which specify 202 the precise behavior of the node; they usually also have outputs, 203 which depend on the result of the decision or action. 205 For a graphical representation of a CPL action, see Figure 1. Nodes 206 and outputs can be thought of informally as boxes and arrows; the CPL 207 is designed so that actions can be conveniently edited graphically 208 using this representation. Nodes are arranged in a tree, starting at 209 a single root node; outputs of nodes are connected to additional 210 nodes. When an action is run, the action or decision described by the 211 action's top-level node is performed; based on the result of that 212 node, the server follows one of the node's outputs, and the 213 subsequent node it points to is performed; this process continues 214 until a node with no specified outputs is reached. Because the graph 215 is acyclic, this will occur after a bounded and predictable number of 216 nodes are visited. 218 If an output to a node does not point to another node, it indicates 219 that the CPL server should perform a node- or protocol-specific 220 action. Some nodes have specific default behavior associated with 221 them; for others, the default behavior is implicit in the underlying 222 signalling protocol, or can be configured by the administrator of the 223 server. For further details on this, see Section 11. 225 _________________ ___________________ ________ busy 226 | Address-switch | | location | | proxy |--------\ 227 Call --->| field: origin | ->| url: sip:jones@ |--->|timeout:| timeout| 228 | subfield: host | / | example.com | | 10s |--------| 229 |-----------------|/ |___________________| | | failure| 230 | subdomain-of: | |________|--------| 231 | example.com | | 232 |-----------------| _____________________________________________/ 233 | otherwise | /.......................................... 234 | |\|. Voicemail . 235 |_________________| \. ____________________ . 236 ->| location | __________ . 237 . | url: sip:jones@ | | redirect | . 238 . | voicemail. |--->| | . 239 . | example.com | |__________| . 240 . |____________________| . 241 .......................................... 243 Figure 1: Sample CPL Action: Graphical Version 245 2.3 Location Model 247 For flexibility, one piece of information necessary for the function 248 of a CPL is not given as node parameters: the set of locations to 249 which a call is to be directed. Instead, this set of locations is 250 stored as an implicit global variable throughout the execution of a 251 processing action (and its subactions). This allows locations to be 252 retrieved from external sources, filtered, and so forth, without 253 requiring general language support for such operations (which could 254 harm the simplicity and tractability of understanding the language). 255 The specific operations which add, retrieve, or filter location sets 256 are given in Section 6. 258 For the incoming top-level call processing action, the location set 259 is initialized to the empty set. For the outgoing action, it is 260 initialized to the destination address of the call. 262 2.4 XML Structure 263 Syntactically, CPL scripts are represented by XML documents. XML is 264 thoroughly specified by [3], and implementors of this specification 265 should be familiar with that document, but as a brief overview, XML 266 consists of a hierarchical structure of tags; each tag can have a 267 number of attributes. It is visually and structurally very similar to 268 HTML [6], as both languages are simplifications of the earlier and 269 larger standard SGML [7]. 271 See Figure 2 for the XML document corresponding to the graphical 272 representation of the CPL script in Figure 1. Both nodes and outputs 273 in the CPL are represented by XML tags; parameters are represented by 274 XML tag attributes. Typically, node tags contain output tags, and 275 vice-versa (with a few exceptions: see Sections 6.1, 6.3, 8.1, and 276 8.2). 278 The connection between the output of a node and another node is 279 represented by enclosing the tag representing the pointed-to node 280 inside the tag for the outer node's output. Convergence (several 281 outputs pointing to a single node) is represented by subactions, 282 discussed further in Section 9. 284 The higher-level structure of a CPL script is represented by tags 285 corresponding to each piece of ancillary information, subactions, and 286 top-level actions, in order. This higher-level information is all 287 enclosed in a special tag "cpl", the outermost tag of the XML 288 document. 290 A complete Document Type Declaration for the CPL is provided in 291 Appendix C. The remainder of the main sections of this document 292 describe the semantics of the CPL, while giving its syntax 293 informally. For the formal syntax, please see the appendix. 295 3 Document Information 297 This section gives information describing how CPL scripts are 298 identified. 300 3.1 CPL Document Identifiers for XML 302 A CPL script list which appears as a top-level XML document is 303 identified with the formal public identifier "-//IETF//DTD RFCxxxx 304 CPL 1.0//EN". 306 A CPL embedded as a fragment within another XML document is 307 identified with the XML namespace identifier "http://www.rfc- 308 editor.org/rfc/rfcxxxx.txt". 310 311 313 314 315 316 317 318 320 321 322
323 324 325 326 327 328 329 330
331 332 333 334 335 336 338 Figure 2: Sample CPL Script: XML Version 340 [Note to RFC editor: please replace "xxxx" above with the 341 number of this RFC.] 343 Note that the URIs specifying XML namespaces are only 344 globally unique names; they do not have to reference any 345 particular actual object. The URI of a canonical source of 346 this specification meets the requirement of being globally 347 unique, and is also useful to document the format. 349 3.2 MIME Registration 351 As an XML type, CPL's MIME registration conforms with "XML Media 352 Types," RFC 3023 [8]. 354 MIME media type name: application 356 MIME subtype name: cpl+xml 358 Mandatory parameters: none 360 Optional parameters: charset 361 As for application/xml in RFC 3023. 363 Encoding considerations: As for application/xml in RFC 3023. 365 Security considerations: See Section 14, and Section 10 of RFC 366 3023. 368 Interoperability considerations: Different CPL servers may use 369 incompatible address types. However, all potential 370 interoperability issues should be resolvable at the time a 371 script is uploaded; there should be no interoperability 372 issues which cannot be detected until runtime. 374 Published specification: This document. 376 Applications which use this media type: None publicly released 377 at this time, as far as the authors are aware. 379 Additional information: 381 Magic number: None 383 File extension: .cpl or .xml 385 Macintosh file type code: "TEXT" 387 Person and e-mail address for further information: 388 Jonathan Lennox 389 Henning Schulzrinne 391 Intended usage: COMMON 393 Author/Change Controller: The IETF. 395 4 Script Structure: Overview 397 As mentioned, a CPL script consists of ancillary information, 398 subactions, and top-level actions. The full syntax of the "cpl" node 399 is given in Figure 3. 401 Tag: "cpl" 402 Parameters: None 403 Sub-tags: "ancillary" See Section 10 404 "subaction" See Section 9 405 "outgoing" Top-level actions to take on this user's 406 outgoing calls 407 "incoming" Top-level actions to take on this user's 408 incoming calls 410 Figure 3: Syntax of the top-level "cpl" tag 412 Call processing actions, both top-level actions and sub-actions, 413 consist of a tree of nodes and outputs. Nodes and outputs are both 414 described by XML tags. There are four categories of CPL nodes: 415 switches, which represent choices a CPL script can make; location 416 modifiers, which add or remove locations from the location set; 417 signalling operations, which cause signalling events in the 418 underlying protocol; and non-signalling operations, which trigger 419 behavior which does not effect the underlying protocol. 421 5 Switches 423 Switches represent choices a CPL script can make, based on either 424 attributes of the original call request or items independent of the 425 call. 427 All switches are arranged as a list of conditions that can match a 428 variable. Each condition corresponds to a node output; the output 429 points to the next node to execute if the condition was true. The 430 conditions are tried in the order they are presented in the script; 431 the output corresponding to the first node to match is taken. 433 There are two special switch outputs that apply to every switch type. 434 The output "not-present", which MAY occur anywhere in the list of 435 outputs, is true if the variable the switch was to match was not 436 present in the original call setup request. (In this document, this 437 is sometimes described by saying that the information is "absent".) 438 The output "otherwise", which MUST be the last output specified if it 439 is present, matches if no other condition matched. 441 If no condition matches and no "otherwise" output was present in the 442 script, the default script behavior is taken. See Section 11 for more 443 information on this. 445 Switches MAY contain no outputs. They MAY contain only an "otherwise" 446 output. 448 Such switches are not particularly useful, but might be 449 created by tools which automatically generate CPL scripts. 451 5.1 Address Switches 453 Address switches allow a CPL script to make decisions based on one of 454 the addresses present in the original call request. They are 455 summarized in Figure 4. 457 Node: "address-switch" 458 Outputs: "address" Specific addresses to match 459 Parameters: "field" "origin", "destination", 460 or "original-destination" 461 "subfield" "address-type", "user", "host", "port", 462 "tel", or "display" 463 (also: "password" and "alias-type") 465 Output: "address" 466 Parameters: "is" exact match 467 "contains" substring match (for "display" only) 468 "subdomain-of" sub-domain match (for "host", "tel" only) 470 Figure 4: Syntax of the "address-switch" node 472 Address switches have two node parameters: "field", and "subfield". 473 The mandatory "field" parameter allows the script to specify which 474 address is to be considered for the switch: either the call's origin 475 address (field "origin"), its current destination address (field 476 "destination"), or its original destination (field "original- 477 destination"), the destination the call had before any earlier 478 forwarding was invoked. Servers MAY define additional field values. 480 The optional "subfield" specifies what part of the address is to be 481 considered. The possible subfield values are: "address-type", "user", 482 "host", "port", "tel", and "display". Additional subfield values MAY 483 be defined for protocol-specific values. (The subfield "password" is 484 defined for SIP in Section 5.1.1; the subfield "alias-type" is 485 defined for H.323 in Appendix B.1.) If no subfield is specified, the 486 "entire" address is matched; the precise meaning of this is defined 487 for each underlying signalling protocol. Servers MAY define 488 additional subfield values. 490 The subfields are defined as follows: 492 address-type This indicates the type of the underlying address; 493 i.e., the URI scheme, if the address can be represented by 494 a URI. The types specifically discussed by this document 495 are "sip", "tel", and "h323". The address type is not 496 case-sensitive. It has a value for all defined address 497 types. 499 user This subfield of the address indicates, for e-mail style 500 addresses, the user part of the address. For telephone 501 number style address, it includes the subscriber number. 502 This subfield is case-sensitive; it may be absent. 504 host This subfield of the address indicates the Internet host 505 name or IP address corresponding to the address, in host 506 name, IPv4, or IPv6 [9] textual representation format. 507 Host names are compared as strings. IP addresses are 508 compared numerically. (In particular, the presence or 509 location of an IPv6 :: omitted-zero-bits block is not 510 significant for matching purposes.) Host names are never 511 equal to IP addresses -- no DNS resolution is performed. 512 IPv4 addresses are never equal to IPv6 addresses, even if 513 the IPv6 address is a v4-in-v6 embedding. 515 For host names only, subdomain matching is supported with 516 the "subdomain-of" match operator. The "subdomain-of" 517 operator ignores leading dots in the hostname or match 518 pattern, if any. This subfield is not case sensitive, and 519 may be absent. 521 port This subfield indicates the TCP or UDP port number of the 522 address, numerically in decimal format. It is not case 523 sensitive, as it MUST only contain decimal digits. Leading 524 zeros are ignored. This subfield may be absent; however, 525 for address types with default ports, an absent port 526 matches the default port number. 528 tel This subfield indicates a telephone subscriber number, if 529 the address contains such a number. It is not case 530 sensitive (the telephone numbers may contain the symbols 531 `A' `B' `C' and `D'), and may be absent. It may be matched 532 using the "subdomain-of" match operator. Punctuation and 533 separator characters in telephone numbers are discarded. 535 display This subfield indicates a "display name" or user-visible 536 name corresponding to an address. It is a Unicode string, 537 and is matched using the case-insensitive algorithm 538 described in Section 5.2. The "contains" operator may be 539 applied to it. It may be absent. 541 For any completely unknown subfield, the server MAY reject the script 542 at the time it is submitted with an indication of the problem; if a 543 script with an unknown subfield is executed, the server MUST consider 544 the "not-present" output to be the valid one. 546 The "address" output tag may take exactly one of three possible 547 parameters, indicating the kind of matching allowed. 549 is An output with this match operator is followed if the 550 subfield being matched in the "address-switch" exactly 551 matches the argument of the operator. It may be used for 552 any subfield, or for the entire address if no subfield was 553 specified. 555 subdomain-of This match operator applies only for the subfields 556 "host" and "tel". In the former case, it matches if the 557 hostname being matched is a subdomain of the domain given 558 in the argument of the match operator; thus, subdomain- 559 of="example.com" would match the hostnames "example.com", 560 "research.example.com", and 561 "zaphod.sales.internal.example.com". IP addresses may be 562 given as arguments to this operator; however, they only 563 match exactly. In the case of the "tel" subfield, the 564 output matches if the telephone number being matched has a 565 prefix that matches the argument of the match operator; 566 subdomain-of="1212555" would match the telephone number "1 567 212 555 1212." 569 contains This match operator applies only for the subfield 570 "display". The output matches if the display name being 571 matched contains the argument of the match as a substring. 573 5.1.1 Usage of "address-switch" with SIP 575 For SIP, the "origin" address corresponds to the address in the 576 "From" header; "destination" corresponds to the "Request-URI"; and 577 "original-destination" corresponds to the "To" header. 579 The "display" subfield of an address is the display-name part of the 580 address, if it is present. Because of SIP's syntax, the "destination" 581 address field will never have a "display" subfield. 583 The "address-type" subfield of an address is the URI scheme of that 584 address. Other address fields depend on that "address-type". 586 For sip URLs, the "user", "host", and "port" subfields correspond to 587 the "user," "host," and "port" elements of the URI syntax. The "tel" 588 subfield is defined to be the "user" part of the URI, with visual 589 separators stripped, if and only if the "user=phone" parameter is 590 given to the URI. An additional subfield, "password" is defined to 591 correspond to the "password" element of the SIP URI, and is case- 592 sensitive. However, use of this field is NOT RECOMMENDED for general 593 security reasons. 595 For tel URLs, the "tel" and "user" subfields are the subscriber name; 596 in the former case, visual separators are stripped. The "host" and 597 "port" subfields are both not present. 599 For h323 URLs, subfields MAY be set according to the scheme described 600 in Appendix B. 602 For other URI schemes, only the "address-type" subfield is defined by 603 this specification; servers MAY set other pre-defined subfields, or 604 MAY support additional subfields. 606 If no subfield is specified for addresses in SIP messages, the string 607 matched is the URI part of the address. For "is" matches, standard 608 SIP URI matching rules are used; for "contains" matches, the URI is 609 used verbatim. 611 5.2 String Switches 613 String switches allow a CPL script to make decisions based on free- 614 form strings present in a call request. They are summarized in Figure 615 5. 617 Node: "string-switch" 618 Outputs: "string" Specific string to match 619 Parameters: "field" "subject", "organization", "user-agent", 620 or "display" 622 Output: "string" 623 Parameters: "is" exact match 624 "contains" substring match 626 Figure 5: Syntax of the "string-switch" node 628 String switches have one node parameter: "field". The mandatory 629 "field" parameter specifies which string is to be matched. 631 String switches are dependent on the call signalling protocol being 632 used. 634 Five fields are defined, listed below. The value of each of these 635 fields, except as specified, is a free-form Unicode string with no 636 other structure defined. 638 "subject" The subject of the call. 640 "organization" The organization of the originator of the call. 642 "user-agent" The name of the program or device with which the 643 call request was made. 645 "display" Free-form text associated with the call, intended to 646 be displayed to the recipient, with no other semantics 647 defined by the signalling protocol. 649 Strings are matched as case-insensitive Unicode strings, in the 650 following manner. First, strings are canonicalized to the 651 "Compatibility Composition" (KC) form, as specified in Unicode 652 Technical Report 15 [10]. Then, strings are compared using locale- 653 insensitive caseless mapping, as specified in Unicode Technical 654 Report 21 [11]. 656 Code to perform the first step, in Java and Perl, is 657 available; see the links from Annex E of UTR 15 [10]. The 658 case-insensitive string comparison in the Java standard 659 class libraries already performs the second step; other 660 Unicode-aware libraries should be similar. 662 The output tags of string matching are named "string", and have a 663 mandatory argument, one of "is" or "contains", indicating whole- 664 string match or substring match, respectively. 666 5.2.1 Usage of "string-switch" with SIP 668 For SIP, the fields "subject", "organization", and "user-agent" 669 correspond to the SIP header fields with the same name. These are 670 used verbatim as they appear in the message. 672 The field "display" is not used, and is never present. 674 5.3 Language Switches 676 Language switches allow a CPL script to make decisions based on the 677 languages in which the originator of the call wishes to communicate. 679 They are summarized in Figure 6. 681 Node: "language-switch" 682 Outputs: "language" Specific string to match 683 Parameters: None 685 Output: "language" 686 Parameters: "matches" Match if the given language matches a 687 language-range of the call. 689 Figure 6: Syntax of the "language-switch" node 691 Language switches take no parameters. 693 The "language" outputs take one parameter, "matches". The value of 694 one of these parameters is a language-tag, as defined in RFC 3066 695 [12]. The caller may have specified a set of language-ranges, also as 696 defined in RFC 3066. The CPL server checks each language-tag 697 specified by the script against the language-ranges specified in the 698 request. 700 See RFC 3066 for the details of how language-ranges match language- 701 tags. Briefly, a language-range matches a language-tag if it exactly 702 equals the tag, or if it exactly equals a prefix of the tag such that 703 the first character following the prefix is "-". 705 If the caller specified the special language-range "*", it is ignored 706 for the purpose of matching. Languages with a "q" value of 0 are 707 also ignored. 709 This switch MAY be not-present. 711 5.3.1 Usage of "language-switch" with SIP 713 The language-ranges for the "language-switch" switch are obtained 714 from the SIP "Accept-Language" header field. The switch is not- 715 present if the initial SIP request did not contain this header field. 717 Note that because of CPL's first-match semantics in 718 switches, "q" values other than 0 of the "Accept-Language" 719 header fields are ignored. 721 5.4 Time Switches 722 Time switches allow a CPL script to make decisions based on the time 723 and/or date the script is being executed. They are summarized in 724 Figure 7. 726 Time switches are independent of the underlying signalling protocol. 728 Node: "time-switch" 729 Outputs: "time" Specific time to match 730 Parameters: "tzid" RFC 2445 Time Zone Identifier 731 "tzurl" RFC 2445 Time Zone URL 733 Output: "time" 734 Parameters: "dtstart" Start of interval (RFC 2445 DATE-TIME) 735 "dtend" End of interval (RFC 2445 DATE-TIME) 736 "duration" Length of interval (RFC 2445 DURATION) 737 "freq" Frequency of recurrence (one of "secondly", 738 "minutely", "hourly", "daily", 739 "weekly", "monthly", or "yearly") 740 "interval" How often the recurrence repeats 741 "until" Bound of recurrence (RFC 2445 DATE-TIME) 742 "count" Number of occurrences of recurrence 743 "bysecond" List of seconds within a minute 744 "byminute" List of minutes within an hour 745 "byhour" List of hours of the day 746 "byday" List of days of the week 747 "bymonthday" List of days of the month 748 "byyearday" List of days of the year 749 "byweekno" List of weeks of the year 750 "bymonth" List of months of the year 751 "wkst" First day of the work week 752 "bysetpos" List of values within set of events specified 754 Figure 7: Syntax of the "time-switch" node 756 Time switches are based closely on the specification of recurring 757 intervals of time in the Internet Calendaring and Scheduling Core 758 Object Specification (iCalendar COS), RFC 2445 [13]. 760 This allows CPL scripts to be generated automatically from 761 calendar books. It also allows us to re-use the extensive 762 existing work specifying time intervals. 764 If future standards-track documents are published that update or 765 obsolete RFC 2445, any changes or clarifications those documents make 766 to recurrence handling apply to CPL time-switches as well. 768 An algorithm to whether an instant falls within a given recurrence is 769 given in Appendix A. 771 The "time-switch" tag takes two optional parameters, "tzid" and 772 "tzurl", both of which are defined in RFC 2445 (Sections 4.8.3.1 and 773 4.8.3.5 respectively). The TZID is the identifying label by which a 774 time zone definition is referenced. If it begins with a forward slash 775 (solidus), it references a to-be-defined global time zone registry; 776 otherwise it is locally-defined at the server. The TZURL gives a 777 network location from which an up-to-date VTIMEZONE definition for 778 the timezone can be retrieved. 780 While TZID labels that do not begin with a forward slash are locally 781 defined, it is RECOMMENDED that servers support at least the naming 782 scheme used by Olson Time Zone database [14]. Examples of timezone 783 databases that use the Olson scheme are the zoneinfo files on most 784 Unix-like systems, and the standard Java TimeZone class. 786 Servers SHOULD resolve TZID and TZURL references to time zone 787 definitions at the time the script is uploaded. They MAY periodically 788 refresh these resolutions to obtain the most up-to-date definition of 789 a time zone. If a TZURL becomes invalid, servers SHOULD remember the 790 most recent valid data retrieved from the URL. 792 If a script is uploaded with a "tzid" and "tzurl" which the CPL 793 server does not recognize or cannot resolve, it SHOULD diagnose and 794 reject this at script upload time. If neither "tzid" nor "tzurl" are 795 present, all non-UTC times within this time switch should be 796 interpreted as being "floating" times, i.e. that they are specified 797 in the local timezone of the CPL server. 799 Because of daylight-savings-time changes over the course of 800 a year, it is necessary to specify time switches in a given 801 timezone. UTC offsets are not sufficient, or a time-of-day 802 routing rule which held between 9 am and 5 pm in the 803 eastern United States would start holding between 8 am and 804 4 pm at the end of October. 806 Authors of CPL servers should be careful to handle correctly the 807 intervals when local time is discontinuous, at the beginning or end 808 of daylight-savings time. Note especially that some times may occur 809 more than once when clocks are set back. The algorithm in Appendix A 810 is believed to handle this correctly. 812 Time nodes specify a list of periods during which their output should 813 be taken. They have two required parameters: "dtstart", which 814 specifies the beginning of the first period of the list, and exactly 815 one of "dtend" or "duration", which specify the ending time or the 816 duration of the period, respectively. The "dtstart" and "dtend" 817 parameters are formatted as iCalendar COS DATE-TIME values, as 818 specified in Section 4.3.5 of RFC 2445 [13]. Because time zones are 819 specified in the top-level "time-switch" tag, only forms 1 or 2 820 (floating or UTC times) can be used. The "duration" parameter is 821 given as an iCalendar COS DURATION parameter, as specified in section 822 4.3.6 of RFC 2445. Both the DATE-TIME and the DURATION syntaxes are 823 subsets of the corresponding syntaxes from ISO 8601 [15]. 825 For a recurring interval, the "duration" parameter MUST be small 826 enough such that subsequent intervals do not overlap. For non- 827 recurring intervals, durations of any positive length are permitted. 828 Zero-length and negative-length durations are not allowed. 830 If no other parameters are specified, a time node indicates only a 831 single period of time. More complicated sets periods intervals are 832 constructed as recurrences. A recurrence is specified by including 833 the "freq" parameter, which indicates the type of recurrence rule. No 834 parameters other than "dtstart", "dtend", and "duration" SHOULD be 835 specified unless "freq" is present, though CPL servers SHOULD accept 836 scripts with such parameters present, and ignore the other 837 parameters. 839 The "freq" parameter takes one of the following values: "secondly", 840 to specify repeating periods based on an interval of a second or 841 more; "minutely", to specify repeating periods based on an interval 842 of a minute or more; "hourly", to specify repeating periods based on 843 an interval of an hour or more; "daily", to specify repeating periods 844 based on an interval of a day or more; "weekly", to specify repeating 845 periods based on an interval of a week or more; "monthly", to specify 846 repeating periods based on an interval of a month or more; and 847 "yearly", to specify repeating periods based on an interval of a year 848 or more. These values are not case-sensitive. 850 The "interval" parameter contains a positive integer representing how 851 often the recurrence rule repeats. The default value is "1", meaning 852 every day for a "daily" rule, every week for a "weekly" rule, every 853 month for a "monthly" rule and every year for a "yearly" rule. 855 The "until" parameter defines an iCalendar COS DATE or DATE-TIME 856 value which bounds the recurrence rule in an inclusive manner. If the 857 value specified by "until" is synchronized with the specified 858 recurrence, this date or date-time becomes the last instance of the 859 recurrence. If specified as a date-time value, then it MUST be 860 specified in an UTC time format. If not present, and the "count" 861 parameter is not also present, the recurrence is considered to repeat 862 forever. 864 The "count" parameter defines the number of occurrences at which to 865 range-bound the recurrence. The "dtstart" parameter counts as the 866 first occurrence. The "until" and "count" parameters MUST NOT occur 867 in the same "time" output. 869 The "bysecond" parameter specifies a comma-separated list of seconds 870 within a minute. Valid values are 0 to 59. The "byminute" parameter 871 specifies a comma-separated list of minutes within an hour. Valid 872 values are 0 to 59. The "byhour" parameter specifies a comma- 873 separated list of hours of the day. Valid values are 0 to 23. 875 The "byday" parameter specifies a comma-separated list of days of the 876 week. "MO" indicates Monday; "TU" indicates Tuesday; "WE" indicates 877 Wednesday; "TH" indicates Thursday; "FR" indicates Friday; "SA" 878 indicates Saturday; "SU" indicates Sunday. These values are not 879 case-sensitive. 881 Each "byday" value can also be preceded by a positive (+n) or 882 negative (-n) integer. If present, this indicates the nth occurrence 883 of the specific day within the "monthly" or "yearly" recurrence. For 884 example, within a "monthly" rule, +1MO (or simply 1MO) represents the 885 first Monday within the month, whereas -1MO represents the last 886 Monday of the month. If an integer modifier is not present, it means 887 all days of this type within the specified frequency. For example, 888 within a "monthly" rule, MO represents all Mondays within the month. 890 The "bymonthday" parameter specifies a comma-separated list of days 891 of the month. Valid values are 1 to 31 or -31 to -1. For example, -10 892 represents the tenth to the last day of the month. 894 The "byyearday" parameter specifies a comma-separated list of days of 895 the year. Valid values are 1 to 366 or -366 to -1. For example, -1 896 represents the last day of the year (December 31st) and -306 897 represents the 306th to the last day of the year (March 1st). 899 The "byweekno" parameter specifies a comma-separated list of ordinals 900 specifying weeks of the year. Valid values are 1 to 53 or -53 to -1. 901 This corresponds to weeks according to week numbering as defined in 902 ISO 8601 [15]. A week is defined as a seven day period, starting on 903 the day of the week defined to be the week start (see "wkst"). Week 904 number one of the calendar year is the first week which contains at 905 least four (4) days in that calendar year. This parameter is only 906 valid for "yearly" rules. For example, 3 represents the third week of 907 the year. 909 Note: Assuming a Monday week start, week 53 can only occur 910 when Thursday is January 1 or if it is a leap year and 911 Wednesday is January 1. 913 The "bymonth" parameter specifies a comma-separated list of months of 914 the year. Valid values are 1 to 12. 916 The "wkst" parameter specifies the day on which the work week starts. 917 Valid values are "MO", "TU", "WE", "TH", "FR", "SA" and "SU". This is 918 significant when a "weekly" recurrence has an interval greater than 919 1, and a "byday" parameter is specified. This is also significant in 920 a "yearly" recurrence when a "byweekno" parameter is specified. The 921 default value is "MO", following ISO 8601 [15]. 923 The "bysetpos" parameter specifies a comma-separated list of values 924 which corresponds to the nth occurrence within the set of events 925 specified by the rule. Valid values are 1 to 366 or -366 to -1. It 926 MUST only be used in conjunction with another byxxx parameter. For 927 example "the last work day of the month" could be represented as: 929