CPL: A Language for User Control of Internet Telephony Services

Transcription

1 Internet Engineering Task Force INTERNET-DRAFT draft-ietf-iptel-cpl-07.ps IPTEL WG Lennox/Wu/Schulzrinne Columbia University August 1, 2003 Expires: February, 2004 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 To view the list Internet-Draft Shadow Directories, see Copyright Notice Copyright (c) The Internet Society (2003). All Rights Reserved. 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@ietf.org and/or the authors. Contents 1 Introduction Conventions of This Document Structure of CPL Scripts High-level Structure Abstract Structure of a Call Processing Action Location Model XML Structure Script Structure: Overview 7 4 Switches Address Switches Usage of address-switch with SIP String Switches

2 4.2.1 Usage of string-switch with SIP Language Switches Usage of language-switch with SIP Time Switches icalendar differences and implementation issues Priority Switches Usage of priority-switch with SIP Location Modifiers Explicit Location Usage of location with SIP Location Lookup Usage of lookup with SIP Location Removal Usage of remove-location with SIP Signalling Operations Proxy Usage of proxy with SIP Redirect Usage of redirect with SIP Reject Usage of reject with SIP Non-signalling Operations Mail Suggested Content of Mailed Information Log Subactions 25 9 Ancillary Information Default Behavior CPL Extensions Examples Example: Call Redirect Unconditional Example: Call Forward Busy/No Answer Example: Call Forward: Redirect and Default Example: Call Screening Example: Priority and Language Routing Example: Outgoing Call Screening Example: Time-of-day Routing Example: Location Filtering Lennox/Wu/Schulzrinne Expires February, 2004 [Page 2]

3 12.9 Example: Non-signalling Operations Example: Hypothetical Extensions Example: A Complex Example Security Considerations IANA Considerations URN Sub-Namespace Registration for urn:ietf:params:xml:ns:cpl MIME Registration Acknowledgments 38 A An Algorithm for Resolving Time Switches 39 B Suggested Usage of CPL with H B.1 Usage of address-switch with H B.2 Usage of string-switch with H B.3 Usage of language-switch with H B.4 Usage of priority-switch with H B.5 Usage of location with H B.6 Usage of lookup with H B.7 Usage of remove-location with H C The XML Schema for CPL 43 D Changes from Earlier Versions 54 D.1 Changes from Draft D.2 Changes from Draft D.3 Changes from Draft D.4 Changes from Draft D.5 Changes from Draft D.6 Changes from Draft D.7 Changes from Draft E Authors Addresses 59 1 Introduction The Call Processing 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 with both the Session Initiation Protocol (SIP) [1] and H.323 [16]. CPL is powerful enough to describe a large number 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. Lennox/Wu/Schulzrinne Expires February, 2004 [Page 3]

4 CPL is also designed to be easily created and edited by graphical tools. It is based on the Extensible Markup Language (XML) [2], so parsing it is easy and many parsers for it are publicly available. The structure 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 of 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 [17]. 1.1 Conventions 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 [3] and indicate requirement levels for compliant CPL implementations. Some paragraphs are indented, like this; they give motivations of design choices, advice to implementors, or thoughts on future development of or extensions to CPL. They are not essential to the specification of the language, and are non-normative. 2 Structure of CPL Scripts 2.1 High-level Structure A CPL script consists of two types of information: ancillary information about the script, and call processing actions. A call processing action is a structured tree that describes the operations and decisions a telephony signalling server performs on a call set-up event. There are two types 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 actions are defined: incoming, the action performed when a call arrives whose destination is the owner of the script; and outgoing, the action performed when a call arrives whose originator is the owner of the script. Subactions are actions which can be called from other actions. CPL forbids subactions from being called recursively: see Section 8. Ancillary information is 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 extensions. 2.2 Abstract Structure of a Call Processing Action Abstractly, a call processing action is described by a collection of nodes, which describe operations that can be performed or decisions that 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 of informally as boxes and arrows; CPL is designed so that actions can be conveniently edited graphically using this representation. Nodes are arranged in a tree, starting at a single root node; outputs of nodes are Lennox/Wu/Schulzrinne Expires February, 2004 [Page 4]

5 connected to additional nodes. When an action is run, the action or decision described by the action s toplevel node is performed; based on the result of that node, the server follows one of the node s outputs, and the subsequent node 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 and predictable number of nodes are visited. If an output to a node does not point to another node, it indicates that the CPL server should perform a node- or protocol-specific action. Some nodes have specific default behavior associated with them; for others, the default behavior is implicit in the underlying signalling protocol, or can be configured by the administrator of the server. For further details on this, see Section 10. Call Address switch field: from subfield: host subdomain of: example.com otherwise location url: sip:jones@ example.com Voic location url: sip:jones@ voic . example.com proxy timeout: 10s redirect busy timeout failure Figure 1: Sample CPL Action: Graphical Version 2.3 Location Model For flexibility, one piece of information necessary for CPL is not given as node parameters: the set of locations to which a call is to be directed. Instead, this set of locations is stored as an implicit global variable throughout the execution of a 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 and tractability of understanding the language). The specific operations which add, retrieve, or filter location sets are given in Section 5. For the incoming top-level call processing action, the location set is initialized to the empty set. For the outgoing action, it is initialized to the destination address of the call. 2.4 XML Structure Syntactically, CPL scripts are represented by XML documents. XML is thoroughly specified by the XML specification [2], and implementors of this specification should be familiar with that document, but as a brief overview, XML consists of a hierarchical structure of tags; each tag can have a number of attributes. It is Lennox/Wu/Schulzrinne Expires February, 2004 [Page 5]

6 <?xml version="1.0" encoding="utf-8"?> <cpl xmlns="urn:ietf:params:xml:ns:cpl" xmlns:xsi=" xsi:schemalocation="urn:ietf:params:xml:ns:cpl cpl.xsd "> <subaction id="voic "> <location <redirect /> </location> </subaction> <incoming> <address-switch field="origin" subfield="host"> <address subdomain-of="example.com"> <location <proxy timeout="10"> <busy> <sub ref="voic " /> </busy> <noanswer> <sub ref="voic " /> </noanswer> <failure> <sub ref="voic " /> </failure> </proxy> </location> </address> <otherwise> <sub ref="voic " /> </otherwise> </address-switch> </incoming> </cpl> Figure 2: Sample CPL Script: XML Version visually and structurally very similar to HTML [18], as both languages are simplifications of the earlier and larger standard SGML [19]. See Figure 2 for the XML document corresponding to the graphical representation of the CPL script in Figure 1. Both nodes and outputs in CPL are represented by XML tags; parameters are represented by XML tag attributes. Typically, node tags contain output tags, and vice-versa (with a few exceptions: see Sections 5.1, 5.3, 7.1, and 7.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 in Section 8. The higher-level structure of a CPL script is represented by tags corresponding to each piece of ancillary information, subactions, and top-level actions, in order. This higher-level information is all enclosed in a special tag cpl, the outermost tag of the XML document. A complete XML Schema for CPL is provided in Appendix C. The remainder of the main sections of this document describe the semantics of CPL, while giving its syntax informally. For the formal syntax, please see the appendix. Lennox/Wu/Schulzrinne Expires February, 2004 [Page 6]

