address is to be considered for the switch: either the call’s origin
address (field "origin"), its current destination address (field
"destination"), or its original destination (field "original-
destination"), the destination the call had before any earlier
forwarding was invoked. Servers MAY define additional field values.
The optional "subfield" specifies which part of the address is to be
considered. The possible subfield values are: "address-type",
"user", "host", "port", "tel", and "display". Additional subfield
values MAY be defined for protocol-specific values. (The subfield
"password" is defined for SIP in Section 4.1.1; the subfield "alias-
type" is defined for H.323 in Appendix B.1.) If no subfield is
specified, the "entire" address is matched; the precise meaning of
this is defined for each underlying signalling protocol. Servers MAY
define additional subfield values.
The subfields are defined as follows:
address-type: This indicates the type of the underlying address,
i.e., the URI scheme, if the address can be represented by a
URI. The types specifically discussed by this document are
"sip", "tel", and "h323". The address type is not case-
sensitive. It has a value for all defined address types.
user: This subfield of the address indicates, for e-mail style
addresses, the user part of the address. For a telephone
number style address, it includes the subscriber number.
This subfield is case-sensitive; it may be absent.
host: This subfield of the address indicates the Internet host
name or IP address corresponding to the address, in host
name, IPv4, or IPv6 [4] textual representation format. Host
names are compared as strings. IP addresses are compared
numerically. (In particular, the presence or location of an
IPv6 :: omitted-zero-bits block is not significant for
matching purposes.) Host names are never equal to IP
addresses -- no DNS resolution is performed. IPv4 addresses
are never equal to IPv6 addresses, even if the IPv6 address
is a v4-in-v6 embedding. This subfield is not case
sensitive, and may be absent.
For host names only, subdomain matching is supported with
the "subdomain-of" match operator. The "subdomain-of"
operator ignores leading dots in the hostname or match
pattern, if any.
port: This subfield indicates the TCP or UDP port number of the
address, numerically, in decimal format. It is not case
sensitive, as it MUST only contain decimal digits. Leading
zeros are ignored.
tel: This subfield indicates a telephone subscriber number, if
the address contains such a number. It is not case
sensitive (telephone numbers may contain the symbols ’A’,
’B’, ’C’, or ’D’), and may be absent. It may be matched
using the "subdomain-of" match operator. Punctuation and
separator characters in telephone numbers are discarded.
display: This subfield indicates a "display name" or user-visible
name corresponding to an address. It is a Unicode string,
and is matched using the case-insensitive algorithm
described in Section 4.2. The "contains" operator may be
applied to it. It may be absent.
For any completely unknown subfield, the server MAY reject the script
at the time it is submitted with an indication of the problem; if a
script with an unknown subfield is executed, the server MUST consider
the "not-present" output to be the valid one.
The "address" output tag may take exactly one of three possible
parameters, indicating the kind of matching allowed.
is: An output with this match operator is followed if the
subfield being matched in the "address-switch" exactly
matches the argument of the operator. It may be used for
any subfield, or for the entire address if no subfield was
specified.
subdomain-of: This match operator applies only for the subfields
"host" and "tel". In the former case, it matches if the
hostname being matched is a subdomain of the domain given in
the argument of the match operator; thus, subdomain-
of="example.com" would match the hostnames "example.com",
"research.example.com", and
"zaphod.sales.internal.example.com". IP addresses may be
given as arguments to this operator; however, they only
match exactly. In the case of the "tel" subfield, the
output matches if the telephone number being matched has a
prefix that matches the argument of the match operator;
subdomain-of="1212555" would match the telephone number "1
212 555 1212."
contains: This match operator applies only for the subfield
"display". The output matches if the display name being
matched contains the argument of the match as a substring.
4.1.1. Usage of "address-switch" with SIP
For SIP, the "origin" address corresponds to the address in the
"From" header, "destination" corresponds to the "Request-URI", and
"original-destination" corresponds to the "To" header.
The "display" subfield of an address is the display-name part of the
address, if it is present. Because of SIP’s syntax, the
"destination" address field will never have a "display" subfield.
The "address-type" subfield of an address is the URI scheme of that
address. Other address fields depend on that "address-type".
For SIP URIs, the "user", "host", and "port" subfields correspond to
the "user," "host," and "port" elements of the URI syntax. (Note
that, following the definitions of RFC 3261 [1], a SIP URI which does
not specify a port is not the same as an explicit port 5060; the
former is indicated by an absent port subfield.) The "tel" subfield
is defined to be the "user" part of the URI, with visual separators
stripped, if the "user=phone" parameter is given to the URI, or if
the server is otherwise configured to recognize the user part as a
telephone number. An additional subfield, "password", is defined to
correspond to the "password" element of the SIP URI, and is case-
sensitive. However, use of this field is NOT RECOMMENDED for general
security reasons.
For tel URLs, the "tel" and "user" subfields are the subscriber name;
in the former case, visual separators are stripped. The "host" and
"port" subfields are both not present.
For h323 URLs, subfields MAY be set according to the scheme described
in Appendix B.
For other URI schemes, only the "address-type" subfield is defined by
this specification; servers MAY set other pre-defined subfields, or
MAY support additional subfields.
If no subfield is specified for addresses in SIP messages, the string
matched is the URI part of the address. For "is" matches, standard
SIP URI matching rules are used; for "contains" matches, the URI is
used verbatim.
4.2. String Switches
String switches allow a CPL script to make decisions based on free-
form strings present in a call request. They are summarized in
Figure 5.
Node: "string-switch"
Outputs: "string" Specific string to match
Parameters: "field" "subject", "organization",
"user-agent", or "display"
Output: "string"
Parameters: "is" Exact match
"contains" Substring match
Figure 5: Syntax of the "string-switch" node
String switches have one node parameter: "field". The mandatory
"field" parameter specifies which string is to be matched.
String switches are dependent on the call signalling protocol being
used.
Four fields are defined and listed below. The value of each of these
fields is a free-form Unicode string with no other structure defined.
subject: The subject of the call.
organization: The organization of the originator of the call.
user-agent: The name of the program or device with which the call
request was made.
display: Free-form text associated with the call, intended to be
displayed to the recipient, with no other semantics defined
by the signalling protocol.
Strings are matched as case-insensitive Unicode strings, in the
following manner. First, strings are canonicalized to the
"Compatibility Composition" (KC) form, as specified in Unicode
Standard Annex #15 [5]. Then, strings are compared using locale-
insensitive caseless mapping, as specified in Unicode Standard Annex
#21 [6].
Code to perform the first step, in Java and Perl, is available;
see the links from Annex 5 of UAX 15 [5]. The case-insensitive
string comparison in the Java standard class libraries already
performs the second step; other Unicode-aware libraries should be
similar.
The output tag of string matching is named "string", and has a
mandatory argument, one of "is" or "contains", indicating whole-
string match or substring match, respectively.
4.2.1. Usage of "string-switch" with SIP
For SIP, the fields "subject", "organization", and "user-agent"
correspond to the SIP header fields with the same name. These are
used verbatim as they appear in the message.
The field "display" is not used, and is never present.
4.3. Language Switches
Language switches allow a CPL script to make decisions based on the
languages in which the originator of the call wishes to communicate.
They are summarized in Figure 6.
Node: "language-switch"
Outputs: "language" Specific string to match
Parameters: None
Output: "language"
Parameters: "matches" Match if the given language
matches a language-range of the
call.
Figure 6: Syntax of the "language-switch" node
Language switches take no parameters.
The "language" output takes one parameter, "matches". The value of
the parameter is a language-tag, as defined in RFC 3066 [7]. The
caller may have specified a set of language-ranges, also as defined
in RFC 3066. The CPL server checks each language-tag specified by
the script against the language-ranges specified in the request.
See RFC 3066 for the details of how language-ranges match language-
tags. Briefly, a language-range matches a language-tag if it exactly
equals the tag, or if it exactly equals a prefix of the tag such that
the first character following the prefix is "-".
If the caller specified the special language-range "*", it is ignored
for the purpose of matching. Languages with a "q" value of 0 are
also ignored.
This switch MAY be not-present.
4.3.1. Usage of "language-switch" with SIP
The language-ranges for the "language-switch" switch are obtained
from the SIP "Accept-Language" header field. The switch is not-
present if the initial SIP request did not contain this header field.
Note that because of CPL’s first-match semantics in switches, "q"
values other than 0 of the "Accept-Language" header fields are
ignored.
4.4. Time Switches
Time switches allow a CPL script to make decisions based on the time
and/or date the script is being executed. They are summarized in
Figure 7.
Time switches are independent of the underlying signalling protocol.
Node: "time-switch"
Outputs: "time" Specific time to match
Parameters: "tzid" RFC 2445 Time Zone Identifier
"tzurl" RFC 2445 Time Zone URL
Output: "time"
Parameters: "dtstart" Start of interval (RFC 2445 DATE-TIME)
"dtend" End of interval (RFC 2445 DATE-TIME)
"duration" Length of interval (RFC 2445 DURATION)
"freq" Frequency of recurrence ("secondly",
"minutely", "hourly", "daily",
"weekly", "monthly", or "yearly")
"interval" How often the recurrence repeats
"until" Bound of recurrence (RFC 2445 DATE-TIME)
"count" Number of occurrences of recurrence
"bysecond" List of seconds within a minute
"byminute" List of minutes within an hour
"byhour" List of hours of the day
"byday" List of days of the week
"bymonthday" List of days of the month
"byyearday" List of days of the year
"byweekno" List of weeks of the year
"bymonth" List of months of the year
"wkst" First day of the work week
"bysetpos" List of values within
set of events specified
Figure 7: Syntax of the "time-switch" node
Time switches are based closely on the specification of recurring
intervals of time in the Internet Calendaring and Scheduling Core
Object Specification (iCalendar COS), RFC 2445 [8].
This allows CPL scripts to be generated automatically from
calendar books. It also allows us to re-use the extensive
existing work specifying time intervals.
If future standards-track documents are published that update or
obsolete RFC 2445, any changes or clarifications those documents make
to recurrence handling apply to CPL time-switches as well.
An algorithm to determine whether an instant falls within a given
recurrence is given in Appendix A.
The "time-switch" tag takes two optional parameters, "tzid" and
"tzurl", both of which are defined in RFC 2445 (Sections 4.8.3.1 and
4.8.3.5 respectively). The "tzid" is the identifying label by which
a time zone definition is referenced. If it begins with a forward
slash (solidus), it references a to-be-defined global time zone
registry; otherwise it is locally-defined at the server. The "tzurl"
gives a network location from which an up-to-date VTIMEZONE
definition for the timezone can be retrieved.
While "tzid" labels that do not begin with a forward slash are
locally defined, it is RECOMMENDED that servers support at least the
naming scheme used by the Olson Time Zone database [9]. Examples of
timezone databases that use the Olson scheme are the zoneinfo files
on most Unix-like systems, and the standard Java TimeZone class.
Servers SHOULD resolve "tzid" and "tzurl" references to time zone
definitions at the time the script is uploaded. They MAY
periodically refresh these resolutions to obtain the most up-to-date
definition of a time zone. If a "tzurl" becomes invalid, servers
SHOULD remember the most recent valid data retrieved from the URL.
If a script is uploaded with a "tzid" and "tzurl" which the CPL
server does not recognize or cannot resolve, it SHOULD diagnose and
reject this at script upload time. If neither "tzid" nor "tzurl" are
present, all non-UTC times within this time switch should be
interpreted as being "floating" times, i.e., that they are specified
in the local timezone of the CPL server.
Because of daylight-savings-time changes over the course of a
year, it is necessary to specify time switches in a given
timezone. UTC offsets are not sufficient, or a time-of-day
routing rule which held between 9 am and 5 pm in the eastern
United States would start holding between 8 am and 4 pm at the end
of October.
Authors of CPL servers should be careful to handle correctly the
intervals when local time is discontinuous, at the beginning or end
of daylight-savings time. Note especially that some times may occur
more than once when clocks are set back. The algorithm in Appendix A
is believed to handle this correctly.
Time nodes specify a list of periods during which their output should
be taken. They have two required parameters: "dtstart", which
specifies the beginning of the first period of the list, and exactly
one of "dtend" or "duration", which specify the ending time or the
duration of the period, respectively. The "dtstart" and "dtend"
parameters are formatted as iCalendar COS DATE-TIME values, as
specified in Section 4.3.5 of RFC 2445 [8]. Because time zones are
specified in the top-level "time-switch" tag, only forms 1 or 2
(floating or UTC times) can be used. The "duration" parameter is
given as an iCalendar COS DURATION parameter, as specified in section
4.3.6 of RFC 2445. Both the DATE-TIME and the DURATION syntaxes are
subsets of the corresponding syntaxes from ISO 8601 [20].
For a recurring interval, the "duration" parameter MUST be small
enough such that subsequent intervals do not overlap. For non-
recurring intervals, durations of any positive length are permitted.
Zero-length and negative-length durations are not allowed.
If no other parameters are specified, a time node indicates only a
single period of time. More complicated sets of period intervals are
constructed as recurrences. A recurrence is specified by including
the "freq" parameter, which indicates the type of recurrence rule.
Parameters other than "dtstart", "dtend", and "duration" SHOULD NOT
be specified unless "freq" is present, though CPL servers SHOULD
accept scripts with such parameters present, and ignore the other
parameters.
The "freq" parameter takes one of the following values: "secondly",
to specify repeating periods based on an interval of a second or
more, "minutely", to specify repeating periods based on an interval
of a minute or more, "hourly", to specify repeating periods based on
an interval of an hour or more, "daily", to specify repeating periods
based on an interval of a day or more, "weekly", to specify repeating
periods based on an interval of a week or more, "monthly", to specify
repeating periods based on an interval of a month or more, and
"yearly", to specify repeating periods based on an interval of a year
or more. These values are not case-sensitive.
The "interval" parameter contains a positive integer representing how
often the recurrence rule repeats. The default value is "1", meaning
every second for a "secondly" rule, every minute for a "minutely"
rule, every hour for an "hourly" rule, every day for a "daily" rule,
every week for a "weekly" rule, every month for a "monthly" rule, and
every year for a "yearly" rule.
The "until" parameter defines an iCalendar COS DATE or DATE-TIME
value which bounds the recurrence rule in an inclusive manner. If
the value specified by "until" is synchronized with the specified
recurrence, this date or date-time becomes the last instance of the
recurrence. If specified as a date-time value, then it MUST be
specified in UTC time format. If not present, and the "count"
parameter is not also present, the recurrence is considered to repeat
forever.
The "count" parameter defines the number of occurrences at which to
range-bound the recurrence. The "dtstart" parameter counts as the
first occurrence. The "until" and "count" parameters MUST NOT occur
in the same "time" output.
The "bysecond" parameter specifies a comma-separated list of seconds
within a minute. Valid values are 0 to 59. The "byminute" parameter
specifies a comma-separated list of minutes within an hour. Valid
values are 0 to 59. The "byhour" parameter specifies a comma-
separated list of hours of the day. Valid values are 0 to 23.
The "byday" parameter specifies a comma-separated list of days of the
week. "MO" indicates Monday, "TU" indicates Tuesday, "WE" indicates
Wednesday, "TH" indicates Thursday, "FR" indicates Friday, "SA"
indicates Saturday, and "SU" indicates Sunday. These values are not
case-sensitive.
Each "byday" value can also be preceded by a positive (+n) or
negative (-n) integer. If present, this indicates the nth occurrence
of the specific day within the "monthly" or "yearly" recurrence. For
example, within a "monthly" rule, +1MO (or simply 1MO) represents the
first Monday within the month, whereas -1MO represents the last
Monday of the month. If an integer modifier is not present, it means
all days of this type within the specified frequency. For example,
within a "monthly" rule, MO represents all Mondays within the month.
The "bymonthday" parameter specifies a comma-separated list of days
of the month. Valid values are 1 to 31 or -31 to -1. For example,
-10 represents the tenth to the last day of the month.
The "byyearday" parameter specifies a comma-separated list of days of
the year. Valid values are 1 to 366 or -366 to -1. For example, -1
represents the last day of the year (December 31st) and -306
represents the 306th to the last day of the year (March 1st).
The "byweekno" parameter specifies a comma-separated list of ordinals
specifying weeks of the year. Valid values are 1 to 53 or -53 to -1.
This corresponds to weeks according to week numbering as defined in
ISO 8601 [20]. A week is defined as a seven day period, starting on
the day of the week defined to be the week start (see "wkst"). Week
number one of the calendar year is the first week which contains at
least four (4) days in that calendar year. This parameter is only
valid for "yearly" rules. For example, 3 represents the third week
of the year.
Note: Assuming a Monday week start, week 53 can only occur when
January 1 is a Thursday or, for leap years, if January 1 is a
Wednesday.
The "bymonth" parameter specifies a comma-separated list of months of
the year. Valid values are 1 to 12.
The "wkst" parameter specifies the day on which the work week starts.
Valid values are "MO", "TU", "WE", "TH", "FR", "SA" and "SU". This
is significant when a "weekly" recurrence has an interval greater
than 1, and a "byday" parameter is specified. This is also
significant in a "yearly" recurrence when a "byweekno" parameter is