tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Gloss.     Arch.     IMS     UICC    |    Misc.    |    search     info

RFC 3880

Proposed STD
Pages: 74
Top     in Index     Prev     Next
in Group Index     Prev in Group     Next in Group     Group: IPTEL

Call Processing Language (CPL): A Language for User Control of Internet Telephony Services

Part 1 of 3, p. 1 to 22
None       Next RFC Part


Top       ToC       Page 1 
Network Working Group                                          J. Lennox
Request for Comments: 3880                                         X. Wu
Category: Standards Track                                 H. Schulzrinne
                                                     Columbia University
                                                            October 2004

                    Call Processing Language (CPL):
       A Language for User Control of Internet Telephony Services

Status of this Memo

   This document specifies an Internet standards track protocol for the
   Internet community, and requests discussion and suggestions for
   improvements.  Please refer to the current edition of the "Internet
   Official Protocol Standards" (STD 1) for the standardization state
   and status of this protocol.  Distribution of this memo is unlimited.

Copyright Notice

   Copyright (C) The Internet Society (2004).


   This document defines the Call Processing Language (CPL), a language
   to describe and control Internet telephony services.  It is designed
   to be implementable on either network servers or user agents.  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.

Top       Page 2 
Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
       1.1.   Conventions of This Document. . . . . . . . . . . . . .  4
   2.  Structure of CPL Scripts . . . . . . . . . . . . . . . . . . .  4
       2.1.   High-level Structure. . . . . . . . . . . . . . . . . .  4
       2.2.   Abstract Structure of a Call Processing Action. . . . .  5
       2.3.   Location Model. . . . . . . . . . . . . . . . . . . . .  6
       2.4.   XML Structure . . . . . . . . . . . . . . . . . . . . .  6
   3.  Script Structure: Overview . . . . . . . . . . . . . . . . . .  7
   4.  Switches . . . . . . . . . . . . . . . . . . . . . . . . . . .  8
       4.1.   Address Switches. . . . . . . . . . . . . . . . . . . .  9
              4.1.1.  Usage of "address-switch" with SIP. . . . . . . 11
       4.2.   String Switches . . . . . . . . . . . . . . . . . . . . 12
              4.2.1.  Usage of "string-switch" with SIP . . . . . . . 13
       4.3.   Language Switches . . . . . . . . . . . . . . . . . . . 14
              4.3.1.  Usage of "language-switch" with SIP . . . . . . 14
       4.4.   Time Switches . . . . . . . . . . . . . . . . . . . . . 15
              4.4.1.  iCalendar differences and implementation
                      issues. . . . . . . . . . . . . . . . . . . . . 20
       4.5.   Priority Switches . . . . . . . . . . . . . . . . . . . 21
              4.5.1.  Usage of "priority-switch" with SIP . . . . . . 22
   5.  Location Modifiers . . . . . . . . . . . . . . . . . . . . . . 22
       5.1.   Explicit Location . . . . . . . . . . . . . . . . . . . 23
              5.1.1.  Usage of "location" with SIP. . . . . . . . . . 23
       5.2.   Location Lookup . . . . . . . . . . . . . . . . . . . . 24
              5.2.1.  Usage of "lookup" with SIP. . . . . . . . . . . 25
       5.3.   Location Removal. . . . . . . . . . . . . . . . . . . . 25
              5.3.1.  Usage of "remove-location" with SIP . . . . . . 26
   6.  Signalling Operations. . . . . . . . . . . . . . . . . . . . . 26
       6.1.   Proxy . . . . . . . . . . . . . . . . . . . . . . . . . 26
              6.1.1.  Usage of "proxy" with SIP . . . . . . . . . . . 29
       6.2.   Redirect. . . . . . . . . . . . . . . . . . . . . . . . 29
              6.2.1.  Usage of "redirect" with SIP. . . . . . . . . . 30
       6.3.   Reject. . . . . . . . . . . . . . . . . . . . . . . . . 30
              6.3.1.  Usage of "reject" with SIP. . . . . . . . . . . 30
   7.  Non-signalling Operations. . . . . . . . . . . . . . . . . . . 31
       7.1.   Mail. . . . . . . . . . . . . . . . . . . . . . . . . . 31
              7.1.1.  Suggested Content of Mailed Information . . . . 32
       7.2.   Log . . . . . . . . . . . . . . . . . . . . . . . . . . 32
   8.  Subactions . . . . . . . . . . . . . . . . . . . . . . . . . . 33
   9.  Ancillary Information. . . . . . . . . . . . . . . . . . . . . 34
   10. Default Behavior . . . . . . . . . . . . . . . . . . . . . . . 35
   11. CPL Extensions . . . . . . . . . . . . . . . . . . . . . . . . 35
   12. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
       12.1.  Example: Call Redirect Unconditional. . . . . . . . . . 37
       12.2.  Example: Call Forward Busy/No Answer. . . . . . . . . . 38
       12.3.  Example: Call Forward: Redirect and Default . . . . . . 39