7 3 Script Structure: Overview As mentioned, a CPL script consists of ancillary information, subactions, and top-level actions. The full syntax of the cpl node is given in Figure 3. Tag: cpl Parameters: None Sub-tags: ancillary See Section 9 subaction See Section 8 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 top-level cpl tag Call processing actions, both top-level actions and sub-actions, consist of a tree of nodes and outputs. Nodes and outputs are both described by XML tags. There are four categories of CPL nodes: switches, which represent choices 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 nonsignalling operations, which trigger behavior which does not effect the underlying protocol. 4 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 arranged 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 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 the switch was to match was not present in the original call setup request. (In this document, this is sometimes described by saying that the information is absent.) The output otherwise, which MUST be the last output specified if it is present, matches if no other condition matched. If no condition matches and no otherwise output was present in the script, the default script behavior is taken. See Section 10 for more information on this. Switches MAY contain no outputs. They MAY contain only an otherwise output. Such switches are not particularly useful, but might be created by tools which automatically generate CPL scripts. 4.1 Address Switches Address switches allow a CPL script to make decisions based on one of the addresses present in the original call request. They are summarized in Figure 4. Lennox/Wu/Schulzrinne Expires February, 2004 [Page 7]

8 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 and alias-type) Output: address Parameters: is Exact match contains Substring match (for display only) subdomain-of Sub-domain match (for host, tel) Figure 4: Syntax of the address-switch node Address switches have two node parameters: field, and subfield. The mandatory field parameter allows the script to specify which address is to be considered for the switch: either the call s origin address (field origin), its current destination address (field destination), or its original destination (field originaldestination), 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 address is to be considered. 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 4.1.1; the subfield aliastype is defined for H.323 in Appendix B.1.) If no subfield is specified, the entire address is matched; the precise meaning of this is defined for each underlying signalling protocol. Servers MAY define additional subfield values. The subfields are defined as follows: address-type This indicates the type 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 is not case-sensitive. It has a value for all defined address types. user This subfield of the address indicates, for style addresses, the user part 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 of the address indicates the Internet host name or IP address corresponding to the address, in host name, IPv4, or IPv6 [4] textual representation format. Host names are compared as strings. IP addresses are compared numerically. (In particular, the presence or location of an IPv6 :: omittedzero-bits block is not significant for matching purposes.) Host names are never equal to IP addresses no DNS resolution is performed. IPv4 addresses are never equal to IPv6 addresses, even if the IPv6 address is a v4-in-v6 embedding. This subfield is not case sensitive, and may be absent. For host names only, subdomain matching is supported with the subdomain-of match operator. The subdomain-of operator ignores leading dots in the hostname or match pattern, if any. Lennox/Wu/Schulzrinne Expires February, 2004 [Page 8]

9 port This subfield indicates the TCP or UDP port number of the address, numerically in decimal format. It is not case sensitive, as it MUST only contain decimal digits. Leading zeros are ignored. tel This subfield indicates a telephone subscriber number, if the address contains such a number. It is not case sensitive (the telephone numbers may contain the symbols A B C and D ), and may be absent. It may 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 is a Unicode string, and is matched using the case-insensitive algorithm described in Section 4.2. The contains operator may be applied to it. It may be absent. For any completely unknown subfield, the server MAY reject the script at the time it is submitted with an indication of the problem; if a script with 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 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 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 a subdomain of the domain given 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 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 match operator; subdomain-of=" " would match the telephone number contains This match operator applies only for the subfield display. The output matches if the display name being matched contains the argument of the match as a substring Usage of address-switch with SIP For SIP, the origin address corresponds to the address in the From header; destination corresponds to the Request-URI; and original-destination corresponds to the To header. The display subfield of an address is the display-name part of the address, if it is present. Because of SIP s syntax, the destination address field will never have a display subfield. The address-type subfield of an address is the URI scheme of that address. Other address fields depend on that address-type. For SIP URIs, the user, host, and port subfields correspond to the user, host, and port elements of the URI syntax. (Note that, following the definitions of RFC 3261 [1], a SIP URI which does not specify a port is not the same as an explicit port 5060; the former is indicated by an absent port subfield.) The tel subfield is defined to be the user part of the URI, with visual separators stripped, if the user=phone parameter is given to the URI, or if the server is otherwise configured to recognize the user part as a telephone Lennox/Wu/Schulzrinne Expires February, 2004 [Page 9]

