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