tech-invite   World Map     

3GPP     Specs     Glossaries     Architecture     IMS     UICC       IETF     RFCs     Groups     SIP     ABNFs       Search

RFC 3880

 
 
 

Call Processing Language (CPL): A Language for User Control of Internet Telephony Services

Part 2 of 3, p. 22 to 51
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 22 
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.

Top      Up      ToC       Page 23 
   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.

Top      Up      ToC       Page 24 
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.

Top      Up      ToC       Page 25 
   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.

Top      Up      ToC       Page 26 
   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.

Top      Up      ToC       Page 27 
         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).

Top      Up      ToC       Page 28 
      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.

Top      Up      ToC       Page 29 
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."

Top      Up      ToC       Page 30 
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

Top      Up      ToC       Page 31 
      "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
   "&amp;" inside parameter values (see Section C.12 of the XML
   specification [2]).

Top      Up      ToC       Page 32 
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,

Top      Up      ToC       Page 33 
   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.

Top      Up      ToC       Page 34 
   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

Top      Up      ToC       Page 35 
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

Top      Up      ToC       Page 36 
   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

Top      Up      ToC       Page 37 
   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

Top      Up      ToC       Page 38 
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

Top      Up      ToC       Page 39 
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

Top      Up      ToC       Page 40 
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

Top      Up      ToC       Page 41 
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

Top      Up      ToC       Page 42 
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

Top      Up      ToC       Page 43 
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

Top      Up      ToC       Page 44 
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

Top      Up      ToC       Page 45 
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

Top      Up      ToC       Page 46 
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

Top      Up      ToC       Page 47 
   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

Top      Up      ToC       Page 48 
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

Top      Up      ToC       Page 49 
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>

Top      Up      ToC       Page 50 
             <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.

Top      Up      ToC       Page 51 
      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.


Next RFC Part