10 number. An additional subfield, password is defined to correspond to the password element of the SIP URI, and is case-sensitive. However, use of this field is NOT RECOMMENDED for general security reasons. For tel URLs, the tel and user subfields are the subscriber name; in 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 the scheme described in Appendix B. For other URI schemes, only the address-type subfield is defined by this specification; servers MAY set other pre-defined subfields, or MAY support additional subfields. If no subfield is specified for addresses in SIP messages, the string matched is the URI part of the address. For is matches, standard SIP URI matching rules are used; for contains matches, the URI is used verbatim. 4.2 String Switches String switches allow a CPL script to make decisions based on free-form strings present in a call request. They are summarized in 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 the string-switch node String switches have one node parameter: field. The mandatory field parameter specifies which string is to be matched. String switches are dependent on the call signalling protocol being used. Five fields are defined, listed below. The value of each of these fields, except as specified, is a free-form Unicode string with no other structure defined. subject The subject of the call. organization The organization of the originator of the call. user-agent The name of the program or device with which the call request was made. display Free-form text associated with the call, intended to be displayed to the recipient, with no other semantics defined by the signalling protocol. Strings are matched as case-insensitive Unicode strings, in the following manner. First, strings are canonicalized to the Compatibility Composition (KC) form, as specified in Unicode Technical Report 15 [5]. Then, strings are compared using locale-insensitive caseless mapping, as specified in Unicode Technical Report 21 [6]. Lennox/Wu/Schulzrinne Expires February, 2004 [Page 10]

11 Code to perform the first step, in Java and Perl, is available; see the links from Annex E of UTR 15 [5]. The caseinsensitive string comparison in the Java standard class libraries already performs the second step; other Unicodeaware libraries should be similar. The output tag of string matching is named string, and has a mandatory argument, one of is or contains, indicating whole-string match or substring match, respectively Usage of string-switch with SIP For SIP, the fields subject, organization, and user-agent correspond to the SIP header fields with the same name. These are used verbatim as they appear in the message. The field display is not used, and is never present. 4.3 Language Switches Language switches allow a CPL script to make decisions based on the languages in which the originator of the call wishes to communicate. They are summarized in Figure 6. Node: language-switch Outputs: language Specific string to match Parameters: None Output: language Parameters: matches Match if the given language matches a language-range of the call. Figure 6: Syntax of the language-switch node Language switches take no parameters. The language output takes one parameter, matches. The value of the parameter is a language-tag, as defined in RFC 3066 [7]. The caller may have specified a set of language-ranges, also as defined in RFC The 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 language-range matches a language-tag if it exactly equals the tag, or if it exactly equals a prefix of the tag such that the first character following the prefix is -. If the caller specified the special language-range *, it is ignored for the purpose of matching. Languages with a q value of 0 are also ignored. This switch MAY be not-present Usage of language-switch with SIP The language-ranges for the language-switch switch are obtained from the SIP Accept-Language header field. The switch is not-present if the 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 Accept-Language header fields are ignored. Lennox/Wu/Schulzrinne Expires February, 2004 [Page 11]