Top      ToC       Page 3 
       12.4.  Example: Call Screening . . . . . . . . . . . . . . . . 40
       12.5.  Example: Priority and Language Routing. . . . . . . . . 41
       12.6.  Example: Outgoing Call Screening. . . . . . . . . . . . 42
       12.7.  Example: Time-of-day Routing. . . . . . . . . . . . . . 43
       12.8.  Example: Location Filtering . . . . . . . . . . . . . . 44
       12.9.  Example: Non-signalling Operations. . . . . . . . . . . 45
       12.10. Example: Hypothetical Extensions. . . . . . . . . . . . 46
       12.11. Example: A Complex Example. . . . . . . . . . . . . . . 48
   13. Security Considerations. . . . . . . . . . . . . . . . . . . . 49
   14. IANA Considerations. . . . . . . . . . . . . . . . . . . . . . 49
       14.1.  URN Sub-Namespace Registration for
              urn:ietf:params:xml:ns:cpl. . . . . . . . . . . . . . . 49
       14.2.  Schema registration . . . . . . . . . . . . . . . . . . 50
       14.3.  MIME Registration . . . . . . . . . . . . . . . . . . . 50
   15. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . . 51
   A.  An Algorithm for Resolving Time Switches . . . . . . . . . . . 52
   B.  Suggested Usage of CPL with H.323. . . . . . . . . . . . . . . 53
       B.1.   Usage of "address-switch" with H.323. . . . . . . . . . 53
       B.2.   Usage of "string-switch" with H.323 . . . . . . . . . . 55
       B.3.   Usage of "language-switch" with H.323 . . . . . . . . . 55
       B.4.   Usage of "priority-switch" with H.323 . . . . . . . . . 55
       B.5.   Usage of "location" with H.323. . . . . . . . . . . . . 56
       B.6.   Usage of "lookup" with H.323. . . . . . . . . . . . . . 56
       B.7.   Usage of "remove-location" with H.323 . . . . . . . . . 56
   C.  The XML Schema for CPL . . . . . . . . . . . . . . . . . . . . 56
   Normative References . . . . . . . . . . . . . . . . . . . . . . . 70
   Informative References . . . . . . . . . . . . . . . . . . . . . . 71
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 73
   Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 74

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 describe
   Internet telephony services.  The language is not Turing-complete,
   and provides no way to write loops or recursion.

   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.

Top      ToC       Page 4 
   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 the
   validity of a script when the server receives it, rather than
   discovering problems 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"

1.1.  Conventions of This Document

   In this document, the key words "MUST", "MUST NOT", "REQUIRED",
   and "OPTIONAL" are to be interpreted as described in BCP 14, RFC 2119
   [3] and indicate requirement levels for compliant CPL

      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.

Top      ToC       Page 5 
   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 that 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 connected to additional nodes.
   When an action is run, the action or decision described by the
   action's top-level 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.

Top      ToC       Page 6 
        _________________      ___________________    ________  busy
       | Address-switch  |    | location          |  | proxy  |--------\
Call-->|  field: origin  |  ->|   url: sip:jones@ |->|timeout:| timeout|
       |  subfield: host | /  |   |  |  10s   |--------|
       |-----------------|/   |___________________|  |        | failure|
       | subdomain-of:   |                           |________|--------|
       |   |                                             |
       |-----------------|  ___________________________________________/
       | otherwise       | /........................................
       |                 |\|. Voicemail                            .
       |_________________| \.  ____________________                .
                            ->| location           |   __________  .
                            . |   url: sip:jones@  |  | redirect | .
                            . |        voicemail.  |->|          | .
                            . | |  |__________| .
                            . |____________________|               .

   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.
   However, as a 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 [18], as both
   languages are simplifications of the earlier and larger standard SGML

