idnits 2.17.1 draft-ietf-iptel-cpl-09.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 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 371: '...-present", which MAY occur anywhere in...' RFC 2119 keyword, line 375: '...therwise", which MUST be the last outp...' RFC 2119 keyword, line 382: '... Switches MAY contain no outputs. Th...' RFC 2119 keyword, line 415: '...invoked. Servers MAY define additional...' RFC 2119 keyword, line 419: '...play". Additional subfield values MAY...' (76 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1985 has weird spacing: '... Schema and ...' -- 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.) -- Couldn't find a document date in the document -- date freshness check skipped. 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 3434 looks like a reference -- Missing reference section? '16' on line 3491 looks like a reference -- Missing reference section? '2' on line 3439 looks like a reference -- Missing reference section? '17' on line 3495 looks like a reference -- Missing reference section? '3' on line 3444 looks like a reference -- Missing reference section? '18' on line 3499 looks like a reference -- Missing reference section? '19' on line 3504 looks like a reference -- Missing reference section? '4' on line 3447 looks like a reference -- Missing reference section? '5' on line 3450 looks like a reference -- Missing reference section? '6' on line 3455 looks like a reference -- Missing reference section? '7' on line 3459 looks like a reference -- Missing reference section? '8' on line 3462 looks like a reference -- Missing reference section? '9' on line 3466 looks like a reference -- Missing reference section? '20' on line 3510 looks like a reference -- Missing reference section? '10' on line 3469 looks like a reference -- Missing reference section? '21' on line 3516 looks like a reference -- Missing reference section? '11' on line 3473 looks like a reference -- Missing reference section? '22' on line 3521 looks like a reference -- Missing reference section? '12' on line 3477 looks like a reference -- Missing reference section? '13' on line 3480 looks like a reference -- Missing reference section? '14' on line 3483 looks like a reference -- Missing reference section? '15' on line 3486 looks like a reference -- Missing reference section? '23' on line 3524 looks like a reference -- Missing reference section? '24' on line 3530 looks like a reference Summary: 3 errors (**), 0 flaws (~~), 3 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/Wu/Schulzrinne 4 Columbia University 5 draft-ietf-iptel-cpl-09.txt 6 April XX, 2004 7 Expires: October, 2004 9 CPL: A Language for User Control of Internet Telephony Services 11 STATUS OF THIS MEMO 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress". 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt 29 To view the list Internet-Draft Shadow Directories, see 30 http://www.ietf.org/shadow.html. 32 Abstract 34 The Call Processing Language (CPL) is a language that can be used to 35 describe and control Internet telephony services. It is designed to 36 be implementable on either network servers or user agent servers. It 37 is meant to be simple, extensible, easily edited by graphical 38 clients, and independent of operating system or signalling protocol. 39 It is suitable for running on a server where users may not be allowed 40 to execute arbitrary programs, as it has no variables, loops, or 41 ability to run external programs. 43 This document is a product of the IP Telephony (IPTEL) working group 44 of the Internet Engineering Task Force. Comments are solicited and 45 should be addressed to the working group's mailing list at 46 iptel@ietf.org and/or the authors. 48 Table of Contents 50 1 Introduction ........................................ 4 51 1.1 Conventions of This Document ........................ 4 52 2 Structure of CPL Scripts ............................ 5 53 2.1 High-level Structure ................................ 5 54 2.2 Abstract Structure of a Call Processing Action ...... 5 55 2.3 Location Model ...................................... 6 56 2.4 XML Structure ....................................... 6 57 3 Script Structure: Overview .......................... 7 58 4 Switches ............................................ 9 59 4.1 Address Switches .................................... 9 60 4.1.1 Usage of "address-switch" with SIP .................. 12 61 4.2 String Switches ..................................... 13 62 4.2.1 Usage of "string-switch" with SIP ................... 14 63 4.3 Language Switches ................................... 14 64 4.3.1 Usage of "language-switch" with SIP ................. 15 65 4.4 Time Switches ....................................... 15 66 4.4.1 iCalendar differences and implementation issues ..... 21 67 4.5 Priority Switches ................................... 23 68 4.5.1 Usage of "priority-switch" with SIP ................. 23 69 5 Location Modifiers .................................. 24 70 5.1 Explicit Location ................................... 24 71 5.1.1 Usage of "location" with SIP ........................ 25 72 5.2 Location Lookup ..................................... 25 73 5.2.1 Usage of "lookup" with SIP .......................... 26 74 5.3 Location Removal .................................... 26 75 5.3.1 Usage of "remove-location" with SIP ................. 27 76 6 Signalling Operations ............................... 27 77 6.1 Proxy ............................................... 27 78 6.1.1 Usage of "proxy" with SIP ........................... 30 79 6.2 Redirect ............................................ 30 80 6.2.1 Usage of "redirect" with SIP ........................ 31 81 6.3 Reject .............................................. 31 82 6.3.1 Usage of "reject" with SIP .......................... 32 83 7 Non-signalling Operations ........................... 32 84 7.1 Mail ................................................ 32 85 7.1.1 Suggested Content of Mailed Information ............. 33 86 7.2 Log ................................................. 34 87 8 Subactions .......................................... 34 88 9 Ancillary Information ............................... 36 89 10 Default Behavior .................................... 36 90 11 CPL Extensions ...................................... 37 91 12 Examples ............................................ 38 92 12.1 Example: Call Redirect Unconditional ................ 38 93 12.2 Example: Call Forward Busy/No Answer ................ 39 94 12.3 Example: Call Forward: Redirect and Default ......... 40 95 12.4 Example: Call Screening ............................. 41 96 12.5 Example: Priority and Language Routing .............. 42 97 12.6 Example: Outgoing Call Screening .................... 43 98 12.7 Example: Time-of-day Routing ........................ 44 99 12.8 Example: Location Filtering ......................... 45 100 12.9 Example: Non-signalling Operations .................. 46 101 12.10 Example: Hypothetical Extensions .................... 47 102 12.11 Example: A Complex Example .......................... 49 103 13 Security Considerations ............................. 50 104 14 IANA Considerations ................................. 51 105 14.1 URN Sub-Namespace Registration for 106 urn:ietf:params:xml:ns:cpl ..................................... 51 107 14.2 Schema registration ................................. 52 108 14.3 MIME Registration ................................... 52 109 15 Acknowledgments ..................................... 53 110 A An Algorithm for Resolving Time Switches ............ 53 111 B Suggested Usage of CPL with H.323 ................... 55 112 B.1 Usage of "address-switch" with H.323 ................ 55 113 B.2 Usage of "string-switch" with H.323 ................. 57 114 B.3 Usage of "language-switch" with H.323 ............... 57 115 B.4 Usage of "priority-switch" with H.323 ............... 57 116 B.5 Usage of "location" with H.323 ...................... 57 117 B.6 Usage of "lookup" with H.323 ........................ 57 118 B.7 Usage of "remove-location" with H.323 ............... 58 119 C The XML Schema for CPL .............................. 58 120 D Changes from Earlier Versions ....................... 72 121 D.1 Changes from Draft -08 .............................. 72 122 D.2 Changes from Draft -07 .............................. 72 123 D.3 Changes from Draft -06 .............................. 73 124 D.4 Changes from Draft -05 .............................. 73 125 D.5 Changes from Draft -04 .............................. 74 126 D.6 Changes from Draft -03 .............................. 75 127 D.7 Changes from Draft -02 .............................. 76 128 D.8 Changes from Draft -01 .............................. 77 129 D.9 Changes from Draft -00 .............................. 78 130 E Authors' Addresses .................................. 79 131 F Normative References ................................ 79 132 G Informative References .............................. 81 134 1 Introduction 136 The Call Processing Language (CPL) is a language that can be used to 137 describe and control Internet telephony services. It is not tied to 138 any particular signalling architecture or protocol; it is anticipated 139 that it will be used with both the Session Initiation Protocol (SIP) 140 [1] and H.323 [16]. 142 CPL is powerful enough to describe a large number of services and 143 features, but it is limited in power so that it can run safely in 144 Internet telephony servers. The intention is to make it impossible 145 for users to do anything more complex (and dangerous) than describing 146 Internet telephony services. The language is not Turing-complete, and 147 provides no way to write loops or recursion. 149 CPL is also designed to be easily created and edited by graphical 150 tools. It is based on the Extensible Markup Language (XML) [2], so 151 parsing it is easy and many parsers for it are publicly available. 152 The structure of the language maps closely to its behavior, so an 153 editor can understand any valid script, even ones written by hand. 154 The language is also designed so that a server can easily confirm 155 scripts' validity at the time they are delivered to it, rather that 156 discovering them while a call is being processed. 158 Implementations of CPL are expected to take place both in Internet 159 telephony servers and in advanced clients; both can usefully process 160 and direct users' calls. This document primarily addresses the usage 161 in servers. A mechanism will be needed to transport scripts between 162 clients and servers; this document does not describe such a 163 mechanism, but related documents will. 165 The framework and requirements for the CPL architecture are described 166 in RFC 2824, "Call Processing Language Framework and Requirements" 167 [17]. 169 1.1 Conventions of This Document 171 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 172 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 173 and "OPTIONAL" are to be interpreted as described in RFC 2119 [3] and 174 indicate requirement levels for compliant CPL implementations. 176 Some paragraphs are indented, like this; they give 177 motivations of design choices, advice to implementors, or 178 thoughts on future development of or extensions to CPL. 179 They are not essential to the specification of the 180 language, and are non-normative. 182 2 Structure of CPL Scripts 184 2.1 High-level Structure 186 A CPL script consists of two types of information: ancillary 187 information about the script, and call processing actions. 189 A call processing action is a structured tree that describes the 190 operations and decisions a telephony signalling server performs on a 191 call set-up event. There are two types of call processing actions: 192 top-level actions and subactions. Top-level actions are actions that 193 are triggered by signalling events that arrive at the server. Two 194 top-level actions are defined: "incoming", the action performed when 195 a call arrives whose destination is the owner of the script; and 196 "outgoing", the action performed when a call arrives whose originator 197 is the owner of the script. Subactions are actions which can be 198 called from other actions. CPL forbids subactions from being called 199 recursively: see Section 8. 201 Ancillary information is information which is necessary for a server 202 to correctly process a script, but which does not directly describe 203 any operations or decisions. Currently, no ancillary information is 204 defined, but the section is reserved for use by extensions. 206 2.2 Abstract Structure of a Call Processing Action 208 Abstractly, a call processing action is described by a collection of 209 nodes, which describe operations that can be performed or decisions 210 that can be made. A node may have several parameters, which specify 211 the precise behavior of the node; they usually also have outputs, 212 which depend on the result of the decision or action. 214 For a graphical representation of a CPL action, see Figure 1. Nodes 215 and outputs can be thought of informally as boxes and arrows; CPL is 216 designed so that actions can be conveniently edited graphically using 217 this representation. Nodes are arranged in a tree, starting at a 218 single root node; outputs of nodes are connected to additional nodes. 219 When an action is run, the action or decision described by the 220 action's top-level node is performed; based on the result of that 221 node, the server follows one of the node's outputs, and the 222 subsequent node it points to is performed; this process continues 223 until a node with no specified outputs is reached. Because the graph 224 is acyclic, this will occur after a bounded and predictable number of 225 nodes are visited. 227 If an output to a node does not point to another node, it indicates 228 that the CPL server should perform a node- or protocol-specific 229 action. Some nodes have specific default behavior associated with 230 them; for others, the default behavior is implicit in the underlying 231 signalling protocol, or can be configured by the administrator of the 232 server. For further details on this, see Section 10. 234 _________________ ___________________ ________ busy 235 | Address-switch | | location | | proxy |--------\ 236 Call-->| field: origin | ->| url: sip:jones@ |->|timeout:| timeout| 237 | subfield: host | / | example.com | | 10s |--------| 238 |-----------------|/ |___________________| | | failure| 239 | subdomain-of: | |________|--------| 240 | example.com | | 241 |-----------------| ___________________________________________/ 242 | otherwise | /........................................ 243 | |\|. Voicemail . 244 |_________________| \. ____________________ . 245 ->| location | __________ . 246 . | url: sip:jones@ | | redirect | . 247 . | voicemail. |->| | . 248 . | example.com | |__________| . 249 . |____________________| . 250 ........................................ 252 Figure 1: Sample CPL Action: Graphical Version 254 2.3 Location Model 256 For flexibility, one piece of information necessary for CPL is not 257 given as node parameters: the set of locations to which a call is to 258 be directed. Instead, this set of locations is stored as an implicit 259 global variable throughout the execution of a processing action (and 260 its subactions). This allows locations to be retrieved from external 261 sources, filtered, and so forth, without requiring general language 262 support for such operations (which could harm the simplicity and 263 tractability of understanding the language). The specific operations 264 which add, retrieve, or filter location sets are given in Section 5. 266 For the incoming top-level call processing action, the location set 267 is initialized to the empty set. For the outgoing action, it is 268 initialized to the destination address of the call. 270 2.4 XML Structure 272 Syntactically, CPL scripts are represented by XML documents. XML is 273 thoroughly specified by the XML specification [2], and implementors 274 of this specification should be familiar with that document, but as a 275 brief overview, XML consists of a hierarchical structure of tags; 276 each tag can have a number of attributes. It is visually and 277 structurally very similar to HTML [18], as both languages are 278 simplifications of the earlier and larger standard SGML [19]. 280 See Figure 2 for the XML document corresponding to the graphical 281 representation of the CPL script in Figure 1. Both nodes and outputs 282 in CPL are represented by XML tags; parameters are represented by XML 283 tag attributes. Typically, node tags contain output tags, and vice- 284 versa (with a few exceptions: see Sections 5.1, 5.3, 7.1, and 7.2). 286 The connection between the output of a node and another node is 287 represented by enclosing the tag representing the pointed-to node 288 inside the tag for the outer node's output. Convergence (several 289 outputs pointing to a single node) is represented by subactions, 290 discussed further in Section 8. 292 The higher-level structure of a CPL script is represented by tags 293 corresponding to each piece of ancillary information, subactions, and 294 top-level actions, in order. This higher-level information is all 295 enclosed in a special tag "cpl", the outermost tag of the XML 296 document. 298 A complete XML Schema for CPL is provided in Appendix C. The 299 remainder of the main sections of this document describe the 300 semantics of CPL, while giving its syntax informally. For the formal 301 syntax, please see the appendix. 303 3 Script Structure: Overview 305 As mentioned, a CPL script consists of ancillary information, 306 subactions, and top-level actions. The full syntax of the "cpl" node 307 is given in Figure 3. 309 310 313 314 315 316 317 318 319 320
321 322 323 324 325 326 327 328
329 330 331 332
333
334
336 Figure 2: Sample CPL Script: XML Version 338 Tag: "cpl" 339 Parameters: None 340 Sub-tags: "ancillary" See Section 9 341 "subaction" See Section 8 342 "outgoing" Top-level actions to take on this user's 343 outgoing calls 344 "incoming" Top-level actions to take on this user's 345 incoming calls 347 Figure 3: Syntax of the top-level "cpl" tag 349 Call processing actions, both top-level actions and sub-actions, 350 consist of a tree of nodes and outputs. Nodes and outputs are both 351 described by XML tags. There are four categories of CPL nodes: 352 switches, which represent choices a CPL script can make; location 353 modifiers, which add or remove locations from the location set; 354 signalling operations, which cause signalling events in the 355 underlying protocol; and non-signalling operations, which trigger 356 behavior which does not effect the underlying protocol. 358 4 Switches 360 Switches represent choices a CPL script can make, based on either 361 attributes of the original call request or items independent of the 362 call. 364 All switches are arranged as a list of conditions that can match a 365 variable. Each condition corresponds to a node output; the output 366 points to the next node to execute if the condition was true. The 367 conditions are tried in the order they are presented in the script; 368 the output corresponding to the first node to match is taken. 370 There are two special switch outputs that apply to every switch type. 371 The output "not-present", which MAY occur anywhere in the list of 372 outputs, is true if the variable the switch was to match was not 373 present in the original call setup request. (In this document, this 374 is sometimes described by saying that the information is "absent".) 375 The output "otherwise", which MUST be the last output specified if it 376 is present, matches if no other condition matched. 378 If no condition matches and no "otherwise" output was present in the 379 script, the default script behavior is taken. See Section 10 for more 380 information on this. 382 Switches MAY contain no outputs. They MAY contain only an "otherwise" 383 output. 385 Such switches are not particularly useful, but might be 386 created by tools which automatically generate CPL scripts. 388 4.1 Address Switches 390 Address switches allow a CPL script to make decisions based on one of 391 the addresses present in the original call request. They are 392 summarized in Figure 4. 394 Node: "address-switch" 395 Outputs: "address" Specific addresses to match 396 Parameters: "field" "origin", "destination", 397 or "original-destination" 398 "subfield" "address-type", "user", "host", 399 "port", "tel", or "display" 400 (also: "password" and "alias-type") 402 Output: "address" 403 Parameters: "is" Exact match 404 "contains" Substring match (for "display" only) 405 "subdomain-of" Sub-domain match (for "host", "tel") 407 Figure 4: Syntax of the "address-switch" node 409 Address switches have two node parameters: "field", and "subfield". 410 The mandatory "field" parameter allows the script to specify which 411 address is to be considered for the switch: either the call's origin 412 address (field "origin"), its current destination address (field 413 "destination"), or its original destination (field "original- 414 destination"), the destination the call had before any earlier 415 forwarding was invoked. Servers MAY define additional field values. 417 The optional "subfield" specifies what part of the address is to be 418 considered. The possible subfield values are: "address-type", "user", 419 "host", "port", "tel", and "display". Additional subfield values MAY 420 be defined for protocol-specific values. (The subfield "password" is 421 defined for SIP in Section 4.1.1; the subfield "alias-type" is 422 defined for H.323 in Appendix B.1.) If no subfield is specified, the 423 "entire" address is matched; the precise meaning of this is defined 424 for each underlying signalling protocol. Servers MAY define 425 additional subfield values. 427 The subfields are defined as follows: 429 address-type This indicates the type of the underlying address; 430 i.e., the URI scheme, if the address can be represented by 431 a URI. The types specifically discussed by this document 432 are "sip", "tel", and "h323". The address type is not 433 case-sensitive. It has a value for all defined address 434 types. 436 user This subfield of the address indicates, for e-mail style 437 addresses, the user part of the address. For telephone 438 number style address, it includes the subscriber number. 439 This subfield is case-sensitive; it may be absent. 441 host This subfield of the address indicates the Internet host 442 name or IP address corresponding to the address, in host 443 name, IPv4, or IPv6 [4] textual representation format. 444 Host names are compared as strings. IP addresses are 445 compared numerically. (In particular, the presence or 446 location of an IPv6 :: omitted-zero-bits block is not 447 significant for matching purposes.) Host names are never 448 equal to IP addresses -- no DNS resolution is performed. 449 IPv4 addresses are never equal to IPv6 addresses, even if 450 the IPv6 address is a v4-in-v6 embedding. This subfield is 451 not case sensitive, and may be absent. 453 For host names only, subdomain matching is supported with 454 the "subdomain-of" match operator. The "subdomain-of" 455 operator ignores leading dots in the hostname or match 456 pattern, if any. 458 port This subfield indicates the TCP or UDP port number of the 459 address, numerically in decimal format. It is not case 460 sensitive, as it MUST only contain decimal digits. Leading 461 zeros are ignored. 463 tel This subfield indicates a telephone subscriber number, if 464 the address contains such a number. It is not case 465 sensitive (the telephone numbers may contain the symbols 466 `A' `B' `C' and `D'), and may be absent. It may be matched 467 using the "subdomain-of" match operator. Punctuation and 468 separator characters in telephone numbers are discarded. 470 display This subfield indicates a "display name" or user-visible 471 name corresponding to an address. It is a Unicode string, 472 and is matched using the case-insensitive algorithm 473 described in Section 4.2. The "contains" operator may be 474 applied to it. It may be absent. 476 For any completely unknown subfield, the server MAY reject the script 477 at the time it is submitted with an indication of the problem; if a 478 script with an unknown subfield is executed, the server MUST consider 479 the "not-present" output to be the valid one. 481 The "address" output tag may take exactly one of three possible 482 parameters, indicating the kind of matching allowed. 484 is An output with this match operator is followed if the 485 subfield being matched in the "address-switch" exactly 486 matches the argument of the operator. It may be used for 487 any subfield, or for the entire address if no subfield was 488 specified. 490 subdomain-of This match operator applies only for the subfields 491 "host" and "tel". In the former case, it matches if the 492 hostname being matched is a subdomain of the domain given 493 in the argument of the match operator; thus, subdomain- 494 of="example.com" would match the hostnames "example.com", 495 "research.example.com", and 496 "zaphod.sales.internal.example.com". IP addresses may be 497 given as arguments to this operator; however, they only 498 match exactly. In the case of the "tel" subfield, the 499 output matches if the telephone number being matched has a 500 prefix that matches the argument of the match operator; 501 subdomain-of="1212555" would match the telephone number "1 502 212 555 1212." 504 contains This match operator applies only for the subfield 505 "display". The output matches if the display name being 506 matched contains the argument of the match as a substring. 508 4.1.1 Usage of "address-switch" with SIP 510 For SIP, the "origin" address corresponds to the address in the 511 "From" header; "destination" corresponds to the "Request-URI"; and 512 "original-destination" corresponds to the "To" header. 514 The "display" subfield of an address is the display-name part of the 515 address, if it is present. Because of SIP's syntax, the "destination" 516 address field will never have a "display" subfield. 518 The "address-type" subfield of an address is the URI scheme of that 519 address. Other address fields depend on that "address-type". 521 For SIP URIs, the "user", "host", and "port" subfields correspond to 522 the "user," "host," and "port" elements of the URI syntax. (Note 523 that, following the definitions of RFC 3261 [1], a SIP URI which does 524 not specify a port is not the same as an explicit port 5060; the 525 former is indicated by an absent port subfield.) The "tel" subfield 526 is defined to be the "user" part of the URI, with visual separators 527 stripped, if the "user=phone" parameter is given to the URI, or if 528 the server is otherwise configured to recognize the user part as a 529 telephone number. An additional subfield, "password" is defined to 530 correspond to the "password" element of the SIP URI, and is case- 531 sensitive. However, use of this field is NOT RECOMMENDED for general 532 security reasons. 534 For tel URLs, the "tel" and "user" subfields are the subscriber name; 535 in the former case, visual separators are stripped. The "host" and 536 "port" subfields are both not present. 538 For h323 URLs, subfields MAY be set according to the scheme described 539 in Appendix B. 541 For other URI schemes, only the "address-type" subfield is defined by 542 this specification; servers MAY set other pre-defined subfields, or 543 MAY support additional subfields. 545 If no subfield is specified for addresses in SIP messages, the string 546 matched is the URI part of the address. For "is" matches, standard 547 SIP URI matching rules are used; for "contains" matches, the URI is 548 used verbatim. 550 4.2 String Switches 552 String switches allow a CPL script to make decisions based on free- 553 form strings present in a call request. They are summarized in Figure 554 5. 556 Node: "string-switch" 557 Outputs: "string" Specific string to match 558 Parameters: "field" "subject", "organization", 559 "user-agent", or "display" 561 Output: "string" 562 Parameters: "is" Exact match 563 "contains" Substring match 565 Figure 5: Syntax of the "string-switch" node 567 String switches have one node parameter: "field". The mandatory 568 "field" parameter specifies which string is to be matched. 570 String switches are dependent on the call signalling protocol being 571 used. 573 Five fields are defined, listed below. The value of each of these 574 fields, except as specified, is a free-form Unicode string with no 575 other structure defined. 577 "subject" The subject of the call. 579 "organization" The organization of the originator of the call. 581 "user-agent" The name of the program or device with which the 582 call request was made. 584 "display" Free-form text associated with the call, intended to 585 be displayed to the recipient, with no other semantics 586 defined by the signalling protocol. 588 Strings are matched as case-insensitive Unicode strings, in the 589 following manner. First, strings are canonicalized to the 590 "Compatibility Composition" (KC) form, as specified in Unicode 591 Technical Report 15 [5]. Then, strings are compared using locale- 592 insensitive caseless mapping, as specified in Unicode Technical 593 Report 21 [6]. 595 Code to perform the first step, in Java and Perl, is 596 available; see the links from Annex E of UTR 15 [5]. The 597 case-insensitive string comparison in the Java standard 598 class libraries already performs the second step; other 599 Unicode-aware libraries should be similar. 601 The output tag of string matching is named "string", and has a 602 mandatory argument, one of "is" or "contains", indicating whole- 603 string match or substring match, respectively. 605 4.2.1 Usage of "string-switch" with SIP 607 For SIP, the fields "subject", "organization", and "user-agent" 608 correspond to the SIP header fields with the same name. These are 609 used verbatim as they appear in the message. 611 The field "display" is not used, and is never present. 613 4.3 Language Switches 615 Language switches allow a CPL script to make decisions based on the 616 languages in which the originator of the call wishes to communicate. 617 They are summarized in Figure 6. 619 Node: "language-switch" 620 Outputs: "language" Specific string to match 621 Parameters: None 623 Output: "language" 624 Parameters: "matches" Match if the given language matches a 625 language-range of the call. 627 Figure 6: Syntax of the "language-switch" node 629 Language switches take no parameters. 631 The "language" output takes one parameter, "matches". The value of 632 the parameter is a language-tag, as defined in RFC 3066 [7]. The 633 caller may have specified a set of language-ranges, also as defined 634 in RFC 3066. The CPL server checks each language-tag specified by the 635 script against the language-ranges specified in the request. 637 See RFC 3066 for the details of how language-ranges match language- 638 tags. Briefly, a language-range matches a language-tag if it exactly 639 equals the tag, or if it exactly equals a prefix of the tag such that 640 the first character following the prefix is "-". 642 If the caller specified the special language-range "*", it is ignored 643 for the purpose of matching. Languages with a "q" value of 0 are also 644 ignored. 646 This switch MAY be not-present. 648 4.3.1 Usage of "language-switch" with SIP 650 The language-ranges for the "language-switch" switch are obtained 651 from the SIP "Accept-Language" header field. The switch is not- 652 present if the initial SIP request did not contain this header field. 654 Note that because of CPL's first-match semantics in 655 switches, "q" values other than 0 of the "Accept-Language" 656 header fields are ignored. 658 4.4 Time Switches 660 Time switches allow a CPL script to make decisions based on the time 661 and/or date the script is being executed. They are summarized in 662 Figure 7. 664 Time switches are independent of the underlying signalling protocol. 666 Node: "time-switch" 667 Outputs: "time" Specific time to match 668 Parameters: "tzid" RFC 2445 Time Zone Identifier 669 "tzurl" RFC 2445 Time Zone URL 671 Output: "time" 672 Parameters: "dtstart" Start of interval (RFC 2445 DATE-TIME) 673 "dtend" End of interval (RFC 2445 DATE-TIME) 674 "duration" Length of interval (RFC 2445 DURATION) 675 "freq" Frequency of recurrence ("secondly", 676 "minutely", "hourly", "daily", 677 "weekly", "monthly", or "yearly") 678 "interval" How often the recurrence repeats 679 "until" Bound of recurrence (RFC 2445 DATE-TIME) 680 "count" Number of occurrences of recurrence 681 "bysecond" List of seconds within a minute 682 "byminute" List of minutes within an hour 683 "byhour" List of hours of the day 684 "byday" List of days of the week 685 "bymonthday" List of days of the month 686 "byyearday" List of days of the year 687 "byweekno" List of weeks of the year 688 "bymonth" List of months of the year 689 "wkst" First day of the work week 690 "bysetpos" List of values within 691 set of events specified 693 Figure 7: Syntax of the "time-switch" node 695 Time switches are based closely on the specification of recurring 696 intervals of time in the Internet Calendaring and Scheduling Core 697 Object Specification (iCalendar COS), RFC 2445 [8]. 699 This allows CPL scripts to be generated automatically from 700 calendar books. It also allows us to re-use the extensive 701 existing work specifying time intervals. 703 If future standards-track documents are published that update or 704 obsolete RFC 2445, any changes or clarifications those documents make 705 to recurrence handling apply to CPL time-switches as well. 707 An algorithm to determine whether an instant falls within a given 708 recurrence is given in Appendix A. 710 The "time-switch" tag takes two optional parameters, "tzid" and 711 "tzurl", both of which are defined in RFC 2445 (Sections 4.8.3.1 and 712 4.8.3.5 respectively). The "tzid" is the identifying label by which a 713 time zone definition is referenced. If it begins with a forward slash 714 (solidus), it references a to-be-defined global time zone registry; 715 otherwise it is locally-defined at the server. The "tzurl" gives a 716 network location from which an up-to-date VTIMEZONE definition for 717 the timezone can be retrieved. 719 While "tzid" labels that do not begin with a forward slash are 720 locally defined, it is RECOMMENDED that servers support at least the 721 naming scheme used by Olson Time Zone database [9]. Examples of 722 timezone databases that use the Olson scheme are the zoneinfo files 723 on most Unix-like systems, and the standard Java TimeZone class. 725 Servers SHOULD resolve "tzid" and "tzurl" references to time zone 726 definitions at the time the script is uploaded. They MAY periodically 727 refresh these resolutions to obtain the most up-to-date definition of 728 a time zone. If a "tzurl" becomes invalid, servers SHOULD remember 729 the most recent valid data retrieved from the URL. 731 If a script is uploaded with a "tzid" and "tzurl" which the CPL 732 server does not recognize or cannot resolve, it SHOULD diagnose and 733 reject this at script upload time. If neither "tzid" nor "tzurl" are 734 present, all non-UTC times within this time switch should be 735 interpreted as being "floating" times, i.e. that they are specified 736 in the local timezone of the CPL server. 738 Because of daylight-savings-time changes over the course of 739 a year, it is necessary to specify time switches in a given 740 timezone. UTC offsets are not sufficient, or a time-of-day 741 routing rule which held between 9 am and 5 pm in the 742 eastern United States would start holding between 8 am and 743 4 pm at the end of October. 745 Authors of CPL servers should be careful to handle correctly the 746 intervals when local time is discontinuous, at the beginning or end 747 of daylight-savings time. Note especially that some times may occur 748 more than once when clocks are set back. The algorithm in Appendix A 749 is believed to handle this correctly. 751 Time nodes specify a list of periods during which their output should 752 be taken. They have two required parameters: "dtstart", which 753 specifies the beginning of the first period of the list, and exactly 754 one of "dtend" or "duration", which specify the ending time or the 755 duration of the period, respectively. The "dtstart" and "dtend" 756 parameters are formatted as iCalendar COS DATE-TIME values, as 757 specified in Section 4.3.5 of RFC 2445 [8]. Because time zones are 758 specified in the top-level "time-switch" tag, only forms 1 or 2 759 (floating or UTC times) can be used. The "duration" parameter is 760 given as an iCalendar COS DURATION parameter, as specified in section 761 4.3.6 of RFC 2445. Both the DATE-TIME and the DURATION syntaxes are 762 subsets of the corresponding syntaxes from ISO 8601 [20]. 764 For a recurring interval, the "duration" parameter MUST be small 765 enough such that subsequent intervals do not overlap. For non- 766 recurring intervals, durations of any positive length are permitted. 767 Zero-length and negative-length durations are not allowed. 769 If no other parameters are specified, a time node indicates only a 770 single period of time. More complicated sets periods intervals are 771 constructed as recurrences. A recurrence is specified by including 772 the "freq" parameter, which indicates the type of recurrence rule. 773 Parameters other than "dtstart", "dtend", and "duration" SHOULD NOT 774 be specified unless "freq" is present, though CPL servers SHOULD 775 accept scripts with such parameters present, and ignore the other 776 parameters. 778 The "freq" parameter takes one of the following values: "secondly", 779 to specify repeating periods based on an interval of a second or 780 more; "minutely", to specify repeating periods based on an interval 781 of a minute or more; "hourly", to specify repeating periods based on 782 an interval of an hour or more; "daily", to specify repeating periods 783 based on an interval of a day or more; "weekly", to specify repeating 784 periods based on an interval of a week or more; "monthly", to specify 785 repeating periods based on an interval of a month or more; and 786 "yearly", to specify repeating periods based on an interval of a year 787 or more. These values are not case-sensitive. 789 The "interval" parameter contains a positive integer representing how 790 often the recurrence rule repeats. The default value is "1", meaning 791 every second for a "secondly" rule, every minute for a "minutely" 792 rule, every hour for an "hourly" rule, every day for a "daily" rule, 793 every week for a "weekly" rule, every month for a "monthly" rule and 794 every year for a "yearly" rule. 796 The "until" parameter defines an iCalendar COS DATE or DATE-TIME 797 value which bounds the recurrence rule in an inclusive manner. If the 798 value specified by "until" is synchronized with the specified 799 recurrence, this date or date-time becomes the last instance of the 800 recurrence. If specified as a date-time value, then it MUST be 801 specified in an UTC time format. If not present, and the "count" 802 parameter is not also present, the recurrence is considered to repeat 803 forever. 805 The "count" parameter defines the number of occurrences at which to 806 range-bound the recurrence. The "dtstart" parameter counts as the 807 first occurrence. The "until" and "count" parameters MUST NOT occur 808 in the same "time" output. 810 The "bysecond" parameter specifies a comma-separated list of seconds 811 within a minute. Valid values are 0 to 59. The "byminute" parameter 812 specifies a comma-separated list of minutes within an hour. Valid 813 values are 0 to 59. The "byhour" parameter specifies a comma- 814 separated list of hours of the day. Valid values are 0 to 23. 816 The "byday" parameter specifies a comma-separated list of days of the 817 week. "MO" indicates Monday; "TU" indicates Tuesday; "WE" indicates 818 Wednesday; "TH" indicates Thursday; "FR" indicates Friday; "SA" 819 indicates Saturday; "SU" indicates Sunday. These values are not 820 case-sensitive. 822 Each "byday" value can also be preceded by a positive (+n) or 823 negative (-n) integer. If present, this indicates the nth occurrence 824 of the specific day within the "monthly" or "yearly" recurrence. For 825 example, within a "monthly" rule, +1MO (or simply 1MO) represents the 826 first Monday within the month, whereas -1MO represents the last 827 Monday of the month. If an integer modifier is not present, it means 828 all days of this type within the specified frequency. For example, 829 within a "monthly" rule, MO represents all Mondays within the month. 831 The "bymonthday" parameter specifies a comma-separated list of days 832 of the month. Valid values are 1 to 31 or -31 to -1. For example, -10 833 represents the tenth to the last day of the month. 835 The "byyearday" parameter specifies a comma-separated list of days of 836 the year. Valid values are 1 to 366 or -366 to -1. For example, -1 837 represents the last day of the year (December 31st) and -306 838 represents the 306th to the last day of the year (March 1st). 840 The "byweekno" parameter specifies a comma-separated list of ordinals 841 specifying weeks of the year. Valid values are 1 to 53 or -53 to -1. 842 This corresponds to weeks according to week numbering as defined in 843 ISO 8601 [20]. A week is defined as a seven day period, starting on 844 the day of the week defined to be the week start (see "wkst"). Week 845 number one of the calendar year is the first week which contains at 846 least four (4) days in that calendar year. This parameter is only 847 valid for "yearly" rules. For example, 3 represents the third week of 848 the year. 850 Note: Assuming a Monday week start, week 53 can only occur 851 when Thursday is January 1 or if it is a leap year and 852 Wednesday is January 1. 854 The "bymonth" parameter specifies a comma-separated list of months of 855 the year. Valid values are 1 to 12. 857 The "wkst" parameter specifies the day on which the work week starts. 858 Valid values are "MO", "TU", "WE", "TH", "FR", "SA" and "SU". This is 859 significant when a "weekly" recurrence has an interval greater than 860 1, and a "byday" parameter is specified. This is also significant in 861 a "yearly" recurrence when a "byweekno" parameter is specified. The 862 default value is "MO", following ISO 8601 [20]. 864 The "bysetpos" parameter specifies a comma-separated list of values 865 which corresponds to the nth occurrence within the set of events 866 specified by the rule. Valid values are 1 to 366 or -366 to -1. It 867 MUST only be used in conjunction with another byxxx parameter. For 868 example "the last work day of the month" could be represented as: 870