12 4.4 Time Switches 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 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 ( 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 List of seconds within a minute byminute List of minutes within an hour byhour List of hours of the day byday List of days of the week bymonthday List of days of the month byyearday List of days of the year byweekno List of weeks of the year bymonth List of months of the year wkst First day of the work week bysetpos List of values within set of events specified Figure 7: Syntax of the time-switch node Time switches are based closely on the specification of recurring intervals of time in the Internet Calendaring and Scheduling Core Object Specification (icalendar COS), RFC 2445 [8]. This allows CPL scripts 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 are published that update or obsolete RFC 2445, any changes or clarifications those documents make to recurrence handling apply to CPL time-switches as well. An algorithm to determine whether an instant falls within a given recurrence is given in Appendix A. The time-switch tag takes two optional parameters, tzid and tzurl, both of which are defined in RFC 2445 (Sections and respectively). The tzid is the identifying label by which a time zone definition is referenced. If it begins with a forward slash (solidus), it references a to-be-defined global time Lennox/Wu/Schulzrinne Expires February, 2004 [Page 12]

13 zone registry; otherwise it is locally-defined at the server. The tzurl gives a network location from which an up-to-date VTIMEZONE definition for the timezone can be retrieved. While tzid labels that do not begin with a forward slash are locally defined, it is RECOMMENDED that servers support at least the naming scheme used by Olson Time Zone database [9]. Examples of timezone databases that use the Olson scheme are the zoneinfo files on most Unix-like systems, and the 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 the URL. If a script is uploaded with 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 are present, all non-utc times within this time switch should be interpreted as being floating times, i.e. that they are specified in the local timezone of the CPL server. Because of daylight-savings-time changes over the course of a year, it is necessary to specify time 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 the beginning or end of daylight-savings time. Note especially that some times may occur more than once when clocks are set back. The algorithm in Appendix A is believed to handle this correctly. Time nodes specify a list of periods during which their output should be taken. They have two required parameters: dtstart, which specifies the beginning of the first period of the list, and exactly one of dtend or duration, which specify the ending time or the duration of the period, respectively. The dtstart and dtend parameters are formatted as icalendar COS DATE-TIME values, as specified in Section of RFC 2445 [8]. Because time zones are specified in the top-level time-switch tag, only forms 1 or 2 (floating or UTC times) can be used. The duration parameter is given as an icalendar COS DURATION parameter, as specified in section of RFC Both the DATE-TIME and the DURATION syntaxes are subsets of the corresponding syntaxes from ISO 8601 [20]. For a recurring interval, the duration parameter MUST be small enough such that subsequent intervals do not overlap. For non-recurring intervals, durations of any positive length are permitted. Zero-length and negative-length durations are not allowed. If no other parameters are specified, a time node indicates only a single period of time. More complicated sets periods intervals are constructed as recurrences. A recurrence is specified by including the freq parameter, which indicates the type of recurrence rule. Parameters other than dtstart, dtend, and duration SHOULD NOT be specified unless freq is present, though CPL servers SHOULD accept scripts with such parameters present, and ignore the other parameters. The freq parameter takes one of the following values: secondly, to specify repeating periods based on an interval of a second or more; minutely, to specify repeating periods based on an interval of a minute or more; hourly, to specify repeating periods based on an interval of an hour or more; daily, to specify repeating periods based on an interval of a day or more; weekly, to specify repeating periods based on an interval of a week or more; monthly, to specify repeating periods based on an interval of a month or more; and yearly, to specify repeating periods based on an interval of a year or more. These values are not case-sensitive. The interval parameter contains a positive integer representing how often the recurrence rule repeats. The default value is 1, meaning every second for a secondly rule, every minute for a minutely rule, every Lennox/Wu/Schulzrinne Expires February, 2004 [Page 13]

14 hour for an hourly rule, every day for a daily rule, every week for a weekly rule, every month for a monthly rule and every year for a yearly rule. The until parameter defines an icalendar COS DATE or DATE-TIME value which bounds the recurrence rule in an inclusive manner. If the value specified by until is synchronized with the specified recurrence, this date or date-time becomes the last instance of the recurrence. If specified as a date-time value, then it MUST be specified in an UTC time format. If not present, and the count parameter is not also present, the recurrence is considered to repeat forever. The count parameter defines the number of occurrences at which to range-bound the recurrence. The dtstart parameter counts as the first occurrence. The until and count parameters MUST NOT occur in the same time output. The bysecond parameter specifies a comma-separated list of seconds within a minute. Valid values are 0 to 59. The byminute parameter specifies a comma-separated list of minutes within an hour. Valid values are 0 to 59. The byhour parameter specifies a comma-separated list of hours of the day. Valid values are 0 to 23. The byday parameter specifies a comma-separated 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 bymonthday parameter specifies a comma-separated 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 byyearday parameter specifies a comma-separated list of days of the year. Valid values are 1 to 366 or -366 to -1. For example, -1 represents the last day of the year (December 31st) and -306 represents the 306th to the last day of the year (March 1st). The byweekno parameter specifies a comma-separated list of ordinals specifying weeks of the year. Valid values are 1 to 53 or -53 to -1. This corresponds to weeks according to week numbering as defined in ISO 8601 [20]. A week is defined as a seven day period, starting on the day of the week defined to be the week start (see wkst). Week number one of the calendar year is the first week which contains at least four (4) days in 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 or if it is a leap year and Wednesday is January 1. The bymonth parameter specifies a comma-separated list of months of the year. Valid values are 1 to 12. The wkst parameter specifies the day on which the work week starts. Valid values are MO, TU, WE, TH, FR, SA and SU. This is significant when a weekly recurrence has an interval greater than 1, and a byday parameter is specified. This is also significant in a yearly recurrence when a byweekno parameter is specified. The default value is MO, following ISO 8601 [20]. The bysetpos parameter specifies a comma-separated list of values which corresponds to the nth occurrence within the set of events specified by the rule. Valid values are 1 to 366 or -366 to -1. It MUST only be used in conjunction with another byxxx parameter. For example the last work day of the month could be Lennox/Wu/Schulzrinne Expires February, 2004 [Page 14]

15 represented as: <time -timerange- freq="monthly" byday="mo,tu,we,th,fr" bysetpos="-1"> Each bysetpos value can include a positive (+n) or negative (-n) integer. If present, this indicates the nth occurrence of the specific occurrence within the set of events specified by the rule. If byxxx parameter values are found which are beyond the available scope (ie, bymonthday= 30 in February), they are simply ignored. Byxxx parameters modify the recurrence in some manner. Byxxx rule parts for a period of time which is the same or greater than the frequency generally reduce or limit the number of occurrences of the recurrence generated. For example, freq= daily bymonth= 1 reduces the number of recurrence instances from all days (if the bymonth parameter is not present) to all days in January. Byxxx parameters for a period of time less than the frequency generally increase or expand the number of occurrences of the recurrence. For example, freq= yearly bymonth= 1,2 increases the number of days within the yearly recurrence set from 1 (if bymonth parameter is not present) to 2. If multiple Byxxx parameters are specified, then after evaluating the specified freq and interval parameters, the Byxxx parameters are applied to the current set of evaluated occurrences in the following order: bymonth, byweekno, byyearday, bymonthday, byday, byhour, byminute, bysecond and bysetpos; then count and until are evaluated. Here is an example of evaluating multiple Byxxx parameters. <time dtstart=" t083000" duration="10m" freq="yearly" interval="2" bymonth="1" byday="su" byhour="8,9" byminute="30"> First, the interval="2" would be applied to freq="yearly" to arrive at every other year. Then, bymonth="1" would be applied to arrive at every January, every other year. Then, byday="su" would be applied to arrive at every Sunday in January, every other year. Then, byhour="8,9" would be applied to arrive at every Sunday in January at 8 AM and 9 AM, every other year. Then, byminute="30" would be applied to arrive at every Sunday in January at 8:30 AM and 9:30 AM, every other year. Then the second is derived from dtstart to end up in every Sunday in January from 8:30:00 AM to 8:40:00 AM, and from and 9:30:00 AM to 9:40:00 AM, every other year. Similarly, if the byminute, byhour, byday, bymonthday or bymonth parameter were missing, the appropriate minute, hour, day or month would have been retrieved from the dtstart parameter. The icalendar COS RDATE, EXRULE and EXDATE recurrence rules are not specifically mapped to components of the time-switch node. Equivalent functionality to the exception rules can be attained by using the ordering of switch rules to exclude times using earlier rules; equivalent functionality to the additionaldate RDATE rules can be attained by using sub nodes (see Section 8) to link multiple outputs to the same subsequent node. The not-present output is never true for a time switch. However, it MAY be included, to allow switch processing to be more regular. Lennox/Wu/Schulzrinne Expires February, 2004 [Page 15]

16 4.4.1 icalendar differences and implementation issues (This sub-sub-section is non-normative.) The specification of recurring events in this section is identical (except for syntax and formatting issues) to that of RFC 2445 [8], with only one additional restriction. That one restriction is that consecutive instances of recurrence intervals may not overlap. It was a matter of some debate, during the design of CPL, whether the entire icalendar COS recurrence specification should be included in CPL, or whether only a subset should be included. It was eventually decided that compatibility between the two protocols was of primary importance. This imposes some additional implementation issues on implementors of CPL servers. It does not appear to be possible to determine, in constant time, whether a given instant of time falls within one of the intervals defined by a full icalendar COS recurrence. The primary concerns are as follows: The count parameter cannot be checked in constant running time, since it requires that the server enumerate all recurrences from dtstart to the present time, in order to determine whether the current recurrence satisfies the parameter. However, a server can expand a count parameter once, off-line, to determine the date of the last recurrence. This date can then be treated as a virtual until parameter for the server s internal processing. Similarly, the bysetpos parameter requires that the server enumerate all instances of the occurrence from the start of the current recurrence set until the present time. This requires somewhat more complex pre-processing, but generally, a single recurrence with a bysetpos parameter can be split up into several recurrences without them. Finally, constant running time of time switches also requires that a candidate starting time for a recurrence can be established quickly and uniquely, to check whether it satisfies the other restrictions. This requires that a recurrence s duration not be longer than its repetition interval, so that a given instant cannot fall within several consecutive potential repetitions of the recurrence. The restriction that consecutive intervals not overlap partially satisfies this condition, but does not fully ensure it. Again, to some extent pre-processing can help resolve this. The algorithm given in Appendix A runs in constant time after these pre-processing steps. Servers ought to check that recurrence rules do not create any absurd run-time or memory requirements, and reject those that do, just as they ought to check that CPL scripts in general are not absurdly large. 4.5 Priority Switches Priority switches allow a CPL script to make decisions based on the priority specified for the original call. They are summarized in Figure 8. They are dependent on the underlying signalling protocol. Priority switches take no parameters. The priority tag takes one of the three parameters greater, less, and equal. The values of these parameters are one of the following priorities: in decreasing order, emergency, urgent, normal, and non-urgent. These values are matched in a case-insensitive manner. Outputs with the less parameter are taken if the priority of the call is less than the priority given in the argument; and so forth. If no priority is specified in a message, the priority is considered to be normal. If an unknown priority is specified in the call, it is considered to be equivalent to normal for the purposes of greater and less comparisons, but it is compared literally for equal comparisons. Lennox/Wu/Schulzrinne Expires February, 2004 [Page 16]

17 Node: priority-switch Outputs: priority Specific priority to match Parameters: None Output: priority Parameters: less Match if priority is less than that specified greater Match if priority is greater than that specified equal Match if priority is equal to that specified Figure 8: Syntax of the priority-switch node Since every message has a priority, the not-present output is never true for a priority switch. However, it MAY be included, to allow switch processing to be more regular Usage of priority-switch with SIP The priority of a SIP message corresponds to the Priority header in the initial INVITE message. 5 Location Modifiers The abstract location model of CPL is described in Section 2.3. The behavior of several of the signalling operations (defined in Section 6) is dependent on the current location set specified. Location nodes add or remove locations from the location set. There are three types of location nodes defined. Explicit locations add literally-specified locations to the current location set; location lookups obtain locations from some outside source; and location filters remove locations from the set, based on some specified criteria. 5.1 Explicit Location Explicit location nodes specify a location literally. Their syntax is described in Figure 9. Explicit location nodes are dependent on the underlying signalling protocol. Node: location Outputs: None (Next node follows directly) Next node: Any node Parameters: url URL of address to add to location set priority Priority of this location ( ) clear Whether to clear the location set before adding the new value Figure 9: Syntax of the location node Lennox/Wu/Schulzrinne Expires February, 2004 [Page 17]

18 Explicit location nodes have three node parameters. The mandatory url parameter s value is the URL of the address to add to the location set. Only one address may be specified per location node; multiple locations may be specified by cascading these nodes. The optional priority parameter specifies a priority for the location. Its value is a floating-point number between 0.0 and 1.0. If it is not specified, the server SHOULD assume a default priority of 1.0. The optional clear parameter specifies whether the location set should be cleared before adding the new location to it. Its value can be yes or no, with no as the default. Basic location nodes have only one possible result, since there is no way that they can fail. (If a basic location node specifies a location which isn t supported by the underlying signalling protocol, the script server SHOULD detect this and report it to the user at the time the script is submitted.) Therefore, their XML representations do not have explicit output tags; the <location> tag directly contains another node Usage of location with SIP All SIP locations are represented as URLs, so the locations specified in location tags are interpreted directly. 5.2 Location Lookup Locations can also be specified up through external means, through the use of location lookups. The syntax of these tags is given in Figure 10. Location lookup is dependent on the underlying signalling protocol. Node: lookup Outputs: success Next node if lookup was successful notfound Next node if lookup found no addresses failure Next node if lookup failed Parameters: source Source of the lookup timeout Time to try before giving up on the lookup clear Whether to clear the location set before adding the new values Output: Parameters: Output: Parameters: Output: Parameters: success none notfound none failure none Figure 10: Syntax of the lookup node Location lookup nodes have one mandatory parameter and two optional parameters. The mandatory parameter is source, the source of the lookup. This can either be a URI, or a non-uri value. If the value of source is a URI, it indicates a location which the CPL server can query to obtain an object with the Lennox/Wu/Schulzrinne Expires February, 2004 [Page 18]

19 text/uri-list media type (see the IANA registration of this type, which also appears in RFC 2483 [10]). The query is performed verbatim, with no additional information (such as URI parameters) added. The server adds the locations contained in this object to the location set. CPL servers MAY refuse to allow URI-based sources for location queries for some or all URI schemes. In this case, they SHOULD reject the script at script upload time. There has been discussion of having CPL servers add URI parameters to the location request, so that (for instance) CGI scripts could be used to resolve them. However, the consensus was that this should be a CPL extension, not a part of the base specification. Non-URL sources indicate a source not specified by a URL which the server can query for addresses to add to the location set. The only non-url source currently defined is registration, which specifies all the locations currently registered with the server. The lookup node also has two optional parameters. The timeout parameter specifies the time, as a positive integer number of seconds, the script is willing to wait for the lookup to be performed. If this is not specified, its default value is 30. The clear parameter specifies whether the location set should be cleared before the new locations are added. Lookup has three outputs: success, notfound, and failure. Notfound is taken if the lookup process succeeded but did not find any locations; failure is taken if the lookup failed for some reason, including that specified timeout was exceeded. If a given output is not present, script execution terminates and the default behavior is performed Usage of lookup with SIP For SIP, the registration lookup source corresponds to the locations registered with the server using REG- ISTER messages. 5.3 Location Removal A CPL script can also remove locations from the location set, through the use of the remove-location node. The syntax of this node is defined in Figure 11. The meaning of this node is dependent on the underlying signalling protocol. Node: remove-location Outputs: None (Next node follows directly) Next node: Any node Parameters: location Location to remove Figure 11: Syntax of the remove-location node A remove-location node removes locations from the location set. It is primarily useful following a lookup node. An example of this is given in Section The remove-location node has one optional parameter. The parameter location gives the URL (or a signalling-protocol-dependent URL pattern) of location or locations to be removed from the set. If this parameter is not given, all locations are removed from the set. The remove-location node has no explicit output tags. In the XML syntax, the XML remove-location tag directly encloses the next node s tag. Lennox/Wu/Schulzrinne Expires February, 2004 [Page 19]