Internet Engineering Task Force IPTEL WG Internet Draft Lennox/Schulzrinne [-draft-ietf-iptel-cpl-05.txt-] {+draft-ietf-iptel-cpl-06.txt+} Columbia University [-November 21, 2001-] {+January 15, 2002+} Expires: [-May,-] {+July,+} 2002 CPL: A Language for User Control of Internet Telephony Services STATUS OF THIS MEMO This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress". The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt To view the list Internet-Draft Shadow Directories, see http://www.ietf.org/shadow.html. Abstract The Call Processing Language (CPL) is a language that can be used to describe and control Internet telephony services. It is designed to be implementable on either network servers or user agent servers. It is meant to be simple, extensible, easily edited by graphical clients, and independent of operating system or signalling protocol. It is suitable for running on a server where users may not be allowed to execute arbitrary programs, as it has no variables, loops, or ability to run external programs. This document is a product of the IP Telephony (IPTEL) working group of the Internet Engineering Task Force. Comments are solicited and should be addressed to the working group's mailing list at iptel@lists.research.bell-labs.com and/or the authors. Lennox/Schulzrinne [Page 1] [-Internet Draft CPL November 21, 2001-] {+Table of Contents+} 1 Introduction [-The-] {+........................................ 4 1.1 Conventions of This Document ........................ 4 2 Structure of CPL Scripts ............................ 4 2.1 High-level Structure ................................ 5 2.2 Abstract Structure of a+} Call Processing {+Action ...... 5 2.3 Location Model ...................................... 6 2.4 XML Structure ....................................... 6 3 Document Information ................................ 7 3.1 CPL Document Identifiers for XML .................... 7 3.2 MIME Registration ................................... 8 4 Script Structure: Overview .......................... 9 5 Switches ............................................ 10 5.1 Address Switches .................................... 11 5.1.1 Usage of "address-switch" with SIP .................. 13 5.2 String Switches ..................................... 14 5.2.1 Usage of "string-switch" with SIP ................... 15 5.3+} Language [-(CPL) is a language that can be used to describe and control Internet telephony services. It is not tied to any particular signalling architecture or protocol; it is anticipated that it will be used-] {+Switches ................................... 15 5.3.1 Usage of "language-switch"+} with [-both-] SIP [-[1]-] {+................. 16 5.4 Time Switches ....................................... 16 5.4.1 iCalendar differences+} and [-H.323 [2]. The CPL is powerful enough to describe a large number-] {+implementation issues ..... 22 5.5 Priority Switches ................................... 23 5.5.1 Usage+} of [-services and features, but it is limited in power so that it can run safely in Internet telephony servers. The intention is to make it impossible for users to do anything more complex (and dangerous) than describing Internet telephony services. The language is not Turing-complete, and provides no way to write loops or recursion. The CPL is also designed to be easily created and edited by graphical tools. It is based on XML [3], so parsing it is easy and many parsers for it are publicly available. The structure-] {+"priority-switch" with SIP ................. 24 6 Location Modifiers .................................. 24 6.1 Explicit Location ................................... 25 6.1.1 Usage+} of [-the language maps closely to its behavior, so an editor can understand any valid script, even ones written by hand. The language is also designed so that a server can easily confirm scripts' validity at the time they are delivered to it, rather that discovering them while a call is being processed. Implementations-] {+"location" with SIP ........................ 26 6.2 Location Lookup ..................................... 26 6.2.1 Usage+} of [-the CPL are expected to take place both in Internet telephony servers and in advanced clients; both can usefully process and direct users' calls. This document primarily addresses the usage in servers. A mechanism will be needed to transport scripts between clients and servers; this document does not describe such a mechanism, but related documents will. The framework and requirements for the CPL architecture are described in RFC 2824, "Call Processing Language Framework and Requirements" [4]. 1.1 Conventions-] {+"lookup" with SIP .......................... 28 6.3 Location Removal .................................... 28 6.3.1 Usage+} of [-This Document In this document, the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119 [5] and indicate requirement levels for compliant CPL implementations. Some paragraphs are indented, like this; they give motivations-] {+"remove-location" with SIP ................. 29 7 Signalling Operations ............................... 29 7.1 Proxy ............................................... 29 7.1.1 Usage+} of [-design choices, or questions for future discussion in the development-] {+"proxy" with SIP ........................... 32 7.2 Redirect ............................................ 32 7.2.1 Usage+} of [-the CPL, and are not essential to the specification-] {+"redirect" with SIP ........................ 32 7.3 Reject .............................................. 33 7.3.1 Usage+} of [-the language. 2 Structure-] {+"reject" with SIP .......................... 33 8 Non-signalling Operations ........................... 34 8.1 Mail ................................................ 34 8.1.1 Suggested Content+} of [-CPL Scripts-] {+Mailed Information ............. 35 8.2 Log ................................................. 35 9 Subactions .......................................... 36+} Lennox/Schulzrinne [Page 2] Internet Draft CPL [-November 21, 2001 2.1 High-level Structure A-] {+January 15, 2002 10 Ancillary Information ............................... 37 11 Default Behavior .................................... 38 12+} CPL [-script consists of two types of information: ancillary information about the script,-] {+Extensions ...................................... 39 13 Examples ............................................ 40 13.1 Example: Call Redirect Unconditional ................ 40 13.2 Example: Call Forward Busy/No Answer ................ 40 13.3 Example: Call Forward: Redirect+} and [-call processing actions. A call processing action is a structured tree that describes the operations-] {+Default ......... 40 13.4 Example: Call Screening ............................. 42 13.5 Example: Priority+} and [-decisions a telephony signalling server performs on a call set-up event. There are two types-] {+Language Routing .............. 42 13.6 Example: Outgoing Call Screening .................... 42 13.7 Example: Time-of-day Routing ........................ 43 13.8 Example: Location Filtering ......................... 44 13.9 Example: Non-signalling Operations .................. 44 13.10 Example: Hypothetical Extensions .................... 45 13.11 Example: A Complex Example .......................... 45 14 Security Considerations ............................. 48 15 IANA Considerations ................................. 49 16 Acknowledgments ..................................... 49 A An Algorithm for Resolving Time Switches ............ 49 B Suggested Usage+} of [-call processing actions: top-level actions and subactions. Top-level actions are actions that are triggered by signalling events that arrive at the server. Two top-level action names are defined: "incoming", the action performed when a call arrives whose destination is the owner-] {+CPL with H.323 ................... 51 B.1 Usage+} of [-the script; and "outgoing", the action performed when a call arrives whose originator is the owner-] {+"address-switch" with H.323 ................ 51 B.2 Usage+} of [-the script. Subactions are actions which can be called from other actions.-] {+"string-switch" with H.323 ................. 53 B.3 Usage of "language-switch" with H.323 ............... 53 B.4 Usage of "priority-switch" with H.323 ............... 53 B.5 Usage of "location" with H.323 ...................... 53 B.6 Usage of "lookup" with H.323 ........................ 53 B.7 Usage of "remove-location" with H.323 ............... 54 C+} The {+XML DTD for+} CPL [-forbids subactions-] {+................................. 54 D Changes+} from [-being called recursively: see Section 9. Ancillary information is information which-] {+Earlier Versions ....................... 60 D.1 Changes from Draft -05 .............................. 60 D.2 Changes from Draft -04 .............................. 61 D.3 Changes from Draft -03 .............................. 62 D.4 Changes from Draft -02 .............................. 62 D.5 Changes from Draft -01 .............................. 63 D.6 Changes from Draft -00 .............................. 65 E Authors' Addresses .................................. 66 F Bibliography ........................................ 66 Lennox/Schulzrinne [Page 3] Internet Draft CPL January 15, 2002 1 Introduction The Call Processing Language (CPL)+} is [-necessary for-] a [-server-] {+language that can be used+} to [-correctly process a script, but which does not directly-] describe {+and control Internet telephony services. It is not tied to+} any [-operations-] {+particular signalling architecture+} or [-decisions. Currently, no ancillary information-] {+protocol; it+} is [-defined, but the section-] {+anticipated that it will be used with both SIP [1] and H.323 [2]. The CPL+} is [-reserved for use by extensions. 2.2 Abstract Structure of a Call Processing Action Abstractly, a call processing action is described by a collection of nodes, which-] {+powerful enough to+} describe [-operations that can be performed or decisions which can be made. A node may have several parameters, which specify the precise behavior of the node; they usually also have outputs, which depend on the result of the decision or action. For a graphical representation of-] a [-CPL action, see Figure 1. Nodes and outputs can be thought-] {+large number+} of [-informally as boxes-] {+services+} and [-arrows; the CPL-] {+features, but it+} is [-designed-] {+limited in power+} so that [-actions-] {+it+} can [-be conveniently edited graphically using this representation. Nodes are arranged-] {+run safely+} in [-a tree, starting at a single root node; outputs of nodes are connected-] {+Internet telephony servers. The intention is+} to [-additional nodes. When an action-] {+make it impossible for users to do anything more complex (and dangerous) than describing Internet telephony services. The language+} is [-run, the action-] {+not Turing-complete, and provides no way to write loops+} or [-decision described-] {+recursion. The CPL is also designed to be easily created and edited+} by [-the action's top-level node-] {+graphical tools. It+} is [-performed;-] based on [-the result of that node, the server follows one of the node's outputs, and the subsequent node-] {+XML [3], so parsing+} it [-points to is performed; this process continues until a node with no specified outputs is reached. Because the graph-] is [-acyclic, this will occur after a bounded-] {+easy+} and [-predictable number of nodes-] {+many parsers for it+} are [-visited. If an output-] {+publicly available. The structure of the language maps closely+} to [-a node does not point-] {+its behavior, so an editor can understand any valid script, even ones written by hand. The language is also designed so that a server can easily confirm scripts' validity at the time they are delivered+} to [-another node, it indicates-] {+it, rather+} that {+discovering them while a call is being processed. Implementations of+} the CPL [-server should perform-] {+are expected to take place both in Internet telephony servers and in advanced clients; both can usefully process and direct users' calls. This document primarily addresses the usage in servers. A mechanism will be needed to transport scripts between clients and servers; this document does not describe such+} a [-node- or protocol-specific action. Some nodes have specific default behavior associated with them;-] {+mechanism, but related documents will. The framework and requirements+} for [-others,-] the [-default behavior is implicit-] {+CPL architecture are described+} in {+RFC 2824, "Call Processing Language Framework and Requirements" [4]. 1.1 Conventions of This Document In this document,+} the [-underlying signalling protocol, or can-] {+key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to+} be [-configured by-] {+interpreted as described in RFC 2119 [5] and indicate requirement levels for compliant CPL implementations. Some paragraphs are indented, like this; they give motivations of design choices, or questions for future discussion in+} the [-administrator-] {+development of the CPL, and are not essential to the specification+} of the {+language. 2 Structure of CPL Scripts+} Lennox/Schulzrinne [Page [-3]-] {+4]+} Internet Draft CPL [-November 21, 2001 server. For further details on this, see Section 11. _________________ ___________________ ________ busy | Address-switch | | location | | proxy |--------\ Call --->| field: origin | ->| url: sip:jones@ |--->|timeout:| timeout| | subfield: host | / | example.com | | 10s |--------| |-----------------|/ |___________________| | | failure| | subdomain-of: | |________|--------| | example.com | | |-----------------| _____________________________________________/ | otherwise | /.......................................... | |\|. Voicemail . |_________________| \. ____________________ . ->| location | __________ . . | url: sip:jones@ | | redirect | . . | voicemail. |--->| | . . | example.com | |__________| . . |____________________| . .......................................... Figure 1: Sample-] {+January 15, 2002 2.1 High-level Structure A+} CPL [-Action: Graphical Version 2.3 Location Model For flexibility, one piece-] {+script consists of two types+} of {+information: ancillary+} information [-necessary for-] {+about+} the [-function of a CPL-] {+script, and call processing actions. A call processing action+} is [-not given as node parameters:-] {+a structured tree that describes+} the [-set of locations to which-] {+operations and decisions a telephony signalling server performs on+} a call [-is to be directed. Instead, this set of locations is stored as an implicit global variable throughout the execution-] {+set-up event. There are two types+} of [-a-] {+call+} processing [-action (and its subactions). This allows locations to be retrieved from external sources, filtered, and so forth, without requiring general language support for such operations (which could harm the simplicity-] {+actions: top-level actions+} and [-tractability of understanding the language). The specific operations which add, retrieve, or filter location sets-] {+subactions. Top-level actions+} are [-given in Section 6. For-] {+actions that are triggered by signalling events that arrive at+} the [-incoming-] {+server. Two+} top-level {+action names are defined: "incoming", the action performed when a+} call [-processing action,-] {+arrives whose destination is+} the [-location set is initialized to-] {+owner of+} the [-empty set. For-] {+script; and "outgoing",+} the [-outgoing action, it-] {+action performed when a call arrives whose originator+} is [-initialized to-] the [-destination address-] {+owner+} of the [-call. 2.4 XML Structure Lennox/Schulzrinne [Page 4] Internet Draft CPL November 21, 2001 Syntactically, CPL scripts-] {+script. Subactions+} are [-represented by XML documents. XML-] {+actions which can be called from other actions. The CPL forbids subactions from being called recursively: see Section 9. Ancillary information+} is [-thoroughly specified-] {+information which is necessary for a server to correctly process a script, but which does not directly describe any operations or decisions. Currently, no ancillary information is defined, but the section is reserved for use+} by [-[3], and implementors-] {+extensions. 2.2 Abstract Structure+} of [-this specification should be familiar with that document, but as-] a [-brief overview, XML consists of-] {+Call Processing Action Abstractly,+} a [-hierarchical structure-] {+call processing action is described by a collection+} of [-tags; each tag-] {+nodes, which describe operations that can be performed or decisions which+} can {+be made. A node may+} have [-a number of attributes. It is visually and structurally very similar to HTML [6], as both languages are simplifications-] {+several parameters, which specify the precise behavior+} of the [-earlier and larger standard SGML [7]. See Figure 2 for-] {+node; they usually also have outputs, which depend on+} the [-XML document corresponding to-] {+result of+} the {+decision or action. For a+} graphical representation of [-the-] {+a+} CPL [-script in-] {+action, see+} Figure 1. [-Both nodes-] {+Nodes+} and outputs [-in-] {+can be thought of informally as boxes and arrows;+} the CPL {+is designed so that actions can be conveniently edited graphically using this representation. Nodes+} are [-represented by XML tags; parameters are represented by XML tag attributes. Typically, node tags contain output tags, and vice-versa (with-] {+arranged in+} a [-few exceptions: see Sections 6.1, 6.3, 8.1, and 8.2). The connection between the output of-] {+tree, starting at+} a [-node and another node-] {+single root node; outputs of nodes are connected to additional nodes. When an action+} is [-represented by enclosing-] {+run,+} the [-tag representing-] {+action or decision described by+} the [-pointed-to-] {+action's top-level+} node [-inside-] {+is performed; based on+} the [-tag for-] {+result of that node, the server follows one of+} the [-outer-] node's [-output. Convergence (several outputs pointing-] {+outputs, and the subsequent node it points+} to [-a single node)-] is [-represented by subactions, discussed further in Section 9. The higher-level structure of-] {+performed; this process continues until+} a [-CPL script-] {+node with no specified outputs+} is [-represented by tags corresponding to each piece of ancillary information, subactions, and top-level actions, in order. This higher-level information-] {+reached. Because the graph+} is [-all enclosed in-] {+acyclic, this will occur after+} a [-special tag "cpl", the outermost tag-] {+bounded and predictable number+} of {+nodes are visited. If an output to a node does not point to another node, it indicates that+} the [-XML document. A complete Document Type Declaration-] {+CPL server should perform a node- or protocol-specific action. Some nodes have specific default behavior associated with them;+} for {+others,+} the [-CPL-] {+default behavior+} is [-provided-] {+implicit+} in [-Appendix C. The remainder of-] the [-main sections of this document describe-] {+underlying signalling protocol, or can be configured by+} the [-semantics-] {+administrator+} of the [-CPL, while giving its syntax informally.-] {+Lennox/Schulzrinne [Page 5] Internet Draft CPL January 15, 2002 server.+} For [-the formal syntax, please see the appendix. 3 Document Information This section gives information describing how CPL scripts are identified. 3.1-] {+further details on this, see Section 11. _________________ ___________________ ________ busy | Address-switch | | location | | proxy |--------\ Call --->| field: origin | ->| url: sip:jones@ |--->|timeout:| timeout| | subfield: host | / | example.com | | 10s |--------| |-----------------|/ |___________________| | | failure| | subdomain-of: | |________|--------| | example.com | | |-----------------| _____________________________________________/ | otherwise | /.......................................... | |\|. Voicemail . |_________________| \. ____________________ . ->| location | __________ . . | url: sip:jones@ | | redirect | . . | voicemail. |--->| | . . | example.com | |__________| . . |____________________| . .......................................... Figure 1: Sample+} CPL [-Document Identifiers-] {+Action: Graphical Version 2.3 Location Model For flexibility, one piece of information necessary+} for [-XML A-] {+the function of a+} CPL [-script list which appears-] {+is not given+} as {+node parameters: the set of locations to which+} a [-top-level XML document-] {+call+} is [-identified with the formal public identifier "-//IETF//DTD RFCxxxx CPL 1.0//EN". A CPL embedded-] {+to be directed. Instead, this set of locations is stored+} as {+an implicit global variable throughout the execution of+} a [-fragment within another XML document is identified with-] {+processing action (and its subactions). This allows locations to be retrieved from external sources, filtered, and so forth, without requiring general language support for such operations (which could harm+} the [-XML namespace identifier "http://www.rfc- editor.org/rfc/rfcxxxx.txt". Lennox/Schulzrinne [Page 5] Internet Draft CPL November 21, 2001
Figure 2: Sample CPL Script: XML Version [Note to RFC editor: please replace "xxxx" above with the number-] {+simplicity and tractability+} of [-this RFC.] Note that-] {+understanding+} the [-URIs specifying XML namespaces-] {+language). The specific operations which add, retrieve, or filter location sets+} are [-only globally unique names; they do not have-] {+given in Section 6. For the incoming top-level call processing action, the location set is initialized+} to [-reference any particular actual object. The URI of a canonical source of this specification meets-] the [-requirement of being globally unique, and-] {+empty set. For the outgoing action, it+} is [-also useful-] {+initialized+} to [-document-] the [-format. 3.2 MIME Registration As an-] {+destination address of the call. 2.4+} XML [-type, CPL's MIME registration conforms with "XML Media Types," RFC 3023 [8].-] {+Structure+} Lennox/Schulzrinne [Page 6] Internet Draft CPL [-November 21, 2001 MIME media type name: application MIME subtype name: cpl+xml Mandatory parameters: none Optional parameters: charset As for application/xml in RFC 3023. Encoding considerations: As for application/xml in RFC 3023. Security considerations: See Section 14,-] {+January 15, 2002 Syntactically, CPL scripts are represented by XML documents. XML is thoroughly specified by [3],+} and [-Section 10-] {+implementors+} of [-RFC 3023. Interoperability considerations: Different CPL servers may use incompatible address types. However, all potential interoperability issues-] {+this specification+} should be [-resolvable at the time-] {+familiar with that document, but as+} a [-script is uploaded; there should be no interoperability issues which cannot be detected until runtime. Published specification: This document. Applications which use this media type: None publicly released at this time, as far-] {+brief overview, XML consists of a hierarchical structure of tags; each tag can have a number of attributes. It is visually and structurally very similar to HTML [6],+} as {+both languages are simplifications of+} the [-authors-] {+earlier and larger standard SGML [7]. See Figure 2 for the XML document corresponding to the graphical representation of the CPL script in Figure 1. Both nodes and outputs in the CPL+} are [-aware. Additional information: Magic number: None File extension: .cpl or .xml Macintosh file type code: "TEXT" Person-] {+represented by XML tags; parameters are represented by XML tag attributes. Typically, node tags contain output tags,+} and [-e-mail address-] {+vice-versa (with a few exceptions: see Sections 6.1, 6.3, 8.1, and 8.2). The connection between the output of a node and another node is represented by enclosing the tag representing the pointed-to node inside the tag+} for {+the outer node's output. Convergence (several outputs pointing to a single node) is represented by subactions, discussed+} further [-information: Jonathan Lennox Henning Schulzrinne Intended usage: COMMON Author/Change Controller:-] {+in Section 9.+} The [-IETF. 4 Script Structure: Overview As mentioned,-] {+higher-level structure of+} a CPL script [-consists-] {+is represented by tags corresponding to each piece+} of ancillary information, subactions, and top-level [-actions. The full syntax-] {+actions, in order. This higher-level information is all enclosed in a special tag "cpl", the outermost tag+} of the [-"cpl" node-] {+XML document. A complete Document Type Declaration for the CPL+} is [-given-] {+provided+} in [-Figure 3. Lennox/Schulzrinne [Page 7] Internet Draft CPL November 21, 2001 Tag: "cpl" Parameters: None Sub-tags: "ancillary" See Section 10 "subaction" See Section 9 "outgoing" Top-level actions to take on this user's outgoing calls "incoming" Top-level actions to take on this user's incoming calls Figure 3: Syntax-] {+Appendix C. The remainder+} of the [-top-level "cpl" tag Call processing actions, both top-level actions and sub-actions, consist-] {+main sections+} of [-a tree-] {+this document describe the semantics+} of [-nodes and outputs. Nodes and outputs are both described by XML tags. There-] {+the CPL, while giving its syntax informally. For the formal syntax, please see the appendix. 3 Document Information This section gives information describing how CPL scripts+} are [-four categories of-] {+identified. 3.1+} CPL [-nodes: switches, which represent choices a-] {+Document Identifiers for XML A+} CPL script [-can make; location modifiers, which add or remove locations from the location set; signalling operations, which cause signalling events in the underlying protocol; and non-signalling operations, which trigger behavior-] {+list+} which [-does not effect the underlying protocol. 5 Switches Switches represent choices-] {+appears as+} a [-CPL script can make, based on either attributes of the original call request or items independent of-] {+top-level XML document is identified with+} the [-call. All switches are arranged-] {+formal public identifier "-//IETF//DTD RFCxxxx CPL 1.0//EN". A CPL embedded+} as a [-list of conditions that can match a variable. Each condition corresponds to a node output; the output points to the next node to execute if the condition was true. The conditions are tried in the order they are presented in the script; the output corresponding to the first node to match-] {+fragment within another XML document+} is [-taken. There are two special switch outputs that apply to every switch type. The output "not-present", which MAY occur anywhere in the list of outputs, is true if the variable-] {+identified with+} the [-switch was-] {+XML namespace identifier "http://www.rfc- editor.org/rfc/rfcxxxx.txt". Lennox/Schulzrinne [Page 7] Internet Draft CPL January 15, 2002
Figure 2: Sample CPL Script: XML Version [Note+} to [-match was not present in-] {+RFC editor: please replace "xxxx" above with+} the [-original call setup request. (In this document,-] {+number of+} this [-is sometimes described by saying-] {+RFC.] Note+} that the [-information is "absent".)-] {+URIs specifying XML namespaces are only globally unique names; they do not have to reference any particular actual object.+} The [-output "otherwise", which MUST be-] {+URI of a canonical source of this specification meets+} the [-last output specified if it is present, matches if no other condition matched. If no condition matches-] {+requirement of being globally unique,+} and [-no "otherwise" output was present in the script, the default script behavior-] is [-taken. See Section 11 for more information on this. 5.1 Address Switches-] {+also useful to document the format. 3.2 MIME Registration As an XML type, CPL's MIME registration conforms with "XML Media Types," RFC 3023 [8].+} Lennox/Schulzrinne [Page 8] Internet Draft CPL [-November 21, 2001 Address switches allow a CPL script to make decisions based on one of the addresses present-] {+January 15, 2002 MIME media type name: application MIME subtype name: cpl+xml Mandatory parameters: none Optional parameters: charset As for application/xml+} in [-the original call request. They are summarized-] {+RFC 3023. Encoding considerations: As for application/xml+} in [-Figure 4. Node: "address-switch" Outputs: "address" Specific addresses to match Parameters: "field" "origin", "destination", or "original-destination" "subfield" "address-type", "user", "host", "port", "tel", or "display" (also: "password"-] {+RFC 3023. Security considerations: See Section 14,+} and [-"alias-type") Output: "address" Parameters: "is" exact match "contains" substring match (for "display" only) "subdomain-of" sub-domain match (for "host", "tel" only) Figure 4: Syntax-] {+Section 10+} of {+RFC 3023. Interoperability considerations: Different CPL servers may use incompatible address types. However, all potential interoperability issues should be resolvable at+} the [-"address-switch" node Address switches have two node parameters: "field", and "subfield". The mandatory "field" parameter allows the-] {+time a+} script [-to specify which address-] is [-to-] {+uploaded; there should+} be [-considered for the switch: either-] {+no interoperability issues which cannot be detected until runtime. Published specification: This document. Applications which use this media type: None publicly released at this time, as far as+} the [-call's origin address (field "origin"), its current destination address (field "destination"),-] {+authors are aware. Additional information: Magic number: None File extension: .cpl+} or [-its original destination (field "original- destination"), the destination the call had before any earlier forwarding was invoked. Servers MAY define additional field values. The optional "subfield" specifies what part of the-] {+.xml Macintosh file type code: "TEXT" Person and e-mail+} address [-is to be considered.-] {+for further information: Jonathan Lennox Henning Schulzrinne Intended usage: COMMON Author/Change Controller:+} The [-possible subfield values are: "address-type", "user", "host", "port", "tel", and "display". Additional subfield values MAY be defined for protocol-specific values. (The subfield "password" is defined for SIP in Section 5.1.1; the subfield "alias-type" is defined for H.323 in Appendix B.1.) If no subfield is specified, the "entire" address is matched; the precise meaning-] {+IETF. 4 Script Structure: Overview As mentioned, a CPL script consists+} of [-this is defined for each underlying signalling protocol. Servers MAY define additional subfield values.-] {+ancillary information, subactions, and top-level actions.+} The [-subfields are defined as follows: address-type This indicates the type-] {+full syntax+} of the [-underlying address; i.e., the URI scheme, if the address can be represented by a URI. The types specifically discussed by this document are "sip", "tel", and "h323". The address type-] {+"cpl" node+} is [-not case-sensitive. It has a value for all defined address types.-] {+given in Figure 3.+} Lennox/Schulzrinne [Page 9] Internet Draft CPL [-November 21, 2001 user This subfield-] {+January 15, 2002 Tag: "cpl" Parameters: None Sub-tags: "ancillary" See Section 10 "subaction" See Section 9 "outgoing" Top-level actions to take on this user's outgoing calls "incoming" Top-level actions to take on this user's incoming calls Figure 3: Syntax+} of the [-address indicates, for e-mail style addresses, the user part-] {+top-level "cpl" tag Call processing actions, both top-level actions and sub-actions, consist+} of [-the address. For telephone number style address, it includes the subscriber number. This subfield is case-sensitive; it may be absent. host This subfield-] {+a tree+} of [-the address indicates the Internet host name or IP address corresponding to the address, in host name, IPv4, or IPv6 [9] textual representation format. Host names-] {+nodes and outputs. Nodes and outputs+} are [-compared as strings. IP addresses-] {+both described by XML tags. There+} are [-compared numerically. (In particular, the presence-] {+four categories of CPL nodes: switches, which represent choices a CPL script can make; location modifiers, which add+} or {+remove locations from the+} location [-of an IPv6 :: omitted-zero-bits block is-] {+set; signalling operations, which cause signalling events in the underlying protocol; and non-signalling operations, which trigger behavior which does+} not [-significant for matching purposes.) Host names-] {+effect the underlying protocol. 5 Switches Switches represent choices a CPL script can make, based on either attributes of the original call request or items independent of the call. All switches+} are [-never equal-] {+arranged as a list of conditions that can match a variable. Each condition corresponds+} to [-IP addresses -- no DNS resolution is performed. IPv4 addresses are never equal-] {+a node output; the output points+} to [-IPv6 addresses, even if-] the [-IPv6 address is a v4-in-v6 embedding. For host names only, subdomain matching is supported with-] {+next node to execute if+} the [-"subdomain-of" match operator.-] {+condition was true.+} The [-"subdomain-of" operator ignores leading dots-] {+conditions are tried+} in the [-hostname or-] {+order they are presented in the script; the output corresponding to the first node to+} match [-pattern, if any. This subfield-] is [-not case sensitive, and may be absent. port This subfield indicates-] {+taken. There are two special switch outputs that apply to every switch type. The output "not-present", which MAY occur anywhere in+} the [-TCP or UDP port number-] {+list+} of {+outputs, is true if+} the [-address, numerically-] {+variable the switch was to match was not present+} in [-decimal format. It is not case sensitive, as it MUST only contain decimal digits. Leading zeros are ignored. This subfield may be absent; however, for address types with default ports, an absent port matches the default port number. tel This subfield indicates a telephone subscriber number, if-] the [-address contains such a number. It-] {+original call setup request. (In this document, this+} is [-not case sensitive (the telephone numbers may contain-] {+sometimes described by saying that+} the [-symbols `A' `B' `C' and `D'), and may be absent. It may-] {+information is "absent".) The output "otherwise", which MUST+} be [-matched using-] the [-"subdomain-of" match operator. Punctuation and separator characters in telephone numbers are discarded. display This subfield indicates a "display name" or user-visible name corresponding to an address. It-] {+last output specified if it+} is [-a Unicode string,-] {+present, matches if no other condition matched. If no condition matches+} and [-is matched using the case-insensitive algorithm described-] {+no "otherwise" output was present+} in [-Section 5.2. The "contains" operator may be applied to it. It may be absent. For any completely unknown subfield,-] the [-server MAY reject-] {+script,+} the {+default+} script [-at the time it-] {+behavior+} is [-submitted with an indication of the problem; if a script with-] {+taken. See Section 11 for more information on this. Switches MAY contain no outputs. They MAY contain only+} an [-unknown subfield is executed, the server MUST consider the "not-present" output to be the valid one. The "address" output tag may take exactly one of three possible-] {+"otherwise"+} Lennox/Schulzrinne [Page 10] Internet Draft CPL [-November 21, 2001 parameters, indicating the kind of matching allowed. is An output with this match operator is followed if the subfield being matched in the "address-switch" exactly matches the argument of the operator. It may-] {+January 15, 2002 output. Such switches are not particularly useful, but might+} be [-used for any subfield, or for the entire address if no subfield was specified. subdomain-of This match operator applies only for the subfields "host" and "tel". In the former case, it matches if the hostname being matched is-] {+created by tools which automatically generate CPL scripts. 5.1 Address Switches Address switches allow+} a [-subdomain-] {+CPL script to make decisions based on one+} of the [-domain given-] {+addresses present+} in the [-argument of the match operator; thus, subdomain- of="example.com" would match the hostnames "example.com", "research.example.com", and "zaphod.sales.internal.example.com". IP-] {+original call request. They are summarized in Figure 4. Node: "address-switch" Outputs: "address" Specific+} addresses [-may be given as arguments-] to [-this operator; however, they only-] match [-exactly. In the case of the "tel" subfield, the output matches if the telephone number being matched has a prefix that matches the argument of the-] {+Parameters: "field" "origin", "destination", or "original-destination" "subfield" "address-type", "user", "host", "port", "tel", or "display" (also: "password" and "alias-type") Output: "address" Parameters: "is" exact+} match [-operator; subdomain-of="1212555" would-] {+"contains" substring+} match [-the telephone number "1 212 555 1212." contains This-] {+(for "display" only) "subdomain-of" sub-domain+} match [-operator applies only for the subfield "display". The output matches if the display name being matched contains the argument-] {+(for "host", "tel" only) Figure 4: Syntax+} of the [-match as a substring. 5.1.1 Usage of-] "address-switch" [-with SIP For SIP,-] {+node Address switches have two node parameters: "field", and "subfield". The mandatory "field" parameter allows+} the [-"origin" address corresponds-] {+script+} to [-the-] {+specify which+} address [-in the "From" header; "destination" corresponds-] {+is+} to {+be considered for+} the [-"Request-URI"; and "original-destination" corresponds to-] {+switch: either+} the [-"To" header. The "display" subfield of an-] {+call's origin+} address [-is the display-name part of-] {+(field "origin"), its current destination address (field "destination"), or its original destination (field "original- destination"),+} the [-address, if it is present. Because of SIP's syntax,-] {+destination+} the [-"destination" address-] {+call had before any earlier forwarding was invoked. Servers MAY define additional+} field [-will never have a "display" subfield.-] {+values.+} The [-"address-type" subfield-] {+optional "subfield" specifies what part+} of [-an address is-] the [-URI scheme of that address. Other-] address [-fields depend on that "address-type". For sip URLs, the-] {+is to be considered. The possible subfield values are: "address-type",+} "user", "host", {+"port", "tel",+} and [-"port" subfields correspond to the "user," "host," and "port" elements of the URI syntax. The "tel"-] {+"display". Additional+} subfield [-is defined to-] {+values MAY+} be [-the "user" part of the URI, with visual separators stripped, if and only if the "user=phone" parameter is given to the URI. An additional subfield,-] {+defined for protocol-specific values. (The subfield+} "password" is defined [-to correspond to-] {+for SIP in Section 5.1.1;+} the [-"password" element of-] {+subfield "alias-type" is defined for H.323 in Appendix B.1.) If no subfield is specified,+} the [-SIP URI, and-] {+"entire" address+} is [-case- sensitive. However, use-] {+matched; the precise meaning+} of this [-field-] is [-NOT RECOMMENDED-] {+defined+} for [-general security reasons.-] {+each underlying signalling protocol. Servers MAY define additional subfield values.+} Lennox/Schulzrinne [Page 11] Internet Draft CPL [-November 21, 2001 For tel URLs, the "tel" and "user"-] {+January 15, 2002 The+} subfields are {+defined as follows: address-type This indicates+} the [-subscriber name; in-] {+type of+} the [-former case, visual separators are stripped. The "host" and "port" subfields are both not present. For h323 URLs, subfields MAY be set according to-] {+underlying address; i.e.,+} the [-scheme described in Appendix B. For other-] URI [-schemes, only-] {+scheme, if+} the [-"address-type" subfield is defined-] {+address can be represented by a URI. The types specifically discussed+} by this [-specification; servers MAY set other pre-defined subfields, or MAY support additional subfields. If no subfield-] {+document are "sip", "tel", and "h323". The address type+} is [-specified-] {+not case-sensitive. It has a value+} for [-addresses in SIP messages,-] {+all defined address types. user This subfield of+} the [-string matched is-] {+address indicates, for e-mail style addresses,+} the [-URI-] {+user+} part of the address. For [-"is" matches, standard SIP URI matching rules are used; for "contains" matches,-] {+telephone number style address, it includes+} the [-URI-] {+subscriber number. This subfield+} is [-used verbatim. 5.2 String Switches String switches allow a CPL script-] {+case-sensitive; it may be absent. host This subfield of the address indicates the Internet host name or IP address corresponding+} to [-make decisions based on free- form strings present-] {+the address,+} in [-a call request. They-] {+host name, IPv4, or IPv6 [9] textual representation format. Host names+} are [-summarized in Figure 5. Node: "string-switch" Outputs: "string" Specific string to match Parameters: "field" "subject", "organization", "user-agent",-] {+compared as strings. IP addresses are compared numerically. (In particular, the presence+} or [-"display" Output: "string" Parameters: "is" exact match "contains" substring match Figure 5: Syntax-] {+location+} of [-the "string-switch" node String switches have one node parameter: "field". The mandatory "field" parameter specifies which string-] {+an IPv6 :: omitted-zero-bits block+} is [-to be matched. String switches-] {+not significant for matching purposes.) Host names+} are [-dependent on the call signalling protocol being used. Five fields-] {+never equal to IP addresses -- no DNS resolution is performed. IPv4 addresses+} are [-defined, listed below. The value of each of these fields, except as specified,-] {+never equal to IPv6 addresses, even if the IPv6 address+} is a [-free-form Unicode string-] {+v4-in-v6 embedding. For host names only, subdomain matching is supported+} with [-no other structure defined. "subject" The subject of-] the [-call. Lennox/Schulzrinne [Page 12] Internet Draft CPL November 21, 2001 "organization"-] {+"subdomain-of" match operator.+} The [-organization of the originator of-] {+"subdomain-of" operator ignores leading dots in+} the [-call. "user-agent" The name of-] {+hostname or match pattern, if any. This subfield is not case sensitive, and may be absent. port This subfield indicates+} the [-program-] {+TCP+} or [-device with which-] {+UDP port number of+} the [-call request was made. "display" Free-form text associated-] {+address, numerically in decimal format. It is not case sensitive, as it MUST only contain decimal digits. Leading zeros are ignored. This subfield may be absent; however, for address types+} with {+default ports, an absent port matches+} the [-call, intended to be displayed to-] {+default port number. tel This subfield indicates a telephone subscriber number, if+} the [-recipient, with no other semantics defined by-] {+address contains such a number. It is not case sensitive (the telephone numbers may contain+} the [-signalling protocol. Strings are-] {+symbols `A' `B' `C' and `D'), and may be absent. It may be+} matched [-as case-insensitive Unicode strings, in the following manner. First, strings are canonicalized to-] {+using+} the [-"Compatibility Composition" (KC) form, as specified-] {+"subdomain-of" match operator. Punctuation and separator characters+} in [-Unicode Technical Report 15 [10]. Then, strings-] {+telephone numbers+} are [-compared using locale- insensitive caseless mapping, as specified in Unicode Technical Report 21 [11]. Code-] {+discarded. display This subfield indicates a "display name" or user-visible name corresponding+} to [-perform the first step, in Java-] {+an address. It is a Unicode string,+} and [-Perl,-] is [-available; see-] {+matched using+} the [-links from Annex E of UTR 15 [10]. The-] case-insensitive [-string comparison-] {+algorithm Lennox/Schulzrinne [Page 12] Internet Draft CPL January 15, 2002 described+} in [-the Java standard class libraries already performs the second step; other Unicode-aware libraries should be similar.-] {+Section 5.2.+} The [-output tags of string matching are named "string", and have a mandatory argument, one of "is" or "contains", indicating whole- string match or substring match, respectively. 5.2.1 Usage of "string-switch" with SIP For SIP, the fields "subject", "organization", and "user-agent" correspond-] {+"contains" operator may be applied+} to {+it. It may be absent. For any completely unknown subfield,+} the [-SIP header fields with-] {+server MAY reject+} the [-same name. These are used verbatim as they appear in-] {+script at+} the [-message. The field "display" is not used, and-] {+time it+} is [-never present. 5.3 Language Switches Language switches allow-] {+submitted with an indication of the problem; if+} a [-CPL-] script [-to make decisions based on the languages in which-] {+with an unknown subfield is executed,+} the [-originator of-] {+server MUST consider+} the [-call wishes-] {+"not-present" output+} to [-communicate. They are summarized in Figure 6. Language switches take no parameters.-] {+be the valid one.+} The [-"language" outputs-] {+"address" output tag may+} take {+exactly+} one [-parameter, "matches". The value-] of [-one-] {+three possible parameters, indicating the kind+} of [-these parameters-] {+matching allowed.+} is [-a language-tag, as defined-] {+An output with this match operator is followed if the subfield being matched+} in [-RFC 3066 [12]. The caller may have specified a set-] {+the "address-switch" exactly matches the argument+} of [-language-ranges, also as defined in RFC 3066. The CPL server checks each language-tag Lennox/Schulzrinne [Page 13] Internet Draft CPL November 21, 2001 Node: "language-switch" Outputs: "language" Specific string to match Parameters: None Output: "language" Parameters: "matches" Match-] {+the operator. It may be used for any subfield, or for the entire address+} if {+no subfield was specified. subdomain-of This match operator applies only for+} the [-given language-] {+subfields "host" and "tel". In the former case, it+} matches {+if the hostname being matched is+} a [-language-range-] {+subdomain+} of the [-call. Figure 6: Syntax-] {+domain given in the argument+} of the [-"language-switch" node specified by-] {+match operator; thus, subdomain- of="example.com" would match+} the [-script against-] {+hostnames "example.com", "research.example.com", and "zaphod.sales.internal.example.com". IP addresses may be given as arguments to this operator; however, they only match exactly. In+} the [-language-ranges specified in-] {+case of+} the [-request. See RFC 3066 for-] {+"tel" subfield,+} the [-details of how language-ranges match language- tags. Briefly, a language-range-] {+output+} matches [-a language-tag-] if [-it exactly equals-] the [-tag, or if it exactly equals-] {+telephone number being matched has+} a prefix {+that matches the argument+} of the [-tag such that-] {+match operator; subdomain-of="1212555" would match+} the [-first character following-] {+telephone number "1 212 555 1212." contains This match operator applies only for+} the [-prefix is "-".-] {+subfield "display".+} The [-special language-range "*" is ignored for-] {+output matches if+} the [-purpose-] {+display name being matched contains the argument+} of [-matching. Languages with-] {+the match as+} a [-"q" value-] {+substring. 5.1.1 Usage+} of [-0 are also ignored. This switch MAY be not-present. 5.3.1 Usage of "language-switch"-] {+"address-switch"+} with SIP [-The language-ranges for the "language-switch" switch are obtained from-] {+For SIP,+} the [-SIP "Accept-Language" header field. The switch is not- present if-] {+"origin" address corresponds to+} the [-initial SIP request did not contain this header field. Note that because of CPL's first-match semantics-] {+address+} in [-switches, "q" values other than 0 of-] the [-"Accept-Language" header fields are ignored. 5.4 Time Switches Time switches allow a CPL script-] {+"From" header; "destination" corresponds+} to [-make decisions based on-] the [-time and/or date-] {+"Request-URI"; and "original-destination" corresponds to+} the [-script is being executed. They are summarized in Figure 7. Time switches are independent-] {+"To" header. The "display" subfield+} of {+an address is+} the [-underlying signalling protocol. Time switches are based closely on-] {+display-name part of+} the [-specification-] {+address, if it is present. Because+} of [-recurring intervals-] {+SIP's syntax, the "destination" address field will never have a "display" subfield. The "address-type" subfield+} of [-time in-] {+an address is+} the [-Internet Calendaring and Scheduling Core-] {+URI scheme of that address. Other address fields depend on that "address-type".+} Lennox/Schulzrinne [Page [-14]-] {+13]+} Internet Draft CPL [-November 21, 2001 Node: "time-switch" Outputs: "time" Specific time-] {+January 15, 2002 For sip URLs, the "user", "host", and "port" subfields correspond+} to [-match Parameters: "tzid" RFC 2445 Time Zone Identifier "tzurl" RFC 2445 Time Zone URL Output: "time" Parameters: "dtstart" Start of interval (RFC 2445 DATE-TIME) "dtend" End of interval (RFC 2445 DATE-TIME) "duration" Length of interval (RFC 2445 DURATION) "freq" Frequency of recurrence (one of "secondly", "minutely", "hourly", "daily", "weekly", "monthly", or "yearly") "interval" How often-] the [-recurrence repeats "until" Bound of recurrence (RFC 2445 DATE-TIME) "count" Number of occurences of recurrence "bysecond" List of seconds within a minute "byminute" List of minutes within an hour "byhour" List of hours-] {+"user," "host," and "port" elements+} of the [-day "byday" List of days of-] {+URI syntax. The "tel" subfield is defined to be+} the [-week "bymonthday" List of days-] {+"user" part+} of the [-month "byyearday" List of days of-] {+URI, with visual separators stripped, if and only if+} the [-year "byweekno" List of weeks of-] {+"user=phone" parameter is given to+} the [-year "bymonth" List of months of-] {+URI. An additional subfield, "password" is defined to correspond to+} the [-year "wkst" First day-] {+"password" element+} of the [-workweek "bysetpos" List of values within set of events specified Figure 7: Syntax-] {+SIP URI, and is case- sensitive. However, use+} of {+this field is NOT RECOMMENDED for general security reasons. For tel URLs,+} the [-"time-switch" node Object Specification (iCalendar COS), RFC 2445 [13]. This allows CPLs to be generated automatically from calendar books. It also allows us to re-use the extensive existing work specifying time intervals. If future standards-track documents-] {+"tel" and "user" subfields+} are [-published that obsolete RFC 2445, any changes or clarifications those documents make to recurrence handling apply to CPL time-switches as well. An algorithm to whether an instant falls within a given recurrence is given-] {+the subscriber name;+} in [-Appendix A.-] {+the former case, visual separators are stripped.+} The [-"time-switch" tag takes two optional parameters, "tzid"-] {+"host"+} and [-"tzurl", both of which-] {+"port" subfields+} are [-defined in RFC 2445 (Sections 4.8.3.1 and 4.8.3.5 respectively). The TZID is-] {+both not present. For h323 URLs, subfields MAY be set according to+} the [-identifying label by which a Lennox/Schulzrinne [Page 15] Internet Draft CPL November 21, 2001 time zone definition-] {+scheme described in Appendix B. For other URI schemes, only the "address-type" subfield+} is [-referenced.-] {+defined by this specification; servers MAY set other pre-defined subfields, or MAY support additional subfields.+} If [-it begins with a forward slash (solidus), it references a to-be-defined global time zone registry; otherwise it-] {+no subfield+} is [-locally-defined at the server. The TZURL gives a network location from which an up-to-date VTIMEZONE definition-] {+specified+} for {+addresses in SIP messages,+} the [-timezone can be retrieved. While TZID labels that do not begin with a forward slash are locally defined, it-] {+string matched+} is [-RECOMMENDED that servers support at least-] the [-naming scheme used by Olson Time Zone database [14]. Examples-] {+URI part+} of [-timezone databases that use the Olson scheme are the zoneinfo files on most Unix-like systems, and-] the {+address. For "is" matches,+} standard [-Java TimeZone class. Servers SHOULD resolve TZID and TZURL references to time zone definitions at the time the script is uploaded. They MAY periodically refresh these resolutions to obtain the most up-to-date definition of a time zone. If a TZURL becomes invalid, servers SHOULD remember the most recent valid data retrieved from-] {+SIP URI matching rules are used; for "contains" matches,+} the [-URL. If a script-] {+URI+} is [-uploaded with-] {+used verbatim. 5.2 String Switches String switches allow+} a [-"tzid" and "tzurl" which the-] CPL [-server does not recognize or cannot resolve, it SHOULD diagnose and reject this at-] script [-upload time. If neither "tzid" nor "tzurl"-] {+to make decisions based on free- form strings present in a call request. They+} are [-present, all non-UTC times within this time switch should be interpreted as being "floating" times, i.e. that they are specified-] {+summarized+} in [-the local timezone of the CPL server. Because-] {+Figure 5. Node: "string-switch" Outputs: "string" Specific string to match Parameters: "field" "subject", "organization", "user-agent", or "display" Output: "string" Parameters: "is" exact match "contains" substring match Figure 5: Syntax+} of [-daylight-savings-time changes over-] the [-course of a year, it-] {+"string-switch" node String switches have one node parameter: "field". The mandatory "field" parameter specifies which string+} is [-necessary-] to [-specify time-] {+be matched. Lennox/Schulzrinne [Page 14] Internet Draft CPL January 15, 2002 String+} switches [-in a given timezone. UTC offsets-] are [-not sufficient, or a time-of-day routing rule which held between 9 am and 5 pm in the eastern United States would start holding between 8 am and 4 pm at the end of October. Authors of CPL servers should be careful to handle correctly the intervals when local time is discontinuous, at-] {+dependent on+} the [-beginning or end of daylight-savings time. Note especially that some times may occur more than once when clocks-] {+call signalling protocol being used. Five fields+} are [-set back.-] {+defined, listed below.+} The [-algorithm in Appendix A-] {+value of each of these fields, except as specified,+} is [-believed to handle this correctly. Time nodes specify-] a [-list-] {+free-form Unicode string with no other structure defined. "subject" The subject+} of [-periods during which their output should be taken. They have two required parameters: "dtstart", which specifies-] the [-beginning-] {+call. "organization" The organization+} of the [-first period-] {+originator+} of the [-list, and exactly one-] {+call. "user-agent" The name+} of [-"dtend"-] {+the program+} or [-"duration",-] {+device with+} which [-specify-] the [-ending time or-] {+call request was made. "display" Free-form text associated with+} the [-duration of-] {+call, intended to be displayed to+} the [-period, respectively. The "dtstart" and "dtend" parameters-] {+recipient, with no other semantics defined by the signalling protocol. Strings+} are [-formatted as iCalendar COS DATE-TIME values,-] {+matched+} as [-specified-] {+case-insensitive Unicode strings,+} in [-Section 4.3.5 of RFC 2445 [13]. Because time zones-] {+the following manner. First, strings+} are [-specified in-] {+canonicalized to+} the [-top-level "time-switch" tag, only forms 1 or 2 (floating or UTC times) can be used. The "duration" parameter is Lennox/Schulzrinne [Page 16] Internet Draft CPL November 21, 2001 given-] {+"Compatibility Composition" (KC) form,+} as [-an iCalendar COS DURATION parameter,-] {+specified in Unicode Technical Report 15 [10]. Then, strings are compared using locale- insensitive caseless mapping,+} as specified in [-section 4.3.6 of RFC 2445. Both-] {+Unicode Technical Report 21 [11]. Code to perform+} the [-DATE-TIME-] {+first step, in Java+} and {+Perl, is available; see+} the [-DURATION syntaxes are subsets-] {+links from Annex E+} of {+UTR 15 [10]. The case-insensitive string comparison in+} the [-corresponding syntaxes from ISO 8601 [15]. For a recurring interval,-] {+Java standard class libraries already performs+} the [-"duration" parameter MUST-] {+second step; other Unicode-aware libraries should+} be [-small enough such that subsequent intervals do not overlap. For non-recurring intervals, durations-] {+similar. The output tags+} of [-any positive length-] {+string matching+} are [-permitted. Zero-length-] {+named "string",+} and [-negative-length durations are not allowed. If no other parameters are specified, a time node indicates only-] {+have+} a [-single period-] {+mandatory argument, one+} of [-time. More complicated sets periods intervals are constructed as recurrences. A recurrence is specified by including the "freq" parameter, which indicates the type-] {+"is" or "contains", indicating whole- string match or substring match, respectively. 5.2.1 Usage+} of [-recurrence rule. No parameters other than "dtstart", "dtend", and "duration" SHOULD be specified unless "freq" is present, though CPL servers SHOULD accept scripts-] {+"string-switch"+} with [-such parameters present,-] {+SIP For SIP, the fields "subject", "organization",+} and [-ignore-] {+"user-agent" correspond to+} the [-other parameters. The "freq" parameter takes one of-] {+SIP header fields with+} the [-following values: "secondly", to specify repeating periods based on an interval of-] {+same name. These are used verbatim as they appear in the message. The field "display" is not used, and is never present. 5.3 Language Switches Language switches allow+} a [-second or more; "minutely",-] {+CPL script+} to [-specify repeating periods-] {+make decisions+} based on [-an interval-] {+the languages in which the originator+} of [-a minute or more; "hourly",-] {+the call wishes+} to [-specify repeating periods based on an interval of an hour or more; "daily",-] {+communicate. Lennox/Schulzrinne [Page 15] Internet Draft CPL January 15, 2002 They are summarized in Figure 6. Node: "language-switch" Outputs: "language" Specific string+} to [-specify repeating periods based on an interval of-] {+match Parameters: None Output: "language" Parameters: "matches" Match if the given language matches+} a [-day or more; "weekly", to specify repeating periods based on an interval-] {+language-range+} of [-a week or more; "monthly", to specify repeating periods based on an interval-] {+the call. Figure 6: Syntax+} of [-a month or more; and "yearly", to specify repeating periods based on an interval-] {+the "language-switch" node Language switches take no parameters. The "language" outputs take one parameter, "matches". The value+} of {+one of these parameters is+} a [-year or more. These values are not case-sensitive.-] {+language-tag, as defined in RFC 3066 [12].+} The [-"interval" parameter contains-] {+caller may have specified+} a [-positive integer representing how often the recurrence rule repeats.-] {+set of language-ranges, also as defined in RFC 3066.+} The [-default value is "1", meaning every day for a "daily" rule, every week for a "weekly" rule, every month-] {+CPL server checks each language-tag specified by the script against the language-ranges specified in the request. See RFC 3066+} for {+the details of how language-ranges match language- tags. Briefly,+} a [-"monthly" rule and every year for-] {+language-range matches+} a [-"yearly" rule. The "until" parameter defines an iCalendar COS DATE-] {+language-tag if it exactly equals the tag,+} or [-DATE-TIME value which bounds-] {+if it exactly equals a prefix of+} the [-recurrence rule in an inclusive manner. If-] {+tag such that+} the [-value specified by "until"-] {+first character following the prefix+} is [-synchronized with-] {+"-". If+} the {+caller+} specified [-recurrence, this date or date-time becomes the last instance of-] the [-recurrence. If specified as a date-time value, then-] {+special language-range "*",+} it [-MUST be specified in an UTC time format. If not present, and the "count" parameter-] is [-not also present,-] {+ignored for+} the [-recurrence is considered to repeat forever.-] {+purpose of matching. Languages with a "q" value of 0 are also ignored. This switch MAY be not-present. 5.3.1 Usage of "language-switch" with SIP+} The [-"count" parameter defines-] {+language-ranges for+} the [-number of occurrences at which to range-bound-] {+"language-switch" switch are obtained from+} the [-recurrence.-] {+SIP "Accept-Language" header field.+} The [-"dtstart" parameter counts as-] {+switch is not- present if+} the [-Lennox/Schulzrinne [Page 17] Internet Draft CPL November 21, 2001 first occurrence. The "until" and "count" parameters MUST NOT occur-] {+initial SIP request did not contain this header field. Note that because of CPL's first-match semantics+} in {+switches, "q" values other than 0 of+} the [-same-] {+"Accept-Language" header fields are ignored. 5.4 Time Switches Lennox/Schulzrinne [Page 16] Internet Draft CPL January 15, 2002 Time switches allow a CPL script to make decisions based on the time and/or date the script is being executed. They are summarized in Figure 7. Time switches are independent of the underlying signalling protocol. Node: "time-switch" Outputs:+} "time" [-output. The-] {+Specific time to match Parameters: "tzid" RFC 2445 Time Zone Identifier "tzurl" RFC 2445 Time Zone URL Output: "time" Parameters: "dtstart" Start of interval (RFC 2445 DATE-TIME) "dtend" End of interval (RFC 2445 DATE-TIME) "duration" Length of interval (RFC 2445 DURATION) "freq" Frequency of recurrence (one of "secondly", "minutely", "hourly", "daily", "weekly", "monthly", or "yearly") "interval" How often the recurrence repeats "until" Bound of recurrence (RFC 2445 DATE-TIME) "count" Number of occurrences of recurrence+} "bysecond" [-parameter specifies a comma-separated list-] {+List+} of seconds within a [-minute. Valid values are 0 to 59. The-] {+minute+} "byminute" [-parameter specifies a comma-separated list-] {+List+} of minutes within an [-hour. Valid values are 0 to 59. The-] {+hour+} "byhour" [-parameter specifies a comma- separated list-] {+List+} of hours of the [-day. Valid values are 0 to 23. The-] {+day+} "byday" [-parameter specifies a comma-separated list-] {+List+} of days of the [-week. "MO" indicates Monday; "TU" indicates Tuesday; "WE" indicates Wednesday; "TH" indicates Thursday; "FR" indicates Friday; "SA" indicates Saturday; "SU" indicates Sunday. These values are not case-sensitive. Each "byday" value can also be preceded by a positive (+n) or negative (-n) integer. If present, this indicates the nth occurrence of the specific day within the "monthly" or "yearly" recurrence. For example, within a "monthly" rule, +1MO (or simply 1MO) represents the first Monday within the month, whereas -1MO represents the last Monday of the month. If an integer modifier is not present, it means all days of this type within the specified frequency. For example, within a "monthly" rule, MO represents all Mondays within the month. The-] {+week+} "bymonthday" [-parameter specifies a comma-separated list-] {+List+} of days of the [-month. Valid values are 1 to 31 or -31 to -1. For example, -10 represents the tenth to the last day of the month. The-] {+month+} "byyearday" [-parameter specifies a comma-separated list-] {+List+} of days of the [-year. Valid values are 1 to 366 or -366 to -1. For example, -1 represents the last day-] {+year "byweekno" List of weeks+} of the year [-(December 31st) and -306 represents the 306th to-] {+"bymonth" List of months of+} the [-last-] {+year "wkst" First+} day of the [-year (March 1st). The "byweekno" parameter specifies a comma-separated list-] {+work week "bysetpos" List+} of [-ordinals specifying weeks-] {+values within set of events specified Figure 7: Syntax+} of the [-year. Valid values-] {+"time-switch" node Time switches+} are [-1 to 53 or -53 to -1. This corresponds to weeks according to week numbering as defined in ISO 8601 [15]. A week is defined as a seven day period, starting-] {+based closely+} on the [-day-] {+specification of recurring intervals+} of {+time in+} the [-week defined-] {+Internet Calendaring and Scheduling Core Object Specification (iCalendar COS), RFC 2445 [13]. This allows CPL scripts+} to be {+generated automatically from calendar books. It also allows us to re-use+} the [-week start (see "wkst"). Week number one of the calendar year is the first week which contains at least four (4) days in-] {+extensive existing work specifying time intervals. If future standards-track documents are published+} that [-calendar year. This parameter is only valid for "yearly" rules. For example, 3 represents the third week of the year. Note: Assuming a Monday week start, week 53 can only occur when Thursday is January 1-] {+update+} or [-if it is a leap year and Wednesday is January 1.-] Lennox/Schulzrinne [Page [-18]-] {+17]+} Internet Draft CPL [-November 21, 2001 The "bymonth" parameter specifies a comma-separated list of months of the year. Valid values are 1-] {+January 15, 2002 obsolete RFC 2445, any changes or clarifications those documents make+} to [-12.-] {+recurrence handling apply to CPL time-switches as well. An algorithm to whether an instant falls within a given recurrence is given in Appendix A.+} The [-"wkst" parameter specifies the day on-] {+"time-switch" tag takes two optional parameters, "tzid" and "tzurl", both of+} which [-the workweek starts. Valid values-] are [-"MO", "TU", "WE", "TH", "FR", "SA"-] {+defined in RFC 2445 (Sections 4.8.3.1+} and [-"SU". This-] {+4.8.3.5 respectively). The TZID+} is [-significant when a "weekly" recurrence has an interval greater than 1, and-] {+the identifying label by which+} a [-"byday" parameter is specified. This-] {+time zone definition+} is [-also significant in-] {+referenced. If it begins with+} a [-"yearly" recurrence when-] {+forward slash (solidus), it references+} a [-"byweekno" parameter is specified. The default value-] {+to-be-defined global time zone registry; otherwise it+} is [-"MO", following ISO 8601 [15].-] {+locally-defined at the server.+} The [-"bysetpos" parameter specifies-] {+TZURL gives+} a [-comma-separated list of values-] {+network location from+} which [-corresponds to the nth occurrence within the set of events specified by-] {+an up-to-date VTIMEZONE definition for+} the [-rule. Valid values are 1 to 366 or -366 to -1. It MUST only-] {+timezone can+} be [-used in conjunction-] {+retrieved. While TZID labels that do not begin+} with [-another byxxx parameter. For example "the last work day of the month" could be represented as: