Internet Draft
Internet Engineering Task Force IPTEL WG
Internet Draft Lennox/Schulzrinne
draft-ietf-iptel-cpl-02.txt Columbia University
July 14, 2000
Expires: January, 2001
CPL: A Language for User Control of Internet Telephony Services
STATUS OF THIS MEMO
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress".
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
Abstract
The Call Processing Language (CPL) is a language that can be used to
describe and control Internet telephony services. It is designed to
be implementable on either network servers or user agent servers. It
is meant to be simple, extensible, easily edited by graphical
clients, and independent of operating system or signalling protocol.
It is suitable for running on a server where users may not be allowed
to execute arbitrary programs, as it has no variables, loops, or
ability to run external programs.
This document is a product of the IP Telephony (IPTEL) working group
of the Internet Engineering Task Force. Comments are solicited and
should be addressed to the working group's mailing list at
iptel@lists.research.bell-labs.com and/or the authors.
1 Introduction
The Call Processing Language (CPL) is a language that can be used to
Lennox/Schulzrinne [Page 1]
Internet Draft CPL July 14, 2000
describe and control Internet telephony services. It is not tied to
any particular signalling architecture or protocol; it is anticipated
that it will be used with both SIP [1] and H.323 [2].
The CPL is powerful enough to describe a large number of services and
features, but it is limited in power so that it can run safely in
Internet telephony servers. The intention is to make it impossible
for users to do anything more complex (and dangerous) than describing
Internet telephony services. The language is not Turing-complete, and
provides no way to write loops or recursion.
The CPL is also designed to be easily created and edited by graphical
tools. It is based on XML [3], so parsing it is easy and many
parsers for it are publicly available. The structure of the language
maps closely to its behavior, so an editor can understand any valid
script, even ones written by hand. The language is also designed so
that a server can easily confirm scripts' validity at the time they
are delivered to it, rather that discovering them while a call is
being processed.
Implementations of the CPL are expected to take place both in
Internet telephony servers and in advanced clients; both can usefully
process and direct users' calls. This document primarily addresses
the usage in servers. A mechanism will be needed to transport scripts
between clients and servers; this document does not describe such a
mechanism, but related documents will.
The framework and requirements for the CPL architecture are described
in RFC 2824, "Call Processing Language Framework and Requirements."
[4].
1.1 Conventions of this document
In this document, the key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY",
and "OPTIONAL" are to be interpreted as described in RFC 2119 [5] and
indicate requirement levels for compliant CPL implementations.
In examples, non-XML strings such as -action1, -action2, and so
forth, are sometimes used. These represent further parts of the
script which are not relevant to the example in question.
Some paragraphs are indented, like this; they give
motivations of design choices, or questions for future
discussion in the development of the CPL, and are not
essential to the specification of the language.
Lennox/Schulzrinne [Page 2]
Internet Draft CPL July 14, 2000
2 Structure of CPL scripts
2.1 High-level structure
A CPL script consists of two types of information: ancillary
information about the script, and call processing actions.
A call processing action is a structured tree that describes the
decisions and actions a telephony signalling server performs on a
call set-up event. There are two types of call processing actions:
top-level actions are actions that are triggered by signalling events
that arrive at the server. Two top-level action names are defined:
incoming, the action performed when a call arrives whose destination
is the owner of the script; and outgoing, the action performed when a
call arrives whose originator is the owner of the script. Sub-actions
are actions which can be called from other actions. The CPL forbids
sub-actions from being called recursively: see section 9.
Note: The names "action," "sub-action," and "top-level
action" are probably not ideal. Suggestions for better
names for these concepts are welcomed.
Ancillary information is information which is necessary for a server
to correctly process a script, but which does not directly describe
any actions. Currently, no ancillary information is defined, but the
section is reserved for future extensions.
2.2 Abstract structure of a call processing action
Abstractly, a call processing action is described by a collection of
nodes, which describe actions that can be performed or choices which
can be made. A node may have several parameters, which specify the
precise behavior of the node; they usually also have outputs, which
depend on the result of the condition or action.
For a graphical representation of a CPL action, see figure 1. Nodes
and outputs can be thought of informally as boxes and arrows; the CPL
is designed so that actions can be conveniently edited graphically
using this representation. Nodes are arranged in a tree, starting at
a single root node; outputs of nodes are connected to additional
nodes. When an action is run, the action or condition described by
the top-level node is performed; based on the result of that node,
the server follows one of the node's outputs, and that action or
condition is performed; this process continues until a node with no
specified outputs is reached. Because the graph is acyclic, this
will occur after a bounded and predictable number of nodes are
visited.
Lennox/Schulzrinne [Page 3]
Internet Draft CPL July 14, 2000
If an output to a node is not specified, it indicates that the CPL
server should perform a node- or protocol-specific action. Some nodes
have specific default actions associated with them; for others, the
default action is implicit in the underlying signalling protocol, or
can be configured by the administrator of the server. For further
details on this, see section 11.
_________________ ___________________ ________ busy
| Address-switch | | location | | proxy |--------\
Call --->| field: origin | ->| url: sip:jones@ |--->|timeout:| timeout|
| subfield: host | / | example.com | | 10s |--------|
|-----------------|/ |___________________| | | failure|
| subdomain-of: | |________|--------|
| example.com | |
|-----------------| _____________________________________________/
| otherwise | /..........................................
| |\|. Voicemail .
|_________________| \. ____________________ .
->| location | __________ .
. | url: sip:jones@ | | redirect | .
. | voicemail. |--->| | .
. | example.com | |__________| .
. |____________________| .
..........................................
Figure 1: Sample CPL Action: Graphical Version
2.3 Location model
For flexibility, one piece of information necessary for the function
of a CPL is not given as node parameters: the set of locations to
which a call is to be directed. Instead, this set of locations is
stored as an implicit global variable throughout the execution of a
processing action (and its sub-actions). This allows locations to be
retrieved from external sources, filtered, and so forth, without
requiring general language support for such actions (which could harm
the simplicity and tractability of understanding the language). The
specific actions which add, retrieve, or filter location sets are
given in section 6.
Lennox/Schulzrinne [Page 4]
Internet Draft CPL July 14, 2000
For the incoming top-level processing action, the location set is
initialized to the empty set. For the outgoing action, it is
initialized to the destination address of the call.
2.4 XML structure
Syntactically, CPL scripts are represented by XML documents. XML is
thoroughly specified by [3], and implementors of this specification
should be familiar with that document, but as a brief overview, XML
consists of a hierarchical structure of tags; each tag can have a
number of attributes. It is visually and structurally very similar to
HTML [6], as both languages are simplifications of the earlier and
larger standard SGML [7].
See figure 2 for the XML document corresponding to the graphical
representation of the CPL script in figure 1. Both nodes and outputs
in the CPL are represented by XML tags; parameters are represented by
XML tag attributes. Typically, node tags contain output tags, and
vice-versa (with one exception; see section 2.3).
The connection between the output of a node and another node is
represented by enclosing the tag representing the pointed-to node
inside the tag for the outer node's output. Convergence (several
outputs pointing to a single node) is represented by sub-actions,
discussed further in section 9.
The higher-level structure of a CPL script is represented by tags
corresponding to each piece of meta-information, sub-actions, and
top-level actions, in order. This higher-level information is all
enclosed in a special tag cpl, the outermost tag of the XML document.
A complete Document Type Declaration for the CPL is provided in
Appendix A. The remainder of the main sections of this document
describe the semantics of the CPL, while giving its syntax
informally. For the formal syntax, please see the appendix.
3 Document information
This section gives meta-information about CPL scripts.
3.1 CPL Document Identifiers for XML
A CPL script list which appears as a top-level XML document is
identified with the formal public identifier "-//IETF//DTD RFCxxxx
CPL 1.0//EN". If this document is published as an RFC, "xxxx" will be
replaced by the RFC number.
Lennox/Schulzrinne [Page 5]
Internet Draft CPL July 14, 2000
Figure 2: Sample CPL Script: XML Version
An CPL embedded as a fragment within another XML document is
identified with the XML namespace identifier
"http://www.ietf.org/internet-drafts/draft-ietf-iptel-cpl-02.txt".
If this document is published as an RFC, the namespace identifier
will be "http://www.rfc-editor.org/rfc/rfcxxxx.txt", where xxxx is
the RFC number.
Note that the URIs specifying XML namespaces are only
globally unique names; they do not have to reference any
particular actual object. The URI of a canonical source of
this specification meets the requirement of being globally
unique, and is also useful to document the format.
3.2 MIME Registration
Lennox/Schulzrinne [Page 6]
Internet Draft CPL July 14, 2000
As an XML type, CPL's MIME registration conforms with "XML Media
Types" [8] as well as RFC 2048 [9].
MIME media type name: application
MIME subtype name: cpl+xml
Mandatory parameters: none
Optional parameters: charset
As for application/xml in "XML Media Types."
Encoding considerations: As for application/xml in "XML Media
Types."
Security considerations: See section 13, and section 10 of "XML
Media Types."
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 detetected until runtime.
Published specification: This document.
Applications which use this media type: None publically released
at this time, as far as the authors are aware.
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
Henning Schulzrinne
Intended usage: COMMON
Author/Change Controller: The IETF.
4 Script structure: overview
As mentioned, a CPL script consists of ancillary information,
Lennox/Schulzrinne [Page 7]
Internet Draft CPL July 14, 2000
subactions, and top-level actions. The full syntax of the cpl node is
given in figure 3.
Tag: cpl
Parameters: none
Sub-tags: ancillary See section 10
subaction See section 9
outgoing Top-level actions to take on this user's
outgoing calls
incoming Top-level actions to take on this user's
incoming calls
Output: outgoing
Parameters: none
Output: incoming
Parameters: none
Figure 3: Syntax of the top-level cpl tag
Call processing actions, both top-level actions and sub-actions,
consist of nodes and outputs. Nodes and outputs are both described by
XML tags. There are four categories of CPL nodes: switches , which
represent choices a CPL script can make; location modifiers , which
add or remove locations from the location set; signalling actions ,
which cause signalling events in the underlying protocol; and non-
signalling actions, which take an action but do not effect the
underlying protocol.
5 Switches
Switches represent choices a CPL script can make, based on either
attributes of the original call request or items independent of the
call.
All switches are arranged as a list of conditions that can match a
variable. Each condition corresponds to a node output; the output
points to the next node to execute if the condition was true. The
conditions are tried in the order they are presented in the script;
the output corresponding to the first node to match is taken.
There are two special switch outputs that apply to every switch type.
The output not-present, which MAY occur anywhere in the list of
outputs, is true if the variable the switch was to match was not
Lennox/Schulzrinne [Page 8]
Internet Draft CPL July 14, 2000
present in the original call setup request. The output otherwise,
which MUST be the last output specified if it is present, matches if
no other condition matched.
If no condition matches and no otherwise output was present in the
script, the default script action is taken. See section 11 for more
information on this.
5.1 Address switches
Address switches allow a CPL script to make decisions based on one of
the addresses present in the original call request. They are
summarized in figure 4.
Node: address-switch
Outputs: address Specific addresses to match
Parameters: field origin, destination, or original-destination
subfield address-type, user, host, port, tel, display,
password, or alias-type
Output: address
Parameters: is exact match
contains substring match (for display only)
subdomain-of sub-domain match (for host, tel only)
Figure 4: Syntax of the address-switch node
Address switches have two node parameters: field, and subfield. The
mandatory field parameter allows the script to specify which address
is to be considered for the switch: either the call's origin address
(field "origin"), its current destination address (field
"destination"), or its original destination (field "original-
destination"), the destination the call had before any earlier
forwarding was invoked. Servers MAY define additional field values.
The optional subfield specifies what part of the address is to be
considered. The possible subfield values are: address-type, user,
host, port, tel, and display. Additional subfield values MAY be
defined: two additional ones, password and asn1 are defined
specifically for SIP and H.323 respectively, in sections 5.1.1 and
5.1.2 below. If no subfield is specified, the "entire" address is
matched; the precise meaning of this is defined for each underlying
signalling protocol. Servers MAY define additional subfield values.
Lennox/Schulzrinne [Page 9]
Internet Draft CPL July 14, 2000
The subfields are defined as follows:
address-type This indicates the type of the underlying address;
i.e., the URI scheme, if the address can be represented by
a URI. The types specifically discussed by this document
are sip, tel, and h323. The address type is not case-
sensitive. It has a value for all defined address types.
user This subfield of the address indicates, for e-mail style
addresses, the user part of the address. For telephone
number style address, it includes the subscriber number.
This subfield is case-sensitive; it may be not present.
host This subfield of the address indicates the Internet host
name or IP address corresponding to the address, in host
name, IPv4, or IPv6 format. For host names only, subdomain
matching is supported with the subdomain-of match operator.
It is not case sensitive, and may be not present.
port This subfield indicates the TCP or UDP port number of the
address, numerically in decimal format. It is not case
sensitive, as it MUST only contain decimal digits. It may
be not present; however, for address types with default
ports, an absent port matches the default port number.
tel This subfield indicates a telephone subscriber number, if
the address contains such a number. It is not case
sensitive (the telephone numbers may contain the symbols
`A' `B' `C' and `D'), and might not be present. It may be
matched using the subdomain-of match operator. Punctuation
and separator characters in telephone numbers are
discarded.
display This subfield indicates a "display name" or user-visible
name corresponding to an address. It is a Unicode string,
and is matched using the case-insensitive algorithm
described in section 5.2. The contains operator may be
applied to it. It may be not present.
For any completely unknown subfield, the server MAY reject the script
at the time it is submitted with an indication of the problem; if a
script with an unknown subfield is executed, the server MUST consider
the not-present output to be the valid one.
The address output tag may take exactly one of three possible
parameters, indicating the kind of matching allowed.
is An output with this match operator is followed if the
Lennox/Schulzrinne [Page 10]
Internet Draft CPL July 14, 2000
subfield being matched in the address-switch exactly
matches the argument of the operator. It may be used for
any subfield, or for the entire address if no subfield was
specified.
subdomain-of This match operator applies only for the subfields
host and tel. In the former case, it matches if the
hostname being matched is a subdomain of the domain given
in the argument of the match operator; thus, subdomain-
of="example.com" would match the hostnames "example.com",
"research.example.com", and
"zaphod.sales.internal.example.com". IP addresses may be
given as arguments to this operator; however, they only
match exactly. In the case of the tel subfield, the output
matches if the telephone number being matched has a prefix
that matches the argument of the match operator;
subdomain-of="1212555" would match the telephone number "1
212 555 1212."
contains This match operator applies only for the subfield
display. The output matches if the display name being
matched contains the argument of the match as a substring.
5.1.1 Address switch mapping for SIP
For SIP, the origin address corresponds to the address in the From
header; destination corresponds to the Request-URI; and original-
destination corresponds to the To header.
The display subfield of an address is the display-name part of the
address, if it is present. Because of SIP's syntax, the destination
address field will never have a display subfield.
The address-type subfield of an address is the URI scheme of that
address. Other address fields depend on that address-type.
For sip URLs, the user, host, and port subfields correspond to the
"user," "host," and "port" elements of the URI syntax. The tel
subfield is defined to be the "user" part of the URI if and only if
the "user=phone" parameter is given to the URI. An additional
subfield, password is defined to correspond to the "password" element
of the SIP URI; however, use of this field is NOT RECOMMENDED for
general security reasons.
For tel URLs, the tel and user subfields are the subscriber name; in
the former case, visual separators are stripped. The host and port
subfields are both not present.
Lennox/Schulzrinne [Page 11]
Internet Draft CPL July 14, 2000
For h323 URLs, the subfields are set as in section 5.1.2 below.
For other URI schemes, only the address-type subfield is defined by
this specification; servers MAY set other pre-defined subfields, or
MAY support additional subfields.
If no subfield is specified for addresses in SIP messages, the string
matched is the URI part of the address. For "sip" URLs, all
parameters are stripped; for other URLs, the URL is used verbatim.
5.1.2 Address switch mapping for H.323
For H.323, the origin address corresponds to the primary alias
address in the sourceAddress field of the Setup-UUIE user-user
information element, and to the Q.931 information element
callingPartyNumber. If both fields are present, which one has
priority is a matter of local server policy; the server SHOULD use
the same resolution as it would use for routing decisions in this
case. Similarly, the destination address corresponds to the primary
alias address of the destinationAddress field, and to the Q.931
information element calledPartyNumber.
This discussion is based on H.323 version 4 [10], which is expected
to be approved in November 2000.
The original-destination address corresponds to the redirectedNumber
Q.931 information element, if it is present; otherwise it is the same
as the destination address.
The mapping of H.323 addresses into subfields depends on the type of
the alias address. An additional subfield type, alias-type, is
defined for H.323 servers, corresponding to the type of the address.
Possible values are dialedDigits, h323-ID, url-ID, transportID,
email-ID, partyNumber, mobileUIM, and Q.931IE. If future versions of
the H.323 specification define additional types of alias addresses,
those names MAY also be used.
In versions of H.323 prior to version 4, dialedDigits was known as
e164. The new name should be used.
The value of the address-type subfield for H.323 messages is "h323"
unless the alias type is url-ID and the URL scheme is something other
than h323; in this case the address-type is the URL scheme, as
specified above for SIP.
If an alias address of type h323-ID is present anywhere among the
sequence of aliases, the first such h323-ID alias address is used for
the display subfield of the address. The values of all other
Lennox/Schulzrinne [Page 12]
Internet Draft CPL July 14, 2000
subfields depend only on the first alias address in the sequence.
The following mappings are used for H.323 alias types:
dialedDigits, partyNumber, mobileUIM, and Q.931IE: the tel and
user subfields are the string of digits, as is the
"entire-address" form. The host and port subfields are not
present.
url-ID with a "h323" URI: the user, host, and port subfields are
set to the corresponding parts of the H.323 URL. The tel
subfield is not present. The "entire-address" form
corresponds to the entire URI.
url-ID with other URI schemes: the same mapping is used as for
SIP, above.
email-ID: the user and host subfields are set to the
corresponding parts of the e-mail address. The port and tel
subfields are not present. The "entire-address" form
corresponds to the entire e-mail address.
transportID: if the TransportAddress is of type "ipAddress,"
"ipSourceRoute," or "ip6Address," the host subfield is set
to the "ip" element of the sequence, translated into the
standard IPv4 or IPv6 textual representation, and the port
subfield is set to the "port" element of the sequence
represented in decimal. The tel and user fields are not
present. The "entire-address" form is not defined. The
representation and mapping of transport addresses is not
defined for non-IP addresses.
5.2 String switches
String switches allow a CPL script to make decisions based on free-
form Unicode strings present in a call request. They are summarized
in figure 5.
String switches have one node parameter: field. The mandatory field
parameter specifies which string is to be matched.
Currently five fields are defined. Three fields are currently
applicable only to SIP, one is currently applicable only to H.323,
and one is applicable to both.
The three fields which are applicable only to SIP are: subject,
indicating the subject of the call; organization, indicating the
Lennox/Schulzrinne [Page 13]
Internet Draft CPL July 14, 2000
Node: string-switch
Outputs: string Specific string to match
Parameters: field subject, organization, user-agent,
language, or display
Output: string
Parameters: is exact match
contains substring match
Figure 5: Syntax of the string-switch node
originator's organization; and user-agent, indicating the program or
device with which the call request was made. All these fields
correspond to the contents of the SIP header fields with the same
names.
The field applicable only to H.323 is display, which corresponds to
the Q.931 information element of the same name.
This is conventionally used for Caller-ID purposes, so
arguably it should be mapped to the display subfield of an
address-match with the field originator. However, since a)
it is a message-level information element, not an address-
level one, and b) the Q.931 specification [11] says only
that "[t]he purpose of the Display information element is
to supply display information that may be displayed by the
user," it seems to be more appropriate to match it as a
string instead.
The field appropriate both to SIP and H.323 is language. This field
contains a list of RFC 1766 [12] language tags, separated by commas,
corresponding to the SIP Accept-Language header and the H.323
language UUIE.
Note that matching based on contains is likely to be much
more useful than matching based on is, for this field.
Strings are matched as case-insensitive Unicode strings, in the
following manner. First, strings are canonicalized to the
"Compatibility Composition" (KC) form, as specified in Unicode
Technical Report 15 [13]. Then, strings are compared using locale-
insensitive caseless mapping, as specified in Unicode Technical
Report 21 [14].
Lennox/Schulzrinne [Page 14]
Internet Draft CPL July 14, 2000
Code to perform the first step, in Java and Perl, is
available; see the links from Annex E of UTR 15 [13]. The
case-insensitive string comparison in the Java standard
class libraries already performs the second step; other
Unicode-aware libraries should be similar.
The output tags of string matching are named string, and have a
mandatory argument, one of is or contains, indicating whole-string
match or substring match, respectively.
5.3 Time switches
Time switches allow a CPL script to make decisions based the time
and/or date the script is being executed. They are summarized in
figure 6.
Node: time-switch
Outputs: time Specific time to match
Parameters: tzid RFC 2445 Time Zone Identifier
tzurl RFC 2445 Time Zone URL
Output: time
Parameters: dtstart Start of interval (RFC 2445 DATE-TIME)
dtend End of interval (RFC 2445 DATE-TIME)
duration Length of interval (RFC 2445 DURATION)
freq Frequency of recurrence (one of "secondly",
"minutely", "hourly", "daily", "weekly",
"monthly", or "yearly")
interval How often the recurrence repeats
until Bound of recurrence (RFC 2445 DATE-TIME)
count Number of occurences of recurrence
bysecond List of seconds within a minute
byminute List of minutes within an hour
byhour List of hours of the day
byday List of days of the week
bymonthday List of days of the month
byyearday List of days of the year
byweekno List of weeks of the year
bymonth List of months of the year
wkst First day of week
bysetpos List of values within set of events specified
Figure 6: Syntax of the time-switch node
Lennox/Schulzrinne [Page 15]
Internet Draft CPL July 14, 2000
Time switches are based closely on the specification of recurring
intervals of time from the Internet Calendaring and Scheduling Core
Object Specification (iCal COS), RFC 2445 [15].
This allows CPLs to be generated automatically from
calendar books. It also allows us to re-use the extensive
existing work specifying time intervals.
The time-switch tag takes two optional parameters, tzid and tzurl,
both of which are defined in RFC 2445 (sections 4.8.3.1 and 4.8.3.5
respectively). The TZID is the identifying label by which a time zone
definition is referenced. If it begins with a forward slash
(solidus), it references a to-be-defined global time zone registry;
otherwise it is locally-defined at the server. The TZURL gives a
network location from which an up-to-date VTIMEZONE definition for
the timezone can be retrieved.
If a script is uploaded with a tzid and tzurl which the CPL server
does not recognize or cannot resolve, it SHOULD diagnose and reject
this at script upload time. If neither tzid nor tzurl are present,
all non-UTC times within this time switch should be interpreted as
being "floating" times, i.e. that they are specified in the local
timezone of the CPL server.
Because of daylight-savings-time changes over the course of
a year, it is necessary to specify time switches in a given
timezone. UTC offsets are not sufficient, or a time-of-day
routing rule which held between 9 am and 5 pm in the
eastern United States would start holding between 8 am and
4 pm at the end of October.
Authors of CPL servers should be careful to handle correctly the
intervals when local time is discontinuous, at the beginning or end
of daylight-savings time.
Time nodes specify a list of periods during which their output should
be taken. They have two required parameters: dtstart, which specifies
the beginning of the first period of the list, and exactly one of
dtend or duration, which specify the ending time or the duration of
the period, respectively. The dtstart and dtend parameters are
formatted as iCal COS DATE-TIME values, as specified in section 4.3.5
of RFC 2445. The duration parameter is given as an iCal COS DURATION
parameter, as specified in section 4.3.6 of RFC 2445.
If no other parameters are specified, a time node indicates only a
single period of time. More complicated sets periods intervals are
Lennox/Schulzrinne [Page 16]
Internet Draft CPL July 14, 2000
constructed as recurrences. A recurrence is specified by including
the freq parameter, which indicates the type of recurrence rule. No
parameters other than dtstart, dtend, and duration SHOULD be
specified unless freq is present.
The freq parameter takes one of the following values: secondly, to
specify repeating periods based on an interval of a second or more;
minutely, to specify repeating periods based on an interval of a
minute or more; hourly, to specify repeating periods based on an
interval of an hour or more; daily, to specify repeating periods
based on an interval of a day or more; weekly, to specify repeating
periods based on an interval of a week or more; monthly, to specify
repeating periods based on an interval of a month or more; and
yearly, to specify repeating periods based on an interval of a year
or more. These values are not case-sensitive.
The interval parameter contains a positive integer representing how
often the recurrence rule repeats. The default value is "1", meaning
every second for a secondly rule, or every minute for a minutely
rule, every hour for an hourly rule, every day for a daily rule,
every week for a weekly rule, every month for a monthly rule and
every year for a yearly rule.
The until parameter defines an iCal COS DATE or DATE-TIME value which
bounds the recurrence rule in an inclusive manner. If the value
specified by until is synchronized with the specified recurrence,
this date or date-time becomes the last instance of the recurrence.
If specified as a date-time value, then it MUST be specified in an
UTC time format. If not present, and the count parameter is also not
present, the recurrence is considered to repeat forever.
The count parameter defines the number of occurrences at which to
range-bound the recurrence. The dtstart parameter counts as the first
occurrence. The until and count parameters MUST NOT occur in the same
time output.
The bysecond parameter specifies a comma-separated list of seconds
within a minute. Valid values are 0 to 59. The byminute parameter
specifies a comma-separated list of minutes within an hour. Valid
values are 0 to 59. The byhour parameter specifies a comma-separated
list of hours of the day. Valid values are 0 to 23.
The byday parameter specifies a comma-separated list of days of the
week. MO indicates Monday; TU indicates Tuesday; WE indicates
Wednesday; TH indicates Thursday; FR indicates Friday; SA indicates
Saturday; SU indicates Sunday. These values are not case-sensitive.
Each byday value can also be preceded by a positive (+n) or negative
Lennox/Schulzrinne [Page 17]
Internet Draft CPL July 14, 2000
(-n) integer. If present, this indicates the nth occurrence of the
specific day within the monthly or yearly recurrence. For example,
within a monthly rule, +1MO (or simply 1MO) represents the first
Monday within the month, whereas -1MO represents the last Monday of
the month. If an integer modifier is not present, it means all days
of this type within the specified frequency. For example, within a
monthly rule, MO represents all Mondays within the month.
The bymonthday parameter specifies a comma-separated list of days of
the month. Valid values are 1 to 31 or -31 to -1. For example, -10
represents the tenth to the last day of the month.
The byyearday parameter specifies a comma-separated list of days of
the year. Valid values are 1 to 366 or -366 to -1. For example, -1
represents the last day of the year (December 31st) and -306
represents the 306th to the last day of the year (March 1st).
The byweekno parameter specifies a comma-separated list of ordinals
specifying weeks of the year. Valid values are 1 to 53 or -53 to -1.
This corresponds to weeks according to week numbering as defined in
[ISO 8601]. A week is defined as a seven day period, starting on the
day of the week defined to be the week start (see wkst). Week number
one of the calendar year is the first week which contains at least
four (4) days in that calendar year. This parameter is only valid for
yearly rules. For example, 3 represents the third week of the year.
Note: Assuming a Monday week start, week 53 can only occur
when Thursday is January 1 or if it is a leap year and
Wednesday is January 1.
The bymonth parameter specifies a comma-separated list of months of
the year. Valid values are 1 to 12.
The wkst parameter specifies the day on which the workweek starts.
Valid values are MO, TU, WE, TH, FR, SA and SU. This is significant
when a weekly recurrence has an interval greater than 1, and a byday
parameter is specified. This is also significant in a yearly
recurrence when a byweekno parameter is specified. The default value
is MO.
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:
Lennox/Schulzrinne [Page 18]
Internet Draft CPL July 14, 2000