Top      ToC       Page 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 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

   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.

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.

   <?xml version="1.0" encoding="UTF-8"?>
   <cpl xmlns="urn:ietf:params:xml:ns:cpl"
     xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd ">
     <subaction id="voicemail">
       <location url="">
         <redirect />
       <address-switch field="origin" subfield="host">
         <address subdomain-of="">
           <location url="">
             <proxy timeout="10">
               <busy> <sub ref="voicemail" /> </busy>
               <noanswer> <sub ref="voicemail" /> </noanswer>
               <failure> <sub ref="voicemail" /> </failure>

Top      ToC       Page 8 
           <sub ref="voicemail" />

   Figure 2: Sample CPL Script: XML Version

           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 subactions,
   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 non-signalling 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

   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 that should be executed if the condition is
   true.  The conditions are tried in the order they are presented in
   the script; the output corresponding to the first node to match is

   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".)

Top      ToC       Page 9 
   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 only contain 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.

          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 "original-
   destination"), the destination the call had before any earlier
   forwarding was invoked.  Servers MAY define additional field values.

   The optional "subfield" specifies which 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 "alias-
   type" is defined for H.323 in Appendix B.1.)  If no subfield is

Top      ToC       Page 10 
   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 e-mail style
            addresses, the user part of the address.  For a 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 :: omitted-zero-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.

      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 (telephone numbers may contain the symbols 'A',
            'B', 'C', or 'D'), and may be absent.  It may be matched
            using the "subdomain-of" match operator.  Punctuation and
            separator characters in telephone numbers are discarded.

Top      ToC       Page 11 
      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

      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="" would match the hostnames "",
            "", and
            "".  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="1212555" would match the telephone number "1
            212 555 1212."

      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.

4.1.1.  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.

Top      ToC       Page 12 
   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 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

Top      ToC       Page 13 
   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

   Four fields are defined and listed below.  The value of each of these
   fields 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
   Standard Annex #15 [5].  Then, strings are compared using locale-
   insensitive caseless mapping, as specified in Unicode Standard Annex
   #21 [6].

      Code to perform the first step, in Java and Perl, is available;
      see the links from Annex 5 of UAX 15 [5].  The case-insensitive
      string comparison in the Java standard class libraries already
      performs the second step; other Unicode-aware libraries should be

   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.

4.2.1.  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.

Top      ToC       Page 14 
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

      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 3066.  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.

4.3.1.  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

Top      ToC       Page 15 
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.

Top      ToC       Page 16 
   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 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 the 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

Top      ToC       Page 17 
   duration of the period, respectively.  The "dtstart" and "dtend"
   parameters are formatted as iCalendar COS DATE-TIME values, as
   specified in Section 4.3.5 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
   4.3.6 of RFC 2445.  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 of period 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

   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 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

Top      ToC       Page 18 
   specified in UTC time format.  If not present, and the "count"
   parameter is not also present, the recurrence is considered to repeat

   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, and "SU" indicates Sunday.  These values are not

   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.

Top      ToC       Page 19 
      Note: Assuming a Monday week start, week 53 can only occur when
      January 1 is a Thursday or, for leap years, if January 1 is a

   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 represented as:

      <time -timerange- freq="monthly" byday="MO,TU,WE,TH,FR"

   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 (i.e., 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.

Top      ToC       Page 20 
   Here is an example of evaluating multiple Byxxx parameters.

      <time dtstart="19970105T083000" 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 additional-date 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.

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.

Top      ToC       Page 21 
   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:

      o  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.

      o  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.

      o  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

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.

Top      ToC       Page 22 
             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

   Priority switches take no parameters.

   The "priority" tag takes one of the three parameters "greater",
   "less", or "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.

   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.

4.5.1.  Usage of "priority-switch" with SIP

   The priority of a SIP message corresponds to the "Priority" header in
   the initial "INVITE" message.

(page 22 continued on part 2)

Next RFC Part