</success>
<failure>
<mail url="mailto:mary@example.com?subject=Lookup%20failed"/>
</failure>
</lookup>
</incoming>
</cpl>
Figure 27: Example Script: Non-signalling Operations
12.10. Example: Hypothetical Extensions
The example in Figure 28 shows a hypothetical extension that
implements distinctive ringing. The XML namespace
"http://www.example.com/distinctive-ring" specifies a new node named
"ring".
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema targetNamespace="http://www.example.com/distinctive-ring"
xmlns="http://www.example.com/distinctive-ring"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:CPL="urn:ietf:params:xml:ns:cpl"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<xs:import namespace="urn:ietf:params:xml:ns:cpl"
schemaLocation="cpl.xsd"/>
<xs:complexType name="DRingAction">
<xs:complexContent>
<xs:extension base="CPL:ActionType">
<xs:attribute name="ringstyle" type="xs:string"
use="optional"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="ring" type="DRingAction"
substitutionGroup="CPL:action"/>
</xs:schema>
<?xml version="1.0" encoding="UTF-8"?>
<cpl xmlns="urn:ietf:params:xml:ns:cpl"
xmlns:dr="http://www.example.com/distinctive-ring"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd
http://www.example.com/distinctive-ring distinctive-ring.xsd">
<incoming>
<address-switch field="origin">
<address is="sip:boss@example.com">
<dr:ring ringstyle="warble"/>
</address>
</address-switch>
</incoming>
</cpl>
Figure 28: Example Schema and Script: Hypothetical
Distinctive-Ringing Extension
The example in Figure 29 implements a hypothetical new attribute for
address switches, to allow regular-expression matches. It defines a
new attribute "regex" for the standard "address" node.
<?xml version="1.0" encoding="UTF-8"?>
<cpl xmlns="urn:ietf:params:xml:ns:cpl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd ">
<incoming>
<address-switch field="origin" subfield="user"
xmlns:re="http://www.example.com/regex">
<address re:regex="(.*.smith|.*.jones)">
<reject status="reject"
reason="I don’t want to talk to Smiths or Joneses"/>
</address>
</address-switch>
</incoming>
</cpl>
Figure 29: Example Script: Hypothetical Regular-Expression Extension
12.11. Example: A Complex Example
Finally, Figure 30 is a complex example which shows the sort of
sophisticated behavior that can be achieved by combining CPL nodes.
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
are forwarded to his mobile phone, and all other calls are directed
to voicemail. If the call setup failed, no operation is specified,
so the server’s default behavior is performed.
<?xml version="1.0" encoding="UTF-8"?>
<cpl xmlns="urn:ietf:params:xml:ns:cpl"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:ietf:params:xml:ns:cpl cpl.xsd ">
<subaction id="voicemail">
<location url="sip:jones@voicemail.example.com">
<redirect />
</location>
</subaction>
<incoming>
<location url="sip:jones@phone.example.com">
<proxy timeout="8">
<busy>
<sub ref="voicemail" />
</busy>
<noanswer>
<address-switch field="origin">
<address is="sip:boss@example.com">
<location url="tel:+19175551212">
<proxy />
</location>
</address>
<otherwise>
<sub ref="voicemail" />
</otherwise>
</address-switch>
</noanswer>
</proxy>
</location>
</incoming>
</cpl>
Figure 30: Example Script: A Complex Example
13. Security Considerations
CPL is designed to allow services to be specified in a manner which
prevents potentially hostile or mis-configured scripts from launching
security attacks, including denial-of-service attacks. Because
script runtime is strictly bounded by acyclicity, and because the
number of possible script operations are strictly limited, scripts
should not be able to inflict damage upon a CPL server.
Because scripts can direct users’ telephone calls, the method by
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.
14. IANA Considerations
This document registers a new MIME type, application/cpl+xml, and a
new URN per RFC 2141 [12], RFC 2648 [13], and RFC 3688 [14].
The XML namespace urn:ietf:params:xml:ns:cpl will only refer to the
version of CPL in this document and will not change. Any CPL
enhancements MUST be made by extensions and MUST have different
namespaces.
14.1. URN Sub-Namespace Registration for urn:ietf:params:xml:ns:cpl
URI: urn:ietf:params:xml:ns:cpl
Registrant Contact: Jonathan Lennox <lennox@cs.columbia.edu>
Xiaotao Wu <xiaotaow@cs.columbia.edu>
Henning Schulzrinne <hgs@cs.columbia.edu>
XML:
BEGIN
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.0//EN"
"http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type"
content="text/html;charset=iso-8859-1"/>
<title>Call Processing Language Namespace</title>
</head>
<body>
<h1>Namespace for Call Processing Language</h1>
<h2>urn:ietf:params:xml:ns:cpl</h2>
<p><a href="ftp://ftp.rfc-editor.org/in-notes/rfc3880.txt">
RFC3880</a>.</p>
</body>
</html>
END
14.2. Schema registration
This specification registers XML Schema for CPL, as per the
guidelines in [14].
URI: urn:ietf:params:xml:schema:cpl
Registrant contact:
Jonathan Lennox <lennox@cs.columbia.edu>
Xiaotao Wu <xiaotaow@cs.columbia.edu>
Henning Schulzrinne <hgs@cs.columbia.edu>
XML: The XML can be found in Appendix C.
14.3. MIME Registration
As an XML type, CPL’s MIME registration conforms with "XML Media
Types," RFC 3023 [15].
MIME media type name: application
MIME subtype name: cpl+xml
Mandatory parameters: none
Optional parameters: charset
As for application/xml in RFC 3023.
Encoding considerations: As for application/xml in RFC 3023.
Security considerations: See Section 13, and Section 10 of RFC
3023.
Interoperability considerations: Different CPL servers may use
incompatible address types. However, all potential
interoperability issues should be resolvable at the time a
script is uploaded; there should be no interoperability
issues which cannot be detected until runtime.
Published specification: This document.
Applications which use this media type: SIP proxy servers and
other telephony servers, and client software to control
their behavior.
Additional information:
Magic number: None
File extension: .cpl or .xml
Macintosh file type code: "TEXT"
Person and e-mail address for further information:
Jonathan Lennox <lennox@cs.columbia.edu>
Xiaotao Wu <xiaotaow@cs.columbia.edu>
Henning Schulzrinne <hgs@cs.columbia.edu>
Intended usage: COMMON
Author/Change Controller: The IETF.
15. Acknowledgments
This document was reviewed and commented upon by the IETF IP
Telephony Working Group. We specifically acknowledge the following
people for their help:
The outgoing call screening script was written by Kenny Hom.
Paul E. Jones contributed greatly to the mappings of H.323 addresses.
The text of the time-switch section was taken (lightly modified) from
RFC 2445 [8], by Frank Dawson and Derik Stenerson.
We drew a good deal of inspiration, notably the language’s lack of
Turing-completeness and the syntax of string matching, from the
specification of Sieve [22], a language for user filtering of
electronic mail messages.
Thomas F. La Porta and Jonathan Rosenberg had many useful
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
The following algorithm determines whether a given instant falls
within a repetition of a "time-switch" recurrence. If the pre-
processing described in Section 4.4.1 has been done, it operates in
constant time. Open-source Java code implementing this algorithm is
available at http://www.cs.columbia.edu/~lennox/Cal-Code/ on the
world wide web.
This algorithm is believed to be correct, but this section is non-
normative. Section 4.4, and RFC 2445 [8], are the definitive
definitions of recurrences.
1. Compute the time of the call, in the timezone of the time
switch.
2. If the call time is earlier than "dtstart", fail NOMATCH.
3. If the call time is less than "duration" after dtstart, succeed
MATCH.
4. Determine the smallest unit specified in a "byxxx" rule or by
the "freq." Call this the Minimum Unit. Determine the
previous instant (before or equal to the call time) when all
the time units smaller than the minimum unit are the same as
those of "dtstart." If the minimum unit is a second, this time
is the same as the instant. If the minimum unit is a minute or
an hour, the minutes or the minutes and hours, respectively,
must be the same as "dtstart". For all other minimum units,
the time-of-day must be the same as "dtstart." If the minimum
unit is a week, the day-of-the-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 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 February 29th. In the Gregorian calendar, it is never
necessary to roll back more than two months if the minimum 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.
5. If the time between the candidate start time and the call time
is more than the duration, fail NOMATCH.
6. If the candidate start time is later than the "until" 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
Frequency Unit. Determine the frequency unit enclosing the
Candidate Start Time, and that enclosing "dtstart". Calculate
the number of frequency units that have passed between these
two times. If this is not a multiple of the "interval"
parameter, fail NOMATCH.
8. For every "byxxx" rule, confirm that the candidate start time
matches one of the options specified by that "byxxx" rule. If
so, 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
This appendix gives a suggested usage of CPL with H.323 [16]. Study
Group 16 of the ITU, which developed H.323, is proposing to work on
official CPL mappings for that protocol. This section is therefore
not normative.
B.1. Usage of "address-switch" with H.323
Address switches are specified in Section 4.1. This section
specifies the mapping between H.323 messages and the fields and
subfields of address-switches.
For H.323, the "origin" address corresponds to the alias addresses in
the "sourceAddress" field of the "Setup-UUIE" user-user information
element, and to the Q.931 [23] information element "Calling party
number." If both fields are present, or if multiple alias addresses
for "sourceAddress" are present, which one has priority is a matter
of local server policy; the server SHOULD use the same resolution as
it would use for routing decisions in this case. Similarly, the
"destination" address corresponds to the alias addresses of the
"destinationAddress" field, and to the Q.931 information element
"Called party number."
The "original-destination" address corresponds to the "Redirecting
number" Q.931 information element, if it is present; otherwise it is
the same as the "destination" address.
The mapping of H.323 addresses into subfields depends on the type of
the alias address. An additional subfield type, "alias-type", is
defined for H.323 servers, corresponding to the type of the address.
Possible values are "dialedDigits", "h323-ID", "url-ID",
"transportID", "email-ID", "partyNumber", "mobileUIM", and "Q.931IE".
If future versions of the H.323 specification define additional types
of alias addresses, those names MAY also be used.
In versions of H.323 prior to version 4, "dialedDigits" was known as
"e164". The two names SHOULD be treated as synonyms.
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 than h323; in this case the address-type is the URL scheme, as
specified in Section 4.1.1 for SIP.
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
aliases, if subfields in the primary address are not present.
The following mappings are used for H.323 alias types:
dialedDigits, partyNumber, mobileUIM, and Q.931IE: the "tel" and
"user" subfields are the string of digits, as is the
"entire-address" form. The "host" and "port" subfields are
not present.
url-ID: the same mappings are used as for SIP, in Section 4.1.1.
h323-ID: the "user" field is the string of characters, as is the
"entire-address" form. All other subfields are not present.
email-ID: the "user" and "host" subfields are set to the
corresponding parts of the e-mail address. The "port" and
"tel" subfields are not present. The "entire-address" form
corresponds to the entire e-mail address.
transportID: if the TransportAddress is of type "ipAddress,"
"ipSourceRoute," or "ip6Address," the "host" subfield is set
to the "ip" element of the sequence, translated into the
standard IPv4 or IPv6 textual representation, and the "port"
subfield is set to the "port" element of the sequence
represented in decimal. The "tel" and "user" fields are not
present. The "entire-address" form is not defined. The
representation and mapping of transport addresses is not
defined for non-IP addresses.
H.323 [16] defines an "h323" URI scheme. This appendix defines a
mapping for these URIs onto the CPL "address-switch" subfields, as
given in Section 4.1. This definition is also available as RFC 3508
[24], which is an excerpt from the H.323 specification.
For h323 URIs, the "user", "host", and "port" subfields are set to
the corresponding parts of the H.323 URL. The "tel" subfield is 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 alias, and for h323 URIs in SIP messages.
B.2. Usage of "string-switch" with H.323
For H.323, the "string-switch" node (see Section 4.2) is used as
follows. The field "display" corresponds to the Q.931 information
element of the same name, copied verbatim. The fields "subject",
"organization", and "user-agent" are not used and are never present.
The "display" IE is conventionally used for Caller-ID purposes, so
arguably it should be mapped to the "display" subfield of an
"address-match" with the field "originator". However, since a) it
is a message-level information element, not an address-level one,
and b) the Q.931 specification [23] says only that "[t]he purpose
of the Display information element is to supply display
information that may be displayed by the user," it seems to be
more appropriate to allow it to be matched in a "string-switch"
instead.
B.3. Usage of "language-switch" with H.323
The language-ranges for the "language-switch" switch are obtained
from the H.323 UUIE "language". The switch is not-present if the
initial message did not contain this UUIE.
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 4.5).
B.5. Usage of "location" with H.323
Locations in explicit location nodes (Section 5.1) are specified as
URLs. Therefore, all locations added in this manner are interpreted
as being of alias type "url-ID" in H.323.
Specifications of other H.323 address alias types will require a CPL
extension (see Section 11).
B.6. Usage of "lookup" with H.323
For location lookup nodes (Section 5.2), the "registration" lookup
source corresponds to the locations registered with the server using
"RAS" messages.
B.7. Usage of "remove-location" with H.323
Location removal nodes (Section 5.3) remove addresses with the alias
type "url-ID" using verbatim string matching on the URLs. If a "tel"
URL is specified as the location, matching addresses (ignoring visual
separators) with the alias types "dialedDigits" ("e164"),
"partyNumber", "mobileUIM", or "Q.931IE" are also removed. No
mechanism is provided to remove other alias types.
C. The XML Schema for CPL
This section includes a full XML Schema describing the XML syntax of
CPL. Every script submitted to a CPL server SHOULD comply with this
XML Schema. When parsing scripts comply with the CPL DTD in earlier
documents, the DOCTYPE lines in the scripts should be ignored. Note
that compliance with this schema is not a sufficient condition for
correctness of a CPL script, as many of the conditions described in
this specification are not expressible in schema syntax. Figure 31
shows the structure of the schema. ’incoming’ and ’outgoing’ are
defined as the substitutionGroup of the ’toplevelaction’. All the
switches are defined as the substitutionGroup of the ’switch’
element. All the actions are defined as the substitutionGroup of the
’action’ element.
+---------+ +------+ +--address
+-+ancillary| |switch|** +--------------+ | +-not-present
| +---------+ +---+--+ **|address-switch+-+-+-address
| | * +--------------+ +--otherwise
| +---------+ +----+ | * +--language
+-+subaction+-+Node| | * +---------------+ | +-not-present
| +---------+ +----+ | **|language-switch|-+-+-language
| | * +---------------+ +--otherwise
| | * +--priority
| | * +---------------+ | +-not-present
| | **|priority-switch|-+-+-priority
| | * +---------------+ +--otherwise
| | * +--string
cpl-+ | * +-------------+ | +-not-present
| | **|string-switch|-+ +-string
| | * +-------------+ +--otherwise
| | * +--time
| +--------------+ +-+--+ * +-----------+ | +-not-present
+-+toplevelaction+-+Node| *|time-switch|-+-+-time
+-----*--------+ +-+--+ +-----------+ +--otherwise
* | +--------+ +----+
* | **|location+-|Node|
* | +--------+ * +--------+ +----+
* +--------+ |-+modifier|** +------+ +-success-Node
**|incoming| | +--------+ *-|lookup+-+-notfound-Node
* +--------+ | * +------+ +-failure-Node
* | +---+ * +---------------+ +----+
* +--------+ +-+Sub+-sub **|remove-location+-+Node|
*|outgoing| | +---+ +---------------+ +----+