RFC 3880
Call Processing Language (CPL): A Language for User Control of Internet Telephony Services
Pages: 74
Proposed Standard
Proposed Standard
Part 2 of 3 – Pages 22 to 51
5. Location Modifiers
The abstract location model of CPL is described in Section 2.3. The behavior of several of the signalling operations (defined in Section 6) is dependent on the current location set specified. Location nodes add or remove locations from the location set.
There are three types of location nodes defined. Explicit locations add literally-specified locations to the current location set, location lookups obtain locations from some outside source, and location filters remove locations from the set, based on some specified criteria.5.1. Explicit Location
Explicit location nodes specify a location literally. Their syntax is described in Figure 9. Explicit location nodes are dependent on the underlying signalling protocol. Node: "location" Outputs: None (Next node follows directly) Next node: Any node Parameters: "url" URL of address to add to location set "priority" Priority of this location (0.0-1.0) "clear" Whether to clear the location set before adding the new value Figure 9: Syntax of the "location" node Explicit location nodes have three node parameters. The mandatory "url" parameter's value is the URL of the address to add to the location set. Only one address may be specified per location node; multiple locations may be specified by cascading these nodes. The optional "priority" parameter specifies a priority for the 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 of 1.0. The optional "clear" parameter specifies whether the location set should be cleared before adding the new location to it. Its value can be "yes" or "no", with "no" as the default. Basic location nodes have only one possible result, since there is no way that they can fail. (If a basic location node specifies a location which isn't supported by the underlying signalling protocol, the script server SHOULD detect this and report it to the user at the time the script is submitted.) Therefore, their XML representations do not have explicit output tags; the <location> tag directly contains another node.5.1.1. Usage of "location" with SIP
All SIP locations are represented as URLs, so the locations specified in "location" tags are interpreted directly.
5.2. Location Lookup
Locations can also be specified up through external means, through the use of location lookups. The syntax of these tags is given in Figure 10. Location lookup is dependent on the underlying signalling protocol. Node: "lookup" Outputs: "success" Next node if lookup was successful "notfound" Next node if lookup found no addresses "failure" Next node if lookup failed Parameters: "source" Source of the lookup "timeout" Time to try before giving up on the lookup "clear" Whether to clear the location set before adding the new values Output: "success" Parameters: none Output: "notfound" Parameters: none Output: "failure" Parameters: none Figure 10: Syntax of the "lookup" node Location lookup nodes have one mandatory parameter and two optional 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 "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 IANA registration of this type, which also appears in RFC 2483 [10]). The query is performed verbatim, with no additional information (such as URI parameters) added. The server adds the locations contained in this object to the location set. CPL servers MAY refuse to allow URI-based sources for location queries for some or all URI schemes. In this case, they SHOULD reject the script at script upload time. There has been discussion of having CPL servers add URI parameters to the location request, so that (for instance) CGI scripts could be used to resolve them. However, the consensus was that this should be a CPL extension, not a part of the base specification.
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 non-URL source currently defined is "registration", which specifies all the locations currently registered with the server. The "lookup" node also has two optional parameters. The "timeout" parameter specifies the time, as a positive integer number of seconds, the script is willing to wait for the lookup to be performed. If this is not specified, its default value is 30. The "clear" parameter specifies whether the location set should be cleared before the new locations are added. Lookup has three outputs: "success", "notfound", and "failure". Notfound is taken if the lookup process succeeded but did not find any locations; failure is taken if the lookup failed for some reason, including that the specified timeout was exceeded. If a given output is not present, script execution terminates and the default behavior is performed.5.2.1. Usage of "lookup" with SIP
For SIP, the "registration" lookup source corresponds to the locations registered with the server using "REGISTER" messages.5.3. Location Removal
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 defined in Figure 11. The meaning of this node is dependent on the underlying signalling Protocol. Node: "remove-location" Outputs: None (Next node follows directly) Next node: Any node Parameters: "location" Location to remove Figure 11: Syntax of the "remove-location" node A "remove-location" node removes locations from the location set. It is primarily useful following a "lookup" node. An example of this is given in Section 12.8. The "remove-location" node has one optional parameter. The parameter "location" gives the URI of a location to be removed from the set, in a signalling-protocol-dependent manner. If this parameter is not given, all locations are removed from the set.
The "remove-location" node has no explicit output tags. In the XML syntax, the XML "remove-location" tag directly encloses the next node's tag.5.3.1. Usage of "remove-location" with SIP
The location specified in the "location" parameter of the "remove- location" node is matched against the location set using the standard rules for SIP URI matching (as are used, e.g., to match Contact addresses when refreshing registrations).6. Signalling Operations
Signalling operation nodes cause signalling events in the underlying signalling protocol. Three signalling operations are defined: "proxy," "redirect," and "reject."6.1. Proxy
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 Figure 12. The specific signalling events invoked by the "proxy" node are signalling-protocol-dependent, though the general concept should apply to any signalling protocol.
Node: "proxy" Outputs: "busy" Next node if call attempt returned "busy" "noanswer" Next node if call attempt was not answered before timeout "redirection" Next node if call attempt was redirected "failure" Next node if call attempt failed "default" Default next node for unspecified outputs Parameters: "timeout" Time to try before giving up on the call attempt "recurse" Whether to recursively look up redirections "ordering" What order to try the location set in. Output: "busy" Parameters: none Output: "noanswer" Parameters: none Output: "redirection" Parameters: none Output: "failure" Parameters: none Output: "default" Parameters: none Figure 12: Syntax of the "proxy" node After a proxy operation has completed, the CPL server chooses the "best" response to the call attempt, as defined by the signalling protocol or the server's administrative configuration rules. 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 "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 before the "timeout" parameter expired, "redirection" is followed if the call was redirected, and "failure" is followed if the call setup failed for any other reason. If one of the conditions above is true, but the corresponding output was not specified, the "default" output of the "proxy" node is followed instead. If there is also no "default" node specified, CPL execution terminates and the server returns to its default behavior (normally, to forward the best response upstream to the originator).
Note: CPL extensions to allow in-call or end-of-call operations
will require an additional output, such as "success", to be added.
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
example, "http" URLs), the "failure" output is taken.
Proxy has three optional parameters. The "timeout" parameter
specifies the time, as a positive integer number of seconds, to wait
for the call to be completed or rejected; after this time has
elapsed, the call attempt is terminated and the "noanswer" branch is
taken. If this parameter is not specified, the default value is 20
seconds if the "proxy" node has a "noanswer" or "default" output
specified; otherwise the server SHOULD allow the call to ring for a
reasonably long period of time (to the maximum extent that server
policy allows).
The second optional parameter is "recurse", which can take two
values, "yes" or "no". This specifies whether the server should
automatically attempt to place further call attempts to telephony
addresses in redirection responses that were returned from the
initial server. Note that if the value of "recurse" is "yes", the
"redirection" output to the script is never taken. In this case this
output SHOULD NOT be present. The default value of this parameter is
"yes".
The third optional parameter is "ordering". This can have three
possible values: "parallel", "sequential", and "first-only". This
parameter specifies in what order the locations of the location set
should be tried. Parallel asks that they all be tried
simultaneously; sequential asks that the one with the highest
priority be tried first, the one with the next-highest priority
second, and so forth, 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 follow one of the outputs. The priority
of locations in a set is determined by server policy, though CPL
servers SHOULD honor the "priority" parameter of the "location" tag.
The default value of this parameter is "parallel".
Once a proxy operation completes, if control is passed on to other
nodes, all locations which have been used are cleared from the
location set. That is, the location set is emptied of proxyable
locations if the "ordering" was "parallel" or "sequential"; the
highest-priority item in the set is removed from the set if
"ordering" was "first-only". (In all cases, non-proxyable locations
such as "http" URIs remain.) In the case of a "redirection" output,
the new addresses to which the call was redirected are then added to
the location set.
6.1.1. Usage of "proxy" with SIP
For SIP, the best response to a "proxy" node is determined by the algorithm of the SIP specification. The node's outputs correspond to the following events: busy: A 486 or 600 response was the best response received for the call request. redirection: A 3xx response was the best response received for the call request. failure: Any other 4xx, 5xx, or 6xx response was the best response received for the call request. no-answer: No final response was received for the call request before the timeout expired. SIP servers SHOULD honor the "q" parameter of SIP registrations when determining location priority.6.2. Redirect
Redirect causes the server to direct the calling party to attempt to place its call to the currently specified set of locations. The syntax of this node is specified in Figure 13. The specific behavior the redirect node invokes is dependent on the underlying signalling protocol involved, though its semantics are generally applicable. Node: "redirect" Outputs: None (No node may follow) Next node: None Parameters: "permanent" Whether the redirection should be considered permanent Figure 13: Syntax of the "redirect" node Redirect immediately terminates execution of the CPL script, so this node has no outputs and no next node. It has one parameter, "permanent", which specifies whether the result returned should indicate that this is a permanent redirection. The value of this parameter is either "yes" or "no" and its default value is "no."
6.2.1. Usage of "redirect" with SIP
The SIP server SHOULD send a 3xx class response to a call request upon executing a "redirect" tag. If "permanent" was "yes", the server SHOULD send the response "301" (Moved permanently), otherwise it SHOULD send "302" (Moved temporarily).6.3. Reject
Reject nodes cause the server to reject the call attempt. Their syntax is given in Figure 14. The specific behavior they invoke is dependent on the underlying signalling protocol involved, though their semantics are generally applicable. Node: "reject" Outputs: None (No node may follow) Next node: None Parameters: "status" Status code to return "reason" Reason phrase to return Figure 14: Syntax of the "reject" node A reject node immediately terminates the execution of a CPL script, so this node has no outputs and no next node. This node has two arguments: "status" and "reason". The "status" argument is required, and can take one of the values "busy", "notfound", "reject", "error", or a signalling-protocol-defined status. The "reason" argument optionally allows the script to specify a reason for the rejection.6.3.1. Usage of "reject" with SIP
Servers which implement SIP SHOULD also allow the "status" field to be a numeric argument corresponding to a SIP status in the 4xx, 5xx, or 6xx range. They SHOULD send the "reason" parameter in the SIP reason phrase. A suggested mapping of the named statuses is as follows. Servers MAY use a different mapping, though similar semantics SHOULD be preserved. "busy": 486 Busy Here "notfound": 404 Not Found
"reject": 603 Decline
"error": 500 Internal Server Error
7. Non-signalling Operations
In addition to the signalling operations, CPL defines several
operations which do not affect and are not dependent on the telephony
signalling protocol.
7.1. Mail
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
15.
Node: "mail"
Outputs: None (Next node follows directly)
Next node: Any node
Parameters: "url" Mailto url to which the mail should be sent
Figure 15: Syntax of the "mail" node
The "mail" node takes one argument: a "mailto" URL giving the
address, and any additional desired parameters, of the mail to be
sent. The server sends the message containing the content to the
given url; it SHOULD also include other status information about the
original call request and the CPL script at the time of the
notification.
Using a full "mailto" URL rather than just an e-mail address
allows additional e-mail headers to be specified, such as
<mail url="mailto:jones@example.com?subject=Lookup%20failed" />.
A mail node has only one possible result, since failure of e-mail
delivery cannot reliably be known in real time. Therefore, its XML
representation does not have output tags: the <mail> tag directly
contains another node tag.
Note that the syntax of XML requires that ampersand characters, "&",
which are used as parameter separators in "mailto" URLs, be quoted as
"&" inside parameter values (see Section C.12 of the XML
specification [2]).
7.1.1. Suggested Content of Mailed Information
This section presents suggested guidelines for the mail sent as a result of the "mail" node, for requests triggered by SIP. The message mailed (triggered by any protocol) SHOULD contain all this information, but servers MAY elect to use a different format. 1. If the "mailto" URI did not specify a subject header, the subject of the e-mail is "[CPL]", followed by the subject header of the SIP request. If the URI specified a subject header, it is used instead. 2. The "From" field of the e-mail is set to a CPL server configured address, overriding any "From" field in the "mailto" URI. 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 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 stripping the URI scheme). 4. If the "mailto" URI specifies a body, it is used. If none was specified, the body SHOULD contain at least the identity of the caller (both the caller's display name and address), the date and time of day, the call subject, and if available, the call priority. The server SHOULD honor the user's requested languages, and send the mail notification using an appropriate language and character set.7.2. Log
The Log node causes the server to log information about the call to non-volatile storage. Its syntax is specified in Figure 16. Node: "log" Outputs: None (Next node follows directly) Next node: Any node Parameters: "name" Name of the log file to use "comment" Comment to be placed in log file 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 the "name" parameter is not given, the event is logged to a standard, server-defined log file for the script owner. This specification does 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 correspond to any physical file on the server. The interpretation of the log file name is server defined, as is a mechanism to access these logs. The CPL server SHOULD NOT directly map log names uninterpreted onto local file names, for security reasons, lest a security-critical file be overwritten. A correctly operating CPL server SHOULD NOT ever allow the "log" event to fail. As such, log nodes can have only one possible result, and their XML representation does not have explicit output tags. A CPL <log> tag directly contains another node tag.8. Subactions
XML syntax defines a tree. To allow more general call flow diagrams, and to allow script re-use and modularity, we define subactions. Two tags are defined for subactions: subaction definitions and subaction references. Their syntax is given in Figure 17. Tag: "subaction" Subtags: Any node Parameters: "id" Name of this subaction Pseudo-node: "sub" Outputs: None in XML tree Parameters: "ref" Name of subaction to execute Figure 17: Syntax of subactions and "sub" pseudo-nodes Subactions are defined through "subaction" tags. These tags are placed in the CPL script after any ancillary information (see Section 9), 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. Subactions are called from "sub" tags. The "sub" tag is a "pseudo- node", and 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, instead control passes to the subaction.
References to subactions MUST refer to subactions defined before the
current action. A "sub" tag MUST NOT refer to the action it 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 means.
Script servers MUST verify at the time the script is submitted that
no "sub" node refers to any subaction that is not its proper
predecessor.
Allowing only back-references of subs forbids any sort of
recursion. Recursion would introduce the possibility of non-
terminating or non-decidable CPL scripts, a possibility our
requirements specifically excluded.
Every sub MUST refer to a subaction ID defined within the same CPL
script. No external links are permitted.
Subaction IDs are case sensitive.
If any subsequent version or extension defines external linkages,
it should probably use a different tag, perhaps XLink [21].
Ensuring termination in the presence of external links is a
difficult problem.
9. Ancillary Information
No ancillary information is defined in the base CPL specification.
If ancillary information, not part of any operation, is found to be
necessary for a CPL extension, it SHOULD be placed within this tag.
The (trivial) definition of the ancillary information tag is given in
Figure 18.
It may be useful to include timezone definitions inside CPL
scripts directly, rather than referencing them externally with
"tzid" and "tzurl" parameters. If it is, an extension could be
defined to include them here.
Tag: "ancillary"
Parameters: None
Subtags: None
Figure 18: Syntax of the "ancillary" tag
10. Default Behavior
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 contain a node, the CPL server's behavior is dependent on the current state of script execution. This section gives the operations that should be taken in each case. no location modifications or signalling operations performed, location set empty: Look up the user's location through whatever mechanism the server would use if no CPL script were in effect. Proxy, redirect, or send a rejection message, using whatever policy the server would use in the absence of a CPL script. no location modifications or signalling operations performed, location set non-empty: (This can only happen for outgoing calls.) Proxy the call to the addresses in the location set. location modifications performed, no signalling operations: Proxy or redirect the call, whichever is the server's standard policy, to the addresses in the current location set. If the location set is empty, return a "notfound" rejection. noanswer output of proxy, no timeout given: (This is a special case.) If the "noanswer" output of a proxy node is unspecified, and no timeout parameter was given to the proxy node, the call should be allowed to ring for the maximum length of time allowed by the server (or the request, if the request specified a timeout). proxy operation previously taken: Return whatever the "best" response is of all accumulated responses to the call to this point, according to the rules of the underlying signalling protocol.11. CPL Extensions
Servers MAY support additional CPL features beyond those listed in this document. Some of the extensions which have been suggested are a means of querying how a call has been authenticated, richer control over H.323 addressing, end-system or administrator-specific features, regular-expression matching for strings and addresses, and mid-call or end-of-call controls. CPL extensions are indicated by XML namespaces [11]. Every extension MUST have an appropriate XML namespace assigned to it. The XML namespace of the extension MUST be different from the XML namespace
defined in Section 14. The extension MUST NOT change the syntax or semantics of the CPL schema defined in this document. All XML tags and attributes that are part of the extension MUST be appropriately qualified so as to place them within that 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 attributes in the CPL namespace "urn:ietf:params:xml:ns:cpl". A CPL script SHOULD NOT specify any namespaces it does not use. For compatibility with non-namespace-aware parsers, a CPL script MAY omit the base CPL namespace for a script which does not use any extensions. A CPL server MUST reject any script containing a reference to a namespace it does not understand. It MUST reject any script containing an extension tag or attribute that is not qualified to be in an appropriate namespace. A syntax such as <extension-switch> <extension has="http://www.example.com/foo"> [extended things] </extension> <otherwise> [non-extended things] </otherwise> </extension-switch> was suggested as an alternate way of handling extensions. This would allow scripts to be uploaded to a server without requiring a script author to somehow determine which extensions a server supports. However, experience developing other languages, notably Sieve [22], was that this added excessive complexity to languages. The "extension-switch" tag could, of course, itself be defined in a CPL extension. In the XML schema of CPL, we introduce three abstract elements, namely 'toplevelaction', 'switch', and 'action', which accordingly have the abstract type 'TopLevelActionType', 'SwitchType', and 'ActionType'. Any top-level action in a CPL extension MUST be defined as the substitutionGroup of the abstract 'toplevelaction' element, and have the type extended from the 'TopLevelActionType'. Any switch in a CPL extension MUST be defined as the substitutionGroup of the abstract 'switch' element, and have the type
extended from the 'SwitchType'. Any action in a CPL extension MUST be defined as the substitutionGroup of the abstract 'action' element, and have the type extended from the 'ActionType'.12. Examples
12.1. Example: Call Redirect Unconditional
The script in Figure 19 is a simple script that redirects all calls to a single fixed location. <?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> <location url="sip:smith@phone.example.com"> <redirect/> </location> </incoming> </cpl> Figure 19: Example Script: Call Redirect Unconditional
12.2. Example: Call Forward Busy/No Answer
The script in Figure 20 illustrates some more complex behavior. We see an initial proxy attempt to one address, with further operations if that fails. We also see how several outputs take the same action subtree, through the use of subactions. <?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"> <proxy/> </location> </subaction> <incoming> <location url="sip:jones@jonespc.example.com"> <proxy timeout="8"> <busy> <sub ref="voicemail"/> </busy> <noanswer> <sub ref="voicemail"/> </noanswer> </proxy> </location> </incoming> </cpl> Figure 20: Example Script: Call Forward Busy/No Answer
12.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. <?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> <location url="sip:jones@jonespc.example.com"> <proxy> <redirection> <redirect/> </redirection> <default> <location url="sip:jones@voicemail.example.com"> <proxy/> </location> </default> </proxy> </location> </incoming> </cpl> Figure 21: Example Script: Call Forward: Redirect and Default
12.4. Example: Call Screening
The script in Figure 22 illustrates address switches and call rejection, in the form of a call screening script. Note also that because the address-switch lacks an "otherwise" clause, if the initial pattern does not match, the script does not define any operations. The server therefore proceeds with its default behavior, which would presumably be to contact the user. <?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"> <address is="anonymous"> <reject status="reject" reason="I reject anonymous calls"/> </address> </address-switch> </incoming> </cpl> Figure 22: Example Script: Call Screening
12.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" 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> <priority-switch> <priority greater="urgent"/> <otherwise> <language-switch> <language matches="es"> <location url="sip:spanish@operator.example.com"> <proxy/> </location> </language> <otherwise> <location url="sip:english@operator.example.com"> <proxy/> </location> </otherwise> </language-switch> </otherwise> </priority-switch> </incoming> </cpl> Figure 23: Example Script: Priority and Language Routing
12.6. Example: Outgoing Call Screening
The script in Figure 24 illustrates a script filtering outgoing calls, in the form of a script which prevent 1-900 (premium) calls from being placed. This script also illustrates subdomain matching. <?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 "> <outgoing> <address-switch field="original-destination" subfield="tel"> <address subdomain-of="1900"> <reject status="reject" reason="Not allowed to make 1-900 calls."/> </address> </address-switch> </outgoing> </cpl> Figure 24: Example Script: Outgoing Call Screening
12.7. Example: Time-of-day Routing
Figure 25 illustrates time-based conditions and timezones. <?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> <time-switch tzid="America/New_York" tzurl="http://zones.example.com/tz/America/New_York"> <time dtstart="20000703T090000" duration="PT8H" freq="weekly" byday="MO,TU,WE,TH,FR"> <lookup source="registration"> <success> <proxy/> </success> </lookup> </time> <otherwise> <location url="sip:jones@voicemail.example.com"> <proxy/> </location> </otherwise> </time-switch> </incoming> </cpl> Figure 25: Example Script: Time-of-day Routing
12.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 Software SIP User Agent" mis-implements some features, and so we must work around its problems. We know that it cannot talk successfully to one particular mobile device we may have registered, so we remove that location from the location set. Once this operation has been completed, call setup is allowed to proceed normally. <?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> <string-switch field="user-agent"> <string is="Inadequate Software SIP User Agent/0.9beta2"> <lookup source="registration"> <success> <remove-location location="sip:me@mobile.provider.net"> <proxy/> </remove-location> </success> </lookup> </string> </string-switch> </incoming> </cpl> Figure 26: Example Script: Location Filtering
12.9. Example: Non-signalling Operations
Figure 27 illustrates non-signalling operations; in particular, 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 out-of-band notification of error conditions, as the user might otherwise be unaware of any problem. <?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> <lookup source="http://www.example.com/cgi-bin/locate.cgi?user=mary" timeout="8"> <success> <proxy/> </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.