specified. The default value is "MO", following ISO 8601 [20].
The "bysetpos" parameter specifies a comma-separated list of values
which corresponds to the nth occurrence within the set of events
specified by the rule. Valid values are 1 to 366 or -366 to -1. It
MUST only be used in conjunction with another byxxx parameter. For
example, "the last work day of the month" could be represented as:
<time -timerange- freq="monthly" byday="MO,TU,WE,TH,FR"
bysetpos="-1">
Each "bysetpos" value can include a positive (+n) or negative (-n)
integer. If present, this indicates the nth occurrence of the
specific occurrence within the set of events specified by the rule.
If byxxx parameter values are found which are beyond the available
scope (i.e., bymonthday="30" in February), they are simply ignored.
Byxxx parameters modify the recurrence in some manner. Byxxx rule
parts for a period of time which is the same or greater than the
frequency generally reduce or limit the number of occurrences of the
recurrence generated. For example, freq="daily" bymonth="1" reduces
the number of recurrence instances from all days (if the "bymonth"
parameter is not present) to all days in January. Byxxx parameters
for a period of time less than the frequency generally increase or
expand the number of occurrences of the recurrence. For example,
freq="yearly" bymonth="1,2" increases the number of days within the
yearly recurrence set from 1 (if "bymonth" parameter is not present)
to 2.
If multiple Byxxx parameters are specified, then after evaluating the
specified "freq" and "interval" parameters, the Byxxx parameters are
applied to the current set of evaluated occurrences in the following
order: "bymonth", "byweekno", "byyearday", "bymonthday", "byday",
"byhour", "byminute", "bysecond", and "bysetpos"; then "count" and
"until" are evaluated.
Here is an example of evaluating multiple Byxxx parameters.
<time dtstart="19970105T083000" duration="10M"
freq="yearly" interval="2" bymonth="1" byday="SU"
byhour="8,9" byminute="30">
First, the interval="2" would be applied to freq="yearly" to arrive
at "every other year." Then, bymonth="1" would be applied to arrive
at "every January, every other year." Then, byday="SU" would be
applied to arrive at "every Sunday in January, every other year."
Then, byhour="8,9" would be applied to arrive at "every Sunday in
January at 8 AM and 9 AM, every other year." Then, byminute="30"
would be applied to arrive at "every Sunday in January at 8:30 AM and
9:30 AM, every other year." Then the second is derived from
"dtstart" to end up in "every Sunday in January from 8:30:00 AM to
8:40:00 AM, and from and 9:30:00 AM to 9:40:00 AM, every other year."
Similarly, if the "byminute", "byhour", "byday", "bymonthday", or
"bymonth" parameter were missing, the appropriate minute, hour, day,
or month would have been retrieved from the "dtstart" parameter.
The iCalendar COS RDATE, EXRULE, and EXDATE recurrence rules are not
specifically mapped to components of the time-switch node.
Equivalent functionality to the exception rules can be attained by
using the ordering of switch rules to exclude times using earlier
rules; equivalent functionality to the additional-date RDATE rules
can be attained by using "sub" nodes (see Section 8) to link multiple
outputs to the same subsequent node.
The "not-present" output is never true for a time switch. However,
it MAY be included to allow switch processing to be more regular.
4.4.1. iCalendar Differences and Implementation Issues
(This sub-sub-section is non-normative.)
The specification of recurring events in this section is identical
(except for syntax and formatting issues) to that of RFC 2445 [8],
with only one additional restriction. That one restriction is that
consecutive instances of recurrence intervals may not overlap.
It was a matter of some debate, during the design of CPL, whether the
entire iCalendar COS recurrence specification should be included in
CPL, or whether only a subset should be included. It was eventually
decided that compatibility between the two protocols was of primary
importance. This imposes some additional implementation issues on
implementors of CPL servers.
It does not appear to be possible to determine, in constant time,
whether a given instant of time falls within one of the intervals
defined by a full iCalendar COS recurrence. The primary concerns are
as follows:
o The "count" parameter cannot be checked in constant running
time, since it requires that the server enumerate all
recurrences from "dtstart" to the present time, in order to
determine whether the current recurrence satisfies the
parameter. However, a server can expand a "count" parameter
once, off-line, to determine the date of the last recurrence.
This date can then be treated as a virtual "until" parameter
for the server’s internal processing.
o Similarly, the "bysetpos" parameter requires that the server
enumerate all instances of the occurrence from the start of the
current recurrence set until the present time. This requires
somewhat more complex pre-processing, but generally, a single
recurrence with a "bysetpos" parameter can be split up into
several recurrences without them.
o Finally, constant running time of time switches also requires
that a candidate starting time for a recurrence can be
established quickly and uniquely, to check whether it satisfies
the other restrictions. This requires that a recurrence’s
duration not be longer than its repetition interval, so that a
given instant cannot fall within several consecutive potential
repetitions of the recurrence. The restriction that
consecutive intervals not overlap partially satisfies this
condition, but does not fully ensure it. Again, to some extent
pre-processing can help resolve this.
The algorithm given in Appendix A runs in constant time after these
pre-processing steps.
Servers ought to check that recurrence rules do not create any absurd
run-time or memory requirements, and reject those that do, just as
they ought to check that CPL scripts in general are not absurdly
large.
4.5. Priority Switches
Priority switches allow a CPL script to make decisions based on the
priority specified for the original call. They are summarized in
Figure 8. They are dependent on the underlying signalling protocol.
Node: "priority-switch"
Outputs: "priority" Specific priority to match
Parameters: None
Output: "priority"
Parameters: "less" Match if priority is less
than that specified
"greater" Match if priority is greater
than that specified
"equal" Match if priority is equal
to that specified
Figure 8: Syntax of the "priority-switch" node
Priority switches take no parameters.
The "priority" tag takes one of the three parameters "greater",
"less", or "equal". The values of these parameters are one of the
following priorities: in decreasing order, "emergency", "urgent",
"normal", and "non-urgent". These values are matched in a case-
insensitive manner. Outputs with the "less" parameter are taken if
the priority of the call is less than the priority given in the
argument, and so forth.
If no priority is specified in a message, the priority is considered
to be "normal". If an unknown priority is specified in the call, it
is considered to be equivalent to "normal" for the purposes of
"greater" and "less" comparisons, but it is compared literally for
"equal" comparisons.
Since every message has a priority, the "not-present" output is never
true for a priority switch. However, it MAY be included, to allow
switch processing to be more regular.
4.5.1. Usage of "priority-switch" with SIP
The priority of a SIP message corresponds to the "Priority" header in
the initial "INVITE" message.
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"