Internet Engineering Task Force IPTEL WG
Internet Draft Lennox/Schulzrinne
draft-ietf-iptel-cpl-01.txt Columbia University
March 10, 2000
Expires: September 2000
CPL: A Language for User Control of Internet Telephony Services
STATUS OF THIS MEMO
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress".
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Abstract
The Call Processing Language (CPL) is a language that can be used to
describe and control Internet telephony services. It is designed to
be implementable on either network servers or user agent servers. It
is meant to be simple, extensible, easily edited by graphical
clients, and independent of operating system or signalling protocol.
It is suitable for running on a server where users may not be allowed
to execute arbitrary programs, as it has no variables, loops, or
ability to run external programs.
This document is a product of the IP Telephony (IPTEL) working group
of the Internet Engineering Task Force. Comments are solicited and
should be addressed to the working group's mailing list at
iptel@lists.research.bell-labs.com and/or the authors.
1 Introduction
The Call Processing Language (CPL) is a language that can be used to
Lennox/Schulzrinne [Page 1]
Internet Draft CPL March 10, 2000
describe and control Internet telephony services. It is not tied to
any particular signalling architecture or protocol; it is anticipated
that it will be used with both SIP [1] and H.323 [2].
The CPL is powerful enough to describe a large number of services and
features, but it is limited in power so that it can run safely in
Internet telephony servers. The intention is to make it impossible
for users to do anything more complex (and dangerous) than describing
Internet telephony services. The language is not Turing-complete, and
provides no way to write loops or recursion.
The CPL is also designed to be easily created and edited by graphical
tools. It is based on XML [3], so parsing it is easy and many
parsers for it are publicly available. The structure of the language
maps closely to its behavior, so an editor can understand any valid
script, even ones written by hand. The language is also designed so
that a server can easily confirm scripts' validity at the time they
are delivered to it, rather that discovering them while a call is
being processed.
Implementations of the CPL are expected to take place both in
Internet telephony servers and in advanced clients; both can usefully
process and direct users' calls. In the former case, a mechanism will
be needed to transport scripts between clients and servers; this
document does not describe such a mechanism, but related documents
will.
The framework and requirements for the CPL architecture are described
in the document "Call Processing Language Framework and
Requirements," which will be an Informational RFC; it is currently
available as the Internet-Draft draft-ietf-iptel-cpl-framework-02
[4].
1.1 Conventions of this document
In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in RFC 2119 [5] and
indicate requirement levels for compliant CPL implementations.
In examples, non-XML strings such as -action1, -action2, and so
forth, are sometimes used. These represent further parts of the
script which are not relevant to the example in question.
Some paragraphs are indented, like this; they give
motivations of design choices, or questions for future
discussion in the development of the CPL, and are not
Lennox/Schulzrinne [Page 2]
Internet Draft CPL March 10, 2000
essential to the specification of the language.
2 Structure of CPL scripts
2.1 High-level structure
A CPL script consists of two types of information: ancillary
information about the script, and call processing actions.
A call processing action is a structured tree that describes the
decisions and actions a telephony signalling server performs on a
call set-up event. There are two types of call processing actions:
top-level actions are actions that are triggered by signalling events
that arrive at the server. Two top-level action names are defined:
incoming, the action performed when a call arrives whose destination
is the owner of the script; and outgoing, the action performed when a
call arrives whose originator is the owner of the script. Sub-actions
are actions which can be called from other actions. The CPL forbids
sub-actions from being called recursively: see section 8.
Note: The names "action," "sub-action," and "top-level
action" are probably not ideal. Suggestions for better
names for these concepts are welcomed.
Ancillary information is information which is necessary for a server
to correctly process a script, but which does not directly describe
any actions. Currently, the only type of ancillary information
defined is timezone definitions; see section 9.
2.2 Abstract structure of a call processing action
Abstractly, a call processing action is described by a collection of
nodes, which describe actions that can be performed or choices which
can be made. A node may have several parameters, which specify the
precise behavior of the node; they usually also have outputs, which
depend on the result of the condition or action.
For a graphical representation of a CPL action, see figure 1. Nodes
and outputs can be thought of informally as boxes and arrows; the CPL
is designed so that actions can be conveniently edited graphically
using this representation. Nodes are arranged in a tree, starting at
a single root node; outputs of nodes are connected to additional
nodes. When an action is run, the action or condition described by
the top-level node is performed; based on the result of that node,
the server follows one of the node's outputs, and that action or
condition is performed; this process continues until a node with no
specified outputs is reached. Because the graph is acyclic, this
Lennox/Schulzrinne [Page 3]
Internet Draft CPL March 10, 2000
will occur after a bounded and predictable number of nodes are
visited.
If an output to a node is not specified, it indicates that the CPL
server should perform a node- or protocol-specific action. Some nodes
have specific default actions associated with them; for others, the
default action is implicit in the underlying signalling protocol, or
can be configured by the administrator of the server. For further
details on this, see section 10.
_________________ ___________________ ________ busy
| Address-switch | | location | | proxy |--------\
Call --->| field: origin | ->| url: sip:jones@ |--->|timeout:| timeout|
| subfield: host | / | example.com | | 10s |--------|
|-----------------|/ |___________________| | | failure|
| subaddress-of: | |________|--------|
| example.com | |
|-----------------| _____________________________________________/
| otherwise | /..........................................
| |\|. Voicemail .
|_________________| \. ____________________ .
->| location | __________ .
. | url: sip:jones@ | | redirect | .
. | voicemail. |--->| | .
. | example.com | |__________| .
. |____________________| .
..........................................
Figure 1: Sample CPL Action: Graphical Version
2.3 Location model
For flexibility, one piece of information necessary for the function
of a CPL is not given as node parameters: the set of locations to
which a call is to be directed. Instead, this set of locations is
stored as an implicit global variable throughout the execution of a
processing action (and its sub-actions). This allows locations to be
retrieved from external sources, filtered, and so forth, without
requiring general language support for such actions (which could harm
the simplicity and tractability of understanding the language). The
Lennox/Schulzrinne [Page 4]
Internet Draft CPL March 10, 2000
specific actions which add, retrieve, or filter location sets are
given in section 5.
For the incoming top-level processing action, the location set is
initialized to the empty set. For the outgoing action, it is
initialized to the destination address of the call.
2.4 XML structure
Syntactically, CPL scripts are represented by XML documents. XML is
thoroughly specified by [3], and implementors of this specification
should be familiar with that document, but as a brief overview, XML
consists of a hierarchical structure of tags; each tag can have a
number of attributes. It is visually and structurally very similar to
HTML [6], as both languages are simplifications of the earlier and
larger standard SGML [7].
See figure 2 for the XML document corresponding to the graphical
representation of the CPL script in figure 1. Both nodes and outputs
in the CPL are represented by XML tags; parameters are represented by
XML tag attributes. Typically, node tags contain output tags, and
vice-versa (with one exception; see section 2.3).
The connection between the output of a node and another node is
represented by enclosing the tag representing the pointed-to node
inside the tag for the outer node's output. Convergence (several
outputs pointing to a single node) is represented by sub-actions,
discussed further in section 8.
The higher-level structure of a CPL script is represented by tags
corresponding to each piece of meta-information, sub-actions, and
top-level actions, in order. This higher-level information is all
enclosed in a special tag cpl, the outermost tag of the XML document.
A complete Document Type Declaration for the CPL is provided in
Appendix A. The remainder of the main sections of this document
describe the semantics of the CPL, while giving its syntax
informally. For the formal syntax, please see the appendix.
3 Script structure: overview
As mentioned, a CPL script consists of ancillary information,
subactions, and top-level actions. The full syntax of the cpl node is
given in figure 3.
Call processing actions, both top-level actions and sub-actions,
Lennox/Schulzrinne [Page 5]
Internet Draft CPL March 10, 2000
Figure 2: Sample CPL Script: XML Version
consist of nodes and outputs. Nodes and outputs are both described by
XML tags. There are four categories of CPL nodes: switches , location
modifiers , signalling actions , and non-signalling actions.
4 Switches
Switches represent choices a CPL script can make, based on either
attributes of the original call request or items independent of the
call.
All switches are arranged as a list of conditions that can match a
variable. Each condition corresponds to a node output; the output
points to the next node to execute if the condition was true. The
conditions are tried in the order they are presented in the script;
the output corresponding to the first node to match is taken.
Lennox/Schulzrinne [Page 6]
Internet Draft CPL March 10, 2000
Node: cpl
Parameters: none
Outputs: timezone See section 9
subaction See section 8
outgoing Top-level actions to take on this user's outgoing calls
incoming Top-level actions to take on this user's incoming calls
Output: outgoing
Parameters: none
Output: incoming
Parameters: none
Figure 3: Syntax of the top-level cpl tag
There are two special switch outputs that apply to every switch type.
The output not-present is true if the variable the switch was to
match was not present in the original call. The output otherwise,
which MUST be the last output specified, matches if no other
condition matched.
If no condition matches and no otherwise output was present in the
script, the default script action is taken. See section 10 for more
information on this.
4.1 Address switches
Address switches allow a CPL script to make decisions based on one of
the addresses present in the original call request. They are
summarized in figure 4.
Address switches have two node parameters: field, and subfield. The
mandatory field parameter allows the script to specify which address
is to be considered for the switch: either the call's origin address
(field "origin"), its current destination address (field
"destination"), or its original destination (field "original-
destination"), the destination the call had before any earlier
forwarding was invoked. Servers MAY define additional subfield
values.
The optional subfield specifies what part of the address is to be
considered. The possible subfield values are: address-type, user,
host, port, tel, and display. Additional subfield values MAY be
defined: two additional ones, password and asn1 are defined
Lennox/Schulzrinne [Page 7]
Internet Draft CPL March 10, 2000
Node: address-switch
Outputs: address Specific addresses to match
Parameters: field origin, destination, or original-destination
subfield address-type, user, host, port, tel, display,
password, or asn1
Output: address
Parameters: is exact match
contains substring match (for display only)
subdomain-of sub-domain match (for host, tel only)
Figure 4: Syntax of the address-switch node
specifically for SIP and H.323 respectively, in sections 4.1.1 and
4.1.2 below. If no subfield is specified, the "entire" address is
matched; the precise meaning of this is defined for each underlying
signalling protocol.
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
the URI. The types specifically discussed by this document
are sip, tel, and h323. The address type is not case-
sensitive; it is always present if the address is present.
user This subfield of the address indicates, for e-mail style
addresses, the user part of the address. For telephone
number style address, it includes the subscriber number.
This subfield is case-sensitive; it may be not present.
host This subfield of the address indicates the Internet host
name or IP address corresponding to the address, in host
name, IPv4, or IPv6 format. For host names only, subdomain
matching is supported with the subdomain-of match operator.
It is not case sensitive, and may be not present.
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. It may
be not present; however, for address types with default
ports, an absent port matches the default port number.
tel This subfield indicates a telephone subscriber number, if
the address contains such a number. It is not case
Lennox/Schulzrinne [Page 8]
Internet Draft CPL March 10, 2000
sensitive (the telephone numbers may contain the symbols
`A' `B' `C' and `D'), and may be not present. 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 not present.
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,
match="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;
match="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 Address switch mapping for SIP
For SIP, the origin address corresponds to the address in the From
header; destination corresponds to the Request-URI; and original-
Lennox/Schulzrinne [Page 9]
Internet Draft CPL March 10, 2000
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 URLs, the user, host, and port subfields correspond to the
"user," "host," and "port" elements of the URI syntax. The tel
subfield is defined to be the "user" part of the URI if and only if
the "user=phone" parameter is given to the URI. An additional
subfield, password is defined to correspond to the "password" element
of the SIP URI; 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, "noise" characters are stripped. the host and port
subfields are both not present.
For other URI schemes, only the address-type subfield is defined by
this specification; servers MAY set others of the 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, with all parameters stripped.
4.1.2 Address switch mapping for H.323
For H.323, the origin address corresponds to the address in the
sourceAddress field; both destination and original-destination
correspond to the destinationAddress field, as H.323 has no
indication of original destination.
For all addresses in H.323 messages, the value of the address-type
field is h323. The tel tag is set to the AliasAddress, if its type is
e164. The user tag is set to h323-ID; host is set to
transportID/TransportAddress/ipAddress, translated to a dotted-quad;
port is set to transportID/TransportAddress/ipAddress/port. The
display tag is not present. An additional subfield, asn1, is defined
as the textually-encoded ASN.1 of the address. The matching if no
subfield is specified is undefined at this time.
TODO: Have this looked over by an H.323 expert for
accuracy/completeness. Once an h323 URL scheme is defined,
it should be used for the whole-address matching.
Lennox/Schulzrinne [Page 10]
Internet Draft CPL March 10, 2000
4.2 String switches
String switches allow a CPL script to make decisions based on free-
form Unicode 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, or user-agent
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. Currently three
fields are defined: subject, indicating the subject of the call;
organization, indicating the originator's organization; and user-
agent, indicating the program or device with which the call request
was made. All these fields correspond to SIP strings.
TODO: Need H.323 free-form strings. "Data"?
Strings are matched as case-insensitive Unicode strings, in the
following manner. First, strings are canonicalized to the
"Compatibility Composition" (KC) form, as specified in Unicode
Technical Report 15 [8]. Then, strings are compared using locale-
insensitive caseless mapping, as specified in Unicode Technical
Report 21 [9].
Code to perform the first step, in Java and Perl, is
available; see the links from Annex E of UTR 15 [8]. 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 tags of string matching are named string, and have a
mandatory argument, one of is or contains, indicating whole-string
match or substring match, respectively.
Lennox/Schulzrinne [Page 11]
Internet Draft CPL March 10, 2000
4.3 Time switches
Time switches allow a CPL script to make decisions based the time
and/or date the script is being executed. They are summarized in
figure 6.
Node: time-switch
Outputs: time Specific time to match
Parameters: timezone local, utc, or other (see section 9)
Output: time
Parameters: year Years to match
month Months to match
date Days of month to match
weekday Days of week to match
timeofday Times of day to match
Figure 6: Syntax of the time-switch node
Time switches take one optional parameter, timezone, which specifies
the time zone in which matching is to take place. Two values of this
are predefined: local indicates the time zone in which the server is
located, and utc indicates Universal Coordinated Time. Timezones may
also be specified in the ancillary information; see section 9.
The time outputs can take the following optional parameters: year,
month, date, day, and timeofday. Each argument is syntactically
expressed as a list of numeric ranges. Ranges are delimited as
value-value; lists elements are separated by commas. Months are
specified in the range 1-12; date as 1-31, day as 0-6 (where 0 is
Sunday), and times of day as 24-hour times in the range 0000-2359;
years are unlimited in range, though only positive values are
allowed.
An output node matches if the time the triggering call was placed
falls within one of specified the ranges in each of the specified
parameters.
The following examples show sample time nodes, and descriptions of
the corresponding time periods they indicate: