idnits 2.17.1 draft-ietf-iptel-cpl-08.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 370: '...-present", which MAY occur anywhere in...' RFC 2119 keyword, line 374: '...therwise", which MUST be the last outp...' RFC 2119 keyword, line 381: '... Switches MAY contain no outputs. Th...' RFC 2119 keyword, line 414: '...invoked. Servers MAY define additional...' RFC 2119 keyword, line 418: '...play". Additional subfield values MAY...' (73 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 1983 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 3421 looks like a reference -- Missing reference section? '16' on line 3479 looks like a reference -- Missing reference section? '2' on line 3426 looks like a reference -- Missing reference section? '17' on line 3483 looks like a reference -- Missing reference section? '3' on line 3431 looks like a reference -- Missing reference section? '18' on line 3487 looks like a reference -- Missing reference section? '19' on line 3492 looks like a reference -- Missing reference section? '4' on line 3434 looks like a reference -- Missing reference section? '5' on line 3437 looks like a reference -- Missing reference section? '6' on line 3442 looks like a reference -- Missing reference section? '7' on line 3446 looks like a reference -- Missing reference section? '8' on line 3449 looks like a reference -- Missing reference section? '9' on line 3453 looks like a reference -- Missing reference section? '20' on line 3498 looks like a reference -- Missing reference section? '10' on line 3456 looks like a reference -- Missing reference section? '21' on line 3504 looks like a reference -- Missing reference section? '11' on line 3460 looks like a reference -- Missing reference section? '22' on line 3509 looks like a reference -- Missing reference section? '12' on line 3464 looks like a reference -- Missing reference section? '13' on line 3467 looks like a reference -- Missing reference section? '14' on line 3470 looks like a reference -- Missing reference section? '15' on line 3474 looks like a reference -- Missing reference section? '23' on line 3512 looks like a reference -- Missing reference section? '24' on line 3518 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-08.txt 6 August XX, 2003 7 Expires: February, 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 -07 .............................. 72 122 D.2 Changes from Draft -06 .............................. 72 123 D.3 Changes from Draft -05 .............................. 73 124 D.4 Changes from Draft -04 .............................. 74 125 D.5 Changes from Draft -03 .............................. 75 126 D.6 Changes from Draft -02 .............................. 76 127 D.7 Changes from Draft -01 .............................. 76 128 D.8 Changes from Draft -00 .............................. 78 129 E Authors' Addresses .................................. 79 130 F Normative References ................................ 79 131 G Informative References .............................. 80 133 1 Introduction 135 The Call Processing Language (CPL) is a language that can be used to 136 describe and control Internet telephony services. It is not tied to 137 any particular signalling architecture or protocol; it is anticipated 138 that it will be used with both the Session Initiation Protocol (SIP) 139 [1] and H.323 [16]. 141 CPL is powerful enough to describe a large number of services and 142 features, but it is limited in power so that it can run safely in 143 Internet telephony servers. The intention is to make it impossible 144 for users to do anything more complex (and dangerous) than describing 145 Internet telephony services. The language is not Turing-complete, and 146 provides no way to write loops or recursion. 148 CPL is also designed to be easily created and edited by graphical 149 tools. It is based on the Extensible Markup Language (XML) [2], so 150 parsing it is easy and many parsers for it are publicly available. 151 The structure of the language maps closely to its behavior, so an 152 editor can understand any valid script, even ones written by hand. 153 The language is also designed so that a server can easily confirm 154 scripts' validity at the time they are delivered to it, rather that 155 discovering them while a call is being processed. 157 Implementations of CPL are expected to take place both in Internet 158 telephony servers and in advanced clients; both can usefully process 159 and direct users' calls. This document primarily addresses the usage 160 in servers. A mechanism will be needed to transport scripts between 161 clients and servers; this document does not describe such a 162 mechanism, but related documents will. 164 The framework and requirements for the CPL architecture are described 165 in RFC 2824, "Call Processing Language Framework and Requirements" 166 [17]. 168 1.1 Conventions of This Document 170 In this document, the key words "MUST", "MUST NOT", "REQUIRED", 171 "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", 172 and "OPTIONAL" are to be interpreted as described in RFC 2119 [3] and 173 indicate requirement levels for compliant CPL implementations. 175 Some paragraphs are indented, like this; they give 176 motivations of design choices, advice to implementors, or 177 thoughts on future development of or extensions to CPL. 178 They are not essential to the specification of the 179 language, and are non-normative. 181 2 Structure of CPL Scripts 183 2.1 High-level Structure 185 A CPL script consists of two types of information: ancillary 186 information about the script, and call processing actions. 188 A call processing action is a structured tree that describes the 189 operations and decisions a telephony signalling server performs on a 190 call set-up event. There are two types of call processing actions: 191 top-level actions and subactions. Top-level actions are actions that 192 are triggered by signalling events that arrive at the server. Two 193 top-level actions are defined: "incoming", the action performed when 194 a call arrives whose destination is the owner of the script; and 195 "outgoing", the action performed when a call arrives whose originator 196 is the owner of the script. Subactions are actions which can be 197 called from other actions. CPL forbids subactions from being called 198 recursively: see Section 8. 200 Ancillary information is information which is necessary for a server 201 to correctly process a script, but which does not directly describe 202 any operations or decisions. Currently, no ancillary information is 203 defined, but the section is reserved for use by extensions. 205 2.2 Abstract Structure of a Call Processing Action 207 Abstractly, a call processing action is described by a collection of 208 nodes, which describe operations that can be performed or decisions 209 that can be made. A node may have several parameters, which specify 210 the precise behavior of the node; they usually also have outputs, 211 which depend on the result of the decision or action. 213 For a graphical representation of a CPL action, see Figure 1. Nodes 214 and outputs can be thought of informally as boxes and arrows; CPL is 215 designed so that actions can be conveniently edited graphically using 216 this representation. Nodes are arranged in a tree, starting at a 217 single root node; outputs of nodes are connected to additional nodes. 218 When an action is run, the action or decision described by the 219 action's top-level node is performed; based on the result of that 220 node, the server follows one of the node's outputs, and the 221 subsequent node it points to is performed; this process continues 222 until a node with no specified outputs is reached. Because the graph 223 is acyclic, this will occur after a bounded and predictable number of 224 nodes are visited. 226 If an output to a node does not point to another node, it indicates 227 that the CPL server should perform a node- or protocol-specific 228 action. Some nodes have specific default behavior associated with 229 them; for others, the default behavior is implicit in the underlying 230 signalling protocol, or can be configured by the administrator of the 231 server. For further details on this, see Section 10. 233 _________________ ___________________ ________ busy 234 | Address-switch | | location | | proxy |--------\ 235 Call-->| field: origin | ->| url: sip:jones@ |->|timeout:| timeout| 236 | subfield: host | / | example.com | | 10s |--------| 237 |-----------------|/ |___________________| | | failure| 238 | subdomain-of: | |________|--------| 239 | example.com | | 240 |-----------------| ___________________________________________/ 241 | otherwise | /........................................ 242 | |\|. Voicemail . 243 |_________________| \. ____________________ . 244 ->| location | __________ . 245 . | url: sip:jones@ | | redirect | . 246 . | voicemail. |->| | . 247 . | example.com | |__________| . 248 . |____________________| . 249 ........................................ 251 Figure 1: Sample CPL Action: Graphical Version 253 2.3 Location Model 255 For flexibility, one piece of information necessary for CPL is not 256 given as node parameters: the set of locations to which a call is to 257 be directed. Instead, this set of locations is stored as an implicit 258 global variable throughout the execution of a processing action (and 259 its subactions). This allows locations to be retrieved from external 260 sources, filtered, and so forth, without requiring general language 261 support for such operations (which could harm the simplicity and 262 tractability of understanding the language). The specific operations 263 which add, retrieve, or filter location sets are given in Section 5. 265 For the incoming top-level call processing action, the location set 266 is initialized to the empty set. For the outgoing action, it is 267 initialized to the destination address of the call. 269 2.4 XML Structure 271 Syntactically, CPL scripts are represented by XML documents. XML is 272 thoroughly specified by the XML specification [2], and implementors 273 of this specification should be familiar with that document, but as a 274 brief overview, XML consists of a hierarchical structure of tags; 275 each tag can have a number of attributes. It is visually and 276 structurally very similar to HTML [18], as both languages are 277 simplifications of the earlier and larger standard SGML [19]. 279 See Figure 2 for the XML document corresponding to the graphical 280 representation of the CPL script in Figure 1. Both nodes and outputs 281 in CPL are represented by XML tags; parameters are represented by XML 282 tag attributes. Typically, node tags contain output tags, and vice- 283 versa (with a few exceptions: see Sections 5.1, 5.3, 7.1, and 7.2). 285 The connection between the output of a node and another node is 286 represented by enclosing the tag representing the pointed-to node 287 inside the tag for the outer node's output. Convergence (several 288 outputs pointing to a single node) is represented by subactions, 289 discussed further in Section 8. 291 The higher-level structure of a CPL script is represented by tags 292 corresponding to each piece of ancillary information, subactions, and 293 top-level actions, in order. This higher-level information is all 294 enclosed in a special tag "cpl", the outermost tag of the XML 295 document. 297 A complete XML Schema for CPL is provided in Appendix C. The 298 remainder of the main sections of this document describe the 299 semantics of CPL, while giving its syntax informally. For the formal 300 syntax, please see the appendix. 302 3 Script Structure: Overview 304 As mentioned, a CPL script consists of ancillary information, 305 subactions, and top-level actions. The full syntax of the "cpl" node 306 is given in Figure 3. 308 309 312 313 314 315 316 317 318 319
320 321 322 323 324 325 326 327
328 329 330 331 332 333 335 Figure 2: Sample CPL Script: XML Version 337 Tag: "cpl" 338 Parameters: None 339 Sub-tags: "ancillary" See Section 9 340 "subaction" See Section 8 341 "outgoing" Top-level actions to take on this user's 342 outgoing calls 343 "incoming" Top-level actions to take on this user's 344 incoming calls 346 Figure 3: Syntax of the top-level "cpl" tag 348 Call processing actions, both top-level actions and sub-actions, 349 consist of a tree of nodes and outputs. Nodes and outputs are both 350 described by XML tags. There are four categories of CPL nodes: 351 switches, which represent choices a CPL script can make; location 352 modifiers, which add or remove locations from the location set; 353 signalling operations, which cause signalling events in the 354 underlying protocol; and non-signalling operations, which trigger 355 behavior which does not effect the underlying protocol. 357 4 Switches 359 Switches represent choices a CPL script can make, based on either 360 attributes of the original call request or items independent of the 361 call. 363 All switches are arranged as a list of conditions that can match a 364 variable. Each condition corresponds to a node output; the output 365 points to the next node to execute if the condition was true. The 366 conditions are tried in the order they are presented in the script; 367 the output corresponding to the first node to match is taken. 369 There are two special switch outputs that apply to every switch type. 370 The output "not-present", which MAY occur anywhere in the list of 371 outputs, is true if the variable the switch was to match was not 372 present in the original call setup request. (In this document, this 373 is sometimes described by saying that the information is "absent".) 374 The output "otherwise", which MUST be the last output specified if it 375 is present, matches if no other condition matched. 377 If no condition matches and no "otherwise" output was present in the 378 script, the default script behavior is taken. See Section 10 for more 379 information on this. 381 Switches MAY contain no outputs. They MAY contain only an "otherwise" 382 output. 384 Such switches are not particularly useful, but might be 385 created by tools which automatically generate CPL scripts. 387 4.1 Address Switches 389 Address switches allow a CPL script to make decisions based on one of 390 the addresses present in the original call request. They are 391 summarized in Figure 4. 393 Node: "address-switch" 394 Outputs: "address" Specific addresses to match 395 Parameters: "field" "origin", "destination", 396 or "original-destination" 397 "subfield" "address-type", "user", "host", 398 "port", "tel", or "display" 399 (also: "password" and "alias-type") 401 Output: "address" 402 Parameters: "is" Exact match 403 "contains" Substring match (for "display" only) 404 "subdomain-of" Sub-domain match (for "host", "tel") 406 Figure 4: Syntax of the "address-switch" node 408 Address switches have two node parameters: "field", and "subfield". 409 The mandatory "field" parameter allows the script to specify which 410 address is to be considered for the switch: either the call's origin 411 address (field "origin"), its current destination address (field 412 "destination"), or its original destination (field "original- 413 destination"), the destination the call had before any earlier 414 forwarding was invoked. Servers MAY define additional field values. 416 The optional "subfield" specifies what part of the address is to be 417 considered. The possible subfield values are: "address-type", "user", 418 "host", "port", "tel", and "display". Additional subfield values MAY 419 be defined for protocol-specific values. (The subfield "password" is 420 defined for SIP in Section 4.1.1; the subfield "alias-type" is 421 defined for H.323 in Appendix B.1.) If no subfield is specified, the 422 "entire" address is matched; the precise meaning of this is defined 423 for each underlying signalling protocol. Servers MAY define 424 additional subfield values. 426 The subfields are defined as follows: 428 address-type This indicates the type of the underlying address; 429 i.e., the URI scheme, if the address can be represented by 430 a URI. The types specifically discussed by this document 431 are "sip", "tel", and "h323". The address type is not 432 case-sensitive. It has a value for all defined address 433 types. 435 user This subfield of the address indicates, for e-mail style 436 addresses, the user part of the address. For telephone 437 number style address, it includes the subscriber number. 438 This subfield is case-sensitive; it may be absent. 440 host This subfield of the address indicates the Internet host 441 name or IP address corresponding to the address, in host 442 name, IPv4, or IPv6 [4] textual representation format. 443 Host names are compared as strings. IP addresses are 444 compared numerically. (In particular, the presence or 445 location of an IPv6 :: omitted-zero-bits block is not 446 significant for matching purposes.) Host names are never 447 equal to IP addresses -- no DNS resolution is performed. 448 IPv4 addresses are never equal to IPv6 addresses, even if 449 the IPv6 address is a v4-in-v6 embedding. This subfield is 450 not case sensitive, and may be absent. 452 For host names only, subdomain matching is supported with 453 the "subdomain-of" match operator. The "subdomain-of" 454 operator ignores leading dots in the hostname or match 455 pattern, if any. 457 port This subfield indicates the TCP or UDP port number of the 458 address, numerically in decimal format. It is not case 459 sensitive, as it MUST only contain decimal digits. Leading 460 zeros are ignored. 462 tel This subfield indicates a telephone subscriber number, if 463 the address contains such a number. It is not case 464 sensitive (the telephone numbers may contain the symbols 465 `A' `B' `C' and `D'), and may be absent. It may be matched 466 using the "subdomain-of" match operator. Punctuation and 467 separator characters in telephone numbers are discarded. 469 display This subfield indicates a "display name" or user-visible 470 name corresponding to an address. It is a Unicode string, 471 and is matched using the case-insensitive algorithm 472 described in Section 4.2. The "contains" operator may be 473 applied to it. It may be absent. 475 For any completely unknown subfield, the server MAY reject the script 476 at the time it is submitted with an indication of the problem; if a 477 script with an unknown subfield is executed, the server MUST consider 478 the "not-present" output to be the valid one. 480 The "address" output tag may take exactly one of three possible 481 parameters, indicating the kind of matching allowed. 483 is An output with this match operator is followed if the 484 subfield being matched in the "address-switch" exactly 485 matches the argument of the operator. It may be used for 486 any subfield, or for the entire address if no subfield was 487 specified. 489 subdomain-of This match operator applies only for the subfields 490 "host" and "tel". In the former case, it matches if the 491 hostname being matched is a subdomain of the domain given 492 in the argument of the match operator; thus, subdomain- 493 of="example.com" would match the hostnames "example.com", 494 "research.example.com", and 495 "zaphod.sales.internal.example.com". IP addresses may be 496 given as arguments to this operator; however, they only 497 match exactly. In the case of the "tel" subfield, the 498 output matches if the telephone number being matched has a 499 prefix that matches the argument of the match operator; 500 subdomain-of="1212555" would match the telephone number "1 501 212 555 1212." 503 contains This match operator applies only for the subfield 504 "display". The output matches if the display name being 505 matched contains the argument of the match as a substring. 507 4.1.1 Usage of "address-switch" with SIP 509 For SIP, the "origin" address corresponds to the address in the 510 "From" header; "destination" corresponds to the "Request-URI"; and 511 "original-destination" corresponds to the "To" header. 513 The "display" subfield of an address is the display-name part of the 514 address, if it is present. Because of SIP's syntax, the "destination" 515 address field will never have a "display" subfield. 517 The "address-type" subfield of an address is the URI scheme of that 518 address. Other address fields depend on that "address-type". 520 For SIP URIs, the "user", "host", and "port" subfields correspond to 521 the "user," "host," and "port" elements of the URI syntax. (Note 522 that, following the definitions of RFC 3261 [1], a SIP URI which does 523 not specify a port is not the same as an explicit port 5060; the 524 former is indicated by an absent port subfield.) The "tel" subfield 525 is defined to be the "user" part of the URI, with visual separators 526 stripped, if the "user=phone" parameter is given to the URI, or if 527 the server is otherwise configured to recognize the user part as a 528 telephone number. An additional subfield, "password" is defined to 529 correspond to the "password" element of the SIP URI, and is case- 530 sensitive. However, use of this field is NOT RECOMMENDED for general 531 security reasons. 533 For tel URLs, the "tel" and "user" subfields are the subscriber name; 534 in the former case, visual separators are stripped. The "host" and 535 "port" subfields are both not present. 537 For h323 URLs, subfields MAY be set according to the scheme described 538 in Appendix B. 540 For other URI schemes, only the "address-type" subfield is defined by 541 this specification; servers MAY set other pre-defined subfields, or 542 MAY support additional subfields. 544 If no subfield is specified for addresses in SIP messages, the string 545 matched is the URI part of the address. For "is" matches, standard 546 SIP URI matching rules are used; for "contains" matches, the URI is 547 used verbatim. 549 4.2 String Switches 551 String switches allow a CPL script to make decisions based on free- 552 form strings present in a call request. They are summarized in Figure 553 5. 555 Node: "string-switch" 556 Outputs: "string" Specific string to match 557 Parameters: "field" "subject", "organization", 558 "user-agent", or "display" 560 Output: "string" 561 Parameters: "is" Exact match 562 "contains" Substring match 564 Figure 5: Syntax of the "string-switch" node 566 String switches have one node parameter: "field". The mandatory 567 "field" parameter specifies which string is to be matched. 569 String switches are dependent on the call signalling protocol being 570 used. 572 Five fields are defined, listed below. The value of each of these 573 fields, except as specified, is a free-form Unicode string with no 574 other structure defined. 576 "subject" The subject of the call. 578 "organization" The organization of the originator of the call. 580 "user-agent" The name of the program or device with which the 581 call request was made. 583 "display" Free-form text associated with the call, intended to 584 be displayed to the recipient, with no other semantics 585 defined by the signalling protocol. 587 Strings are matched as case-insensitive Unicode strings, in the 588 following manner. First, strings are canonicalized to the 589 "Compatibility Composition" (KC) form, as specified in Unicode 590 Technical Report 15 [5]. Then, strings are compared using locale- 591 insensitive caseless mapping, as specified in Unicode Technical 592 Report 21 [6]. 594 Code to perform the first step, in Java and Perl, is 595 available; see the links from Annex E of UTR 15 [5]. The 596 case-insensitive string comparison in the Java standard 597 class libraries already performs the second step; other 598 Unicode-aware libraries should be similar. 600 The output tag of string matching is named "string", and has a 601 mandatory argument, one of "is" or "contains", indicating whole- 602 string match or substring match, respectively. 604 4.2.1 Usage of "string-switch" with SIP 606 For SIP, the fields "subject", "organization", and "user-agent" 607 correspond to the SIP header fields with the same name. These are 608 used verbatim as they appear in the message. 610 The field "display" is not used, and is never present. 612 4.3 Language Switches 614 Language switches allow a CPL script to make decisions based on the 615 languages in which the originator of the call wishes to communicate. 616 They are summarized in Figure 6. 618 Node: "language-switch" 619 Outputs: "language" Specific string to match 620 Parameters: None 622 Output: "language" 623 Parameters: "matches" Match if the given language matches a 624 language-range of the call. 626 Figure 6: Syntax of the "language-switch" node 628 Language switches take no parameters. 630 The "language" output takes one parameter, "matches". The value of 631 the parameter is a language-tag, as defined in RFC 3066 [7]. The 632 caller may have specified a set of language-ranges, also as defined 633 in RFC 3066. The CPL server checks each language-tag specified by the 634 script against the language-ranges specified in the request. 636 See RFC 3066 for the details of how language-ranges match language- 637 tags. Briefly, a language-range matches a language-tag if it exactly 638 equals the tag, or if it exactly equals a prefix of the tag such that 639 the first character following the prefix is "-". 641 If the caller specified the special language-range "*", it is ignored 642 for the purpose of matching. Languages with a "q" value of 0 are also 643 ignored. 645 This switch MAY be not-present. 647 4.3.1 Usage of "language-switch" with SIP 649 The language-ranges for the "language-switch" switch are obtained 650 from the SIP "Accept-Language" header field. The switch is not- 651 present if the initial SIP request did not contain this header field. 653 Note that because of CPL's first-match semantics in 654 switches, "q" values other than 0 of the "Accept-Language" 655 header fields are ignored. 657 4.4 Time Switches 659 Time switches allow a CPL script to make decisions based on the time 660 and/or date the script is being executed. They are summarized in 661 Figure 7. 663 Time switches are independent of the underlying signalling protocol. 665 Node: "time-switch" 666 Outputs: "time" Specific time to match 667 Parameters: "tzid" RFC 2445 Time Zone Identifier 668 "tzurl" RFC 2445 Time Zone URL 670 Output: "time" 671 Parameters: "dtstart" Start of interval (RFC 2445 DATE-TIME) 672 "dtend" End of interval (RFC 2445 DATE-TIME) 673 "duration" Length of interval (RFC 2445 DURATION) 674 "freq" Frequency of recurrence ("secondly", 675 "minutely", "hourly", "daily", 676 "weekly", "monthly", or "yearly") 677 "interval" How often the recurrence repeats 678 "until" Bound of recurrence (RFC 2445 DATE-TIME) 679 "count" Number of occurrences of recurrence 680 "bysecond" List of seconds within a minute 681 "byminute" List of minutes within an hour 682 "byhour" List of hours of the day 683 "byday" List of days of the week 684 "bymonthday" List of days of the month 685 "byyearday" List of days of the year 686 "byweekno" List of weeks of the year 687 "bymonth" List of months of the year 688 "wkst" First day of the work week 689 "bysetpos" List of values within 690 set of events specified 692 Figure 7: Syntax of the "time-switch" node 694 Time switches are based closely on the specification of recurring 695 intervals of time in the Internet Calendaring and Scheduling Core 696 Object Specification (iCalendar COS), RFC 2445 [8]. 698 This allows CPL scripts to be generated automatically from 699 calendar books. It also allows us to re-use the extensive 700 existing work specifying time intervals. 702 If future standards-track documents are published that update or 703 obsolete RFC 2445, any changes or clarifications those documents make 704 to recurrence handling apply to CPL time-switches as well. 706 An algorithm to determine whether an instant falls within a given 707 recurrence is given in Appendix A. 709 The "time-switch" tag takes two optional parameters, "tzid" and 710 "tzurl", both of which are defined in RFC 2445 (Sections 4.8.3.1 and 711 4.8.3.5 respectively). The "tzid" is the identifying label by which a 712 time zone definition is referenced. If it begins with a forward slash 713 (solidus), it references a to-be-defined global time zone registry; 714 otherwise it is locally-defined at the server. The "tzurl" gives a 715 network location from which an up-to-date VTIMEZONE definition for 716 the timezone can be retrieved. 718 While "tzid" labels that do not begin with a forward slash are 719 locally defined, it is RECOMMENDED that servers support at least the 720 naming scheme used by Olson Time Zone database [9]. Examples of 721 timezone databases that use the Olson scheme are the zoneinfo files 722 on most Unix-like systems, and the standard Java TimeZone class. 724 Servers SHOULD resolve "tzid" and "tzurl" references to time zone 725 definitions at the time the script is uploaded. They MAY periodically 726 refresh these resolutions to obtain the most up-to-date definition of 727 a time zone. If a "tzurl" becomes invalid, servers SHOULD remember 728 the most recent valid data retrieved from the URL. 730 If a script is uploaded with a "tzid" and "tzurl" which the CPL 731 server does not recognize or cannot resolve, it SHOULD diagnose and 732 reject this at script upload time. If neither "tzid" nor "tzurl" are 733 present, all non-UTC times within this time switch should be 734 interpreted as being "floating" times, i.e. that they are specified 735 in the local timezone of the CPL server. 737 Because of daylight-savings-time changes over the course of 738 a year, it is necessary to specify time switches in a given 739 timezone. UTC offsets are not sufficient, or a time-of-day 740 routing rule which held between 9 am and 5 pm in the 741 eastern United States would start holding between 8 am and 742 4 pm at the end of October. 744 Authors of CPL servers should be careful to handle correctly the 745 intervals when local time is discontinuous, at the beginning or end 746 of daylight-savings time. Note especially that some times may occur 747 more than once when clocks are set back. The algorithm in Appendix A 748 is believed to handle this correctly. 750 Time nodes specify a list of periods during which their output should 751 be taken. They have two required parameters: "dtstart", which 752 specifies the beginning of the first period of the list, and exactly 753 one of "dtend" or "duration", which specify the ending time or the 754 duration of the period, respectively. The "dtstart" and "dtend" 755 parameters are formatted as iCalendar COS DATE-TIME values, as 756 specified in Section 4.3.5 of RFC 2445 [8]. Because time zones are 757 specified in the top-level "time-switch" tag, only forms 1 or 2 758 (floating or UTC times) can be used. The "duration" parameter is 759 given as an iCalendar COS DURATION parameter, as specified in section 760 4.3.6 of RFC 2445. Both the DATE-TIME and the DURATION syntaxes are 761 subsets of the corresponding syntaxes from ISO 8601 [20]. 763 For a recurring interval, the "duration" parameter MUST be small 764 enough such that subsequent intervals do not overlap. For non- 765 recurring intervals, durations of any positive length are permitted. 766 Zero-length and negative-length durations are not allowed. 768 If no other parameters are specified, a time node indicates only a 769 single period of time. More complicated sets periods intervals are 770 constructed as recurrences. A recurrence is specified by including 771 the "freq" parameter, which indicates the type of recurrence rule. 772 Parameters other than "dtstart", "dtend", and "duration" SHOULD NOT 773 be specified unless "freq" is present, though CPL servers SHOULD 774 accept scripts with such parameters present, and ignore the other 775 parameters. 777 The "freq" parameter takes one of the following values: "secondly", 778 to specify repeating periods based on an interval of a second or 779 more; "minutely", to specify repeating periods based on an interval 780 of a minute or more; "hourly", to specify repeating periods based on 781 an interval of an hour or more; "daily", to specify repeating periods 782 based on an interval of a day or more; "weekly", to specify repeating 783 periods based on an interval of a week or more; "monthly", to specify 784 repeating periods based on an interval of a month or more; and 785 "yearly", to specify repeating periods based on an interval of a year 786 or more. These values are not case-sensitive. 788 The "interval" parameter contains a positive integer representing how 789 often the recurrence rule repeats. The default value is "1", meaning 790 every second for a "secondly" rule, every minute for a "minutely" 791 rule, every hour for an "hourly" rule, every day for a "daily" rule, 792 every week for a "weekly" rule, every month for a "monthly" rule and 793 every year for a "yearly" rule. 795 The "until" parameter defines an iCalendar COS DATE or DATE-TIME 796 value which bounds the recurrence rule in an inclusive manner. If the 797 value specified by "until" is synchronized with the specified 798 recurrence, this date or date-time becomes the last instance of the 799 recurrence. If specified as a date-time value, then it MUST be 800 specified in an UTC time format. If not present, and the "count" 801 parameter is not also present, the recurrence is considered to repeat 802 forever. 804 The "count" parameter defines the number of occurrences at which to 805 range-bound the recurrence. The "dtstart" parameter counts as the 806 first occurrence. The "until" and "count" parameters MUST NOT occur 807 in the same "time" output. 809 The "bysecond" parameter specifies a comma-separated list of seconds 810 within a minute. Valid values are 0 to 59. The "byminute" parameter 811 specifies a comma-separated list of minutes within an hour. Valid 812 values are 0 to 59. The "byhour" parameter specifies a comma- 813 separated list of hours of the day. Valid values are 0 to 23. 815 The "byday" parameter specifies a comma-separated list of days of the 816 week. "MO" indicates Monday; "TU" indicates Tuesday; "WE" indicates 817 Wednesday; "TH" indicates Thursday; "FR" indicates Friday; "SA" 818 indicates Saturday; "SU" indicates Sunday. These values are not 819 case-sensitive. 821 Each "byday" value can also be preceded by a positive (+n) or 822 negative (-n) integer. If present, this indicates the nth occurrence 823 of the specific day within the "monthly" or "yearly" recurrence. For 824 example, within a "monthly" rule, +1MO (or simply 1MO) represents the 825 first Monday within the month, whereas -1MO represents the last 826 Monday of the month. If an integer modifier is not present, it means 827 all days of this type within the specified frequency. For example, 828 within a "monthly" rule, MO represents all Mondays within the month. 830 The "bymonthday" parameter specifies a comma-separated list of days 831 of the month. Valid values are 1 to 31 or -31 to -1. For example, -10 832 represents the tenth to the last day of the month. 834 The "byyearday" parameter specifies a comma-separated list of days of 835 the year. Valid values are 1 to 366 or -366 to -1. For example, -1 836 represents the last day of the year (December 31st) and -306 837 represents the 306th to the last day of the year (March 1st). 839 The "byweekno" parameter specifies a comma-separated list of ordinals 840 specifying weeks of the year. Valid values are 1 to 53 or -53 to -1. 841 This corresponds to weeks according to week numbering as defined in 842 ISO 8601 [20]. A week is defined as a seven day period, starting on 843 the day of the week defined to be the week start (see "wkst"). Week 844 number one of the calendar year is the first week which contains at 845 least four (4) days in that calendar year. This parameter is only 846 valid for "yearly" rules. For example, 3 represents the third week of 847 the year. 849 Note: Assuming a Monday week start, week 53 can only occur 850 when Thursday is January 1 or if it is a leap year and 851 Wednesday is January 1. 853 The "bymonth" parameter specifies a comma-separated list of months of 854 the year. Valid values are 1 to 12. 856 The "wkst" parameter specifies the day on which the work week starts. 857 Valid values are "MO", "TU", "WE", "TH", "FR", "SA" and "SU". This is 858 significant when a "weekly" recurrence has an interval greater than 859 1, and a "byday" parameter is specified. This is also significant in 860 a "yearly" recurrence when a "byweekno" parameter is specified. The 861 default value is "MO", following ISO 8601 [20]. 863 The "bysetpos" parameter specifies a comma-separated list of values 864 which corresponds to the nth occurrence within the set of events 865 specified by the rule. Valid values are 1 to 366 or -366 to -1. It 866 MUST only be used in conjunction with another byxxx parameter. For 867 example "the last work day of the month" could be represented as: 869