draft-ietf-iptel-cpl-04.txt   draft-ietf-iptel-cpl-05.txt 
Internet Engineering Task Force IPTEL WG Internet Engineering Task Force IPTEL WG
Internet Draft Lennox/Schulzrinne Internet Draft Lennox/Schulzrinne
draft-ietf-iptel-cpl-04.txt Columbia University draft-ietf-iptel-cpl-05.txt Columbia University
November 14, 2000 November 21, 2001
Expires: May, 2001 Expires: May, 2002
CPL: A Language for User Control of Internet Telephony Services CPL: A Language for User Control of Internet Telephony Services
STATUS OF THIS MEMO STATUS OF THIS MEMO
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 3, line 15 skipping to change at page 3, line 15
2.1 High-level Structure 2.1 High-level Structure
A CPL script consists of two types of information: ancillary A CPL script consists of two types of information: ancillary
information about the script, and call processing actions. information about the script, and call processing actions.
A call processing action is a structured tree that describes the A call processing action is a structured tree that describes the
operations and decisions a telephony signalling server performs on a operations and decisions a telephony signalling server performs on a
call set-up event. There are two types of call processing actions: call set-up event. There are two types of call processing actions:
top-level actions and subactions. Top-level actions are actions that top-level actions and subactions. Top-level actions are actions that
are triggered by signalling events that arrive at the server. Two are triggered by signalling events that arrive at the server. Two
top-level action names are defined: incoming, the action performed top-level action names are defined: "incoming", the action performed
when a call arrives whose destination is the owner of the script; and when a call arrives whose destination is the owner of the script; and
outgoing, the action performed when a call arrives whose originator "outgoing", the action performed when a call arrives whose originator
is the owner of the script. Subactions are actions which can be is the owner of the script. Subactions are actions which can be
called from other actions. The CPL forbids subactions from being called from other actions. The CPL forbids subactions from being
called recursively: see Section 9. called recursively: see Section 9.
Ancillary information is information which is necessary for a server Ancillary information is information which is necessary for a server
to correctly process a script, but which does not directly describe to correctly process a script, but which does not directly describe
any operations or decisions. Currently, no ancillary information is any operations or decisions. Currently, no ancillary information is
defined, but the section is reserved for use by extensions. defined, but the section is reserved for use by extensions.
2.2 Abstract Structure of a Call Processing Action 2.2 Abstract Structure of a Call Processing Action
skipping to change at page 5, line 28 skipping to change at page 5, line 28
The connection between the output of a node and another node is The connection between the output of a node and another node is
represented by enclosing the tag representing the pointed-to node represented by enclosing the tag representing the pointed-to node
inside the tag for the outer node's output. Convergence (several inside the tag for the outer node's output. Convergence (several
outputs pointing to a single node) is represented by subactions, outputs pointing to a single node) is represented by subactions,
discussed further in Section 9. discussed further in Section 9.
The higher-level structure of a CPL script is represented by tags The higher-level structure of a CPL script is represented by tags
corresponding to each piece of ancillary information, subactions, and corresponding to each piece of ancillary information, subactions, and
top-level actions, in order. This higher-level information is all top-level actions, in order. This higher-level information is all
enclosed in a special tag cpl, the outermost tag of the XML document. enclosed in a special tag "cpl", the outermost tag of the XML
document.
A complete Document Type Declaration for the CPL is provided in A complete Document Type Declaration for the CPL is provided in
Appendix C. The remainder of the main sections of this document Appendix C. The remainder of the main sections of this document
describe the semantics of the CPL, while giving its syntax describe the semantics of the CPL, while giving its syntax
informally. For the formal syntax, please see the appendix. informally. For the formal syntax, please see the appendix.
3 Document Information 3 Document Information
This section gives information describing how CPL scripts are This section gives information describing how CPL scripts are
identified. identified.
skipping to change at page 6, line 47 skipping to change at page 6, line 47
Note that the URIs specifying XML namespaces are only Note that the URIs specifying XML namespaces are only
globally unique names; they do not have to reference any globally unique names; they do not have to reference any
particular actual object. The URI of a canonical source of particular actual object. The URI of a canonical source of
this specification meets the requirement of being globally this specification meets the requirement of being globally
unique, and is also useful to document the format. unique, and is also useful to document the format.
3.2 MIME Registration 3.2 MIME Registration
As an XML type, CPL's MIME registration conforms with "XML Media As an XML type, CPL's MIME registration conforms with "XML Media
Types," RFC YYYY [8]. Types," RFC 3023 [8].
[Note to RFC Editor: please replace "YYYY" in this section,
and in bibliography entry [8], with the RFC number assigned
to the Internet-Draft draft-murata-xml-09.txt, approved for
Proposed Standard.]
MIME media type name: application MIME media type name: application
MIME subtype name: cpl+xml MIME subtype name: cpl+xml
Mandatory parameters: none Mandatory parameters: none
Optional parameters: charset Optional parameters: charset
As for application/xml in RFC YYYY. As for application/xml in RFC 3023.
Encoding considerations: As for application/xml in RFC YYYY. Encoding considerations: As for application/xml in RFC 3023.
Security considerations: See Section 14, and Section 10 of RFC Security considerations: See Section 14, and Section 10 of RFC
YYYY. 3023.
Interoperability considerations: Different CPL servers may use Interoperability considerations: Different CPL servers may use
incompatible address types. However, all potential incompatible address types. However, all potential
interoperability issues should be resolvable at the time a interoperability issues should be resolvable at the time a
script is uploaded; there should be no interoperability script is uploaded; there should be no interoperability
issues which cannot be detected until runtime. issues which cannot be detected until runtime.
Published specification: This document. Published specification: This document.
Applications which use this media type: None publicly released Applications which use this media type: None publicly released
skipping to change at page 8, line 4 skipping to change at page 7, line 47
Person and e-mail address for further information: Person and e-mail address for further information:
Jonathan Lennox <lennox@cs.columbia.edu> Jonathan Lennox <lennox@cs.columbia.edu>
Henning Schulzrinne <hgs@cs.columbia.edu> Henning Schulzrinne <hgs@cs.columbia.edu>
Intended usage: COMMON Intended usage: COMMON
Author/Change Controller: The IETF. Author/Change Controller: The IETF.
4 Script Structure: Overview 4 Script Structure: Overview
As mentioned, a CPL script consists of ancillary information, As mentioned, a CPL script consists of ancillary information,
subactions, and top-level actions. The full syntax of the cpl node is subactions, and top-level actions. The full syntax of the "cpl" node
given in Figure 3. is given in Figure 3.
Tag: cpl Tag: "cpl"
Parameters: None Parameters: None
Sub-tags: ancillary See Section 10 Sub-tags: "ancillary" See Section 10
subaction See Section 9 "subaction" See Section 9
outgoing Top-level actions to take on this user's "outgoing" Top-level actions to take on this user's
outgoing calls outgoing calls
incoming Top-level actions to take on this user's "incoming" Top-level actions to take on this user's
incoming calls incoming calls
Figure 3: Syntax of the top-level cpl tag Figure 3: Syntax of the top-level "cpl" tag
Call processing actions, both top-level actions and sub-actions, Call processing actions, both top-level actions and sub-actions,
consist of a tree of nodes and outputs. Nodes and outputs are both consist of a tree of nodes and outputs. Nodes and outputs are both
described by XML tags. There are four categories of CPL nodes: described by XML tags. There are four categories of CPL nodes:
switches , which represent choices a CPL script can make; location switches , which represent choices a CPL script can make; location
modifiers , which add or remove locations from the location set; modifiers , which add or remove locations from the location set;
signalling operations , which cause signalling events in the signalling operations , which cause signalling events in the
underlying protocol; and non-signalling operations , which trigger underlying protocol; and non-signalling operations , which trigger
behavior which does not effect the underlying protocol. behavior which does not effect the underlying protocol.
skipping to change at page 8, line 41 skipping to change at page 8, line 38
attributes of the original call request or items independent of the attributes of the original call request or items independent of the
call. call.
All switches are arranged as a list of conditions that can match a All switches are arranged as a list of conditions that can match a
variable. Each condition corresponds to a node output; the output variable. Each condition corresponds to a node output; the output
points to the next node to execute if the condition was true. The 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; conditions are tried in the order they are presented in the script;
the output corresponding to the first node to match is taken. the output corresponding to the first node to match is taken.
There are two special switch outputs that apply to every switch type. There are two special switch outputs that apply to every switch type.
The output not-present, which MAY occur anywhere in the list of 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 outputs, is true if the variable the switch was to match was not
present in the original call setup request. (In this document, this present in the original call setup request. (In this document, this
is sometimes described by saying that the information is "absent".) is sometimes described by saying that the information is "absent".)
The output otherwise, which MUST be the last output specified if it The output "otherwise", which MUST be the last output specified if it
is present, matches if no other condition matched. is present, matches if no other condition matched.
If no condition matches and no otherwise output was present in the If no condition matches and no "otherwise" output was present in the
script, the default script behavior is taken. See Section 11 for more script, the default script behavior is taken. See Section 11 for more
information on this. information on this.
5.1 Address Switches 5.1 Address Switches
Address switches allow a CPL script to make decisions based on one of Address switches allow a CPL script to make decisions based on one of
the addresses present in the original call request. They are the addresses present in the original call request. They are
summarized in Figure 4. summarized in Figure 4.
Node: address-switch Node: "address-switch"
Outputs: address Specific addresses to match Outputs: "address" Specific addresses to match
Parameters: field origin, destination, or original-destination Parameters: "field" "origin", "destination", or "original-destination"
subfield address-type, user, host, port, tel, or display "subfield" "address-type", "user", "host", "port", "tel", or "display"
(also: password and alias-type) (also: "password" and "alias-type")
Output: address Output: "address"
Parameters: is exact match Parameters: "is" exact match
contains substring match (for display only) "contains" substring match (for "display" only)
subdomain-of sub-domain match (for host, tel only) "subdomain-of" sub-domain match (for "host", "tel" only)
Figure 4: Syntax of the address-switch node Figure 4: Syntax of the "address-switch" node
Address switches have two node parameters: field, and subfield. The Address switches have two node parameters: "field", and "subfield".
mandatory field parameter allows the script to specify which address The mandatory "field" parameter allows the script to specify which
is to be considered for the switch: either the call's origin address address is to be considered for the switch: either the call's origin
(field "origin"), its current destination address (field address (field "origin"), its current destination address (field
"destination"), or its original destination (field "original- "destination"), or its original destination (field "original-
destination"), the destination the call had before any earlier destination"), the destination the call had before any earlier
forwarding was invoked. Servers MAY define additional field values. forwarding was invoked. Servers MAY define additional field values.
The optional subfield specifies what part of the address is to be The optional "subfield" specifies what part of the address is to be
considered. The possible subfield values are: address-type, user, considered. The possible subfield values are: "address-type", "user",
host, port, tel, and display. Additional subfield values MAY be "host", "port", "tel", and "display". Additional subfield values MAY
defined for protocol-specific values. (The subfield password is be defined for protocol-specific values. (The subfield "password" is
defined for SIP in Section 5.1.1; the subfield alias-type is defined defined for SIP in Section 5.1.1; the subfield "alias-type" is
for H.323 in Appendix B.1.) If no subfield is specified, the 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 "entire" address is matched; the precise meaning of this is defined
for each underlying signalling protocol. Servers MAY define for each underlying signalling protocol. Servers MAY define
additional subfield values. additional subfield values.
The subfields are defined as follows: The subfields are defined as follows:
address-type This indicates the type of the underlying address; address-type This indicates the type of the underlying address;
i.e., the URI scheme, if the address can be represented by i.e., the URI scheme, if the address can be represented by
a URI. The types specifically discussed by this document a URI. The types specifically discussed by this document
are sip, tel, and h323. The address type is not case- are "sip", "tel", and "h323". The address type is not
sensitive. It has a value for all defined address types. case-sensitive. It has a value for all defined address
types.
user This subfield of the address indicates, for e-mail style user This subfield of the address indicates, for e-mail style
addresses, the user part of the address. For telephone addresses, the user part of the address. For telephone
number style address, it includes the subscriber number. number style address, it includes the subscriber number.
This subfield is case-sensitive; it may be absent. This subfield is case-sensitive; it may be absent.
host This subfield of the address indicates the Internet host host This subfield of the address indicates the Internet host
name or IP address corresponding to the address, in host name or IP address corresponding to the address, in host
name, IPv4, or IPv6 format. For host names only, subdomain name, IPv4, or IPv6 [9] textual representation format.
matching is supported with the subdomain-of match operator. Host names are compared as strings. IP addresses are
It is not case sensitive, and may be absent. 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.
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. This subfield is not case sensitive, and
may be absent.
port This subfield indicates the TCP or UDP port number of the port This subfield indicates the TCP or UDP port number of the
address, numerically in decimal format. It is not case address, numerically in decimal format. It is not case
sensitive, as it MUST only contain decimal digits. It may sensitive, as it MUST only contain decimal digits. Leading
be absent; however, for address types with default ports, zeros are ignored. This subfield may be absent; however,
an absent port matches the default port number. for address types with default ports, an absent port
matches the default port number.
tel This subfield indicates a telephone subscriber number, if tel This subfield indicates a telephone subscriber number, if
the address contains such a number. It is not case the address contains such a number. It is not case
sensitive (the telephone numbers may contain the symbols sensitive (the telephone numbers may contain the symbols
`A' `B' `C' and `D'), and may be absent. It may be matched `A' `B' `C' and `D'), and may be absent. It may be matched
using the subdomain-of match operator. Punctuation and using the "subdomain-of" match operator. Punctuation and
separator characters in telephone numbers are discarded. separator characters in telephone numbers are discarded.
display This subfield indicates a "display name" or user-visible display This subfield indicates a "display name" or user-visible
name corresponding to an address. It is a Unicode string, name corresponding to an address. It is a Unicode string,
and is matched using the case-insensitive algorithm and is matched using the case-insensitive algorithm
described in Section 5.2. The contains operator may be described in Section 5.2. The "contains" operator may be
applied to it. It may be absent. applied to it. It may be absent.
For any completely unknown subfield, the server MAY reject the script 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 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 script with an unknown subfield is executed, the server MUST consider
the not-present output to be the valid one. the "not-present" output to be the valid one.
The address output tag may take exactly one of three possible The "address" output tag may take exactly one of three possible
parameters, indicating the kind of matching allowed. parameters, indicating the kind of matching allowed.
is An output with this match operator is followed if the is An output with this match operator is followed if the
subfield being matched in the address-switch exactly subfield being matched in the "address-switch" exactly
matches the argument of the operator. It may be used for matches the argument of the operator. It may be used for
any subfield, or for the entire address if no subfield was any subfield, or for the entire address if no subfield was
specified. specified.
subdomain-of This match operator applies only for the subfields subdomain-of This match operator applies only for the subfields
host and tel. In the former case, it matches if the "host" and "tel". In the former case, it matches if the
hostname being matched is a subdomain of the domain given hostname being matched is a subdomain of the domain given
in the argument of the match operator; thus, subdomain- in the argument of the match operator; thus, subdomain-
of="example.com" would match the hostnames "example.com", of="example.com" would match the hostnames "example.com",
"research.example.com", and "research.example.com", and
"zaphod.sales.internal.example.com". IP addresses may be "zaphod.sales.internal.example.com". IP addresses may be
given as arguments to this operator; however, they only given as arguments to this operator; however, they only
match exactly. In the case of the tel subfield, the output match exactly. In the case of the "tel" subfield, the
matches if the telephone number being matched has a prefix output matches if the telephone number being matched has a
that matches the argument of the match operator; prefix that matches the argument of the match operator;
subdomain-of="1212555" would match the telephone number "1 subdomain-of="1212555" would match the telephone number "1
212 555 1212." 212 555 1212."
contains This match operator applies only for the subfield contains This match operator applies only for the subfield
display. The output matches if the display name being "display". The output matches if the display name being
matched contains the argument of the match as a substring. matched contains the argument of the match as a substring.
5.1.1 Usage of address-switch with SIP 5.1.1 Usage of "address-switch" with SIP
For SIP, the origin address corresponds to the address in the From For SIP, the "origin" address corresponds to the address in the
header; destination corresponds to the Request-URI; and original- "From" header; "destination" corresponds to the "Request-URI"; and
destination corresponds to the To header. "original-destination" corresponds to the "To" header.
The display subfield of an address is the display-name part of the 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, if it is present. Because of SIP's syntax, the "destination"
address field will never have a display subfield. address field will never have a "display" subfield.
The address-type subfield of an address is the URI scheme of that The "address-type" subfield of an address is the URI scheme of that
address. Other address fields depend on that address-type. address. Other address fields depend on that "address-type".
For sip URLs, the user, host, and port subfields correspond to the For sip URLs, the "user", "host", and "port" subfields correspond to
"user," "host," and "port" elements of the URI syntax. The tel the "user," "host," and "port" elements of the URI syntax. The "tel"
subfield is defined to be the "user" part of the URI, with visual subfield is defined to be the "user" part of the URI, with visual
separators stripped, separators stripped, if and only if the "user=phone" parameter is
given to the URI. An additional subfield, "password" is defined to
if and only if the "user=phone" parameter is given to the URI. An correspond to the "password" element of the SIP URI, and is case-
additional subfield, password is defined to correspond to the sensitive. However, use of this field is NOT RECOMMENDED for general
"password" element of the SIP URI, and is case-sensitive. However, security reasons.
use of this field is NOT RECOMMENDED for general security reasons.
For tel URLs, the tel and user subfields are the subscriber name; in For tel URLs, the "tel" and "user" subfields are the subscriber name;
the former case, visual separators are stripped. The host and port in the former case, visual separators are stripped. The "host" and
subfields are both not present. "port" subfields are both not present.
For h323 URLs, subfields MAY be set according to the scheme described For h323 URLs, subfields MAY be set according to the scheme described
in Appendix B. in Appendix B.
For other URI schemes, only the address-type subfield is defined by For other URI schemes, only the "address-type" subfield is defined by
this specification; servers MAY set other pre-defined subfields, or this specification; servers MAY set other pre-defined subfields, or
MAY support additional subfields. MAY support additional subfields.
If no subfield is specified for addresses in SIP messages, the string If no subfield is specified for addresses in SIP messages, the string
matched is the URI part of the address. For "sip" URLs, all matched is the URI part of the address. For "is" matches, standard
parameters are stripped; for other URLs, the URL is used verbatim. SIP URI matching rules are used; for "contains" matches, the URI is
used verbatim.
5.2 String Switches 5.2 String Switches
String switches allow a CPL script to make decisions based on free- String switches allow a CPL script to make decisions based on free-
form strings present in a call request. They are summarized in Figure form strings present in a call request. They are summarized in Figure
5. 5.
Node: string-switch Node: "string-switch"
Outputs: string Specific string to match Outputs: "string" Specific string to match
Parameters: field subject, organization, user-agent, Parameters: "field" "subject", "organization", "user-agent",
language, or display or "display"
Output: string Output: "string"
Parameters: is exact match Parameters: "is" exact match
contains substring match "contains" substring match
Figure 5: Syntax of the string-switch node Figure 5: Syntax of the "string-switch" node
String switches have one node parameter: field. The mandatory field String switches have one node parameter: "field". The mandatory
parameter specifies which string is to be matched. "field" parameter specifies which string is to be matched.
String switches are dependent on the call signalling protocol being String switches are dependent on the call signalling protocol being
used. used.
Five fields are defined, listed below. The value of each of these Five fields are defined, listed below. The value of each of these
fields, except as specified, is a free-form Unicode string with no fields, except as specified, is a free-form Unicode string with no
other structure defined. other structure defined.
subject The subject of the call. "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.
language The languages in which the originator of the call "organization" The organization of the originator of the call.
wishes to receive responses. This contains a list of RFC
1766 [9] language tags, separated by commas.
Note that matching based on contains is likely to be "user-agent" The name of the program or device with which the
much more useful than matching based on is, for this call request was made.
field.
display Free-form text associated with the call, intended to be "display" Free-form text associated with the call, intended to
displayed to the recipient, with no other semantics defined be displayed to the recipient, with no other semantics
by the signalling protocol. defined by the signalling protocol.
Strings are matched as case-insensitive Unicode strings, in the Strings are matched as case-insensitive Unicode strings, in the
following manner. First, strings are canonicalized to the following manner. First, strings are canonicalized to the
"Compatibility Composition" (KC) form, as specified in Unicode "Compatibility Composition" (KC) form, as specified in Unicode
Technical Report 15 [10]. Then, strings are compared using locale- Technical Report 15 [10]. Then, strings are compared using locale-
insensitive caseless mapping, as specified in Unicode Technical insensitive caseless mapping, as specified in Unicode Technical
Report 21 [11]. Report 21 [11].
Code to perform the first step, in Java and Perl, is Code to perform the first step, in Java and Perl, is
available; see the links from Annex E of UTR 15 [10]. The available; see the links from Annex E of UTR 15 [10]. The
case-insensitive string comparison in the Java standard case-insensitive string comparison in the Java standard
class libraries already performs the second step; other class libraries already performs the second step; other
Unicode-aware libraries should be similar. Unicode-aware libraries should be similar.
The output tags of string matching are named string, and have a The output tags of string matching are named "string", and have a
mandatory argument, one of is or contains, indicating whole-string mandatory argument, one of "is" or "contains", indicating whole-
match or substring match, respectively. string match or substring match, respectively.
5.2.1 Usage of string-switch with SIP 5.2.1 Usage of "string-switch" with SIP
For SIP, the fields subject, organization, and user-agent correspond For SIP, the fields "subject", "organization", and "user-agent"
to the SIP header fields with the same name. These are used verbatim correspond to the SIP header fields with the same name. These are
as they appear in the message. used verbatim as they appear in the message.
The field language corresponds to the SIP Accept-Language header. It The field "display" is not used, and is never present.
is converted to a list of comma-separated languages as described
above.
The field display is not used, and is never present. 5.3 Language Switches
5.3 Time 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.
Language switches take no parameters.
The "language" outputs take one parameter, "matches". The value of
one of these parameters is a language-tag, as defined in RFC 3066
[12]. The caller may have specified a set of language-ranges, also as
defined in RFC 3066. The CPL server checks each language-tag
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
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 "-".
The special language-range "*" is ignored for the purpose of
matching. Languages with a "q" value of 0 are also ignored.
This switch MAY be not-present.
5.3.1 Usage of "language-switch" with SIP
The 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.
5.4 Time Switches
Time switches allow a CPL script to make decisions based on the time 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 and/or date the script is being executed. They are summarized in
Figure 6. Figure 7.
Time switches are independent of the underlying signalling protocol. Time switches are independent of the underlying signalling protocol.
Node: time-switch Time switches are based closely on the specification of recurring
Outputs: time Specific time to match intervals of time in the Internet Calendaring and Scheduling Core
Parameters: tzid RFC 2445 Time Zone Identifier Node: "time-switch"
tzurl RFC 2445 Time Zone URL Outputs: "time" Specific time to match
Parameters: "tzid" RFC 2445 Time Zone Identifier
"tzurl" RFC 2445 Time Zone URL
Output: time Output: "time"
Parameters: dtstart Start of interval (RFC 2445 DATE-TIME) Parameters: "dtstart" Start of interval (RFC 2445 DATE-TIME)
dtend End of interval (RFC 2445 DATE-TIME) "dtend" End of interval (RFC 2445 DATE-TIME)
duration Length of interval (RFC 2445 DURATION) "duration" Length of interval (RFC 2445 DURATION)
freq Frequency of recurrence (one of "daily", "freq" Frequency of recurrence (one of "secondly",
"minutely", "hourly", "daily",
"weekly", "monthly", or "yearly") "weekly", "monthly", or "yearly")
interval How often the recurrence repeats "interval" How often the recurrence repeats
until Bound of recurrence (RFC 2445 DATE-TIME) "until" Bound of recurrence (RFC 2445 DATE-TIME)
byday List of days of the week "count" Number of occurences of recurrence
bymonthday List of days of the month "bysecond" List of seconds within a minute
byyearday List of days of the year "byminute" List of minutes within an hour
byweekno List of weeks of the year "byhour" List of hours of the day
bymonth List of months of the year "byday" List of days of the week
wkst First day of workweek "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 workweek
"bysetpos" List of values within set of events specified
Figure 6: Syntax of the time-switch node Figure 7: Syntax of the "time-switch" node
Time switches are based on a large subset of how recurring intervals Object Specification (iCalendar COS), RFC 2445 [13].
of time are specified in the Internet Calendaring and Scheduling Core
Object Specification (iCal COS), RFC 2445 [12].
This allows CPLs to be generated automatically from This allows CPLs to be generated automatically from
calendar books. It also allows us to re-use the extensive calendar books. It also allows us to re-use the extensive
existing work specifying time intervals. existing work specifying time intervals.
The subset was designed with the goal that a time-switch If future standards-track documents are published that obsolete RFC
can be evaluated -- an instant can be determined to fall 2445, any changes or clarifications those documents make to
within an interval, or not -- in constant (O(1)) time. recurrence handling apply to CPL time-switches as well.
An algorithm to whether an instant falls within a given recurrence is An algorithm to whether an instant falls within a given recurrence is
given in Appendix A. given in Appendix A.
The time-switch tag takes two optional parameters, tzid and tzurl, The "time-switch" tag takes two optional parameters, "tzid" and
both of which are defined in RFC 2445 (Sections 4.8.3.1 and 4.8.3.5 "tzurl", both of which are defined in RFC 2445 (Sections 4.8.3.1 and
respectively). The TZID is the identifying label by which a time zone 4.8.3.5 respectively). The TZID is the identifying label by which a
definition is referenced. If it begins with a forward slash time zone definition is referenced. If it begins with a forward slash
(solidus), it references a to-be-defined global time zone registry; (solidus), it references a to-be-defined global time zone registry;
otherwise it is locally-defined at the server. The TZURL gives a otherwise it is locally-defined at the server. The TZURL gives a
network location from which an up-to-date VTIMEZONE definition for network location from which an up-to-date VTIMEZONE definition for
the timezone can be retrieved. the timezone can be retrieved.
While TZID labels that do not begin with a forward slash are locally While TZID labels that do not begin with a forward slash are locally
defined, it is RECOMMENDED that servers support at least the naming defined, it is RECOMMENDED that servers support at least the naming
scheme used by Olson Time Zone database [13]. Examples of timezone scheme used by Olson Time Zone database [14]. Examples of timezone
databases that use the Olson scheme are the zoneinfo files on most databases that use the Olson scheme are the zoneinfo files on most
Unix-like systems, and the standard Java TimeZone class. Unix-like systems, and the standard Java TimeZone class.
If a script is uploaded with a tzid and tzurl which the CPL server Servers SHOULD resolve TZID and TZURL references to time zone
does not recognize or cannot resolve, it SHOULD diagnose and reject definitions at the time the script is uploaded. They MAY periodically
this at script upload time. If neither tzid nor tzurl are present, refresh these resolutions to obtain the most up-to-date definition of
all non-UTC times within this time switch should be interpreted as a time zone. If a TZURL becomes invalid, servers SHOULD remember the
being "floating" times, i.e. that they are specified in the local most recent valid data retrieved from the URL.
timezone of the CPL server.
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 Because of daylight-savings-time changes over the course of
a year, it is necessary to specify time switches in a given a year, it is necessary to specify time switches in a given
timezone. UTC offsets are not sufficient, or a time-of-day timezone. UTC offsets are not sufficient, or a time-of-day
routing rule which held between 9 am and 5 pm in the routing rule which held between 9 am and 5 pm in the
eastern United States would start holding between 8 am and eastern United States would start holding between 8 am and
4 pm at the end of October. 4 pm at the end of October.
Authors of CPL servers should be careful to handle correctly the Authors of CPL servers should be careful to handle correctly the
intervals when local time is discontinuous, at the beginning or end intervals when local time is discontinuous, at the beginning or end
of daylight-savings time. Note especially that some times may occur of daylight-savings time. Note especially that some times may occur
more than once when clocks are set back. The algorithm in Appendix A more than once when clocks are set back. The algorithm in Appendix A
is believed to handle this correctly. is believed to handle this correctly.
Time nodes specify a list of periods during which their output should Time nodes specify a list of periods during which their output should
be taken. They have two required parameters: dtstart, which specifies be taken. They have two required parameters: "dtstart", which
the beginning of the first period of the list, and exactly one of specifies the beginning of the first period of the list, and exactly
dtend or duration, which specify the ending time or the duration of one of "dtend" or "duration", which specify the ending time or the
the period, respectively. The dtstart and dtend parameters are duration of the period, respectively. The "dtstart" and "dtend"
formatted as iCal COS DATE-TIME values, as specified in Section 4.3.5 parameters are formatted as iCalendar COS DATE-TIME values, as
of RFC 2445 [12]. Because time zones are specified in the top-level specified in Section 4.3.5 of RFC 2445 [13]. Because time zones are
time-switch tag, only forms 1 or 2 (floating or UTC times) can be specified in the top-level "time-switch" tag, only forms 1 or 2
used. The duration parameter is given as an iCal COS DURATION (floating or UTC times) can be used. The "duration" parameter is
parameter, as specified in section 4.3.6 of RFC 2445. Both the DATE- given as an iCalendar COS DURATION parameter, as specified in section
TIME and the DURATION syntaxes are subsets of the corresponding 4.3.6 of RFC 2445. Both the DATE-TIME and the DURATION syntaxes are
syntaxes from ISO 8601 [14]. subsets of the corresponding syntaxes from ISO 8601 [15].
For a recurring interval, the duration parameter MUST be less than For a recurring interval, the "duration" parameter MUST be small
twenty-four hours. For non-recurring intervals, durations of any enough such that subsequent intervals do not overlap.
length are permitted.
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 If no other parameters are specified, a time node indicates only a
single period of time. More complicated sets periods intervals are single period of time. More complicated sets periods intervals are
constructed as recurrences. A recurrence is specified by including constructed as recurrences. A recurrence is specified by including
the freq parameter, which indicates the type of recurrence rule. No the "freq" parameter, which indicates the type of recurrence rule. No
parameters other than dtstart, dtend, and duration SHOULD be parameters other than "dtstart", "dtend", and "duration" SHOULD be
specified unless freq is present. 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: daily, to The "freq" parameter takes one of the following values: "secondly",
specify repeating periods based on an interval of a day or more; to specify repeating periods based on an interval of a second or
weekly, to specify repeating periods based on an interval of a week more; "minutely", to specify repeating periods based on an interval
or more; monthly, to specify repeating periods based on an interval of a minute or more; "hourly", to specify repeating periods based on
of a month or more; and yearly, to specify repeating periods based on an interval of an hour or more;
an interval of a year or more. These values are not case-sensitive.
The values secondly, minutely, and hourly are present in "daily", to specify repeating periods based on an interval of a day
iCal, but were removed from CPL. 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 The "interval" parameter contains a positive integer representing how
often the recurrence rule repeats. The default value is "1", meaning often the recurrence rule repeats. The default value is "1", meaning
every day for a daily rule, every week for a weekly rule, every month every day for a "daily" rule, every week for a "weekly" rule, every
for a monthly rule and every year for a yearly rule. month for a "monthly" rule and every year for a "yearly" rule.
The until parameter defines an iCal COS DATE or DATE-TIME value which The "until" parameter defines an iCalendar COS DATE or DATE-TIME
bounds the recurrence rule in an inclusive manner. If the value value which bounds the recurrence rule in an inclusive manner. If the
specified by until is synchronized with the specified recurrence, value specified by "until" is synchronized with the specified
this date or date-time becomes the last instance of the recurrence. recurrence, this date or date-time becomes the last instance of the
If specified as a date-time value, then it MUST be specified in an recurrence. If specified as a date-time value, then it MUST be
UTC time format. If not present, the recurrence is considered to specified in an UTC time format. If not present, and the "count"
repeat forever. parameter is not also present, the recurrence is considered to repeat
forever.
iCal also defines a count parameter, which allows an The "count" parameter defines the number of occurrences at which to
alternate method of specifying a bound to a recurrence. range-bound the recurrence. The "dtstart" parameter counts as the
This bound has been removed from CPL. Translating from full first occurrence. The "until" and "count" parameters MUST NOT occur
iCal recurrences to CPL recurrences requires that the count in the same "time" output.
parameter be converted to an until parameter, which can be
done by enumerating the recurrence and determining its
final date.
The byday parameter specifies a comma-separated list of days of the The "bysecond" parameter specifies a comma-separated list of seconds
week. MO indicates Monday; TU indicates Tuesday; WE indicates within a minute. Valid values are 0 to 59. The "byminute" parameter
Wednesday; TH indicates Thursday; FR indicates Friday; SA indicates specifies a comma-separated list of minutes within an hour. Valid
Saturday; SU indicates Sunday. These values are not case-sensitive. values are 0 to 59. The "byhour" parameter specifies a comma-
separated list of hours of the day. Valid values are 0 to 23.
Each byday value can also be preceded by a positive (+n) or negative The "byday" parameter specifies a comma-separated list of days of the
(-n) integer. If present, this indicates the nth occurrence of the week. "MO" indicates Monday; "TU" indicates Tuesday; "WE" indicates
specific day within the monthly or yearly recurrence. For example, Wednesday; "TH" indicates Thursday; "FR" indicates Friday; "SA"
within a monthly rule, +1MO (or simply 1MO) represents the first indicates Saturday; "SU" indicates Sunday. These values are not
Monday within the month, whereas -1MO represents the last Monday of case-sensitive.
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 Each "byday" value can also be preceded by a positive (+n) or
the month. Valid values are 1 to 31 or -31 to -1. For example, -10 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. represents the tenth to the last day of the month.
The byyearday parameter specifies a comma-separated list of days of 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 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 last day of the year (December 31st) and -306
represents the 306th to the last day of the year (March 1st). represents the 306th to the last day of the year (March 1st).
The byweekno parameter specifies a comma-separated list of ordinals 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. 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 This corresponds to weeks according to week numbering as defined in
ISO 8601 [14]. A week is defined as a seven day period, starting on ISO 8601 [15]. 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 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 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 least four (4) days in that calendar year. This parameter is only
valid for yearly rules. For example, 3 represents the third week of valid for "yearly" rules. For example, 3 represents the third week of
the year. the year.
Note: Assuming a Monday week start, week 53 can only occur Note: Assuming a Monday week start, week 53 can only occur
when Thursday is January 1 or if it is a leap year and when Thursday is January 1 or if it is a leap year and
Wednesday is January 1. Wednesday is January 1.
The bymonth parameter specifies a comma-separated list of months of The "bymonth" parameter specifies a comma-separated list of months of
the year. Valid values are 1 to 12. the year. Valid values are 1 to 12.
The wkst parameter specifies the day on which the workweek starts. The "wkst" parameter specifies the day on which the workweek starts.
Valid values are MO, TU, WE, TH, FR, SA and SU. This is significant Valid values are "MO", "TU", "WE", "TH", "FR", "SA" and "SU". This is
when a weekly recurrence has an interval greater than 1, and a byday significant when a "weekly" recurrence has an interval greater than
parameter is specified. This is also significant in a yearly 1, and a "byday" parameter is specified. This is also significant in
recurrence when a byweekno parameter is specified. The default value a "yearly" recurrence when a "byweekno" parameter is specified. The
is MO, following ISO 8601 [14]. default value is "MO", following ISO 8601 [15].
iCal also includes the Byxxx parameters bysecond, byminute, The "bysetpos" parameter specifies a comma-separated list of values
byhour, and bysetpos, which have been removed from CPL. 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"
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 If byxxx parameter values are found which are beyond the available
scope (ie, bymonthday="30" in February), they are simply ignored. scope (ie, bymonthday="30" in February), they are simply ignored.
Byxxx parameters modify the recurrence in some manner. Byxxx rule Byxxx parameters modify the recurrence in some manner. Byxxx rule
parts for a period of time which is the same or greater than the 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 frequency generally reduce or limit the number of occurrences of the
recurrence generated. For example, freq="daily" bymonth="1" reduces recurrence generated. For example, freq="daily" bymonth="1" reduces
the number of recurrence instances from all days (if the bymonth the number of recurrence instances from all days (if the "bymonth"
parameter is not present) to all days in January. Byxxx parameters parameter is not present) to all days in January. Byxxx parameters
for a period of time less than the frequency generally increase or for a period of time less than the frequency generally increase or
expand the number of occurrences of the recurrence. For example, expand the number of occurrences of the recurrence. For example,
freq="yearly" bymonth="1,2" increases the number of days within the freq="yearly" bymonth="1,2" increases the number of days within the
yearly recurrence set from 1 (if bymonth parameter is not present) to yearly recurrence set from 1 (if "bymonth" parameter is not present)
2. to 2.
If multiple Byxxx parameters are specified, then after evaluating the If multiple Byxxx parameters are specified, then after evaluating the
specified freq and interval parameters, the Byxxx parameters are specified "freq" and "interval" parameters, the Byxxx parameters are
applied to the current set of evaluated occurrences in the following applied to the current set of evaluated occurrences in the following
order: bymonth, byweekno, byyearday, bymonthday, and byday; then order: "bymonth", "byweekno", "byyearday", "bymonthday", "byday",
until is evaluated. "byhour", "byminute", "bysecond" and "bysetpos"; then "count" and
"until" are evaluated.
Here is an example of evaluating multiple Byxxx parameters. Here is an example of evaluating multiple Byxxx parameters.
<time dtstart="19970105T083000" duration="PT10M" <time dtstart="19970105T083000" duration="10M"
freq="yearly" interval="2" bymonth="1" byday="SU"> 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 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 other year." Then, bymonth="1" would be applied to arrive
at "every January, every other year." Then, byday="SU" would be at "every January, every other year." Then, byday="SU" would be
applied to arrive at "every Sunday in January, every other year." applied to arrive at "every Sunday in January, every other year."
Then the time of day is derived from dtstart to end up in "every Then, byhour="8,9" would be applied to arrive at "every Sunday in
Sunday in January from 8:30:00 AM to 8:40:00 AM, every other year." January at 8 AM and 9 AM, every other year." Then, byminute="30"
Similarly, if the byday, bymonthday or bymonth parameter were would be applied to arrive at "every Sunday in January at 8:30 AM and
missing, the appropriate day or month would have been retrieved from 9:30 AM, every other year." Then the second is derived from "dtstart"
the dtstart parameter. 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 iCal COS RDATE, EXRULE and EXDATE recurrence rules are not The iCalendar COS RDATE, EXRULE and EXDATE recurrence rules are not
specifically mapped to components of the time-switch node. Equivalent specifically mapped to components of the time-switch node. Equivalent
functionality to the exception rules can be attained by using the functionality to the exception rules can be attained by using the
ordering of switch rules to exclude times using earlier rules; ordering of switch rules to exclude times using earlier rules;
equivalent functionality to the additional-date RDATE rules can be equivalent functionality to the additional-date RDATE rules can be
attained by using sub nodes (see Section 9) to link multiple outputs attained by using "sub" nodes (see Section 9) to link multiple
to the same subsequent node. outputs to the same subsequent node.
The not-present output is never true for a time switch. However, it The "not-present" output is never true for a time switch. However, it
MAY be included, to allow switch processing to be more regular. MAY be included, to allow switch processing to be more regular.
5.3.1 Motivations for the iCal Subset 5.4.1 iCalendar differences and implementation issues
(This sub-sub-section is non-normative.) (This sub-sub-section is non-normative.)
The syntax of the CPL time-switch was based on that of the iCal COS The specification of recurring events in this section is identical
RRULE, but as mentioned above, certain features were omitted and (except for syntax and formatting issues) to that of RFC 2445 [13],
restrictions were added. Specifically: with only one additional restriction. That one restriction is that
consecutive instances of recurrence intervals may not overlap.
1. All recurrence intervals and rules describing periods less It was a matter of some debate, during the design of the CPL, whether
than a day were removed. These were the frequencies the entire iCalendar COS recurrence specification should be included
secondly, minutely, and hourly, and the Byxxx rules in CPL, or whether only a subset should be included. It was
bysecond, byminute, and byhour. eventually decided that compatibility between the two protocols was
of primary importance. This imposes some additional implementation
issues on implementors of CPL servers.
2. The count and bysetpos parameters were removed. 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:
3. Durations were constrained to less than 24 hours for o The "count" parameter cannot be checked in constant running
recurring intervals. 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" paramter
once, off-line, to determime the date of the last recurrence.
This date can then be treated as a virtual "until" parameter
for the server's internal processing.
These restrictions were added so that time switches could be resolved o Similarly, the "bysetpos" parameter requires that the server
efficiently, in O(1) time. This restriction means that it must be enumerate all instances of the currence from the start of the
possible to resolve a time switch without having to enumerate all its current recurrence set until the present time. This requires
recurrences from dtstart to the present interval. As far as we have somewhat more complex pre-processing, but generally, a single
been able to determine, it is not possible to test whether the count recurrence with a "bysetpos" parameter can be split up into
and bysetpos parameters are satisfied without performing such an several recurrences without them.
enumeration.
Constant running time of time switches also requires that a candidate o Finally, constant running time of time switches also requires
starting time for a recurrence can be established quickly and that a candidate starting time for a recurrence can be
uniquely, to check whether it satisfies the other restrictions. This established quickly and uniquely, to check whether it
requires that a recurrence's duration not be longer than its satisfies the other restrictions. This requires that a
repetition interval, so that a given instant cannot fall within recurrence's duration not be longer than its repetition
several consecutive repetitions of the recurrence. We guaranteed this interval, so that a given instant cannot fall within several
by eliminating durations longer than 24 hours, and repetitions consecutive potential repetitions of the recurrence. The
shorter than that period. The one-day point seemed to be the most restriction that consecutive intervals not overlap partially
generally useful place to place this division, as some investigation satisfies this condition, but does not fully ensure it. Again,
showed that many common calendaring applications do not support to some extent pre-processing can help resolve this.
durations longer than a day, none that we found supported repetitions
shorter than a day. Eliminating sub-day repetitions also greatly
simplifies the handling of daylight-savings transitions.
The algorithm given in Appendix A runs in constant time, and The algorithm given in Appendix A runs in constant time after these
motivated the development of this iCal subset. pre-processing steps.
5.4 Priority Switches 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.
5.5 Priority Switches
Priority switches allow a CPL script to make decisions based on the Priority switches allow a CPL script to make decisions based on the
priority specified for the original call. They are summarized in priority specified for the original call. They are summarized in
Figure 7. They are dependent on the underlying signalling protocol. Figure 8. They are dependent on the underlying signalling protocol.
Node: priority-switch Node: "priority-switch"
Outputs: priority Specific priority to match Outputs: "priority" Specific priority to match
Parameters: None Parameters: None
Output: priority Output: "priority"
Parameters: less Match if priority is less than specified Parameters: "less" Match if priority is less than specified
greater Match if priority is greater than specified "greater" Match if priority is greater than specified
equal Match if priority is equal to specified "equal" Match if priority is equal to specified
Figure 7: Syntax of the priority-switch node Figure 8: Syntax of the "priority-switch" node
Priority switches take no parameters. Priority switches take no parameters.
The priority tags take one of the three parameters greater, less, and The "priority" tags take one of the three parameters "greater",
equal. The values of these tags are one of the following priorities: "less", and "equal". The values of these tags are one of the
in decreasing order, emergency, urgent, normal, and non-urgent. These following priorities: in decreasing order, "emergency", "urgent",
values are matched in a case-insensitive manner. Outputs with the "normal", and "non-urgent". These values are matched in a case-
less parameter are taken if the priority of the call is less than the insensitive manner. Outputs with the "less" parameter are taken if
priority given in the argument; and so forth. the priority of the call is less than the priority given in the
argument; and so forth.
If no priority header is specified in a message, the priority is If no priority header is specified in a message, the priority is
considered to be normal. If an unknown priority is specified in the 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 call, it is considered to be equivalent to "normal" for the purposes
greater and less comparisons, but it is compared literally for equal of "greater" and "less" comparisons, but it is compared literally for
comparisons. "equal" comparisons.
Since every message has a priority, the not-present output is never Since every message has a priority, the "not-present" output is never
true for a priority switch. However, it MAY be included, to allow true for a priority switch. However, it MAY be included, to allow
switch processing to be more regular. switch processing to be more regular.
5.4.1 Usage of priority-switch with SIP 5.5.1 Usage of "priority-switch" with SIP
The priority of a SIP message corresponds to the Priority header in The priority of a SIP message corresponds to the "Priority" header in
the initial INVITE message. the initial "INVITE" message.
6 Location Modifiers 6 Location Modifiers
The abstract location model of the CPL is described in Section 2.3. The abstract location model of the CPL is described in Section 2.3.
The behavior of several of the signalling operations (defined in The behavior of several of the signalling operations (defined in
Section 7) is dependent on the current location set specified. Section 7) is dependent on the current location set specified.
Location nodes add or remove locations from the location set. Location nodes add or remove locations from the location set.
There are three types of location nodes defined. Explicit locations There are three types of location nodes defined. Explicit locations
add literally-specified locations to the current location set; add literally-specified locations to the current location set;
location lookups obtain locations from some outside source; and location lookups obtain locations from some outside source; and
location filters remove locations from the set, based on some location filters remove locations from the set, based on some
specified criteria. specified criteria.
6.1 Explicit Location 6.1 Explicit Location
Explicit location nodes specify a location literally. Their syntax is Explicit location nodes specify a location literally. Their syntax is
described in Figure 8. described in Figure 9.
Explicit location nodes are dependent on the underlying signalling Explicit location nodes are dependent on the underlying signalling
protocol. protocol.
Node: location Node: "location"
Outputs: None (next node follows directly) Outputs: None (next node follows directly)
Next node: Any node Next node: Any node
Parameters: url URL of address to add to location set Parameters: "url" URL of address to add to location set
priority Priority of this location (0.0-1.0) "priority" Priority of this location (0.0-1.0)
clear Whether to clear the location set before adding "clear" Whether to clear the location set before adding
the new value the new value
Figure 8: Syntax of the location node Figure 9: Syntax of the "location" node
Explicit location nodes have three node parameters. The mandatory url Explicit location nodes have three node parameters. The mandatory
parameter's value is the URL of the address to add to the location "url" parameter's value is the URL of the address to add to the
set. Only one address may be specified per location node; multiple location set. Only one address may be specified per location node;
locations may be specified by cascading these nodes. multiple locations may be specified by cascading these nodes.
The optional priority parameter specifies a priority for the The optional "priority" parameter specifies a priority for the
location. Its value is a floating-point number between 0.0 and 1.0. 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 If it is not specified, the server SHOULD assume a default priority
of 1.0. The optional clear parameter specifies whether the location of 1.0. The optional "clear" parameter specifies whether the location
set should be cleared before adding the new location to it. Its value set should be cleared before adding the new location to it. Its value
can be "yes" or "no", with "no" as the default. can be "yes" or "no", with "no" as the default.
Basic location nodes have only one possible result, since there is no Basic location nodes have only one possible result, since there is no
way that they can fail. (If a basic location node specifies a way that they can fail. (If a basic location node specifies a
location which isn't supported by the underlying signalling protocol, location which isn't supported by the underlying signalling protocol,
the script server SHOULD detect this and report it to the user at the the script server SHOULD detect this and report it to the user at the
time the script is submitted.) Therefore, their XML representations time the script is submitted.) Therefore, their XML representations
do not have explicit output tags; the <location> tag directly do not have explicit output tags; the <location> tag directly
contains another node. contains another node.
6.1.1 Usage of location with SIP 6.1.1 Usage of "location" with SIP
All SIP locations are represented as URLs, so the locations specified All SIP locations are represented as URLs, so the locations specified
in location tags are interpreted directly. in "location" tags are interpreted directly.
6.2 Location Lookup 6.2 Location Lookup
Locations can also be specified up through external means, through Locations can also be specified up through external means, through
the use of location lookups. The syntax of these tags is given in the use of location lookups. The syntax of these tags is given in
Figure 9. Figure 10.
Location lookup is dependent on the underlying signalling protocol. Location lookup is dependent on the underlying signalling protocol.
Node: lookup Node: "lookup"
Outputs: success Next node if lookup was successful Outputs: "success" Next node if lookup was successful
notfound Next node if lookup found no addresses "notfound" Next node if lookup found no addresses
failure Next node if lookup failed "failure" Next node if lookup failed
Parameters: source Source of the lookup Parameters: "source" Source of the lookup
timeout Time to try before giving up on the lookup "timeout" Time to try before giving up on the lookup
use Caller preferences fields to use "use" Caller preferences fields to use
ignore Caller preferences fields to ignore "ignore" Caller preferences fields to ignore
clear Whether to clear the location set before adding "clear" Whether to clear the location set before adding
the new values the new values
Output: success Output: "success"
Parameters: none Parameters: none
Output: notfound Output: "notfound"
Parameters: none Parameters: none
Output: failure Output: "failure"
Parameters: none Parameters: none
Figure 9: Syntax of the lookup node Figure 10: Syntax of the "lookup" node
Location lookup nodes have one mandatory parameter, and four optional Location lookup nodes have one mandatory parameter, and four optional
parameters. The mandatory parameter is source, the source of the 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 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 "source" is a URI, it indicates a location which the CPL server can
query to obtain an object with the text/uri-list media type (see the query to obtain an object with the text/uri-list media type (see the
IANA registration of this type, which also appears in RFC 2483 [15]). IANA registration of this type, which also appears in RFC 2483 [16]).
The query is performed verbatim, with no additional information (such The query is performed verbatim, with no additional information (such
as URI parameters) added. The server adds the locations contained in as URI parameters) added. The server adds the locations contained in
this object to the location set. this object to the location set.
CPL servers MAY refuse to allow URI-based sources for location CPL servers MAY refuse to allow URI-based sources for location
queries for some or all URI schemes. In this case, they SHOULD reject queries for some or all URI schemes. In this case, they SHOULD reject
the script at script upload time. the script at script upload time.
There has been discussion of having CPL servers add URI There has been discussion of having CPL servers add URI
parameters to the location request, so that (for instance) parameters to the location request, so that (for instance)
CGI scripts could be used to resolve them. However, the CGI scripts could be used to resolve them. However, the
consensus was that this should be a CPL extension, not a consensus was that this should be a CPL extension, not a
part of the base specification. part of the base specification.
Non-URL sources indicate a source not specified by a URL which the 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 server can query for addresses to add to the location set. The only
non-URL source currently defined is registration, which specifies all non-URL source currently defined is "registration", which specifies
the locations currently registered with the server. all the locations currently registered with the server.
The lookup node also has four optional parameters. The timeout The "lookup" node also has four optional parameters. The "timeout"
parameter specifies the time, in seconds, the script is willing to parameter specifies the time, as a positive integer number of
wait for the lookup to be performed. If this is not specified, its seconds, the script is willing to wait for the lookup to be
default value is 30. The clear parameter specifies whether the performed. If this is not specified, its default value is 30. The
location set should be cleared before the new locations are added. "clear" parameter specifies whether the location set should be
cleared before the new locations are added.
The other two optional parameters affect the interworking of the CPL The other two optional parameters affect the interworking of the CPL
script with caller preferences and caller capabilities. By default, script with caller preferences and caller capabilities. By default,
a CPL server SHOULD invoke the appropriate caller preferences a CPL server SHOULD invoke the appropriate caller preferences
filtering of the underlying signalling protocol, if the corresponding filtering of the underlying signalling protocol, if the corresponding
information is available. The two parameters use and ignore allow the information is available. The two parameters "use" and "ignore" allow
script to modify how the script applies caller preferences filtering. the script to modify how the script applies caller preferences
The specific meaning of the values of these parameters is filtering. The specific meaning of the values of these parameters is
signalling-protocol dependent; see Section 6.2.1 for SIP and Appendix signalling-protocol dependent; see Section 6.2.1 for SIP and Appendix
B.5 for H.323. B.6 for H.323.
Lookup has three outputs: success, notfound, and failure. Notfound is Lookup has three outputs: "success", "notfound", and "failure".
taken if the lookup process succeeded but did not find any locations; Notfound is taken if the lookup process succeeded but did not find
failure is taken if the lookup failed for some reason, including that any locations; failure is taken if the lookup failed for some reason,
specified timeout was exceeded. If a given output is not present, including that specified timeout was exceeded. If a given output is
script execution terminates and the default behavior is performed. not present, script execution terminates and the default behavior is
performed.
Clients SHOULD specify the three outputs success, notfound, and Clients SHOULD specify the three outputs "success", "notfound", and
failure in that order, so their script complies with the DTD given in "failure" in that order, so their script complies with the DTD given
Appendix C, but servers MAY accept them in any order. in Appendix C, but servers MAY accept them in any order.
6.2.1 Usage of lookup with SIP 6.2.1 Usage of "lookup" with SIP
Caller preferences for SIP are defined in "SIP Caller Preferences and Caller preferences for SIP are defined in "SIP Caller Preferences and
Callee Capabilities" [16]. By default, a CPL server SHOULD honor any Callee Capabilities" [17]. By default, a CPL server SHOULD honor any
Accept-Contact and Reject-Contact headers of the original call "Accept-Contact" and "Reject-Contact" headers of the original call
request, as specified in that document. The two parameters use and request, as specified in that document. The two parameters "use" and
ignore allow the script to modify the data input to the caller "ignore" allow the script to modify the data input to the caller
preferences algorithm. These parameters both take as their arguments preferences algorithm. These parameters both take as their arguments
comma-separated lists of caller preferences parameters. If use is comma-separated lists of caller preferences parameters. If "use" is
given, the server applies the caller preferences resolution algorithm given, the server applies the caller preferences resolution algorithm
only to those preference parameters given in the use parameter, and only to those preference parameters given in the "use" parameter, and
ignores all others; if the ignore parameter is given, the server ignores all others; if the "ignore" parameter is given, the server
ignores the specified parameters, and uses all the others. Only one ignores the specified parameters, and uses all the others. Only one
of use and ignore can be specified. of "use" and "ignore" can be specified.
The addr-spec part of the caller preferences is always applied, and The addr-spec part of the caller preferences is always applied, and
the script cannot modify it. the script cannot modify it.
If a SIP server does not support caller preferences and callee If a SIP server does not support caller preferences and callee
capabilities, if the call request does not contain any preferences, capabilities, if the call request does not contain any preferences,
or if the callee's registrations do not contain any capabilities, the or if the callee's registrations do not contain any capabilities, the
use and ignore parameters are ignored. "use" and "ignore" parameters are ignored.
6.3 Location Removal 6.3 Location Removal
A CPL script can also remove locations from the location set, through 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 the use of the "remove-location" node. The syntax of this node is
defined in Figure 10. defined in Figure 11.
The meaning of this node is dependent on the underlying signalling The meaning of this node is dependent on the underlying signalling
protocol. protocol.
Node: remove-location Node: "remove-location"
Outputs: None (next node follows directly) Outputs: None (next node follows directly)
Next node: Any node Next node: Any node
Parameters: location Location to remove Parameters: "location" Location to remove
param Caller preference parameters to apply "param" Caller preference parameters to apply
value Value of caller preference parameters "value" Value of caller preference parameters
Figure 10: Syntax of the remove-location node Figure 11: Syntax of the "remove-location" node
A remove-location node removes locations from the location set. It is A "remove-location" node removes locations from the location set. It
primarily useful following a lookup node. An example of this is is primarily useful following a "lookup" node. An example of this is
given in Section 13.8. given in Section 13.8.
The remove-location node has three optional parameters. The parameter The "remove-location" node has three optional parameters. The
location gives the URL (or a signalling-protocol-dependent URL parameter "location" gives the URL (or a signalling-protocol-
pattern) of location or locations to be removed from the set. If this dependent URL pattern) of location or locations to be removed from
parameter is not given, all locations, subject to the constraints of the set. If this parameter is not given, all locations, subject to
the other parameters, are removed from the set. the constraints of the other parameters, are removed from the set.
If param and value are present, their values are comma-separated If param and value are present, their values are comma-separated
lists of caller preferences parameters and corresponding values, lists of caller preferences parameters and corresponding values,
respectively. The nth entry in the param list matches the nth entry respectively. The nth entry in the param list matches the nth entry
in the value list. There MUST be the same number of parameters as in the value list. There MUST be the same number of parameters as
values specified. The meaning of these parameters is signalling- values specified. The meaning of these parameters is signalling-
protocol dependent. protocol dependent.
The remove-location node has no explicit output tags. In the XML The "remove-location" node has no explicit output tags. In the XML
syntax, the XML remove-location tag directly encloses the next node's syntax, the XML "remove-location" tag directly encloses the next
tag. node's tag.
6.3.1 Usage of remove-location with SIP 6.3.1 Usage of "remove-location" with SIP
For SIP-based CPL servers, the remove-location node has the same For SIP-based CPL servers, the "remove-location" node has the same
effect on the location set as a Reject-Contact header in caller effect on the location set as a "Reject-Contact" header in caller
preferences [16]. The value of the location parameter is treated as preferences [17]. The value of the "location" parameter is treated as
though it were the addr-spec field of a Reject-Contact header; thus, though it were the addr-spec field of a Reject-Contact header; thus,
an absent header is equivalent to an addr-spec of "*" in that an absent header is equivalent to an addr-spec of "*" in that
specification. The param and value parameters are treated as though specification. The "param" and "value" parameters are treated as
they appeared in the params field of a Reject-Location header, as "; though they appeared in the params field of a Reject-Location header,
param=value" for each one. as "; param=value" for each one.
If the CPL server does not support caller preferences and callee If the CPL server does not support caller preferences and callee
capabilities, or if the callee did not supply any preferences, the capabilities, or if the callee did not supply any preferences, the
param and value parameters are ignored. "param" and "value" parameters are ignored.
7 Signalling Operations 7 Signalling Operations
Signalling operation nodes cause signalling events in the underlying Signalling operation nodes cause signalling events in the underlying
signalling protocol. Three signalling operations are defined: signalling protocol. Three signalling operations are defined:
"proxy," "redirect," and "reject." "proxy," "redirect," and "reject."
7.1 Proxy 7.1 Proxy
Proxy causes the triggering call to be forwarded on to the currently Proxy causes the triggering call to be forwarded on to the currently
specified set of locations. The syntax of the proxy node is given in specified set of locations. The syntax of the proxy node is given in
Figure 11. Figure 12.
The specific signalling events invoked by the proxy node are The specific signalling events invoked by the "proxy" node are
signalling-protocol-dependent, though the general concept should signalling-protocol-dependent, though the general concept should
apply to any signalling protocol. apply to any signalling protocol.
After a proxy operation has completed, the CPL server chooses the After a proxy operation has completed, the CPL server chooses the
"best" response to the call attempt, as defined by the signalling "best" response to the call attempt, as defined by the signalling
protocol or the server's administrative configuration rules. protocol or the server's administrative configuration rules.
If the call attempt was successful, CPL execution terminates and the Node: "proxy"
server proceeds to its default behavior (normally, to allow the call Outputs: "busy" Next node if call attempt returned "busy"
Node: proxy "noanswer" Next node if call attempt was not answered
Outputs: busy Next node if call attempt returned "busy" before timeout
noanswer Next node if call attempt was not answered before timeout "redirection" Next node if call attempt was redirected
redirection Next node if call attempt was redirected "failure" Next node if call attempt failed
failure Next node if call attempt failed "default" Default next node for unspecified outputs
default Default next node for unspecified outputs Parameters: "timeout" Time to try before giving up on the call attempt
Parameters: timeout Time to try before giving up on the call attempt "recurse" Whether to recursively look up redirections
recurse Whether to recursively look up redirections "ordering" What order to try the location set in.
ordering What order to try the location set in.
Output: busy Output: "busy"
Parameters: none Parameters: none
Output: noanswer Output: "noanswer"
Parameters: none Parameters: none
Output: redirection Output: "redirection"
Parameters: none Parameters: none
Output: failure Output: "failure"
Parameters: none Parameters: none
Output: default Output: "default"
Parameters: none Parameters: none
Figure 11: Syntax of the proxy node Figure 12: Syntax of the "proxy" node
If the call attempt was successful, CPL execution terminates and the
server proceeds to its default behavior (normally, to allow the call
to be set up). Otherwise, the next node corresponding to one of the to be set up). Otherwise, the next node corresponding to one of the
proxy node's outputs is taken. The busy output is followed if the "proxy" node's outputs is taken. The "busy" output is followed if the
call was busy; noanswer is followed if the call was not answered call was busy; "noanswer" is followed if the call was not answered
before the timeout parameter expired; redirection is followed if the before the "timeout" parameter expired; "redirection" is followed if
call was redirected; and failure is followed if the call setup failed the call was redirected; and "failure" is followed if the call setup
for any other reason. failed for any other reason.
If one of the conditions above is true, but the corresponding output If one of the conditions above is true, but the corresponding output
was not specified, the default output of the proxy node is followed was not specified, the "default" output of the "proxy" node is
instead. If there is also no default node specified, CPL execution followed instead. If there is also no "default" node specified, CPL
terminates and the server returns to its default behavior (normally, execution terminates and the server returns to its default behavior
to forward the best response upstream to the originator). (normally, to forward the best response upstream to the originator).
Note: CPL extensions to allow in-call or end-of-call Note: CPL extensions to allow in-call or end-of-call
operations will require an additional output, such as operations will require an additional output, such as
success, to be added. "success", to be added.
If no locations were present in the set, or if the only locations in If no locations were present in the set, or if the only locations in
the set were locations to which the server cannot proxy a call (for the set were locations to which the server cannot proxy a call (for
example, "http" URLs), the failure output is taken. example, "http" URLs), the "failure" output is taken.
Proxy has three optional parameters. The timeout parameter specifies Proxy has three optional parameters. The "timeout" parameter
the time, in seconds, to wait for the call to be completed or specifies the time, as a positive integer number of seconds, to wait
rejected; after this time has elapsed, the call attempt is terminated for the call to be completed or rejected; after this time has
and the noanswer branch is taken. If this parameter is not specified, elapsed, the call attempt is terminated and the "noanswer" branch is
the default value is 20 seconds if the proxy node has a noanswer or taken. If this parameter is not specified, the default value is 20
default output specified; otherwise the server SHOULD allow the call seconds if the "proxy" node has a "noanswer" or "default" output
to ring for a reasonably long period of time (to the maximum extent specified; otherwise the server SHOULD allow the call to ring for a
that server policy allows). reasonably long period of time (to the maximum extent that server
policy allows).
The second optional parameter is recurse, which can take two values, The second optional parameter is "recurse", which can take two
yes or no. This specifies whether the server should automatically values, "yes" or "no". This specifies whether the server should
attempt to place further call attempts to telephony addresses in automatically attempt to place further call attempts to telephony
redirection responses that were returned from the initial server. addresses in redirection responses that were returned from the
Note that if the value of recurse is yes, the redirection output to initial server. Note that if the value of "recurse" is "yes", the
the script is never taken. In this case this output SHOULD NOT be "redirection" output to the script is never taken. In this case this
present. The default value of this parameter is yes. output SHOULD NOT be present. The default value of this parameter is
"yes".
The third optional parameter is ordering. This can have three The third optional parameter is "ordering". This can have three
possible values: parallel, sequential, and first-only. This possible values: "parallel", "sequential", and "first-only". This
parameter specifies in what order the locations of the location set parameter specifies in what order the locations of the location set
should be tried. Parallel asks that they all be tried simultaneously; should be tried. Parallel asks that they all be tried simultaneously;
sequential asks that the one with the highest priority be tried sequential asks that the one with the highest priority be tried
first, the one with the next-highest priority second, and so forth, first, the one with the next-highest priority second, and so forth,
until one succeeds or the set is exhausted. First-only instructs the until one succeeds or the set is exhausted. First-only instructs the
server to try only the highest-priority address in the set, and then server to try only the highest-priority address in the set, and then
follow one of the outputs. The priority of locations in a set is follow one of the outputs. The priority of locations in a set is
determined by server policy, though CPL servers SHOULD honor the determined by server policy, though CPL servers SHOULD honor the
priority parameter of the location tag. The default value of this "priority" parameter of the "location" tag. The default value of this
parameter is parallel. parameter is "parallel".
Once a proxy operation completes, if control is passed on to other Once a proxy operation completes, if control is passed on to other
nodes, all locations which have been used are cleared from the nodes, all locations which have been used are cleared from the
location set. That is, the location set is emptied of proxyable location set. That is, the location set is emptied of proxyable
locations if the ordering was parallel or sequential; the highest- locations if the "ordering" was "parallel" or "sequential"; the
priority item in the set is removed from the set if ordering was highest-priority item in the set is removed from the set if
first-only. (In all cases, non-proxyable locations such as "http" "ordering" was "first-only". (In all cases, non-proxyable locations
URIs remain.) In the case of a redirection output, the new addresses such as "http" URIs remain.) In the case of a "redirection" output,
to which the call was redirected are then added to the location set. the new addresses to which the call was redirected are then added to
the location set.
7.1.1 Usage of proxy with SIP 7.1.1 Usage of "proxy" with SIP
For SIP, the best response to a proxy node is determined by the For SIP, the best response to a "proxy" node is determined by the
algorithm of the SIP specification. The node's outputs correspond to algorithm of the SIP specification. The node's outputs correspond to
the following events: the following events:
busy A 486 or 600 response was the best response received to the "busy" A 486 or 600 response was the best response received to
call request. the call request.
redirection A 3xx response was the best response received to the "redirection" A 3xx response was the best response received to
call request. the call request.
failure Any other 4xx, 5xx, or 6xx response was the best "failure" Any other 4xx, 5xx, or 6xx response was the best
response received to the call request. response received to the call request.
no-answer No final response was received to the call request "no-answer" No final response was received to the call request
before the timeout expired. before the timeout expired.
SIP servers SHOULD honor the q parameter of SIP registrations and the SIP servers SHOULD honor the "q" parameter of SIP registrations and
output of the caller preferences lookup algorithm when determining the output of the caller preferences lookup algorithm when
location priority. determining location priority.
7.2 Redirect 7.2 Redirect
Redirect causes the server to direct the calling party to attempt to Redirect causes the server to direct the calling party to attempt to
place its call to the currently specified set of locations. The place its call to the currently specified set of locations. The
syntax of this node is specified in Figure 12. syntax of this node is specified in Figure 13.
The specific behavior the redirect node invokes is dependent on the The specific behavior the redirect node invokes is dependent on the
underlying signalling protocol involved, though its semantics are underlying signalling protocol involved, though its semantics are
generally applicable. generally applicable.
Node: redirect Node: "redirect"
Outputs: None (no node may follow) Outputs: None (no node may follow)
Next node: None Next node: None
Parameters: permanent Whether the redirection should be Parameters: "permanent" Whether the redirection should be
considered permanent considered permanent
Figure 12: Syntax of the redirect node Figure 13: Syntax of the "redirect" node
Redirect immediately terminates execution of the CPL script, so this Redirect immediately terminates execution of the CPL script, so this
node has no outputs and no next node. It has one parameter, node has no outputs and no next node. It has one parameter,
permanent, which specifies whether the result returned should "permanent", which specifies whether the result returned should
indicate that this is a permanent redirection. The value of this indicate that this is a permanent redirection. The value of this
parameter is either "yes" or "no" and its default value is "no." parameter is either "yes" or "no" and its default value is "no."
7.2.1 Usage of redirect with SIP 7.2.1 Usage of "redirect" with SIP
The SIP server SHOULD send a 3xx class response to a call request The SIP server SHOULD send a 3xx class response to a call request
upon executing a redirect tag. If permanent was yes, the server upon executing a "redirect" tag. If "permanent" was "yes", the server
SHOULD send the response "301 Moved permanently"; otherwise it SHOULD SHOULD send the response "301 Moved permanently"; otherwise it SHOULD
send "302 Moved temporarily". send "302 Moved temporarily".
7.3 Reject 7.3 Reject
Reject nodes cause the server to reject the call attempt. Their Reject nodes cause the server to reject the call attempt. Their
syntax is given in Figure 13. The specific behavior they invoke is syntax is given in Figure 14. The specific behavior they invoke is
dependent on the underlying signalling protocol involved, though dependent on the underlying signalling protocol involved, though
their semantics are generally applicable. their semantics are generally applicable.
Node: reject Node: "reject"
Outputs: None (no node may follow) Outputs: None (no node may follow)
Next node: None Next node: None
Parameters: status Status code to return Parameters: "status" Status code to return
reason Reason phrase to return "reason" Reason phrase to return
Figure 13: Syntax of the reject node Figure 14: Syntax of the "reject" node
This immediately terminates execution of the CPL script, so this node This immediately terminates execution of the CPL script, so this node
has no outputs and no next node. has no outputs and no next node.
This node has two arguments: status and reason. The status argument This node has two arguments: "status" and "reason". The "status"
is required, and can take one of the values busy, notfound, reject, argument is required, and can take one of the values "busy",
and error, or a signalling-protocol-defined status. "notfound", "reject", and "error", or a signalling-protocol-defined
status.
The reason argument optionally allows the script to specify a reason The "reason" argument optionally allows the script to specify a
for the rejection. reason for the rejection.
7.3.1 Usage of reject with SIP 7.3.1 Usage of "reject" with SIP
Servers which implement SIP SHOULD also allow the status field to be Servers which implement SIP SHOULD also allow the "status" field to
a numeric argument corresponding to a SIP status in the 4xx, 5xx, or be a numeric argument corresponding to a SIP status in the 4xx, 5xx,
6xx range. or 6xx range.
They SHOULD send the "reason" parameter in the SIP reason phrase. They SHOULD send the "reason" parameter in the SIP reason phrase.
A suggested mapping of the named statuses is as follows. Servers MAY A suggested mapping of the named statuses is as follows. Servers MAY
use a different mapping, though similar semantics SHOULD be use a different mapping, though similar semantics SHOULD be
preserved. preserved.
busy: 486 Busy Here "busy": 486 Busy Here
notfound: 404 Not Found "notfound": 404 Not Found
reject: 603 Decline
error: 500 Internal Server Error "reject": 603 Decline
"error": 500 Internal Server Error
8 Non-signalling Operations 8 Non-signalling Operations
In addition to the signalling operations , the CPL defines several In addition to the signalling operations , the CPL defines several
operations which do not affect and are not dependent on the telephony operations which do not affect and are not dependent on the telephony
signalling protocol. signalling protocol.
8.1 Mail 8.1 Mail
The mail node causes the server to notify a user of the status of the The mail node causes the server to notify a user of the status of the
CPL script through electronic mail. Its syntax is given in Figure 14. CPL script through electronic mail. Its syntax is given in Figure 15.
Node: mail Node: "mail"
Outputs: None (next node follows directly) Outputs: None (next node follows directly)
Next node: Any node Next node: Any node
Parameters: url Mailto url to which the mail should be sent Parameters: "url" Mailto url to which the mail should be sent
Figure 14: Syntax of the mail node Figure 15: Syntax of the "mail" node
The mail node takes one argument: a mailto URL giving the address, The "mail" node takes one argument: a mailto URL giving the address,
and any additional desired parameters, of the mail to be sent. The and any additional desired parameters, of the mail to be sent. The
server sends the message containing the content to the given url; it server sends the message containing the content to the given url; it
SHOULD also include other status information about the original call SHOULD also include other status information about the original call
request and the CPL script at the time of the notification. request and the CPL script at the time of the notification.
Using a full mailto URL rather than just an e-mail address Using a full mailto URL rather than just an e-mail address
allows additional e-mail headers to be specified, such as allows additional e-mail headers to be specified, such as
<mail <mail
url="mailto:jones@example.com?subject=lookup%20failed" />. url="mailto:jones@example.com?subject=lookup%20failed" />.
Mail nodes have only one possible result, since failure of e-mail Mail nodes have only one possible result, since failure of e-mail
delivery cannot reliably be known in real-time. Therefore, its XML delivery cannot reliably be known in real-time. Therefore, its XML
representation does not have output tags: the <mail> tag directly representation does not have output tags: the <mail> tag directly
contains another node tag. contains another node tag.
Note that the syntax of XML requires that ampersand characters, "&", Note that the syntax of XML requires that ampersand characters, "&",
which are used as parameter separators in mailto URLs, be quoted as which are used as parameter separators in "mailto" URLs, be quoted as
"&amp;" inside parameter values (see Section C.12 of [3]). "&amp;" inside parameter values (see Section C.12 of [3]).
8.1.1 Suggested Content of Mailed Information 8.1.1 Suggested Content of Mailed Information
This section presents suggested guidelines for the mail sent as a This section presents suggested guidelines for the mail sent as a
result of the mail node, for requests triggered by SIP. The message result of the "mail" node, for requests triggered by SIP. The message
mailed (triggered by any protocol) SHOULD contain all this mailed (triggered by any protocol) SHOULD contain all this
information, but servers MAY elect to use a different format. information, but servers MAY elect to use a different format.
1. If the mailto URI did not specify a subject header, the 1. If the "mailto" URI did not specify a subject header, the
subject of the e-mail is "[CPL]" followed by the subject subject of the e-mail is "[CPL]" followed by the subject
header of the SIP request. If the URI specified a subject header of the SIP request. If the URI specified a subject
header, it is used instead. header, it is used instead.
2. The From field of the e-mail is set to a CPL server 2. The "From" field of the e-mail is set to a CPL server
configured address, overriding any From field in the mailto configured address, overriding any "From" field in the
URI. "mailto" URI.
3. Any Reply-To header in the URI is honored. If none is 3. Any "Reply-To" header in the URI is honored. If none is
given, then an e-mail-ized version of the origin field of given, then an e-mail-ized version of the origin field of
the request is used, if possible (e.g., a SIP From header the request is used, if possible (e.g., a SIP "From" header
with a sip: URI would be converted to an e-mail address by with a sip: URI would be converted to an e-mail address by
stripping the URI scheme). stripping the URI scheme).
4. If the mailto URI specifies a body, it is used. If none was 4. If the "mailto" URI specifies a body, it is used. If none
specified, the body SHOULD contain at least the identity of was specified, the body SHOULD contain at least the
the caller (both the caller's display name and address), identity of the caller (both the caller's display name and
the date and time of day, the call subject, and if address), the date and time of day, the call subject, and
available, the call priority. if available, the call priority.
The server SHOULD honor the user's requested languages, and send the The server SHOULD honor the user's requested languages, and send the
mail notification using an appropriate language and character set. mail notification using an appropriate language and character set.
8.2 Log 8.2 Log
The Log node causes the server to log information about the call to The Log node causes the server to log information about the call to
non-volatile storage. Its syntax is specified in Figure 15. non-volatile storage. Its syntax is specified in Figure 16.
Node: log Log takes two arguments, both optional: "name", which specifies the
name of the log, and "comment", which gives a comment about the
information being logged. Servers SHOULD also include other
information in the log, such as the time of the logged event,
information that triggered the call to be logged, and so forth. Logs
Node: "log"
Outputs: None (next node follows directly) Outputs: None (next node follows directly)
Next node: Any node Next node: Any node
Parameters: name Name of the log file to use Parameters: "name" Name of the log file to use
comment Comment to be placed in log file "comment" Comment to be placed in log file
Figure 15: Syntax of the log node Figure 16: Syntax of the "log" node
Log takes two arguments, both optional: name, which specifies the
name of the log, and comment, which gives a comment about the
information being logged. Servers SHOULD also include other
information in the log, such as the time of the logged event,
information that triggered the call to be logged, and so forth. Logs
are specific to the owner of the script which logged the event. If are specific to the owner of the script which logged the event. If
the name parameter is not given, the event is logged to a standard, the "name" parameter is not given, the event is logged to a standard,
server-defined log file for the script owner. This specification does server-defined log file for the script owner. This specification does
not define how users may retrieve their logs from the server. not define how users may retrieve their logs from the server.
The name of a log is a logical name only, and does not necessarily The name of a log is a logical name only, and does not necessarily
correspond to any physical file on the server. The interpretation of correspond to any physical file on the server. The interpretation of
the log file name is server defined, as is a mechanism to access the log file name is server defined, as is a mechanism to access
these logs. The CPL server SHOULD NOT directly map log names these logs. The CPL server SHOULD NOT directly map log names
uninterpreted onto local file names, for security reasons, lest a uninterpreted onto local file names, for security reasons, lest a
security-critical file be overwritten. security-critical file be overwritten.
A correctly operating CPL server SHOULD NOT ever allow the log event A correctly operating CPL server SHOULD NOT ever allow the "log"
to fail. As such, log nodes can have only one possible result, and event to fail. As such, log nodes can have only one possible result,
their XML representation does not have explicit output tags. A CPL and their XML representation does not have explicit output tags. A
<log> tag directly contains another node tag. CPL <log> tag directly contains another node tag.
9 Subactions 9 Subactions
XML syntax defines a tree. To allow more general call flow diagrams, XML syntax defines a tree. To allow more general call flow diagrams,
and to allow script re-use and modularity, we define subactions. and to allow script re-use and modularity, we define subactions.
Two tags are defined for subactions: subaction definitions and Two tags are defined for subactions: subaction definitions and
subaction references. Their syntax is given in Figure 16. subaction references. Their syntax is given in Figure 17.
Tag: subaction
Subtags: Any node
Parameters: id Name of this subaction
Pseudo-node: sub Subactions are defined through "subaction" tags. These tags are
Outputs: None in XML tree placed in the CPL after any ancillary information (see Section 10)
Parameters: ref Name of subaction to execute but before any top-level tags. They take one argument: "id", a token
indicating a script-chosen name for the subaction. The "id" value for
every "subaction" tag in a script MUST be unique within that script.
Figure 16: Syntax of subactions and sub pseudo-nodes Subactions are called from "sub" tags. The "sub" tag is a "pseudo-
node": it can be used anyplace in a CPL action that a true node could
be used. It takes one parameter, "ref", the name of the subaction to
be called. The "sub" tag contains no outputs of its own; control
instead passes to the subaction.
Subactions are defined through subaction tags. These tags are placed Tag: "subaction"
in the CPL after any ancillary information (see Section 10) but Subtags: Any node
before any top-level tags. They take one argument: id, a token Parameters: "id" Name of this subaction
indicating a script-chosen name for the subaction.
Subactions are called from sub tags. The sub tag is a "pseudo-node": Pseudo-node: "sub"
Outputs: None in XML tree
Parameters: "ref" Name of subaction to execute
it can be used anyplace in a CPL action that a true node could be Figure 17: Syntax of subactions and "sub" pseudo-nodes
used. It takes one parameter, ref, the name of the subaction to be
called. The sub tag contains no outputs of its own; control instead
passes to the subaction.
References to subactions MUST refer to subactions defined before the References to subactions MUST refer to subactions defined before the
current action. A sub tag MUST NOT refer to the action which it current action. A "sub" tag MUST NOT refer to the action which it
appears in, or to any action defined later in the CPL script. Top- appears in, or to any action defined later in the CPL script. Top-
level actions cannot be called from sub tags, or through any other level actions cannot be called from "sub" tags, or through any other
means. Script servers MUST verify at the time the script is submitted means. Script servers MUST verify at the time the script is submitted
that no sub node refers to any subaction which is not its proper that no "sub" node refers to any subaction which is not its proper
predecessor. predecessor.
Allowing only back-references of subs forbids any sort of Allowing only back-references of subs forbids any sort of
recursion. Recursion would introduce the possibility of recursion. Recursion would introduce the possibility of
non-terminating or non-decidable CPL scripts, a possibility non-terminating or non-decidable CPL scripts, a possibility
our requirements specifically excluded. our requirements specifically excluded.
Every sub MUST refer to a subaction ID defined within the same CPL Every sub MUST refer to a subaction ID defined within the same CPL
script. No external links are permitted. script. No external links are permitted.
Subaction IDs are case sensitive. Subaction IDs are case sensitive.
If any subsequent version or extension defines external If any subsequent version or extension defines external
linkages, it should probably use a different tag, perhaps linkages, it should probably use a different tag, perhaps
XLink [17]. Ensuring termination in the presence of XLink [18]. Ensuring termination in the presence of
external links is a difficult problem. external links is a difficult problem.
10 Ancillary Information 10 Ancillary Information
No ancillary information is defined in the base CPL specification. If No ancillary information is defined in the base CPL specification. If
ancillary information, not part of any operation, is found to be ancillary information, not part of any operation, is found to be
necessary for a CPL extension, it SHOULD be placed within this tag. necessary for a CPL extension, it SHOULD be placed within this tag.
The (trivial) definition of the ancillary information tag is given in The (trivial) definition of the ancillary information tag is given in
Figure 17. Figure 18.
It may be useful to include timezone definitions inside CPL It may be useful to include timezone definitions inside CPL
scripts directly, rather than referencing them externally scripts directly, rather than referencing them externally
with tzid and tzurl parameters. If it is, an extension with "tzid" and "tzurl" parameters. If it is, an extension
could be defined to include them here. could be defined to include them here.
11 Default Behavior Tag: "ancillary"
Tag: ancillary
Parameters: None Parameters: None
Subtags: None Subtags: None
Figure 17: Syntax of the ancillary tag Figure 18: Syntax of the "ancillary" tag
11 Default Behavior
When a CPL node reaches an unspecified output, either because the When a CPL node reaches an unspecified output, either because the
output tag is not present, or because the tag is present but does not output tag is not present, or because the tag is present but does not
contain a node, the CPL server's behavior is dependent on the current contain a node, the CPL server's behavior is dependent on the current
state of script execution. This section gives the operations that state of script execution. This section gives the operations that
should be taken in each case. should be taken in each case.
no location modifications or signalling operations performed, no location modifications or signalling operations performed,
location set empty: Look up the user's location through location set empty: Look up the user's location through
whatever mechanism the server would use if no CPL script whatever mechanism the server would use if no CPL script
skipping to change at page 34, line 31 skipping to change at page 36, line 39
absence of a CPL script. absence of a CPL script.
no location modifications or signalling operations performed, no location modifications or signalling operations performed,
location set non-empty: (This can only happen for outgoing location set non-empty: (This can only happen for outgoing
calls.) Proxy the call to the addresses in the location calls.) Proxy the call to the addresses in the location
set. set.
location modifications performed, no signalling operations: location modifications performed, no signalling operations:
Proxy or redirect the call, whichever is the server's Proxy or redirect the call, whichever is the server's
standard policy, to the addresses in the current location standard policy, to the addresses in the current location
set. If the location set is empty, return notfound set. If the location set is empty, return "notfound"
rejection. rejection.
noanswer output of proxy, no timeout given: (This is a special noanswer output of proxy, no timeout given: (This is a special
case.) If the noanswer output of a proxy node is case.) If the "noanswer" output of a proxy node is
unspecified, and no timeout parameter was given to the unspecified, and no timeout parameter was given to the
proxy node, the call should be allowed to ring for the proxy node, the call should be allowed to ring for the
maximum length of time allowed by the server (or the maximum length of time allowed by the server (or the
request, if the request specified a timeout). request, if the request specified a timeout).
proxy operation previously taken: Return whatever the "best" proxy operation previously taken: Return whatever the "best"
response is of all accumulated responses to the call to response is of all accumulated responses to the call to
this point, according to the rules of the underlying this point, according to the rules of the underlying
signalling protocol. signalling protocol.
skipping to change at page 35, line 4 skipping to change at page 37, line 11
proxy node, the call should be allowed to ring for the proxy node, the call should be allowed to ring for the
maximum length of time allowed by the server (or the maximum length of time allowed by the server (or the
request, if the request specified a timeout). request, if the request specified a timeout).
proxy operation previously taken: Return whatever the "best" proxy operation previously taken: Return whatever the "best"
response is of all accumulated responses to the call to response is of all accumulated responses to the call to
this point, according to the rules of the underlying this point, according to the rules of the underlying
signalling protocol. signalling protocol.
12 CPL Extensions 12 CPL Extensions
Servers MAY support additional CPL features beyond those listed in Servers MAY support additional CPL features beyond those listed in
this document. Some of the extensions which have been suggested are a this document. Some of the extensions which have been suggested are a
means of querying how a call has been authenticated; richer control means of querying how a call has been authenticated; richer control
over H.323 addressing; end-system or administrator-specific features; over H.323 addressing; end-system or administrator-specific features;
regular-expression matching for strings and addresses; mid-call or regular-expression matching for strings and addresses; mid-call or
end-of-call controls; and the parts of iCal COS recurrence rules end-of-call controls; and the parts of iCalendar COS recurrence rules
omitted from time switches. omitted from time switches.
CPL extensions are indicated by XML namespaces [18]. Every extension CPL extensions are indicated by XML namespaces [19]. Every extension
MUST have an appropriate XML namespace assigned to it. All XML tags MUST have an appropriate XML namespace assigned to it. All XML tags
and attributes that are part of the extension MUST be appropriately and attributes that are part of the extension MUST be appropriately
qualified so as to place them within that namespace. qualified so as to place them within that namespace.
Tags or attributes in a CPL script which are in the global namespace Tags or attributes in a CPL script which are in the global namespace
(i.e., not associated with any namespace) are equivalent to tags and (i.e., not associated with any namespace) are equivalent to tags and
attributes in the CPL namespace "http://www.rfc- attributes in the CPL namespace "http://www.rfc-
editor.org/rfc/rfcxxxx.txt". editor.org/rfc/rfcxxxx.txt".
A CPL server MUST reject any script which contains a reference to a A CPL server MUST reject any script which contains a reference to a
skipping to change at page 35, line 44 skipping to change at page 38, line 4
<extension-switch> <extension-switch>
<extension has="http://www.example.com/foo"> <extension has="http://www.example.com/foo">
[extended things] [extended things]
</extension> </extension>
<otherwise> <otherwise>
[non-extended things] [non-extended things]
</otherwise> </otherwise>
</extension-switch> </extension-switch>
was suggested as an alternate way of handling extensions. was suggested as an alternate way of handling extensions.
This would allow scripts to be uploaded to a server without This would allow scripts to be uploaded to a server without
requiring a script author to somehow determine which requiring a script author to somehow determine which
extensions a server supports. However, experience extensions a server supports. However, experience
developing other languages, notably Sieve [19], was that developing other languages, notably Sieve [20], was that
this added excessive complexity to languages. The this added excessive complexity to languages. The
extension-switch tag could, of course, itself be defined in "extension-switch" tag could, of course, itself be defined
a CPL extension. in a CPL extension.
It is unfortunately true that XML DTDs, such as the CPL DTD It is unfortunately true that XML DTDs, such as the CPL DTD
given in Appendix C, are not powerful enough to encompass given in Appendix C, are not powerful enough to encompass
namespaces, since the base XML specification (which defines namespaces, since the base XML specification (which defines
DTDs) predates the XML namespace specification. XML schemas DTDs) predates the XML namespace specification. XML schemas
[20] are a work in progress to define a namespace-aware [21] are a work in progress to define a namespace-aware
method for validating XML documents, as well as improving method for validating XML documents, as well as improving
upon DTDs' expressive power in many other ways. upon DTDs' expressive power in many other ways.
13 Examples 13 Examples
13.1 Example: Call Redirect Unconditional 13.1 Example: Call Redirect Unconditional
The script in Figure 18 is a simple script which redirects all calls The script in Figure 19 is a simple script which redirects all calls
to a single fixed location. to a single fixed location.
<?xml version="1.0" ?> <?xml version="1.0" ?>
<!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd">
<cpl> <cpl>
<incoming> <incoming>
<location url="sip:smith@phone.example.com"> <location url="sip:smith@phone.example.com">
<redirect /> <redirect />
</location> </location>
</incoming> </incoming>
</cpl> </cpl>
Figure 18: Example Script: Call Redirect Unconditional Figure 19: Example Script: Call Redirect Unconditional
13.2 Example: Call Forward Busy/No Answer 13.2 Example: Call Forward Busy/No Answer
The script in Figure 19 illustrates some more complex behavior. We The script in Figure 20 illustrates some more complex behavior. We
see an initial proxy attempt to one address, with further operations see an initial proxy attempt to one address, with further operations
if that fails. We also see how several outputs take the same action if that fails. We also see how several outputs take the same action
subtree, through the use of subactions. subtree, through the use of subactions.
13.3 Example: Call Forward: Redirect and Default
The script in Figure 20 illustrates further proxy behavior. The
server initially tries to proxy to a single address. If this attempt
is redirected, a new redirection is generated using the locations
returned. In all other failure cases for the proxy node, a default
operation -- forwarding to voicemail -- is performed.
<?xml version="1.0" ?> <?xml version="1.0" ?>
<!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd">
<cpl> <cpl>
<subaction id="voicemail"> <subaction id="voicemail">
<location url="sip:jones@voicemail.example.com" > <location url="sip:jones@voicemail.example.com" >
<proxy /> <proxy />
</location> </location>
</subaction> </subaction>
skipping to change at page 37, line 29 skipping to change at page 39, line 29
<sub ref="voicemail" /> <sub ref="voicemail" />
</busy> </busy>
<noanswer> <noanswer>
<sub ref="voicemail" /> <sub ref="voicemail" />
</noanswer> </noanswer>
</proxy> </proxy>
</location> </location>
</incoming> </incoming>
</cpl> </cpl>
Figure 19: Example Script: Call Forward Busy/No Answer Figure 20: Example Script: Call Forward Busy/No Answer
13.3 Example: Call Forward: Redirect and Default
The script in Figure 21 illustrates further proxy behavior. The
server initially tries to proxy to a single address. If this attempt
is redirected, a new redirection is generated using the locations
returned. In all other failure cases for the proxy node, a default
operation -- forwarding to voicemail -- is performed.
13.4 Example: Call Screening 13.4 Example: Call Screening
The script in Figure 21 illustrates address switches and call The script in Figure 22 illustrates address switches and call
rejection, in the form of a call screening script. Note also that rejection, in the form of a call screening script. Note also that
because the address-switch lacks an otherwise clause, if the initial because the address-switch lacks an "otherwise" clause, if the
pattern did not match, the script does not define any operations. The initial pattern did not match, the script does not define any
server therefore proceeds with its default behavior, which would operations. The server therefore proceeds with its default behavior,
presumably be to contact the user. which would presumably be to contact the user.
13.5 Example: Priority and Language Routing
The script in Figure 22 illustrates service selection based on a
call's priority value and language settings. If the call request had
a priority of "urgent" or higher, the default script behavior is
performed. Otherwise, the language string field is checked for the
string "es" (Spanish). If it is present, the call is proxied to a
Spanish-speaking operator; other calls are proxied to an English-
<?xml version="1.0" ?> <?xml version="1.0" ?>
<!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd">
<cpl> <cpl>
<subaction id="voicemail">
</subaction>
<incoming> <incoming>
<location url="sip:jones@jonespc.example.com"> <location url="sip:jones@jonespc.example.com">
<proxy> <proxy>
<redirection> <redirection>
<redirect /> <redirect />
</redirection> </redirection>
<default> <default>
<location url="sip:jones@voicemail.example.com" > <location url="sip:jones@voicemail.example.com" >
<proxy /> <proxy />
</location> </location>
</default> </default>
</proxy> </proxy>
</location> </location>
</incoming> </incoming>
</cpl> </cpl>
Figure 20: Example Script: Call Forward: Redirect and Default Figure 21: Example Script: Call Forward: Redirect and Default
<?xml version="1.0" ?> <?xml version="1.0" ?>
<!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd">
<cpl> <cpl>
<incoming> <incoming>
<address-switch field="origin" subfield="user"> <address-switch field="origin" subfield="user">
<address is="anonymous"> <address is="anonymous">
<reject status="reject" <reject status="reject"
reason="I don't accept anonymous calls" /> reason="I don't accept anonymous calls" />
</address> </address>
</address-switch> </address-switch>
</incoming> </incoming>
</cpl> </cpl>
Figure 21: Example Script: Call Screening Figure 22: Example Script: Call Screening
speaking operator.
13.5 Example: Priority and Language Routing
The script in Figure 23 illustrates service selection based on a
call's priority value and language settings. If the call request had
a priority of "urgent" or higher, the default script behavior is
performed. Otherwise, the language field is checked for the language
"es" (Spanish). If it is present, the call is proxied to a Spanish-
speaking operator; other calls are proxied to an English-speaking
operator.
<?xml version="1.0" ?> <?xml version="1.0" ?>
<!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd">
<cpl> <cpl>
<incoming> <incoming>
<priority-switch> <priority-switch>
<priority greater="urgent" /> <priority greater="urgent" />
<otherwise> <otherwise>
<string-switch field="language"> <language-switch>
<string contains="es"> <language matches="es">
<location url="sip:spanish@operator.example.com"> <location url="sip:spanish@operator.example.com">
<proxy /> <proxy />
</location> </location>
</string> </language>
<otherwise> <otherwise>
<location url="sip:english@operator.example.com"> <location url="sip:english@operator.example.com">
<proxy /> <proxy />
</location> </location>
</otherwise> </otherwise>
</string-switch> </language-switch>
</otherwise> </otherwise>
</priority-switch> </priority-switch>
</incoming> </incoming>
</cpl> </cpl>
Figure 22: Example Script: Priority and Language Routing Figure 23: Example Script: Priority and Language Routing
13.6 Example: Outgoing Call Screening 13.6 Example: Outgoing Call Screening
The script in Figure 23 illustrates a script filtering outgoing The script in Figure 24 illustrates a script filtering outgoing
calls, in the form of a script which prevent 1-900 (premium) calls calls, in the form of a script which prevent 1-900 (premium) calls
from being placed. This script also illustrates subdomain matching. from being placed. This script also illustrates subdomain matching.
13.7 Example: Time-of-day Routing 13.7 Example: Time-of-day Routing
Figure 24 illustrates time-based conditions and timezones. Figure 25 illustrates time-based conditions and timezones.
13.8 Example: Location Filtering
Figure 25 illustrates filtering operations on the location set. In
<?xml version="1.0" ?> <?xml version="1.0" ?>
<!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd">
<cpl> <cpl>
<outgoing> <outgoing>
<address-switch field="original-destination" subfield="tel"> <address-switch field="original-destination" subfield="tel">
<address subdomain-of="1900"> <address subdomain-of="1900">
<reject status="reject" <reject status="reject"
reason="Not allowed to make 1-900 calls." /> reason="Not allowed to make 1-900 calls." />
</address> </address>
</address-switch> </address-switch>
</outgoing> </outgoing>
</cpl> </cpl>
Figure 23: Example Script: Outgoing Call Screening Figure 24: Example Script: Outgoing Call Screening
<?xml version="1.0" ?> <?xml version="1.0" ?>
<!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd">
<cpl> <cpl>
<incoming> <incoming>
<time-switch tzid="America/New_York" <time-switch tzid="America/New_York"
tzurl="http://zones.example.com/tz/America/New_York"> tzurl="http://zones.example.com/tz/America/New_York">
<time dtstart="20000703T090000" duration="PT8H" <time dtstart="20000703T090000" duration="PT8H"
freq="weekly" byday="MO,TU,WE,TH,FR"> freq="weekly" byday="MO,TU,WE,TH,FR">
skipping to change at page 40, line 44 skipping to change at page 42, line 45
</time> </time>
<otherwise> <otherwise>
<location url="sip:jones@voicemail.example.com"> <location url="sip:jones@voicemail.example.com">
<proxy /> <proxy />
</location> </location>
</otherwise> </otherwise>
</time-switch> </time-switch>
</incoming> </incoming>
</cpl> </cpl>
Figure 24: Example Script: Time-of-day Routing Figure 25: Example Script: Time-of-day Routing
13.8 Example: Location Filtering
Figure 26 illustrates filtering operations on the location set. In
this example, we assume that version 0.9beta2 of the "Inadequate this example, we assume that version 0.9beta2 of the "Inadequate
Software SIP User Agent" mis-implements some features, and so we must Software SIP User Agent" mis-implements some features, and so we must
work around its problems. We assume, first, that the value of its work around its problems. We assume, first, that the value of its
"feature" parameter in caller preferences is known to be unreliable,
so we ignore it; we also know that it cannot talk successfully to one
particular mobile device we may have registered, so we remove that particular mobile device we may have registered, so we remove that
location from the location set. Once these two operations have been location from the location set. Once these two operations have been
completed, call setup is allowed to proceed normally. completed, call setup is allowed to proceed normally.
<?xml version="1.0" ?> <?xml version="1.0" ?>
<!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd">
<cpl> <cpl>
<incoming> <incoming>
<string-switch field="user-agent"> <string-switch field="user-agent">
skipping to change at page 41, line 27 skipping to change at page 43, line 36
<remove-location location="sip:me@mobile.provider.net"> <remove-location location="sip:me@mobile.provider.net">
<proxy /> <proxy />
</remove-location> </remove-location>
</success> </success>
</lookup> </lookup>
</string> </string>
</string-switch> </string-switch>
</incoming> </incoming>
</cpl> </cpl>
Figure 25: Example Script: Location Filtering Figure 26: Example Script: Location Filtering
13.9 Example: Non-signalling Operations 13.9 Example: Non-signalling Operations
Figure 26 illustrates non-signalling operations; in particular, Figure 27 illustrates non-signalling operations; in particular,
alerting a user by electronic mail if the lookup server failed. The alerting a user by electronic mail if the lookup server failed. The
primary motivation for having the mail node is to allow this sort of primary motivation for having the "mail" node is to allow this sort
out-of-band notification of error conditions, as the user might of out-of-band notification of error conditions, as the user might
otherwise be unaware of any problem. otherwise be unaware of any problem.
13.10 Example: Hypothetical Extensions 13.10 Example: Hypothetical Extensions
The example in Figure 27 shows a hypothetical extension which
implements distinctive ringing. The XML namespace
"http://www.example.com/distinctive-ring" specifies a new node named
ring.
The example in Figure 28 implements a hypothetical new attribute for
address switches, to allow regular-expression matches. It defines a
<?xml version="1.0" ?> <?xml version="1.0" ?>
<!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd">
<cpl> <cpl>
<incoming> <incoming>
<lookup source="http://www.example.com/cgi-bin/locate.cgi?user=jones" <lookup
source="http://www.example.com/cgi-bin/locate.cgi?user=jones"
timeout="8"> timeout="8">
<success> <success>
<proxy /> <proxy />
</success> </success>
<failure> <failure>
<mail url="mailto:jones@example.com?subject=lookup%20failed" /> <mail url="mailto:jones@example.com?subject=lookup%20failed" />
</failure> </failure>
</lookup> </lookup>
</incoming> </incoming>
</cpl> </cpl>
Figure 26: Example Script: Non-signalling Operations Figure 27: Example Script: Non-signalling Operations
The example in Figure 28 shows a hypothetical extension which
implements distinctive ringing. The XML namespace
"http://www.example.com/distinctive-ring" specifies a new node named
"ring".
<?xml version="1.0" ?> <?xml version="1.0" ?>
<!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd">
<cpl xmlns="http://www.ietf.org/internet-drafts/draft-ietf-iptel-cpl-03.txt" <cpl xmlns="http://www.rfc-editor.org/rfc/rfcXXXX.txt"
xmlns:dr="http://www.example.com/distinctive-ring"> xmlns:dr="http://www.example.com/distinctive-ring">
<incoming> <incoming>
<address-switch field="origin"> <address-switch field="origin">
<address is="sip:boss@example.com"> <address is="sip:boss@example.com">
<dr:ring ringstyle="warble" /> <dr:ring ringstyle="warble" />
</address> </address>
</address-switch> </address-switch>
</incoming> </incoming>
</cpl> </cpl>
Figure 27: Example Script: Hypothetical Distinctive-Ringing Extension Figure 28: Example Script: Hypothetical Distinctive-Ringing Extension
The example in Figure 29 implements a hypothetical new attribute for
new attribute regex for the standard address node. In this example, address switches, to allow regular-expression matches. It defines a
the global namespace is not specified. new attribute "regex" for the standard "address" node. In this
example, the global namespace is not specified.
13.11 Example: A Complex Example
Finally, Figure 29 is a complex example which shows the sort of
<?xml version="1.0" ?> <?xml version="1.0" ?>
<!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd">
<cpl> <cpl>
<incoming> <incoming>
<address-switch field="origin" subfield="user" <address-switch field="origin" subfield="user"
xmlns:re="http://www.example.com/regex"> xmlns:re="http://www.example.com/regex">
<address re:regex="(.*.smith|.*.jones)"> <address re:regex="(.*.smith|.*.jones)">
<reject status="reject" <reject status="reject"
reason="I don't want to talk to Smiths or Joneses" /> reason="I don't want to talk to Smiths or Joneses" />
</address> </address>
</address-switch> </address-switch>
</incoming> </incoming>
</cpl> </cpl>
Figure 28: Example Script: Hypothetical Regular-Expression Extension Figure 29: Example Script: Hypothetical Regular-Expression Extension
13.11 Example: A Complex Example
Finally, Figure 30 is a complex example which shows the sort of
sophisticated behavior which can be achieved by combining CPL nodes. sophisticated behavior which can be achieved by combining CPL nodes.
In this case, the user attempts to have his calls reach his desk; if In this case, the user attempts to have his calls reach his desk; if
he does not answer within a small amount of time, calls from his boss he does not answer within a small amount of time, calls from his boss
are forwarded to his mobile phone, and all other calls are directed are forwarded to his mobile phone, and all other calls are directed
to voicemail. If the call setup failed, no operation is specified, to voicemail. If the call setup failed, no operation is specified,
so the server's default behavior is performed. so the server's default behavior is performed.
14 Security Considerations 14 Security Considerations
The CPL is designed to allow services to be specified in a manner The CPL is designed to allow services to be specified in a manner
which prevents potentially hostile or mis-configured scripts from which prevents potentially hostile or mis-configured scripts from
launching security attacks, including denial-of-service attacks. launching security attacks, including denial-of-service attacks.
Because script runtime is strictly bounded by acyclicity, and because Because script runtime is strictly bounded by acyclicity, and because
the number of possible script operations are strictly limited, the number of possible script operations are strictly limited,
scripts should not be able to inflict damage upon a CPL server. scripts should not be able to inflict damage upon a CPL server.
Because scripts can direct users' telephone calls, the method by Because scripts can direct users' telephone calls, the method by
which scripts are transmitted from a client to a server MUST be which scripts are transmitted from a client to a server MUST be
strongly authenticated. Such a method is not specified in this
document.
Script servers SHOULD allow server administrators to control the
details of what CPL operations are permitted.
15 IANA Considerations
This document registers the MIME type application/cpl+xml. See
<?xml version="1.0" ?> <?xml version="1.0" ?>
<!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd"> <!DOCTYPE cpl PUBLIC "-//IETF//DTD RFCxxxx CPL 1.0//EN" "cpl.dtd">
<cpl> <cpl>
<subaction id="voicemail"> <subaction id="voicemail">
<location url="sip:jones@voicemail.example.com"> <location url="sip:jones@voicemail.example.com">
<redirect /> <redirect />
</location> </location>
</subaction> </subaction>
skipping to change at page 44, line 37 skipping to change at page 46, line 37
<otherwise> <otherwise>
<sub ref="voicemail" /> <sub ref="voicemail" />
</otherwise> </otherwise>
</address-switch> </address-switch>
</noanswer> </noanswer>
</proxy> </proxy>
</location> </location>
</incoming> </incoming>
</cpl> </cpl>
Figure 29: Example Script: A Complex Example Figure 30: Example Script: A Complex Example
strongly authenticated. Such a method is not specified in this
document.
Script servers SHOULD allow server administrators to control the
details of what CPL operations are permitted.
15 IANA Considerations
This document registers the MIME type application/cpl+xml. See
Section 3.2. Section 3.2.
16 Acknowledgments 16 Acknowledgments
This document was reviewed and commented upon by IETF IP Telephony This document was reviewed and commented upon by IETF IP Telephony
Working Group. We specifically acknowledge the following people for Working Group. We specifically acknowledge the following people for
their help: their help:
The outgoing call screening script was written by Kenny Hom. The outgoing call screening script was written by Kenny Hom.
Paul E. Jones contributed greatly to the mappings of H.323 addresses. Paul E. Jones contributed greatly to the mappings of H.323 addresses.
The text of the time-switch section was taken (lightly modified) from The text of the time-switch section was taken (lightly modified) from
RFC 2445 [12], by Frank Dawson and Derik Stenerson. RFC 2445 [13], by Frank Dawson and Derik Stenerson.
We drew a good deal of inspiration, notably the language's lack of We drew a good deal of inspiration, notably the language's lack of
Turing-completeness and the syntax of string matching, from the Turing-completeness and the syntax of string matching, from the
specification of Sieve [19], a language for user filtering of specification of Sieve [20], a language for user filtering of
electronic mail messages. electronic mail messages.
Thomas F. La Porta and Jonathan Rosenberg had many useful Thomas F. La Porta and Jonathan Rosenberg had many useful
discussions, contributions, and suggestions. discussions, contributions, and suggestions.
Richard Gumpertz performed a very useful last-minute technical and
editorial review of the specification.
A An Algorithm for Resolving Time Switches A An Algorithm for Resolving Time Switches
The following algorithm resolves, in constant time, whether a given The following algorithm determines whether a given instant falls
instant falls within a repetition of a time-switch recurrence. Open- within a repetition of a "time-switch" recurrence. If the pre-
source Java code implementing this algorithm is available on the processing described in Section 5.4.1 has been done, it operates in
world wide web at <http://www.cs.columbia.edu/~lennox/Cal-Code/> constant time. Open-source Java code implementing this algorithm is
available on the world wide web at
<http://www.cs.columbia.edu/~lennox/Cal-Code/>
This algorithm is believed to be correct, but this section is non-
normative. Section 5.4, and RFC 2445 [13], are the definitive
definitions of recurrences.
1. Compute the time of the call, in the timezone of the time 1. Compute the time of the call, in the timezone of the time
switch. (No step after this needs to consider time zones switch.
-- all calculations are done using continuously-running
standard Gregorian time.)
2. If the call time is earlier than dtstart, fail NOMATCH. 2. If the call time is earlier than "dtstart", fail NOMATCH.
3. If the call time is less than duration after dtstart, 3. If the call time is less than "duration" after dtstart,
succeed MATCH. succeed MATCH.
4. Determine the smallest unit specified in a byxxx rule or by 4. Determine the smallest unit specified in a "byxxx" rule or
the freq. Call this the Minimum Unit. Determine the by the "freq." Call this the Minimum Unit. Determine the
previous instant (before the call time) when all the time previous instant (before the call time) when all the time
units smaller than the minimum unit are the same as those units smaller than the minimum unit are the same as those
of dtstart. (For all minimum units, the time-of-day must be of "dtstart." If the minimum unit is a second, this time is
the same as dtstart. If the minimum unit is a week, the the same as the instant. If the minimum unit is a minute or
day-of-the-week must be the same as dtstart. If the minimum an hour, the minutes or the minutes and hours,
unit is a month, the day-of-the-month must be the same as respectively, must be the same as "dtstart". For all other
dtstart. If the minimum unit is a year, the month and day- minimum units, the time-of-day must be the same as
of-month must both be the same as dtstart. (Note that this "dtstart." If the minimum unit is a week, the day-of-the-
means it may be necessary to roll back more than one week must be the same as "dtstart." If the minimum unit is
a month, the day-of-the-month must be the same as
"dtstart." If the minimum unit is a year, the month and
day-of-month must both be the same as "dtstart." (Note that
this means it may be necessary to roll back more than one
minimum unit -- if the minimum unit is a month, then some minimum unit -- if the minimum unit is a month, then some
months do not have a 31st (or 30th or 29th) day; if the months do not have a 31st (or 30th or 29th) day; if the
minimum unit is a year, then some years do not have a minimum unit is a year, then some years do not have a
February 29th. In the Gregorian calendar, it is never February 29th. In the Gregorian calendar, it is never
necessary to roll back more than two months, or eight years necessary to roll back more than two months if the minimum
(four years between 1904 and 2096).) unit is a month, or eight years if the minimum unit is a
year. Between 1904 and 2096, it is never necessary to roll
back more than four years -- the eight-year rollback can
only occur when the Gregorian calendar "skips" a leap year.
Call this instant the Candidate Start Time. Call this instant the Candidate Start Time.
5. If the time between the candidate start time and the call 5. If the time between the candidate start time and the call
time is more than the duration, fail NOMATCH. time is more than the duration, fail NOMATCH.
6. If the candidate start time is later than the until 6. If the candidate start time is later than the "until"
parameter of the recurrence, fail NOMATCH. parameter of the recurrence (or the virtual "until"
computed off-line from "count") , fail NOMATCH.
7. Call the unit of the freq parameter of the recurrence the 7. Call the unit of the "freq" parameter of the recurrence the
Frequency Unit. Determine the frequency unit enclosing the Frequency Unit. Determine the frequency unit enclosing the
Candidate Start Time, and that enclosing dtstart. Calculate Candidate Start Time, and that enclosing "dtstart".
the number of frequency units that have passed between Calculate the number of frequency units that have passed
these two times. If this is not a multiple of the interval between these two times. If this is not a multiple of the
parameter, fail NOMATCH. "interval" parameter, fail NOMATCH.
8. For every byxxx rule, confirm that the candidate start time 8. For every "byxxx" rule, confirm that the candidate start
matches one of the options specified by that byxxx rule. If time matches one of the options specified by that "byxxx"
not, fail NOMATCH. rule. If so, succeed MATCH.
9. Succeed MATCH. 9. Calculate a previous candidate start time. Repeat until the
difference between the candidate start time and the call
time is more than the duration. If no candidate start time
has been validated, fail NOMATCH.
B Suggested Usage of CPL with H.323 B Suggested Usage of CPL with H.323
This appendix gives a suggested usage of CPL with H.323 [2]. Study This appendix gives a suggested usage of CPL with H.323 [2]. Study
Group 16 of the ITU, which developed H.323, is proposing to work on Group 16 of the ITU, which developed H.323, is proposing to work on
official CPL mappings for that protocol. This section is therefore official CPL mappings for that protocol. This section is therefore
not normative. not normative.
B.1 Usage of address-switch with H.323 B.1 Usage of "address-switch" with H.323
Address switches are specified in Section 5.1. This section specifies Address switches are specified in Section 5.1. This section specifies
the mapping between H.323 messages and the fields and subfields of the mapping between H.323 messages and the fields and subfields of
address-switches address-switches
For H.323, the origin address corresponds to the alias addresses in For H.323, the "origin" address corresponds to the alias addresses in
the sourceAddress field of the Setup-UUIE user-user information the "sourceAddress" field of the "Setup-UUIE" user-user information
element, and to the Q.931 [21] information element "Calling party element, and to the Q.931 [22] information element "Calling party
number." If both fields are present, or if multiple aliases addresses number." If both fields are present, or if multiple aliases addresses
for sourceAddress are present, which one has priority is a matter of for "sourceAddress" are present, which one has priority is a matter
local server policy; the server SHOULD use the same resolution as it of local server policy; the server SHOULD use the same resolution as
would use for routing decisions in this case. Similarly, the it would use for routing decisions in this case. Similarly, the
destination address corresponds to the alias addresses of the "destination" address corresponds to the alias addresses of the
destinationAddress field, and to the Q.931 information element "destinationAddress" field, and to the Q.931 information element
"Called party number." "Called party number."
The original-destination address corresponds to the "Redirecting The "original-destination" address corresponds to the "Redirecting
number" Q.931 information element, if it is present; otherwise it is number" Q.931 information element, if it is present; otherwise it is
the same as the destination address. the same as the "destination" address.
The mapping of H.323 addresses into subfields depends on the type of The mapping of H.323 addresses into subfields depends on the type of
the alias address. An additional subfield type, alias-type, is the alias address. An additional subfield type, "alias-type", is
defined for H.323 servers, corresponding to the type of the address. defined for H.323 servers, corresponding to the type of the address.
Possible values are dialedDigits, h323-ID, url-ID, transportID, Possible values are "dialedDigits", "h323-ID", "url-ID",
email-ID, partyNumber, mobileUIM, and Q.931IE. If future versions of "transportID", "email-ID", "partyNumber", "mobileUIM", and "Q.931IE".
the H.323 specification define additional types of alias addresses, If future versions of the H.323 specification define additional types
those names MAY also be used. of alias addresses, those names MAY also be used.
In versions of H.323 prior to version 4, dialedDigits was known as In versions of H.323 prior to version 4, "dialedDigits" was known as
e164. The two names SHOULD be treated as synonyms. "e164". The two names SHOULD be treated as synonyms.
The value of the address-type subfield for H.323 messages is "h323" The value of the "address-type" subfield for H.323 messages is "h323"
unless the alias type is url-ID and the URL scheme is something other unless the alias type is "url-ID" and the URL scheme is something
than h323; in this case the address-type is the URL scheme, as other than h323; in this case the address-type is the URL scheme, as
specified in Section 5.1.1 for SIP. specified in Section 5.1.1 for SIP.
An H.323-aware CPL server SHOULD map the address subfields from the An H.323-aware CPL server SHOULD map the address subfields from the
primary alias used for routing. It MAY also map subfields from other primary alias used for routing. It MAY also map subfields from other
aliases, if subfields in the primary address are not present. aliases, if subfields in the primary address are not present.
The following mappings are used for H.323 alias types: The following mappings are used for H.323 alias types:
dialedDigits, partyNumber, mobileUIM, and Q.931IE: the tel and dialedDigits, partyNumber, mobileUIM, and Q.931IE: the "tel" and
user subfields are the string of digits, as is the "user" subfields are the string of digits, as is the
"entire-address" form. The host and port subfields are not "entire-address" form. The "host" and "port" subfields are
present. not present.
url-ID: the same mappings are used as for SIP, in Section 5.1.1. url-ID: the same mappings are used as for SIP, in Section 5.1.1.
h323-ID: the user field is the string of characters, as is the h323-ID: the "user" field is the string of characters, as is the
"entire-address" form. All other subfields are not present. "entire-address" form. All other subfields are not present.
email-ID: the user and host subfields are set to the email-ID: the "user" and "host" subfields are set to the
corresponding parts of the e-mail address. The port and tel corresponding parts of the e-mail address. The "port" and
subfields are not present. The "entire-address" form "tel" subfields are not present. The "entire-address" form
corresponds to the entire e-mail address. corresponds to the entire e-mail address.
transportID: if the TransportAddress is of type "ipAddress," transportID: if the TransportAddress is of type "ipAddress,"
"ipSourceRoute," or "ip6Address," the host subfield is set "ipSourceRoute," or "ip6Address," the "host" subfield is
to the "ip" element of the sequence, translated into the set to the "ip" element of the sequence, translated into
standard IPv4 or IPv6 textual representation, and the port the standard IPv4 or IPv6 textual representation, and the
subfield is set to the "port" element of the sequence "port" subfield is set to the "port" element of the
represented in decimal. The tel and user fields are not sequence represented in decimal. The "tel" and "user"
present. The "entire-address" form is not defined. The fields are not present. The "entire-address" form is not
representation and mapping of transport addresses is not defined. The representation and mapping of transport
defined for non-IP addresses. addresses is not defined for non-IP addresses.
H.323 version 4 [22] and the Internet-Draft draft-levin-iptel-h323- H.323 version 4 [23] and the Internet-Draft draft-levin-iptel-h323-
url-scheme-00 [23] define a "h323" URI scheme. This appendix defines url-scheme-00 [24] define a "h323" URI scheme. This appendix defines
a mapping for these URIs onto the CPL address-switch subfields, as a mapping for these URIs onto the CPL "address-switch" subfields, as
given in Section 5.1. Neither of these documents has yet been given in Section 5.1. Neither of these documents has yet been
formally published in a final form, so this appendix is non- formally published in a final form, so this appendix is non-
normative. normative.
For h323 URIs, the the user, host, and port subfields are set to the For h323 URIs, the the "user", "host", and "port" subfields are set
corresponding parts of the H.323 URL. The tel subfield is not to the corresponding parts of the H.323 URL. The "tel" subfield is
present. The "entire-address" form corresponds to the entire URI. not present. The "entire-address" form corresponds to the entire URI.
This mapping MAY be used both for h323 URIs in an h323 url-ID address This mapping MAY be used both for h323 URIs in an h323 "url-ID"
alias, and for h323 URIs in SIP messages. address alias, and for h323 URIs in SIP messages.
B.2 Usage of string-switch with H.323 B.2 Usage of "string-switch" with H.323
For H.323, the string-switch node (see Section 5.2) is used as For H.323, the "string-switch" node (see Section 5.2) is used as
follows. The field language corresponds to the H.323 UUIE language, follows. The field "display" corresponds to the Q.931 information
translated to the format specified for that field. The field display element of the same name, copied verbatim. The fields "subject",
corresponds to the Q.931 information element of the same name, copied "organization", and "user-agent" are not used and are never present.
verbatim. The fields subject, organization, and user-agent are not
used and are never present.
The display IE is conventionally used for Caller-ID The "display" IE is conventionally used for Caller-ID
purposes, so arguably it should be mapped to the display purposes, so arguably it should be mapped to the "display"
subfield of an address-match with the field originator. subfield of an "address-match" with the field "originator".
However, since a) it is a message-level information However, since a) it is a message-level information
element, not an address-level one, and b) the Q.931 element, not an address-level one, and b) the Q.931
specification [21] says only that "[t]he purpose of the specification [22] says only that "[t]he purpose of the
Display information element is to supply display Display information element is to supply display
information that may be displayed by the user," it seems to information that may be displayed by the user," it seems to
be more appropriate to allow it to be matched in a string- be more appropriate to allow it to be matched in a
switch instead. "string-switch" instead.
B.3 Usage of priority-switch with H.323 B.3 Usage of "language-switch" with H.323
All H.323 messages are considered to have priority normal for the The language-ranges for the "language-switch" switch are obtained
purpose of a priority switch (see Section 5.4). from the H.323 UUIE "language". The switch is not-present if the
initial message did not contain this UUIE.
B.4 Usage of location with H.323 B.4 Usage of "priority-switch" with H.323
All H.323 messages are considered to have priority "normal" for the
purpose of a priority switch (see Section 5.5).
B.5 Usage of "location" with H.323
Locations in explicit location nodes (Section 6.1) are specified as Locations in explicit location nodes (Section 6.1) are specified as
URLs. Therefore, all locations added in this manner are interpreted URLs. Therefore, all locations added in this manner are interpreted
as being of alias type url-ID in H.323. as being of alias type "url-ID" in H.323.
Specifications of other H.323 address alias types will require a CPL Specifications of other H.323 address alias types will require a CPL
extension (see Section 12). extension (see Section 12).
B.5 Usage of lookup with H.323 B.6 Usage of "lookup" with H.323
For location lookup nodes (Section 6.2), the registration lookup For location lookup nodes (Section 6.2), the "registration" lookup
source corresponds to the locations registered with the server using source corresponds to the locations registered with the server using
RAS messages. "RAS" messages.
As H.323 currently has no counterpart of SIP caller preferences and As H.323 currently has no counterpart of SIP caller preferences and
callee capabilities, the use and ignore parameters of the lookup node callee capabilities, the "use" and "ignore" parameters of the
are ignored. "lookup" node are ignored.
B.6 Usage of remove-location with H.323 B.7 Usage of "remove-location" with H.323
For location removal nodes (Section 6.3), only literal URLs can be For location removal nodes (Section 6.3), only literal URLs can be
removed. No URL patterns are defined. removed. No URL patterns are defined.
As H.323 currently has no counterpart of SIP caller preferences and As H.323 currently has no counterpart of SIP caller preferences and
callee capabilities, the param and value parameters of the remove- callee capabilities, the "param" and "value" parameters of the
location node are ignored. "remove-location" node are ignored.
C The XML DTD for CPL C The XML DTD for CPL
This section includes a full DTD describing the XML syntax of the This section includes a full DTD describing the XML syntax of the
CPL. Every script submitted to a CPL server SHOULD comply with this CPL. Every script submitted to a CPL server SHOULD comply with this
DTD. However, CPL servers MAY allow minor variations from it, DTD. However, CPL servers MAY allow minor variations from it,
particularly in the ordering of the outputs of nodes. Note that particularly in the ordering of the outputs of nodes. Note that
compliance with this DTD is not a sufficient condition for compliance with this DTD is not a sufficient condition for
correctness of a CPL script, as many of the conditions described correctness of a CPL script, as many of the conditions described in
above are not expressible in DTD syntax. this specification are not expressible in DTD syntax.
<?xml version="1.0" encoding="US-ASCII" ?> <?xml version="1.0" encoding="US-ASCII" ?>
<!-- <!--
Draft DTD for CPL, corresponding to Draft DTD for CPL, corresponding to
draft-ietf-iptel-cpl-01. draft-ietf-iptel-cpl-01.
--> -->
<!-- Nodes. --> <!-- Nodes. -->
<!-- Switch nodes --> <!-- Switch nodes -->
<!ENTITY % Switch 'address-switch|string-switch|time-switch| <!ENTITY % Switch 'address-switch|string-switch|language-switch|
priority-switch' > time-switch|priority-switch' >
<!-- Location nodes --> <!-- Location nodes -->
<!ENTITY % Location 'location|lookup|remove-location' > <!ENTITY % Location 'location|lookup|remove-location' >
<!-- Signalling action nodes --> <!-- Signalling action nodes -->
<!ENTITY % SignallingAction 'proxy|redirect|reject' > <!ENTITY % SignallingAction 'proxy|redirect|reject' >
<!-- Other actions --> <!-- Other actions -->
<!ENTITY % OtherAction 'mail|log' > <!ENTITY % OtherAction 'mail|log' >
skipping to change at page 50, line 44 skipping to change at page 53, line 44
<!-- Switches: choices a CPL script can make. --> <!-- Switches: choices a CPL script can make. -->
<!-- All switches can have an 'otherwise' output. --> <!-- All switches can have an 'otherwise' output. -->
<!ELEMENT otherwise ( %Node; ) > <!ELEMENT otherwise ( %Node; ) >
<!-- All switches can have a 'not-present' output. --> <!-- All switches can have a 'not-present' output. -->
<!ELEMENT not-present ( %Node; ) > <!ELEMENT not-present ( %Node; ) >
<!-- Address-switch makes choices based on addresses. --> <!-- Address-switch makes choices based on addresses. -->
<!ELEMENT address-switch ( (address|not-present)+, otherwise? ) > <!ELEMENT address-switch ( (address|not-present)*, otherwise? ) >
<!-- <not-present> must appear at most once --> <!-- <not-present> must appear at most once -->
<!ATTLIST address-switch <!ATTLIST address-switch
field CDATA #REQUIRED field CDATA #REQUIRED
subfield CDATA #IMPLIED subfield CDATA #IMPLIED
> >
<!ELEMENT address ( %Node; ) > <!ELEMENT address ( %Node; ) >
<!ATTLIST address <!ATTLIST address
is CDATA #IMPLIED is CDATA #IMPLIED
contains CDATA #IMPLIED contains CDATA #IMPLIED
subdomain-of CDATA #IMPLIED subdomain-of CDATA #IMPLIED
> <!-- Exactly one of these three attributes must appear --> > <!-- Exactly one of these three attributes must appear -->
<!-- String-switch makes choices based on strings. --> <!-- String-switch makes choices based on strings. -->
<!ELEMENT string-switch ( (string|not-present)+, otherwise? ) > <!ELEMENT string-switch ( (string|not-present)*, otherwise? ) >
<!-- <not-present> must appear at most once --> <!-- <not-present> must appear at most once -->
<!ATTLIST string-switch <!ATTLIST string-switch
field CDATA #REQUIRED field CDATA #REQUIRED
> >
<!ELEMENT string ( %Node; ) > <!ELEMENT string ( %Node; ) >
<!ATTLIST string <!ATTLIST string
is CDATA #IMPLIED is CDATA #IMPLIED
contains CDATA #IMPLIED contains CDATA #IMPLIED
> <!-- Exactly one of these two attributes must appear --> > <!-- Exactly one of these two attributes must appear -->
<!-- Language-switch makes choices based on the originator's preferred
languages. -->
<!ELEMENT language-switch ( (language|not-present)*, otherwise? ) >
<!-- <not-present> must appear at most once -->
<!ELEMENT language ( %Node; ) >
<!ATTLIST language
matches CDATA #REQUIRED
>
<!-- Time-switch makes choices based on the current time. --> <!-- Time-switch makes choices based on the current time. -->
<!ELEMENT time-switch ( (time|not-present)+, otherwise? ) > <!ELEMENT time-switch ( (time|not-present)*, otherwise? ) >
<!ATTLIST time-switch <!ATTLIST time-switch
tzid CDATA #IMPLIED tzid CDATA #IMPLIED
tzurl CDATA #IMPLIED tzurl CDATA #IMPLIED
> >
<!ELEMENT time ( %Node; ) > <!ELEMENT time ( %Node; ) >
<!-- Exactly one of the two attributes "dtend" and "duration" <!-- Exactly one of the two attributes "dtend" and "duration"
must occur. --> must occur. -->
<!-- The value of "freq" is (daily|weekly|monthly|yearly). It is <!-- The value of "freq" is (daily|weekly|monthly|yearly). It is
skipping to change at page 52, line 14 skipping to change at page 55, line 27
byday CDATA #IMPLIED byday CDATA #IMPLIED
bymonthday CDATA #IMPLIED bymonthday CDATA #IMPLIED
byyearday CDATA #IMPLIED byyearday CDATA #IMPLIED
byweekno CDATA #IMPLIED byweekno CDATA #IMPLIED
bymonth CDATA #IMPLIED bymonth CDATA #IMPLIED
wkst CDATA "MO" wkst CDATA "MO"
> >
<!-- Priority-switch makes choices based on message priority. --> <!-- Priority-switch makes choices based on message priority. -->
<!ELEMENT priority-switch ( (priority|not-present)+, otherwise? ) > <!ELEMENT priority-switch ( (priority|not-present)*, otherwise? ) >
<!-- <not-present> must appear at most once --> <!-- <not-present> must appear at most once -->
<!ENTITY % PriorityVal '(emergency|urgent|normal|non-urgent)' > <!ENTITY % PriorityVal '(emergency|urgent|normal|non-urgent)' >
<!ELEMENT priority ( %Node; ) > <!ELEMENT priority ( %Node; ) >
<!-- Exactly one of these three attributes must appear --> <!-- Exactly one of these three attributes must appear -->
<!ATTLIST priority <!ATTLIST priority
less %PriorityVal; #IMPLIED less %PriorityVal; #IMPLIED
greater %PriorityVal; #IMPLIED greater %PriorityVal; #IMPLIED
skipping to change at page 52, line 39 skipping to change at page 56, line 6
(proxy, redirect) will attempt to contact. --> (proxy, redirect) will attempt to contact. -->
<!ENTITY % Clear 'clear (yes|no) "no"' > <!ENTITY % Clear 'clear (yes|no) "no"' >
<!ELEMENT location ( %Node; ) > <!ELEMENT location ( %Node; ) >
<!ATTLIST location <!ATTLIST location
url CDATA #REQUIRED url CDATA #REQUIRED
priority CDATA #IMPLIED priority CDATA #IMPLIED
%Clear; %Clear;
> >
<!-- priority is in the range 0.0 - 1.0. Its default value SHOULD
be 1.0 -->
<!ELEMENT lookup ( success,notfound?,failure? ) > <!ELEMENT lookup ( success?,notfound?,failure? ) >
<!ATTLIST lookup <!ATTLIST lookup
source CDATA #REQUIRED source CDATA #REQUIRED
timeout CDATA "30" timeout CDATA "30"
use CDATA #IMPLIED use CDATA #IMPLIED
ignore CDATA #IMPLIED ignore CDATA #IMPLIED
%Clear; %Clear;
> >
<!ELEMENT success ( %Node; ) > <!ELEMENT success ( %Node; ) >
<!ELEMENT notfound ( %Node; ) > <!ELEMENT notfound ( %Node; ) >
skipping to change at page 53, line 24 skipping to change at page 56, line 39
<!-- Signalling Actions: call-signalling actions the script can <!-- Signalling Actions: call-signalling actions the script can
take. --> take. -->
<!ELEMENT proxy ( busy?,noanswer?,redirection?,failure?,default? ) > <!ELEMENT proxy ( busy?,noanswer?,redirection?,failure?,default? ) >
<!-- The default value of timeout is "20" if the <noanswer> output <!-- The default value of timeout is "20" if the <noanswer> output
exists. --> exists. -->
<!ATTLIST proxy <!ATTLIST proxy
timeout CDATA #IMPLIED timeout CDATA #IMPLIED
recurse (yes|no) "yes" recurse (yes|no) "yes"
ordering CDATA "parallel" ordering (parallel|sequential|first-only) "parallel"
> >
<!ELEMENT busy ( %Node; ) > <!ELEMENT busy ( %Node; ) >
<!ELEMENT noanswer ( %Node; ) > <!ELEMENT noanswer ( %Node; ) >
<!ELEMENT redirection ( %Node; ) > <!ELEMENT redirection ( %Node; ) >
<!-- "failure" repeats from lookup, above. --> <!-- "failure" repeats from lookup, above. -->
<!ELEMENT default ( %Node; ) > <!ELEMENT default ( %Node; ) >
<!ELEMENT redirect EMPTY > <!ELEMENT redirect EMPTY >
<!ATTLIST redirect <!ATTLIST redirect
skipping to change at page 55, line 10 skipping to change at page 58, line 24
<!-- The top-level element of the script. --> <!-- The top-level element of the script. -->
<!ELEMENT cpl ( %Ancillary;,%Subactions;,%TopLevelActions; ) > <!ELEMENT cpl ( %Ancillary;,%Subactions;,%TopLevelActions; ) >
D Changes from Earlier Versions D Changes from Earlier Versions
[Note to RFC Editor: please remove this appendix before [Note to RFC Editor: please remove this appendix before
publication as an RFC.] publication as an RFC.]
D.1 Changes from Draft -03 D.1 Changes from Draft -04
The changebars in the Postscript and PDF versions of this document The changebars in the Postscript and PDF versions of this document
indicate significant changes from this version. indicate significant changes from this version.
o Broke out language switches into their own switch node.
o Restored the full iCalendar COS recurrence specification.
Added text describing the consequences of this for
implementors, and expanded somewhat on the recurrence
algorithm.
o Clarified when time zones are resolved.
o Spelled out "iCalendar" rather than abbreviating it "iCal."
o Clarified some points about host and port matching.
o Whole-address matching in SIP uses the standard SIP URL-match
rules.
o Specified that proxy and lookup timeouts are positive integer
number of seconds.
o Specified that "subaction" "id" parameters must be unique.
o Corrected example scripts' namespace and DTD references
indicating older drafts of this document.
o Deleted an unused subaction from the "Call Forward: Redirect
and Default" example script.
o Made empty switches legal in the DTD.
o Made the legal values for the "proxy" "ordering" parameter
explicit in the DTD.
o Made the "success" output of "lookup" optional in the DTD. It
can trigger a default action, just like anything else.
o Clarified that the time-switch resolution algorithm is non-
normative.
o Updated references to previously-unpublished RFCs, now
published.
o Thanked Richard Gumpertz.
D.2 Changes from Draft -03
o Removed an obsolete reference to a usage in examples which o Removed an obsolete reference to a usage in examples which
wasn't actually used anywhere. wasn't actually used anywhere.
o Added forward references to remove-location, mail and log, as o Added forward references to "remove-location", "mail" and
well as location, in the XML syntax as examples of nodes that "log", as well as "location", in the XML syntax as examples of
don't have explicit output tags. nodes that don't have explicit output tags.
o Made the usage of some terminology more consistent: "output" o Made the usage of some terminology more consistent: "output"
vs. "next node"; "action" vs. "operation" vs. "behavior"; vs. "next node"; "action" vs. "operation" vs. "behavior";
"sub-actions" and "subactions"; "other operations" and "non- "sub-actions" and "subactions"; "other operations" and "non-
call operations" and "non-signalling operations"; "meta- call operations" and "non-signalling operations"; "meta-
information" and "ancillary information." information" and "ancillary information."
o The tel subfield of addresses which come from sip URIs should o The "tel" subfield of addresses which come from sip URIs
have its visual separators stripped. should have its visual separators stripped.
o The default value of the priority value of the location node o The default value of the "priority" value of the "location"
is 1.0. node is 1.0.
o Corrected the media type of a set of URIs to text/uri-list, o Corrected the media type of a set of URIs to text/uri-list,
and added a reference to it. and added a reference to it.
o Added some wording clarifying how URI-based lookup queries o Added some wording clarifying how URI-based lookup queries
work. work.
o Corrected the syntax of duration parameter in the examples. o Corrected the syntax of "duration" parameter in the examples.
o Performed some pre-RFC textual cleanups (e.g. removing the o Performed some pre-RFC textual cleanups (e.g. removing the
reference to the Internet-Draft URL from the XML namespace reference to the Internet-Draft URL from the XML namespace
identifier). identifier).
o Re-worded text in the description of the Ancillary tag which o Re-worded text in the description of the Ancillary tag which
implied that information could be placed in that node in the implied that information could be placed in that node in the
base CPL specification. Clarified that the tag is for use by base CPL specification. Clarified that the tag is for use by
extensions only. extensions only.
o Expunged some references to sub-daily recurrences which had o Expunged some references to sub-daily recurrences which had
accidentally been left in the text. accidentally been left in the text.
o Updated bibliography to refer to the latest versions of the o Updated bibliography to refer to the latest versions of the
cited documents. cited documents.
o Fixed a number of typographical errors. o Fixed a number of typographical errors.
D.2 Changes from Draft -02 D.3 Changes from Draft -02
o Reduced time-switches from the full iCal recurrence to an iCal o Reduced time-switches from the full iCal recurrence to an iCal
subset. Added an appendix giving an algorithm to resolve subset. Added an appendix giving an algorithm to resolve
time-switches. time-switches.
o Added the extension mechanism. o Added the extension mechanism.
o Made explicit how each node is dependent on protocol handling. o Made explicit how each node is dependent on protocol handling.
Separated out protocol-specific information -- for SIP in Separated out protocol-specific information -- for SIP in
subsections of the main text, for H.323 in a non-normative subsections of the main text, for H.323 in a non-normative
appendix. appendix.
o Clarified some address mapping rules for H.323. o Clarified some address mapping rules for H.323.
o Corrected the name of the "Redirecting number" in Q.931. o Corrected the name of the "Redirecting number" in Q.931.
o Clarified that address matching on the password subfield is o Clarified that address matching on the "password" subfield is
case-sensitive. case-sensitive.
o Added a recommendation that TZID labels follow the usage of o Added a recommendation that TZID labels follow the usage of
the Olson database. the Olson database.
o Added the priority parameter to location nodes. o Added the "priority" parameter to "location" nodes.
o Added the default output to the proxy node. o Added the "default" output to the "proxy" node.
o Made the meaning of the proxy node's outputs explicit. o Made the meaning of the "proxy" node's outputs explicit.
o Added suggested content for the e-mail generated by mail o Added suggested content for the e-mail generated by "mail"
nodes. nodes.
o Pointed out that "&" must be escaped in XML (this is relevant o Pointed out that "&" must be escaped in XML (this is relevant
for mailto URIs). for "mailto" URIs).
o Pointed out that log names are logical names, and should not o Pointed out that log names are logical names, and should not
be interpreted as verbatim filenames. be interpreted as verbatim filenames.
o Added some examples. o Added some examples.
o Clarified some wording. o Clarified some wording.
o Fixed some typographical errors. o Fixed some typographical errors.
D.3 Changes from Draft -01 D.4 Changes from Draft -01
o Completely re-wrote changes to time switches: they are now o Completely re-wrote changes to time switches: they are now
based on iCal rather than on crontab. based on iCal rather than on crontab.
o Timezone references are now defined within time switches o Timezone references are now defined within time switches
rather than in the ancillary section. The ancillary section is rather than in the ancillary section. The ancillary section is
now empty, but still defined for future use. To facilitate now empty, but still defined for future use. To facilitate
this, an explicit ancillary tag was added. this, an explicit "ancillary" tag was added.
o Added XML document type identifiers (the public identifier and o Added XML document type identifiers (the public identifier and
the namespace), and MIME registration information. the namespace), and MIME registration information.
o Clarified that the not-present output can appear anywhere in a o Clarified that the "not-present" output can appear anywhere in
switch. a switch.
o Re-wrote H.323 address mappings. Added the alias-type subfield o Re-wrote H.323 address mappings. Added the "alias-type"
for H.323 addresses. subfield for H.323 addresses.
o Added the language and display string switch fields. o Added the "language" and "display" string switch fields.
o Clarified why useless not-present outputs can appear in time o Clarified why useless "not-present" outputs can appear in time
and priority switches. and priority switches.
o Added the clear parameter to location and lookup nodes. (It o Added the "clear" parameter to "location" and "lookup" nodes.
had been in the DTD previously, but not in the text.) (It had been in the DTD previously, but not in the text.)
o Weakened support for non-validating scripts from SHOULD to o Weakened support for non-validating scripts from SHOULD to
MAY, to allow the use of validating XML parsers. MAY, to allow the use of validating XML parsers.
o Added redirection output of proxy nodes. o Added "redirection" output of "proxy" nodes.
o Clarified some aspects of how proxy nodes handle the location o Clarified some aspects of how proxy nodes handle the location
set. set.
o Added permanent parameter of redirect nodes. o Added "permanent" parameter of "redirect" nodes.
o Add example script for outgoing call screening (from Kenny o Add example script for outgoing call screening (from Kenny
Hom) Hom)
o Updated example scripts to use the public identifier. o Updated example scripts to use the public identifier.
o Add omitted tag to example script for call forward busy/no o Add omitted tag to example script for call forward busy/no
answer answer
o Clarified in introduction that this document mainly deals with o Clarified in introduction that this document mainly deals with
servers. servers.
o Updated reference to RFC 2824 now that it has been published. o Updated reference to RFC 2824 now that it has been published.
o Added explanatory text to the introduction to types of nodes. o Added explanatory text to the introduction to types of nodes.
o Numerous minor clarifications and wording changes. o Numerous minor clarifications and wording changes.
o Fixed copy-and-paste errors, typos. o Fixed copy-and-paste errors, typos.
D.4 Changes from Draft -00 D.5 Changes from Draft -00
o Added high-level structure; script doesn't just start at a o Added high-level structure; script doesn't just start at a
first action. first action.
o Added a section giving a high-level explanation of the o Added a section giving a high-level explanation of the
location model. location model.
o Added informal syntax specifications for each tag so people o Added informal syntax specifications for each tag so people
don't have to try to understand a DTD to figure out the don't have to try to understand a DTD to figure out the
syntax. syntax.
o Added subactions, replacing the old link tags. Links were far o Added subactions, replacing the old "link" tags. Links were
too reminiscent of gotos for everyone's taste. far too reminiscent of gotos for everyone's taste.
o Added ancillary information section, and timezone support. o Added ancillary information section, and timezone support.
o Added not-present switch output. o Added not-present switch output.
o Added address switches. o Added address switches.
o Made case-insensitive string matching locale-independent. o Made case-insensitive string matching locale-independent.
o Added priority switch. o Added priority switch.
o Deleted "Other switches" section. None seem to be needed. o Deleted "Other switches" section. None seem to be needed.
o Unified url and source parameters of lookup. o Unified "url" and "source" parameters of "lookup".
o Added caller prefs to lookup. o Added caller prefs to "lookup".
o Added location filtering. o Added location filtering.
o Eliminated "clear" parameter of location setting. Instead, o Eliminated "clear" parameter of location setting. Instead,
proxy "eats" locations it has used. "proxy" "eats" locations it has used.
o Added recurse and ordering parameters to proxy. o Added "recurse" and "ordering" parameters to "proxy".
o Added default value of timeout for proxy. o Added default value of "timeout" for proxy.
o Renamed response to reject. o Renamed "response" to "reject".
o Changed notify to mail, and simplified it. o Changed "notify" to "mail", and simplified it.
o Simplified log, eliminating its failure output. o Simplified "log", eliminating its "failure" output.
o Added description of default actions at various times during o Added description of default actions at various times during
script processing. script processing.
o Updated examples for these changes. o Updated examples for these changes.
o Updated DTD to reflect new syntax. o Updated DTD to reflect new syntax.
E Authors' Addresses E Authors' Addresses
skipping to change at page 60, line 24 skipping to change at page 64, line 36
W3C Recommendation REC-html401-19991224, World Wide Web Consortium W3C Recommendation REC-html401-19991224, World Wide Web Consortium
(W3C), Dec. 1999. Available at http://www.w3.org/TR/html4/. (W3C), Dec. 1999. Available at http://www.w3.org/TR/html4/.
[7] ISO (International Organization for Standardization), [7] ISO (International Organization for Standardization),
"Information processing -- text and office systems -- standard "Information processing -- text and office systems -- standard
generalized markup language (SGML)," ISO Standard ISO 8879:1986(E), generalized markup language (SGML)," ISO Standard ISO 8879:1986(E),
International Organization for Standardization, Geneva, Switzerland, International Organization for Standardization, Geneva, Switzerland,
Oct. 1986. Oct. 1986.
[8] M. Murata, S. S. Laurent, and D. Kohn, "XML media types," Request [8] M. Murata, S. S. Laurent, and D. Kohn, "XML media types," Request
for Comments YYYY, Internet Engineering Task Force, Sept. 2000. for Comments 3023, Internet Engineering Task Force, Jan. 2001.
[Draft draft-murata-xml-09.txt, approved for Proposed Standard. RFC
Editor: please fill in appropriate bibliographic information.].
[9] H. Alvestrand, "Tags for the identification of languages," [9] R. Hinden and S. Deering, "IP version 6 addressing architecture,"
Request for Comments 1766, Internet Engineering Task Force, Mar. Request for Comments 2373, Internet Engineering Task Force, July
1995. 1998.
[10] M. Davis and M. Duerst, "Unicode normalization forms," Unicode [10] M. Davis and M. Duerst, "Unicode normalization forms," Unicode
Technical Report 15, Unicode Consortium, Aug. 2000. Revision 19; Technical Report 15, Unicode Consortium, Aug. 2000. Revision 19;
part of Unicode 3.0.1. Available at part of Unicode 3.0.1. Available at
http://www.unicode.org/unicode/reports/tr15/. http://www.unicode.org/unicode/reports/tr15/.
[11] M. Davis, "Case mappings," Unicode Technical Report 21, Unicode [11] M. Davis, "Case mappings," Unicode Technical Report 21, Unicode
Consortium, Oct. 2000. Revision 4.3. Available at Consortium, Oct. 2000. Revision 4.3. Available at
http://www.unicode.org/unicode/reports/tr21/. http://www.unicode.org/unicode/reports/tr21/.
[12] F. Dawson and D. Stenerson, "Internet calendaring and scheduling [12] H. Alvestrand, "Tags for the identification of languages,"
Request for Comments 3066, Internet Engineering Task Force, Jan.
2001.
[13] F. Dawson and D. Stenerson, "Internet calendaring and scheduling
core object specification (icalendar)," Request for Comments 2445, core object specification (icalendar)," Request for Comments 2445,
Internet Engineering Task Force, Nov. 1998. Internet Engineering Task Force, Nov. 1998.
[13] P. Eggert, "Sources for time zone and daylight saving time [14] P. Eggert, "Sources for time zone and daylight saving time
data." Available at http://www.twinsun.com/tz/tz-link.htm. data." Available at http://www.twinsun.com/tz/tz-link.htm.
[14] ISO (International Organization for Standardization), "Data [15] ISO (International Organization for Standardization), "Data
elements and interchange formats -- information interchange -- elements and interchange formats -- information interchange --
representation of dates and times," ISO Standard ISO 8601:1988(E), representation of dates and times," ISO Standard ISO 8601:1988(E),
International Organization for Standardization, Geneva, Switzerland, International Organization for Standardization, Geneva, Switzerland,
June 1986. June 1986.
[15] M. Mealling and R. Daniel, "URI resolution services necessary [16] M. Mealling and R. Daniel, "URI resolution services necessary
for URN resolution," Request for Comments 2483, Internet Engineering for URN resolution," Request for Comments 2483, Internet Engineering
Task Force, Jan. 1999. Task Force, Jan. 1999.
[16] H. Schulzrinne and J. Rosenberg, "SIP caller preferences and [17] H. Schulzrinne and J. Rosenberg, "SIP caller preferences and
callee capabilities," Internet Draft, Internet Engineering Task callee capabilities," Internet Draft, Internet Engineering Task
Force, July 2000. Work in progress. Force, Nov. 2000. Work in progress.
[17] S. DeRose, E. Maler, D. Orchard, and B. Trafford, "XML linking [18] S. DeRose, E. Maler, D. Orchard, and B. Trafford, "XML linking
language (XLink) version 1.0," W3C Candidate Recommendation CR- language (XLink) version 1.0," W3C Candidate Recommendation CR-
xlink-20000703, World Wide Web Consortium (W3C), July 2000. xlink-20000703, World Wide Web Consortium (W3C), July 2000.
Available at http://www.w3.org/TR/xlink/. Available at http://www.w3.org/TR/xlink/.
[18] T. Bray, D. Hollander, and A. Layman, "Namespaces in XML," W3C [19] T. Bray, D. Hollander, and A. Layman, "Namespaces in XML," W3C
Recommendation REC-xml-names-19900114, World Wide Web Consortium Recommendation REC-xml-names-19900114, World Wide Web Consortium
(W3C), Jan. 1999. Available at http://www.w3.org/TR/REC-xml-names/. (W3C), Jan. 1999. Available at http://www.w3.org/TR/REC-xml-names/.
[19] T. Showalter, "Sieve: A mail filtering language," Request for [20] T. Showalter, "Sieve: A mail filtering language," Request for
Comments YYYY, Internet Engineering Task Force, Aug. 2000. [Draft Comments 3028, Internet Engineering Task Force, Jan. 2001.
draft-showalter-sieve-12.txt, approved for Proposed Standard. RFC
Editor: please fill in appropriate bibliographic information.].
[20] D. C. Fallside, "XML schema part 0: Primer," W3C Candidate [21] D. C. Fallside, "XML schema part 0: Primer," W3C Candidate
Recommendation CR-xmlschema-0-20001024, World Wide Web Consortium Recommendation CR-xmlschema-0-20001024, World Wide Web Consortium
(W3C), Oct. 2000. Available at http://www.w3.org/TR/xmlschema-0/. (W3C), Oct. 2000. Available at http://www.w3.org/TR/xmlschema-0/.
[21] International Telecommunication Union, "Digital subscriber [22] International Telecommunication Union, "Digital subscriber
signalling system no. 1 (dss 1) - isdn user-network interface layer 3 signalling system no. 1 (dss 1) - isdn user-network interface layer 3
specification for basic call control," Recommendation Q.931, specification for basic call control," Recommendation Q.931,
Telecommunication Standardization Sector of ITU, Geneva, Switzerland, Telecommunication Standardization Sector of ITU, Geneva, Switzerland,
Mar. 1993. Mar. 1993.
[22] International Telecommunication Union, "Packet based multimedia [23] International Telecommunication Union, "Packet based multimedia
communication systems," Recommendation H.323 Draft v4, communication systems," Recommendation H.323, Telecommunication
Telecommunication Standardization Sector of ITU, Geneva, Switzerland, Standardization Sector of ITU, Geneva, Switzerland, Nov. 2000.
July 2000. To be published November 2000.
[23] O. Levin, "H.323 URL scheme definition," Internet Draft, [24] O. Levin, "H.323 URL scheme definition," Internet Draft,
Internet Engineering Task Force, Aug. 2000. Work in progress. Internet Engineering Task Force, Nov. 2001. Work in progress.
Full Copyright Statement Full Copyright Statement
Copyright (c) The Internet Society (2000). All Rights Reserved. Copyright (c) The Internet Society (2001). All Rights Reserved.
This document and translations of it may be copied and furnished to This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of Internet organizations, except as needed for the purpose of
skipping to change at page 62, line 39 skipping to change at page 67, line 9
2 Structure of CPL Scripts ............................ 2 2 Structure of CPL Scripts ............................ 2
2.1 High-level Structure ................................ 3 2.1 High-level Structure ................................ 3
2.2 Abstract Structure of a Call Processing Action ...... 3 2.2 Abstract Structure of a Call Processing Action ...... 3
2.3 Location Model ...................................... 4 2.3 Location Model ...................................... 4
2.4 XML Structure ....................................... 4 2.4 XML Structure ....................................... 4
3 Document Information ................................ 5 3 Document Information ................................ 5
3.1 CPL Document Identifiers for XML .................... 5 3.1 CPL Document Identifiers for XML .................... 5
3.2 MIME Registration ................................... 6 3.2 MIME Registration ................................... 6
4 Script Structure: Overview .......................... 7 4 Script Structure: Overview .......................... 7
5 Switches ............................................ 8 5 Switches ............................................ 8
5.1 Address Switches .................................... 9 5.1 Address Switches .................................... 8
5.1.1 Usage of address-switch with SIP .................... 11 5.1.1 Usage of "address-switch" with SIP .................. 11
5.2 String Switches ..................................... 12 5.2 String Switches ..................................... 12
5.2.1 Usage of string-switch with SIP ..................... 13 5.2.1 Usage of "string-switch" with SIP ................... 13
5.3 Time Switches ....................................... 13 5.3 Language Switches ................................... 13
5.3.1 Motivations for the iCal Subset ..................... 18 5.3.1 Usage of "language-switch" with SIP ................. 14
5.4 Priority Switches ................................... 19 5.4 Time Switches ....................................... 14
5.4.1 Usage of priority-switch with SIP ................... 20 5.4.1 iCalendar differences and implementation issues ..... 20
6 Location Modifiers .................................. 20 5.5 Priority Switches ................................... 21
6.1 Explicit Location ................................... 21 5.5.1 Usage of "priority-switch" with SIP ................. 22
6.1.1 Usage of location with SIP .......................... 21 6 Location Modifiers .................................. 22
6.2 Location Lookup ..................................... 22 6.1 Explicit Location ................................... 23
6.2.1 Usage of lookup with SIP ............................ 23 6.1.1 Usage of "location" with SIP ........................ 23
6.3 Location Removal .................................... 24 6.2 Location Lookup ..................................... 24
6.3.1 Usage of remove-location with SIP ................... 25 6.2.1 Usage of "lookup" with SIP .......................... 25
7 Signalling Operations ............................... 25 6.3 Location Removal .................................... 26
7.1 Proxy ............................................... 25 6.3.1 Usage of "remove-location" with SIP ................. 27
7.1.1 Usage of proxy with SIP ............................. 27 7 Signalling Operations ............................... 27
7.2 Redirect ............................................ 28 7.1 Proxy ............................................... 27
7.2.1 Usage of redirect with SIP .......................... 28 7.1.1 Usage of "proxy" with SIP ........................... 30
7.3 Reject .............................................. 29 7.2 Redirect ............................................ 30
7.3.1 Usage of reject with SIP ............................ 29 7.2.1 Usage of "redirect" with SIP ........................ 31
8 Non-signalling Operations ........................... 30 7.3 Reject .............................................. 31
8.1 Mail ................................................ 30 7.3.1 Usage of "reject" with SIP .......................... 31
8.1.1 Suggested Content of Mailed Information ............. 30 8 Non-signalling Operations ........................... 32
8.2 Log ................................................. 31 8.1 Mail ................................................ 32
9 Subactions .......................................... 32 8.1.1 Suggested Content of Mailed Information ............. 33
10 Ancillary Information ............................... 33 8.2 Log ................................................. 33
11 Default Behavior .................................... 33 9 Subactions .......................................... 34
12 CPL Extensions ...................................... 34 10 Ancillary Information ............................... 35
13 Examples ............................................ 36 11 Default Behavior .................................... 36
13.1 Example: Call Redirect Unconditional ................ 36 12 CPL Extensions ...................................... 37
13.2 Example: Call Forward Busy/No Answer ................ 36 13 Examples ............................................ 38
13.3 Example: Call Forward: Redirect and Default ......... 36 13.1 Example: Call Redirect Unconditional ................ 38
13.4 Example: Call Screening ............................. 37 13.2 Example: Call Forward Busy/No Answer ................ 38
13.5 Example: Priority and Language Routing .............. 37 13.3 Example: Call Forward: Redirect and Default ......... 39
13.6 Example: Outgoing Call Screening .................... 39 13.4 Example: Call Screening ............................. 39
13.7 Example: Time-of-day Routing ........................ 39 13.5 Example: Priority and Language Routing .............. 40
13.8 Example: Location Filtering ......................... 39 13.6 Example: Outgoing Call Screening .................... 41
13.9 Example: Non-signalling Operations .................. 41 13.7 Example: Time-of-day Routing ........................ 41
13.10 Example: Hypothetical Extensions .................... 41 13.8 Example: Location Filtering ......................... 43
13.11 Example: A Complex Example .......................... 42 13.9 Example: Non-signalling Operations .................. 43
14 Security Considerations ............................. 43 13.10 Example: Hypothetical Extensions .................... 43
15 IANA Considerations ................................. 43 13.11 Example: A Complex Example .......................... 45
16 Acknowledgments ..................................... 44 14 Security Considerations ............................. 45
A An Algorithm for Resolving Time Switches ............ 45 15 IANA Considerations ................................. 46
B Suggested Usage of CPL with H.323 ................... 46 16 Acknowledgments ..................................... 47
B.1 Usage of address-switch with H.323 .................. 46 A An Algorithm for Resolving Time Switches ............ 47
B.2 Usage of string-switch with H.323 ................... 48 B Suggested Usage of CPL with H.323 ................... 48
B.3 Usage of priority-switch with H.323 ................. 48 B.1 Usage of "address-switch" with H.323 ................ 49
B.4 Usage of location with H.323 ........................ 48 B.2 Usage of "string-switch" with H.323 ................. 50
B.5 Usage of lookup with H.323 .......................... 49 B.3 Usage of "language-switch" with H.323 ............... 51
B.6 Usage of remove-location with H.323 ................. 49 B.4 Usage of "priority-switch" with H.323 ............... 51
C The XML DTD for CPL ................................. 49 B.5 Usage of "location" with H.323 ...................... 51
D Changes from Earlier Versions ....................... 55 B.6 Usage of "lookup" with H.323 ........................ 51
D.1 Changes from Draft -03 .............................. 55 B.7 Usage of "remove-location" with H.323 ............... 51
D.2 Changes from Draft -02 .............................. 56 C The XML DTD for CPL ................................. 52
D.3 Changes from Draft -01 .............................. 57 D Changes from Earlier Versions ....................... 58
D.4 Changes from Draft -00 .............................. 58 D.1 Changes from Draft -04 .............................. 58
E Authors' Addresses .................................. 59 D.2 Changes from Draft -03 .............................. 59
F Bibliography ........................................ 59 D.3 Changes from Draft -02 .............................. 60
D.4 Changes from Draft -01 .............................. 61
D.5 Changes from Draft -00 .............................. 62
E Authors' Addresses .................................. 63
F Bibliography ........................................ 63
 End of changes. 

This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/