moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-13 21:05:09 -05:00
Code Issues Releases Wiki Activity
d80cf397fe
xeps/inbox/calendaring.xml

1175 lines
73 KiB
XML
Raw Normal View History

added all existing inbox items available in XML format
2010-07-21 16:33:01 -04:00
<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
<!ENTITY rfc2445 "<span class='ref'><link url='http://tools.ietf.org/html/rfc2445'>iCalendar</link></span> <note>RFC 2445: Internet Calendaring and Scheduling Core Object Specification (iCalendar) &lt;<link url='http://tools.ietf.org/html/rfc2445'>http://tools.ietf.org/html/rfc2445</link>&gt;.</note>" >
<!ENTITY rfc2446 "<span class='ref'><link url='http://tools.ietf.org/html/rfc2446'>iTIP</link></span> <note>RFC 2446: iCalendar Transport-Independent Interoperability Protocol (iTIP) &lt;<link url='http://tools.ietf.org/html/rfc2446'>http://tools.ietf.org/html/rfc2446</link>&gt;.</note>" >
<!ENTITY rfc2447 "<span class='ref'><link url='http://tools.ietf.org/html/rfc2447'>iMIP</link></span> <note>RFC 2447: iCalendar Message-Based Interoperability Protocol (iMIP) &lt;<link url='http://tools.ietf.org/html/rfc2447'>http://tools.ietf.org/html/rfc2447</link>&gt;.</note>" >
<!ENTITY rfc3283 "<span class='ref'><link url='http://tools.ietf.org/html/rfc3283'>Guide to Internet Calendaring</link></span> <note>RFC 3283: Guide to Internet Calendaring &lt;<link url='http://tools.ietf.org/html/rfc3283'>http://tools.ietf.org/html/rfc3283</link>&gt;.</note>" >
<!ENTITY rfc4791 "<span class='ref'><link url='http://tools.ietf.org/html/rfc4791'>CalDAV</link></span> <note>RFC 4791: Calendaring Extensions to WebDAV (CalDAV) &lt;<link url='http://tools.ietf.org/html/rfc4791'>http://tools.ietf.org/html/rfc4791</link>&gt;.</note>" >
<!ENTITY rfc4918 "<span class='ref'><link url='http://tools.ietf.org/html/rfc4918'>WebDAV</link></span> <note>RFC 4918: HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV) &lt;<link url='http://tools.ietf.org/html/rfc4918'>http://tools.ietf.org/html/rfc4918</link>&gt;.</note>" >
<!ENTITY draft-sched "<span class='ref'><link url='http://tools.ietf.org/html/draft-desruisseaux-caldav-sched'>scheduling extension</link></span> <note>CalDAV Scheduling Extensions to WebDAV &lt;<link url='http://tools.ietf.org/html/draft-desruisseaux-caldav-sched-04'>http://tools.ietf.org/html/draft-desruisseaux-caldav-sched-04</link>&gt;.</note>" >
<!ENTITY draft-xcal "<span class='ref'><link url='http://tools.ietf.org/html/draft-royer-calsch-xcal'>iCalendar in XML Format</link></span> <note>iCalendar in XML Format (xCal-Basic) &lt;<link url='http://tools.ietf.org/html/draft-royer-calsch-xcal-03'>http://tools.ietf.org/html/draft-royer-calsch-xcal-03</link>&gt;.</note>" >
<!ENTITY ITEM "&lt;item/&gt;">
<!ENTITY ITEMS "&lt;items/&gt;">
<!ENTITY PUBSUB "&lt;pubsub/&gt;">
<!ENTITY VEVENT "&lt;vevent/&gt;">
<!ENTITY VTODO "&lt;vtodo/&gt;">
<!ENTITY VJOURNAL "&lt;vjournal/&gt;">
<!ENTITY VFREEBUSY "&lt;vfreebusy/&gt;">
<!ENTITY VALARM "&lt;valarm/&gt;">
<!ENTITY VTIMEZONE "&lt;vtimezone/&gt;">
<!ENTITY SN "calendar">
<!ENTITY NS "urn:xmpp:tmp:&SN;:0">
<!ENTITY TODO "## TODO. ##">
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
<title>Calendaring Extensions to Publish-Subscribe</title>
<abstract>This specification defines calendaring extensions to Publish-Subscribe for the purposes of group calendaring and scheduling between "Calendar Users" (CUs), accessing, managing, and sharing calendaring and scheduling information on a Calendar Server, and a mechanism for alarm notifications.</abstract>
&LEGALNOTICE;
<number>xxxx</number>
<status>ProtoXEP</status>
<type>Standards Track</type>
<sig>Standards</sig>
<dependencies>
<spec>XMPP Core</spec>
<spec>XEP-0004</spec>
<spec>XEP-0030</spec>
<spec>XEP-0060</spec>
<spec>XEP-0068</spec>
<spec>XEP-0082</spec>
<spec>RFC 2445</spec>
<spec>RFC 2446</spec>
<spec>RFC 4791</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>&SN;</shortname>
<author>
<firstname>Klaus</firstname>
<surname>Hartke</surname>
<email>klaus.hartke@googlemail.com</email>
<jid>nx@jabber.org</jid>
</author>
<revision>
<version>0.0.3.1</version>
<date>2009-02-14</date>
<initials>kh</initials>
<remark><p>Added XML schema; fixed a number of minor issues.</p></remark>
</revision>
<revision>
<version>0.0.3</version>
<date>2008-08-01</date>
<initials>kh</initials>
<remark><p>Clarified a number of issues; cleaned up specification.</p></remark>
</revision>
<revision>
<version>0.0.2</version>
<date>2008-05-25</date>
<initials>kh</initials>
<remark><p>First (semi) complete version supporting all use cases.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2007-12-08</date>
<initials>kh</initials>
<remark><p>First rough draft.</p></remark>
</revision>
</header>
<!-- =======================================================================
Introduction
======================================================================= -->
<section1 topic='Introduction' anchor='intro'>
<!-- == Overview ========================================================= -->
<section2 topic='Overview' anchor='intro-overview'>
<p>The &rfc3283; describes the relationship between various internet calendaring specifications like this: "&rfc2445; is the language used to describe calendar objects. &rfc2446; (Transport-Independent Interoperability Protocol) describes a way to use the iCalendar language to do scheduling. &rfc2447; (Message-Based Interoperability Protocol) describes how to do iTIP scheduling via e-mail."</p>
<p>Recently another standard track protocol for calendar and scheduling access has appeared. &rfc4791; (Calendaring Extensions to WebDAV) is a &rfc4918; (Web-based Distributed Authoring and Versioning) based mechanism for manipulating internet calendars, and viewing free/busy lists, and via a planned &draft-sched;, could be used for proposing calendar events as well.</p>
<p>This specification defines calendaring extensions to &xep0060; for the purposes of group calendaring and scheduling between "Calendar Users" (CUs) as defined by <cite>iTIP</cite>. Additionally, it defines extensions for accessing, managing, and sharing calendaring and scheduling information on a calendar server, reusing the syntax and semantics defined by <cite>CalDAV</cite>. Finally, it defines a mechanism for reminding of upcoming events by alarm notifications.</p>
<p>The protocol enables all common transactions such as publish, schedule, reschedule, respond to scheduling requests, negotiation of changes or cancel <cite>iCalendar</cite>-based calendar components, as well as search for busy time information. The protocol is a superset of <cite>Publish-Subscribe</cite> and will gracefully degrade to <cite>Publish-Subscribe</cite> for clients that do not support the calendaring extensions defined.</p>
</section2>
<!-- == How It Works ===================================================== -->
<section2 topic='How It Works' anchor='intro-howitworks'>
<p>This specification follows the same pattern as the Internet calendaring and scheduling standards by developing all features based on a well-described data model. This model is described in <link url='#datamodel'>Calendaring Data Model</link>. As a brief overview, calendars are modeled as nodes of a calendaring-aware publish-subscribe service; each calendar node contains a number of items representing calendar objects. Each item representing a calendar object (event, to-do, journal entry, or other calendar components) is called a "calendar item".</p>
<p>Calendar objects are represented using &draft-xcal;. The format is not an alternative or next generation of <cite>iCalendar</cite> but defines how to use XML to represent iCalendar objects in XML. For example, both examples below describe the same single event that begins on July 14, 1997 at 00:00 UTC and ends on July 15, 1997 at 03:59 UTC.</p>
<example caption='Bastille Day Party (iCalendar)'><![CDATA[
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//ACME/DesktopCalendar//EN
BEGIN:VEVENT
ORGANIZER:xmpp:a@example.com
DTSTART:19970714T170000Z
DTEND:19970715T035959Z
DTSTAMP:19970611T190000Z
SUMMARY;LANGUAGE="en_US":Bastille Day Party
UID:fcd5cb18-93a6-478d-8f71-95cd78e8ebe6
END:VEVENT
END:VCALENDAR
]]></example>
<example caption='Bastille Day Party (iCalendar in XML)'><![CDATA[
<vcalendar xmlns='urn:ietf:params:xml:ns:xcal'>
<version>2.0</version>
<prodid>-//ACME/DesktopCalendar//EN</prodid>
<vevent>
<organizer>xmpp:a@example.com</organizer>
<dtstart>1997-07-14T17:00:00Z</dtstart>
<dtend>1997-07-15T03:59:59Z</dtend>
<dtstamp>1997-06-11T19:00:00Z</dtstamp>
<summary xml:lang='en-US'>Bastille Day Party</summary>
<uid>fcd5cb18-93a6-478d-8f71-95cd78e8ebe6</uid>
</vevent>
</vcalendar>
]]></example>
<p>This specification is structured as follows: <link url='#disco'>Discovering Support</link> describes how to discover support for the calendaring extensions defined by this specification. An entity may create new calendar nodes as described in <link url='#create'>Creating Calendars</link>. The section on <link url='#publish'>Scheduling Calendar Entries</link> provides the transport specific information necessary to convey <cite>iTIP</cite> messages over <cite>Publish-Subscribe</cite> which enables transactions such as publish, schedule, reschedule, respond to scheduling requests, negotiation of changes or cancel iCalendar-based calendar components. The sections <link url='#retrieve'>Retrieving Calendar Entries</link> and <link url='#freebusy'>Retrieving Free/Busy Time</link> define how to retrieve items from a calendar node, and how to search for busy time information. <link url='#alarm'>Alarm Notifications</link> provide a mechanism for setting up and subscribing to alarm notifications.</p>
</section2>
<!-- == Formatting Conventions =========================================== -->
<section2 topic='Formatting Conventions' anchor='intro-conventions'>
<p>In order to refer to elements of the calendaring and scheduling model, core object or interoperability protocol defined in <cite>RFC 2445</cite> and <cite>RFC 2446</cite> several formatting conventions have been utilized.</p>
<p>Calendaring and scheduling roles are referred to in quoted-strings of text with the first character of each word in upper case. For example, "Organizer" refers to a role of a "Calendar User" (CU) within the scheduling protocol defined by <cite>RFC 2446</cite>.</p>
<p>Scheduling methods defined by <cite>RFC 2446</cite> are referred to with capitalized, quoted-strings of text. For example, "REQUEST" refers to the method for requesting a scheduling calendar component be created or modified, "REPLY" refers to the method a recipient of a request uses to update their status with the "Organizer" of the calendar component.</p>
<p>Calendar components defined by <cite>RFC 2445</cite> are referred to with capitalized text. All calendar components start with the letter "V". For example, VEVENT refers to the event calendar component, VTODO refers to the to-do calendar component and VJOURNAL refers to the daily journal calendar component.</p>
<p>Properties defined by <cite>RFC 2445</cite> are referred to with capitalized, quoted-strings of text, followed by the word "property". For example, "ATTENDEE" property refers to the iCalendar property used to convey the calendar address of a "Calendar User". Property parameters are referred to with lower case, quoted-strings of text, followed by the word "parameter". For example, "value" parameter refers to the iCalendar property parameter used to override the default data type for a property value. Values are referred to with quoted-strings of text, either alone or followed by the word "value".</p>
</section2>
<!-- == Related Documents ================================================ -->
<section2 topic='Related Documents' anchor='intro-related'>
<p>Implementers will need to be familiar with several other specifications that describe the Internet calendaring and scheduling standards. The related documents are:</p>
<ul>
<li><cite>RFC 2445</cite> specifies the objects, data types, properties and property parameters used in the protocols;</li>
<li><cite>RFC 2446</cite> specifies an interoperability protocol for scheduling static and dynamic event, to-do, journal and free/busy objects;</li>
<li><cite>RFC 4791</cite> specifies the syntax for calendaring reports used by this specification.</li>
</ul>
<p>This specification is an extension of the Publish-Subscribe protocol specified by <cite>XEP-0060</cite>, so implementers will need to be familiar with that as well.</p>
<p>This specification does not attempt to repeat the specification of concepts or definitions from these other specifications. Where possible, references are made to the specification that provides that provides the relevant concepts or definitions.</p>
</section2>
</section1>
<!-- =======================================================================
Calendaring Data Model
======================================================================= -->
<section1 topic='Calendaring Data Model' anchor='datamodel'>
<!--
<p>This specification follows the same pattern as the Internet calendaring and scheduling standards by developing all features based on a well-described data model.</p>
<p>As a brief overview, a calendar is modeled as a publish-subscribe node with a defined structure; each calendar node contains a number of items representing calendar objects. Each item representing a calendar object (event, to-do, journal entry, or other calendar components) is called a "calendar item".</p>
-->
<!-- == Calendar Service ================================================= -->
<section2 topic='Calendar Service' anchor='datamodel-service'>
<p>A calendar service is a calendaring-aware engine combined with a publish-subscribe service. A publish-subscribe service enables XMPP entities to create nodes and publish information at those nodes; an event notification (with or without payload) is then broadcasted to all entities that have subscribed to the node.</p>
<p>A calendar service MAY include calendar data in some of its nodes, and non-calendaring data in others.</p>
<p>A publish-subscribe service can advertise itself as a calendar service if it supports the functionality defined in this specification at any of its nodes. That might mean that calendar nodes are spread throughout the service and mixed with non-calendar nodes. Calendaring features are only required in the nodes that are calendar nodes.</p>
<p>The calendar service is the canonical location for calendar data and state information. Entities may submit requests to change data or download data. Entities may store calendar objects offline and attempt to synchronize at a later time. However, entities MUST be prepared for calendar data on the service to change between the time of last synchronization and when attempting an update, as calendar nodes may be shared and accessed by multiple entities.</p>
</section2>
<!-- == Calendar Nodes =================================================== -->
<section2 topic='Calendar Nodes' anchor='datamodel-nodes'>
<p>A calendar node contains calendar items that represent calendar components within a calendar. A calendar node is manifested to entities as a publish-subscribe node identified by a NodeID. A calendar node MUST report the '&NS;' feature &VNOTE; in the result of a 'disco#info' query. A calendar service MUST persist items for a calendar node.</p>
<p>A calendar node can be created through provisioning (i.e., automatically created when a user's account is provisioned), or it can be created with the publish-subscribe &lt;create/&gt; request (see section <link url='#create'>Creating Calendars</link>). It can be useful for a user to create additional calendars (e.g., soccer schedule) or for users to share a calendar (e.g., team events or conference rooms). However, note that this specification doesn&apos;t define the purpose of calendar nodes. Users may use the 'pubsub#title' and 'pubsub#description' fields in node meta-data to find out what a calendar node is for.</p>
<p>Calendar nodes MUST only contain calendar items. This ensures that entities do not have to deal with non-calendar data in a calendar node.</p>
</section2>
<!-- == Calendar Items =================================================== -->
<section2 topic='Calendar Items' anchor='datamodel-items'>
<p>Calendar items in a calendar node MUST NOT contain more than one type of calendar component (e.g., VEVENT, VTODO, VJOURNAL, VFREEBUSY, etc.) with the exception of VTIMEZONE components, which MUST be specified for each unique "TZID" parameter value specified in the iCalendar object. For instance, a calendar item can contain one VEVENT component and one VTIMEZONE component, but it cannot contain one VEVENT component and one VTODO component. Instead, the VEVENT and VTODO components would have to be stored in separate calendar items in the same node.</p>
<p>Calendar object items in calendar collections MUST NOT specify the iCalendar "METHOD" property.</p>
<p>The "UID" property value of the calendar components contained in a calendar item MUST be unique in the scope of the calendar node in which they are stored.</p>
<p>Calendar components in a calendar node that have different "UID" property values MUST be stored in separate calendar items.</p>
<p>Calendar components with the same "UID" property value, in a given calendar node, MUST be contained in the same calendar item. This ensures that all components in a recurrence "set" are contained in the same calendar item. It is possible for a calendar item to just contain components that represent "overridden" instances (ones that modify the behavior of a regular instance, and thus include a "RECURRENCE-ID" property) without also including the "master" recurring component (the one that defines the recurrence "set" and does not contain any "RECURRENCE-ID" property).</p>
</section2>
</section1>
<!-- =======================================================================
Preliminaries
======================================================================= -->
<section1 topic='Preliminaries' anchor='preliminaries'>
<!-- == Roles and Transactions =========================================== -->
<section2 topic='Roles and Transactions' anchor='rolesandtransactions'>
<p>This specification uses methods defined by <cite>RFC 2446</cite> for exchanging calendar objects for the purposes of group calendaring and scheduling between "Calendar Users" (CUs). CUs take on one of two roles in iTIP. The CU who initiates an exchange takes on the role of "Organizer". For example, the CU who proposes a group meeting is the "Organizer". The CUs asked to participate in the group meeting by the "Organizer" take on the role of "Attendee".</p>
<p class='box'>Note: "role" is also a descriptive parameter to the "ATTENDEE" property. Its use is to convey descriptive context to an "Attendee" such as "chair", "req-participant" or "non-participant" and has nothing to do with the calendaring workflow.</p>
<p>A calendar entry is created and managed by an "Organizer". The "Organizer" interacts with other CUs by sending one or more requests specifying the "REQUEST" method to a calendar service which will forward these to "Attendees" (and send notifications to pubsub subscribers). "Attendees" use the same requests specifying the "REPLY" method to communicate their status back to the calendar service. "Attendees" cannot make any changes to the calendar entry except for their own status. They can, however, use requests specifying the "COUNTER" method to suggest changes to the "Organizer". In any case, the "Organizer" has complete control over the master calendar entry.</p>
<table caption='Methods'>
<tr>
<th>Method</th>
<th>Description</th>
</tr>
<tr>
<td>PUBLISH</td>
<td>Used to publish a calendar object to a calendar node and when sending notifications to pubsub subscribers. There is no interactivity between the publisher and any other calendar user. An example might include a baseball team publishing its schedule to the public.</td>
</tr>
<tr>
<td>REQUEST</td>
<td>Used to schedule a calendar entry with other Calendar Users. Requests are interactive in that they require the receiver to respond using the Reply methods. Invitations and the assignment of To-Dos to other Calendar Users are examples. Requests are also used by the "Organizer" to update the status of a calendar entry.</td>
</tr>
<tr>
<td>REPLY</td>
<td>A Reply is used in response to a Request to convey "Attendee" status to the calendar service (which will forward it to the "Organizer"). Replies are commonly used to respond to meeting and task requests.</td>
</tr>
<tr>
<td>ADD</td>
<td>Add one or more instances to an existing VEVENT, VTODO, or VJOURNAL.</td>
</tr>
<tr>
<td>CANCEL</td>
<td>Cancel one or more instances of an existing VEVENT, VTODO, or VJOURNAL. This does not remove the calendar entry from persistent storage.</td>
</tr>
<tr>
<td>COUNTER</td>
<td>The Counter method is used by an "Attendee" to negotiate a change in the calendar entry. Examples include the request to change a proposed Event time or change the due date for a To-Do.</td>
</tr>
</table>
<p>The methods listed above and their usage and semantics are defined in section 3 of <cite>RFC 2446</cite>.</p>
<p>The other methods defined by <cite>RFC 2446</cite>, REFRESH and DECLINECOUNTER, are not used and MUST NOT be specified by requesting entities. Entities SHOULD use the reporting methods defined in this specification to request the latest version of a calendar entry. "Organizers" MAY decline a proposed counter-proposal by sending a rude chat message to the "Attendee" who proposed the counter-proposal.</p>
</section2>
<!-- == Subscriptions =============================================== -->
<section2 topic='Subscriptions' anchor='subscriptions'>
<p>Subscriptions to a calendar node may exist in three different ways.</p>
<!--
<p>Subscriptions to a calendar node may exist in three different ways: 'attendee', 'freebusy-subscriber', and/or 'subscriber'. These are not mutually exclusive.</p>
<p>The "authorize" access model is RECOMMENDED.</p>
-->
<p>&TODO;</p>
</section2>
<!-- == Permissions =================================================== -->
<section2 topic='Permissions' anchor='permissions'>
<p>Group scheduling is accomplished using the set of "request" and "response" methods described above. To manage permissions, this specification builds on the hierarchy of affiliations defined by <cite>XEP-0060</cite>. Therefore, a calendar service MUST support and adhere to the requirements of pubsub affiliations. Calendaring permissions are calculated from the pubsub affiliation of the XMPP entity and, if applicable, the properties of the calendar item involved in an operation.</p>
<!--
<p>A calendar service MUST support the mechanism defined in this section.</p>
<p>The following table shows the methods broken down by who can send them.</p>
-->
<p>&TODO;</p>
</section2>
<!-- == Calendar Entry State ============================================= -->
<section2 topic='Calendar Entry State' anchor='entrystate'>
<p>There are two distinct states relevant to calendar entries: the overall state of the entry and the state associated with an "Attendee" to that entry.</p>
<p>The state of an entry is defined by the "STATUS" property and is controlled by the "Organizer." There is no default value for the "STATUS" property. The "Organizer" sets the "STATUS" property to the appropriate value for each calendar entry.</p>
<p>The state of a particular "Attendee" relative to an entry is defined by the "partstat" parameter in the "ATTENDEE" property for each "Attendee". When an "Organizer" issues the initial entry, "Attendee" status is unknown. The "Organizer" specifies this by setting the "partstat" parameter to "needs-action". Each "Attendee" modifies their "ATTENDEE" property "partstat" parameter to an appropriate value.</p>
</section2>
<!-- == Calendar Item Revisions ========================================== -->
<section2 topic='Calendar Item Revisions' anchor='itemrevisions'>
<p>The "SEQUENCE" property is used by the "Organizer" to indicate revisions to the calendar item. The rules for incrementing the "SEQUENCE" number for a given "UID" in a calendar component are as follows:</p>
<ul>
<li>For the "PUBLISH" and "REQUEST" methods, the "SEQUENCE" property value is incremented according to the rules defined in <cite>RFC 2445</cite>.</li>
<li>The "SEQUENCE" property value MUST be incremented each time the "Organizer" uses the "ADD" or "CANCEL" methods.</li>
<li>The "SEQUENCE" property value MUST NOT be incremented when an "Attendee" modifies the "ATTENDEE" property "partstat" parameter, when an "Attendee" submits a counter proposal to negotiate a change in a calendar item, or when an "Attendee" grants another CU (or several CUs) the right to attend on their behalf.</li>
<li>The "SEQUENCE" property value MUST NOT be incremented when retrieving calendar objects from a calendar node or sending pubsub notifications to subscribers.</li>
</ul>
<p>The value of the "SEQUENCE" property contained in a response from an "Attendee" may not always match the current revision of the master calendar entry. Implementations may choose to indicate to the "Attendee" that the response is to an entry that has been revised and allow the CU to decide whether or not to send the response.</p>
</section2>
<!-- == Request Sequencing =============================================== -->
<section2 topic='Request Sequencing' anchor='requestsequencing'>
<p>Calendar services must often correlate a component in a calendar node with a component received in a pubsub request. For example, an event may be updated with a later revision of the same event. To accomplish this, a calendar service must correlate the version of the event already in the calendar node with the version sent in the pubsub request. In addition to this correlation, there are several factors that can cause requests to arrive in an unexpected order. That is, a calendar service could receive a reply to an earlier revision of a component AFTER receiving a reply to a later revision.</p>
<p>To maximize interoperability and to handle messages that arrive in an unexpected order, implementations SHOULD follow the rules in section 2.1.5 of <cite>RFC 2446</cite>. Hence, a calendar service must persist the following component properties: "UID", "RECURRENCE-ID", "SEQUENCE", and "DTSTAMP". Furthermore, for each "ATTENDEE" property of a component a calendar service must persist the "SEQUENCE" and "DTSTAMP" property values associated with the "Attendee's" response.</p>
</section2>
</section1>
<!-- =======================================================================
Discovering Support
======================================================================= -->
<section1 topic='Discovering Support' anchor='disco'>
<!-- == Service Features ================================================= -->
<section2 topic='Service Features' anchor='disco-service'>
<p>A calendar service MUST respond to service discovery information requests qualified by the 'http://jabber.org/protocol/disco#info' namespace. The "disco#info" result returned by a calendar service MUST indicate the identity of a pubsub service and indicate which pubsub features are supported. A calendar service supporting the features described in this specification MUST also include "&NS;" as a feature in the "disco#info" result. A feature of "&NS;" &VNOTE; in the result MUST indicate that the service supports all MUST level requirements in this specification.</p>
<example caption='Entity queries calendar service regarding supported features'><![CDATA[
<iq type='get'
from='francisco@denmark.lit/barracks'
to='pubsub.shakespeare.lit'
id='feature1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption='Calendar service returns set of supported features'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='feature1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity category='pubsub' type='service'/>
<feature var='http://jabber.org/protocol/pubsub'/>
<feature var='urn:xmpp:tmp:calendar:0'/>
...
</query>
</iq>
]]></example>
</section2>
<!-- == Node Information ================================================= -->
<section2 topic='Node Information' anchor='disco-node'>
<p>A calendar service MUST also allow entities to query individual nodes for the information associated with that node. A calendar service supporting the features described in this specification MUST include "&NS;" &VNOTE; as a feature in the "disco#info" result for a calendar node. It MUST NOT include the feature in the result for a non-calendar node. The "disco#info" result MAY include detailed meta-data about the node as described in section 5.4 of <cite>XEP-0060</cite>.</p>
<example caption='Entity queries a node for information'><![CDATA[
<iq type='get'
from='francisco@denmark.lit/barracks'
to='pubsub.shakespeare.lit'
id='meta1'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='princely_musings'/>
</iq>
]]></example>
<example caption='Service responds with information and meta-data'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='meta1'>
<query xmlns='http://jabber.org/protocol/disco#info'
node='princely_musings'/>
<identity category='pubsub' type='leaf'/>
<feature var='http://jabber.org/protocol/pubsub'/>
<feature var='urn:xmpp:tmp:calendar:0'/>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#meta-data</value>
</field>
<field var='pubsub#type' label='Payload type'>
<value>urn:ietf:params:xml:ns:xcal</value>
</field>
<field var='pubsub#creator' label='Node creator'>
<value>hamlet@denmark.lit</value>
</field>
<field var='pubsub#creation_date' label='Creation date'>
<value>2003-07-29T22:56Z</value>
</field>
<field var='pubsub#title' label='A short name for the node'>
<value>Princely Musings (Atom)</value>
</field>
<field var='pubsub#description' label='A description of the node'>
<value>Updates for Hamlet&apos;s Princely Musings weblog.</value>
</field>
<field var='pubsub#language' label='Default language'>
<value>en</value>
</field>
<field var='pubsub#contact' label='People to contact with questions'>
<value>bard@shakespeare.lit</value>
</field>
<field var='pubsub#owner' label='Node owners'>
<value>hamlet@denmark.lit</value>
</field>
<field var='pubsub#publisher' label='Publishers to this node'>
<value>hamlet@denmark.lit</value>
</field>
<field var='pubsub#num_subscribers' label='Number of subscribers to this node'>
<value>1066</value>
</field>
</x>
</query>
</iq>
]]></example>
</section2>
</section1>
<!-- =======================================================================
Creating Calendars
======================================================================= -->
<section1 topic='Creating Calendars' anchor='create'>
<!-- == Request ========================================================== -->
<section2 topic='Request' anchor='create-request'>
<p>An entity may want to create a new calendar node. Support for this feature is RECOMMENDED. However, a calendar service MAY disallow creation of calendar nodes based on the identity of the requesting entity, or MAY disallow calendar node creation altogether (e.g., reserving that privilege to a service-wide administrator).</p>
<p>The methods to create a node are explained in section 8.1 of <cite>XEP-0060</cite>. To create a new calendar node, the requesting entity MUST include a Data Form containing a 'pubsub#type' field whose &lt;value/&gt; is "urn:ietf:params:xml:ns:xcal".</p>
<example caption='Entity requests a new calendar node with "authorize" access model'><![CDATA[
<iq type='set'
from='bard@shakespeare.lit/globe'
to='cal.example.com'
id='create3'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<create node='/home/lisa/calendars/events/'/>
<configure>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#node_config</value>
</field>
<field var='pubsub#type'>
<value>urn:ietf:params:xml:ns:xcal</value>
</field>
<field var='pubsub#access_model'>
<value>authorize</value>
</field>
<field var='pubsub#title'>
<value>Lisa's Events</value>
</field>
<field var='pubsub#description'>
<value>Calendar restricted to events.</value>
</field>
<field var='calendar#component_set'>
<value>VEVENT</value>
<value>VFREEBUSY</value>
</fields>
</x>
</configure>
</pubsub>
</iq>
]]></example>
</section2>
<!-- == Success Case ===================================================== -->
<section2 topic='Success Case' anchor='create-success'>
<p>If calendar nodes are supported and none of the general or method-specific errors has occurred, the calendar service SHOULD create the node and inform the requesting entity of success.</p>
<example caption='Service informs requesting entity of success'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='bard@shakespeare.lit/globe'
id='create3'/>
]]></example>
</section2>
<!-- == Error Cases ====================================================== -->
<section2 topic='Error Cases' anchor='create-error'>
<p>In addition to the errors already defined for leaf nodes by <cite>XEP-0060</cite>, there are several reasons why the calendar node creation request might fail:</p>
<ol>
<li>The service does not support creation of calendar nodes.</li>
<li>The requesting entity does not have sufficient privileges to create calendar nodes.</li>
</ol>
<p>These error cases are described more fully in the following sections.</p>
<section3 topic='Calendar Node Creation Not Supported' anchor='create-error-notallowed'>
<p>If the calendar service does not allow new calendar nodes to be created, it MUST respond with a &notallowed; error.</p>
<example caption='Service does not allow creation of calendar nodes'><![CDATA[
<iq type='error'
from='hamlet@denmark.lit/elsinore'
to='pubsub.shakespeare.lit'
id='config1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
<configure node='princely_musings'/>
</pubsub>
<error type='cancel'>
<not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section3>
<section3 topic='Insufficient Privileges' anchor='create-error-forbidden'>
<p>If the requesting entity has insufficient privileges to create new calendar nodes, the service MUST respond with a &forbidden; error.</p>
<example caption='Requesting entity has insufficient privileges to create calendar nodes'><![CDATA[
<iq type='error'
from='pubsub.shakespeare.lit'
to='hamlet@denmark.lit/elsinore'
id='config1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub#owner'>
<configure node='princely_musings'/>
</pubsub>
<error type='auth'>
<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
</section3>
</section2>
<!-- == Calendar Node Configuration ====================================== -->
<section2 topic='Calendar Node Configuration' anchor='config'>
<p>A calendar service MUST offer a couple of node configuration options that are specific to calendar nodes and not provided by standard pubsub leaf nodes. The following table shows these configuration options and defines a mapping to the calendar properties specified by <cite>RFC 4791</cite>:</p>
<table caption='Calendar configuration options'>
<tr>
<th>Configuration option</th>
<th>Type</th>
<th>Description</th>
<th>CalDAV property</th>
</tr>
<tr>
<td>pubsub#title</td>
<td>text-single</td>
<td>Provides a human-readable description of the calendar node.</td>
<td>calendar-description</td>
</tr>
<tr>
<td>&SN;#timezone</td>
<td>text-single</td>
<td>Specifies a time zone on a calendar node.</td>
<td>calendar-timezone</td>
</tr>
<tr>
<td>&SN;#component_set</td>
<td>text-multi</td>
<td>Specifies the calendar component types (e.g., VEVENT,
VTODO, etc.) that calendar items can contain in the calendar
node.</td>
<td>supported-calendar-component-set</td>
</tr>
<tr>
<td>pubsub#type</td>
<td>text-single</td>
<td>Specifies what media types are allowed for calendar items in
a calendar node.</td>
<td>supported-calendar-data</td>
</tr>
<tr>
<td>pubsub#max_payload_size</td>
<td>text-single</td>
<td>Provides a numeric value indicating the maximum size of a
resource in octets that the calendar service is willing to accept
when a calendar item is stored in a calendar node.</td>
<td>max-resource-size</td>
</tr>
<tr>
<td>&SN;#min_date_time</td>
<td>text-single</td>
<td>Provides a DATE-TIME value indicating the earliest date and
time (in UTC) that the calendar service is willing to accept for
any DATE or DATE-TIME value in a calendar item stored in a calendar
node.</td>
<td>min-date-time</td>
</tr>
<tr>
<td>&SN;#max_date_time</td>
<td>text-single</td>
<td>Provides a DATE-TIME value indicating the latest date and
time (in UTC) that the calendar service is willing to accept for
any DATE or DATE-TIME value in a calendar item stored in a calendar
node.</td>
<td>max-date-time</td>
</tr>
<tr>
<td>&SN;#max_instances</td>
<td>text-single</td>
<td>Provides a numeric value indicating the maximum number of
recurrence instances that a calendar item stored in a calendar
node can generate.</td>
<td>max-instances</td>
</tr>
<tr>
<td>&SN;#max_attendees_per_instance</td>
<td>text-single</td>
<td>Provides a numeric value indicating the maximum number of
"ATTENDEE" properties in any instance of a calendar item stored
in a calendar node.</td>
<td>max-attendees-per-instance</td>
</tr>
</table>
<p>An entity SHOULD should specify the 'pubsub#title' field for a human-readable name of the calendar when configuring a calendar node. The entity SHOULD NOT set the 'pubsub#title' field to be the same as any other calendar node owned by the same entity. When displaying calendar nodes to users, clients SHOULD check the 'pubsub#title' field and use that value as the name of the calendar. In the event that the 'pubsub#title' field is empty, the client MAY use the NodeID of the calendar as the name; however, the NodeID may be "opaque" and not represent any meaningful human-readable text.</p>
</section2>
</section1>
<!-- =======================================================================
Scheduling Calendar Entries
======================================================================= -->
<section1 topic='Scheduling Calendar Entries' anchor='publish'>
<!-- == Request ========================================================== -->
<section2 topic='Request' anchor='publish-request'>
<p>An entity may schedule calendar entries by sending a &lt;publish/&gt; request to the calendar service. Support for this feature is REQUIRED.</p>
<p>The syntax is as follows:</p>
<ul>
<li>The &lt;publish/&gt; element MUST possess a 'node' attribute, specifying the NodeID of the calendar node.</li>
<li>Depending on the node configuration, the &lt;publish/&gt; element MAY contain no &ITEM; elements, one &ITEM; element, or (for Batch Processing) more than one &ITEM; element.</li>
<li>Each &ITEM; element MUST contain a &lt;vcalendar/&gt; element qualified by the 'urn:ietf:params:xml:ns:xcal' namespace.</li>
<li>The &lt;vcalendar/&gt; element MUST contain a &lt;method/&gt; element, specifying the calendaring-specific method of the request.</li>
<li>The &lt;vcalendar/&gt; element MUST contain an XML element qualified by the 'urn:ietf:params:xml:ns:xcal' namespace representing the calendar object to publish (i.e. &lt;vevent/&gt;, &lt;vtodo/&gt;, &lt;vjournal/&gt;, etc.).</li>
<li>The calendar object MAY contain an "UID" property, specifying a unique ItemID for the item. If an ItemID is not provided, the calendar service MUST generate one and MUST ensure that it is unique for that calendar node.</li>
<li>If an ItemID is specified in the publish request, the &ITEM; element MUST possess an 'id' attribute whose value is the ItemID. Otherwise, the &ITEM; element MUST NOT possess an 'id' attribute.</li>
<li>The calendar object MUST conform to the property constraints defined in <cite>RFC 2446</cite> for the specified method, except for the "UID" property which is OPTIONAL for ItemID generation purposes as described above. The "ORGANIZER" property MUST be present and MUST be set to an XMPP URI identifying the publishing entity.</li>
</ul>
<p>The example below publishes a single event that begins on July 1, 1997 at 20:00 UTC. This event contains the minimum set of properties for publishing an event to a calendar.</p>
<example caption='"Organizer" publishes a minimal event with an ItemID'><![CDATA[
<iq type='set'
from='romeo@montague.net/orchard'
to='calendar.shakespeare.lit'
id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<item id='4785a496-9200-43f7-ba32-53c58e03ba37'>
<vcalendar xmlns='urn:ietf:params:xml:ns:xcal'>
<method>PUBLISH</method>
<prodid>-//ACME/DesktopCalendar//EN</prodid>
<version>2.0</version>
<vevent>
<organizer>xmpp:romeo@montague.net</organizer>
<dtstart>1997-07-01T20:00:00Z</dtstart>
<dtstamp>1997-06-11T19:00:00Z</dtstamp>
<summary>ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES</summary>
<uid>4785a496-9200-43f7-ba32-53c58e03ba37</uid>
</vevent>
</vcalendar>
</item>
</publish>
</pubsub>
</iq>
]]></example>
</section2>
<!-- == Success Case ===================================================== -->
<section2 topic='Success Case' anchor='publish-success'>
<p>If the calendar service can successfully process the request, it MUST inform the publisher of success. If the publish request did not include an ItemID, the IQ-result SHOULD include an empty &lt;item/&gt; element that specifies the ItemID of the published item.</p>
<example caption='Service replies with success'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='hamlet@denmark.lit/blogbot'
id='publish1'/>
]]></example>
<p class='box'>Note: If the publisher previously published an item with the same ItemID, successfully processing the request means that the service MUST proceed as described in <cite>RFC 2446</cite> for the calendaring-specific method used. This usually means that the service MUST overwrite the old calendar entry with a modified entry and then proceed as follows.</p>
<p>The calendar service MUST then send one &MESSAGE; stanza containing a pubsub event notification to each entity that meets the criteria for receiving a notification, as described in section 7.1.2 of <cite>XEP-0060</cite>. Event notifications MUST be sent specifying the "PUBLISH" method, even if the event notification results from a publishing request that specified a different method.</p>
</section2>
<!-- == Error Cases ====================================================== -->
<section2 topic='Error Cases' anchor='publish-error'>
<p>In addition to the errors already defined for publish requests by <cite>XEP-0060</cite>, there are several reasons why the request might fail:</p>
<ol>
<li>The namespace of the root payload element submitted in the request does not match the configured namespace for the node, or the payload does not conform to the syntax of the 'urn:ietf:params:xml:ns:xcal' namespace.</li>
<li>The calendar component submitted in the request does not contain a type of calendar component that is supported in the calendar node.</li>
<li>The calendar component submitted in the request does not obey all restrictions.</li>
<li>The calendar component submitted in the request does not conform to the configuration.</li>
</ol>
<p>These error cases are described more fully in the following sections.</p>
<section3 topic='Bad Payload' anchor='publish-error-badpayload'>
<p>If the namespace of the root payload element submitted in the request does not match the configured namespace for the node (i.e., the 'urn:ietf:params:xml:ns:xcal' namespace) or the payload does not conform to the syntax of the 'urn:ietf:params:xml:ns:xcal' namespace, the service MUST respond with a &badrequest; error, which SHOULD also include a pubsub-specific error condition of &lt;invalid-payload/&gt;.</p>
<example caption='Entity attempts to publish item with invalid payload'><![CDATA[
<iq type='error'
from='pubsub.shakespeare.lit'
to='hamlet@denmark.lit/elsinore'
id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='princely_musings'>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
... INVALID PAYLOAD ...
</item>
</publish>
</pubsub>
<error type='modify'>
<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<invalid-payload xmlns='http://jabber.org/protocol/pubsub#errors'/>
</error>
</iq>
]]></example>
</section3>
<section3 topic='Unsupported Calendar Component' anchor='publish-error-unsupported'>
<p>If the calendar component submitted in the request does not contain a type of calendar component that is supported in the calendar node (see section <link url='#config'>Calendar Node Configuration</link>), the service MUST respond with a &badrequest; error, which SHOULD also include a pubsub-specific error condition of &lt;item-forbidden/&gt;.</p>
</section3>
<section3 topic='Invalid Calendar Item' anchor='publish-error-invalid'>
<p>If the calendar component submitted in the request does not obey all restrictions specified in section <link url='#datamodel-items'>Calendar Items</link> (e.g., calendar items MUST NOT contain more than one type of calendar component), in section <link url='#publish-request'>Request</link> (e.g., the request MUST specify an iCalendar "METHOD" property, etc.), and/or those defined for the specified iCalendar method, the service MUST respond with a &badrequest; error, which SHOULD also include a pubsub-specific error condition of &lt;invalid-payload/&gt;.</p>
</section3>
<section3 topic='Request Does Not Match Configuration' anchor='publish-error-forbidden'>
<p>If the calendar component submitted in the request does not conform to the configuration of the calendar node where the component will be stored (see section <link url='#config'>Calendar Node Configuration</link>), the service MUST respond with a &badrequest; error, which SHOULD also include a pubsub-specific error condition. The following rules apply:</p>
<ul>
<li>If the calendar component contains a DATE or DATE-TIME property value (for any recurring instance) less than to the value of the "&SN;#min_date_time" configuration option, the service MUST respond with a &badrequest; error and a pubsub-specific error condition of &lt;item-forbidden/&gt;.</li>
<li>If the calendar component contains a DATE or DATE-TIME property value (for any recurring instance) greater than or equal to the "&SN;#max_date_time" configuration option, the service MUST respond with a &badrequest; error and a pubsub-specific error condition of &lt;item-forbidden/&gt;.</li>
<li>If the calendar component generates a number of recurring instances greater than the value of the "&SN;#max_instances" configuration option, the service MUST respond with a &badrequest; error and a pubsub-specific error condition of &lt;item-forbidden/&gt;.</li>
<li>If the calendar component has a number of "ATTENDEE" properties on any one instance greater than the value of the "&SN;#max_attendees_per_instance" configuration option, the service MUST respond with a &badrequest; error and a pubsub-specific error condition of &lt;item-forbidden/&gt;.</li>
</ul>
</section3>
</section2>
</section1>
<!-- =======================================================================
Retrieving Calendar Entries
======================================================================= -->
<section1 topic='Retrieving Calendar Entries' anchor='retrieve'>
<!-- == Request ========================================================== -->
<section2 topic='Request' anchor='retrieve-request'>
<p>A calendar service MUST allow entities to request existing calendar items from a calendar node. The reporting method described in this section is an extension of the pubsub &lt;items/&gt; request (defined in section 6.4 of <cite>XEP-0060</cite>), but can involve much more complex processing. This is valuable in cases where the calendar service has access to all of the information needed to perform the complex request (such as a query), and where it would require multiple requests for the client to retrieve the information needed to perform the same request.</p>
<p>The &lt;calendar-query/&gt; report performs a search for all calendar items that match a specified filter. The response of this report will contain all the calendar item data specified in the request. In the case of the &lt;calendar-data/&gt;, one can explicitly specify the calendar components and properties that should be returned in the calendar item data that matches the filter.</p>
<p>Support for the &lt;calendar-query/&gt; report is REQUIRED.</p>
<p>The syntax is as follows:</p>
<ul>
<li>The &lt;items/&gt; element MUST possess a 'node' attribute, specifying the NodeID of the node.</li>
<li>The &lt;items/&gt; element MAY possess a 'max_items' attribute to limit the number of calendar items returned.</li>
<li>The &lt;items/&gt; element MAY contain a &lt;calendar-query/&gt; element qualified by the 'urn:ietf:params:xml:ns:caldav' namespace.</li>
<li>The syntax of the &lt;calendar-query/&gt; element is defined in <cite>RFC 4791</cite>.</li>
</ul>
<example caption='Subscriber requests Events by Time Range'><![CDATA[
<iq type='get'
from='juliet@capulet.com/balcony'
to='calendaring.shakespeare.lit'
id='items1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<calendar-query xmlns='urn:ietf:params:xml:ns:caldav'>
<filter>
<comp-filter name='VCALENDAR'>
<comp-filter name='VEVENT'>
<time-range start='2006-01-04T00:00:00Z' end='2006-01-05T00:00:00Z'/>
</comp-filter>
</comp-filter>
</filter>
</calendar-query>
</items>
</pubsub>
</iq>
]]></example>
</section2>
<!-- == Success Case ===================================================== -->
<section2 topic='Success Case' anchor='retrieve-success'>
<p>If the calendar service can successfully process the request, it SHOULD return all requested calendar item data, although it MAY truncate the result set if it contains a large number of items.</p>
<example caption='Service returns all Events within the requested Time Range'><![CDATA[
<iq type='result'
from='pubsub.shakespeare.lit'
to='francisco@denmark.lit/barracks'
id='items1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='princely_musings'>
<item id='368866411b877c30064a5f62b917cffe'>
... PAYLOAD ...
</item>
<item id='4e30f35051b7b8b42abe083742187228'>
... PAYLOAD ...
</item>
<item id='ae890ac52d0df67ed7cfdf51b644e901'>
... PAYLOAD ...
</item>
</items>
</pubsub>
</iq>
]]></example>
</section2>
<!-- == Error Cases ====================================================== -->
<section2 topic='Error Cases' anchor='retrieve-error'>
<p>In addition to the errors already defined for retrieval requests by <cite>XEP-0060</cite>, there are several reasons why the request might fail:</p>
<ol>
<li>The &lt;filter/&gt; element does not conform to the syntax of the 'urn:ietf:params:xml:ns:caldav' namespace.</li>
<li>The &lt;filter/&gt; element attempts to reference an unsupported component, property, or parameter.</li>
<li>The reporting request does not conform to the configuration of the calendar node being queried.</li>
<li>An XML attribute specifying a collation does not specify a supported collation.</li>
</ol>
<p>These error cases are described more fully in the following sections.</p>
<section3 topic='Invalid Filter' anchor='retrieve-error-invalid'>
<p>If the &lt;filter/&gt; element does not conform to the syntax of the 'urn:ietf:params:xml:ns:caldav' namespace, the service MUST respond with a &badrequest; error. For instance, a &lt;filter/&gt; cannot nest a &lt;comp name='VEVENT'/&gt; element in a &lt;comp name='VTODO'/&gt; element, and a &lt;filter/&gt; cannot nest a &lt;time-range start='...' end='...'/&gt; element in a &lt;prop name='SUMMARY'/&gt; element.</p>
</section3>
<section3 topic='Unsupported Filter' anchor='retrieve-error-unsupported'>
<p>If any &lt;comp-filter/&gt;, &lt;prop-filter/&gt;, or &lt;param-filter/&gt; element used in the &lt;filter/&gt; element in the report request makes a reference to components, properties, or parameters for which queries are not supported by the server (i.e., if the &lt;filter/&gt; element attempts to reference an unsupported component, property, or parameter), the service MUST respond with a &badrequest; error.</p>
</section3>
<section3 topic='Request Does Not Match Configuration' anchor='retrieve-error-forbidden'>
<p>If the reporting request does not conform to the configuration of the calendar node being queried (see section <link url='#config'>Calendar Node Configuration</link>), the service MUST respond with a &badrequest; error<!--, which SHOULD also include a pubsub-specific error condition-->. The following rules apply:</p>
<ul>
<li>If any XML element specifying a range of time has its start or end DATE or DATE-TIME values less than the value of "&SN;#min_date_time" configuration option, the service MUST respond with a &badrequest; error.</li>
<li>If any XML element specifying a range of time has its start or end DATE or DATE-TIME values greater than the value of the "&SN;#max_date_time" configuration option, the service MUST respond with a &badrequest; error.</li>
</ul>
</section3>
<section3 topic='Unsupported Collation' anchor='retrieve-error-collation'>
<p>If any XML attribute specifying a collation does not specify a collation supported by the calendar service as described in section 7.5 of <cite>RFC 4791</cite>, the service MUST respond with a &badrequest; error.</p>
</section3>
</section2>
</section1>
<!-- =======================================================================
Retrieving Free/Busy Time
======================================================================= -->
<section1 topic='Retrieving Free/Busy Time' anchor='freebusy'>
<!-- == Request ========================================================== -->
<section2 topic='Request' anchor='freebusy-request'>
<p>The &lt;free-busy-query/&gt; report generates a VFREEBUSY object containing free busy information for all the calendar items targeted by the request and that have the "read-free-busy" or "read" privilege granted to the requesting entity. The reporting method described in this section is an extension of the pubsub &lt;items/&gt; request (defined in section 6.4 of <cite>XEP-0060</cite>).</p>
<p>Support for the &lt;free-busy-query/&gt; report is REQUIRED.</p>
<p>Only VEVENT objects without a "TRANSP" property or with the "TRANSP" property set to "opaque", and VFREEBUSY components SHOULD be considered in generating the free busy time information.</p>
<p>In the case of VEVENT objects, the free or busy time type ("fbtype" parameter) of the "FREEBUSY" properties in the returned VFREEBUSY object SHOULD be derived from the value of the "TRANSP" and "STATUS" properties; see section 7.10 of <cite>RFC 4791</cite>.</p>
<p>Duplicate busy time periods with the same "fbtype" parameter value SHOULD NOT be specified in the returned VFREEBUSY component. A calendar service SHOULD coalesce consecutive or overlapping busy time periods of the same type. Busy time periods with different "fbtype" parameter values MAY overlap.</p>
<p>The syntax is as follows:</p>
<ul>
<li>The &lt;items/&gt; element MUST possess a 'node' attribute, specifying the NodeID of the node.</li>
<li>The &lt;items/&gt; element MAY contain a &lt;free-busy-query/&gt; element qualified by the 'urn:ietf:params:xml:ns:caldav' namespace.</li>
<li>The syntax of the &lt;free-busy-query/&gt; element is defined in <cite>RFC 4791</cite>.</li>
</ul>
<p>In the following example, Juliet requests the server to return free busy information on the calendar "ccfc0b59-b9d9-4d0f-ac2f-829e7077640e", between 9:00 A.M. and 5:00 P.M. EST (2:00 P.M. and 10:00 P.M. UTC) on the January 4, 2006.</p>
<example caption='Subscriber requests Free Busy Time Information'><![CDATA[
<iq type='get'
from='juliet@capulet.com/balcony'
to='calendaring.shakespeare.lit'
id='items4'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<free-busy-query xmlns='urn:ietf:params:xml:ns:caldav'>
<time-range start='2006-01-04T14:00:00Z' end='2006-01-05T22:00:00Z'/>
</free-busy-query>
</items>
</pubsub>
</iq>
]]></example>
</section2>
<!-- == Success Case ===================================================== -->
<section2 topic='Success Case' anchor='freebusy-success'>
<p>If the calendar service can successfully process the request, it MUST return the generated VFREEBUSY object. The example indicates two busy time intervals of one hour, one of which is tentative.</p>
<example caption='Service returns Free Busy Time Information'><![CDATA[
<iq type='result'
from='calendaring.shakespeare.lit'
to='juliet@capulet.com/balcony'
id='items4'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<item>
<vfreebusy xmlns='urn:ietf:params:xml:ns:xcal'>
<dtstamp>2005-01-25T09:00:00Z</dtstamp>
<dtstart>2006-01-04T14:00:00Z</dtstart>
<dtend>2006-01-05T22:00:00Z</dtend>
<freebusy fbtype='busy-tentative'>2006-01-04T15:00:00Z PT1H</freebusy>
<freebusy>2006-01-04T19:00:00Z PT1H</freebusy>
</vfreebusy>
</item>
</items>
</pubsub>
</iq>
]]></example>
</section2>
<!-- == Error Cases ====================================================== -->
<section2 topic='Error Cases' anchor='freebusy-error'>
<p>There are no errors in addition to those already defined for retrieval requests by <cite>XEP-0060</cite>.</p>
<!--
<p>In addition to the errors already defined for retrieval requests by <cite>XEP-0060</cite>, there are several reasons why the request might fail:</p>
<ol>
<li>&TODO;</li>
</ol>
<p>These error cases are described more fully in the following sections.</p>
-->
</section2>
</section1>
<!-- =======================================================================
Alarm Notifications
======================================================================= -->
<section1 topic='Alarm Notifications' anchor='alarm'>
<!-- == Creating Alarms ================================================== -->
<section2 topic='Setting up Alarms' anchor='alarm-setup'>
<p>An "ORGANIZER" MAY include a VALARM calendar component in any VEVENT or VTODO component. A VALARM calendar component is a grouping of component properties that is a reminder or alarm for an event or a to-do. For example, it may be used to define a reminder for a pending event or an overdue to-do.</p>
<p>The following example publishes an event with a VALARM calendar component that specifies an audio alarm that will sound at a precise time and repeat 4 more times at 15 minute intervals:</p>
<example caption='"Organizer" publishes an event with an alarm'><![CDATA[
<iq type='set'
from='romeo@montague.net/orchard'
to='calendar.shakespeare.lit'
id='publish1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<item id='4785a496-9200-43f7-ba32-53c58e03ba37'>
<vcalendar xmlns='urn:ietf:params:xml:ns:xcal'>
<method>PUBLISH</method>
<prodid>-//ACME/DesktopCalendar//EN</prodid>
<version>2.0</version>
<vevent>
<organizer>xmpp:romeo@montague.net</organizer>
<dtstart>1997-07-01T20:00:00Z</dtstart>
<dtstamp>1997-06-11T19:00:00Z</dtstamp>
<summary>ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES</summary>
<uid>4785a496-9200-43f7-ba32-53c58e03ba37</uid>
<valarm>
<trigger value='date-time'>1997-03-17T13:30:00Z</trigger>
<repeat>4</repeat>
<duration>PT15M</duration>
<action>audio</action>
<attach fmttype='audio/basic'>ftp://host.com/pub/sounds/bell-01.aud</attach>
</valarm>
</vevent>
</vcalendar>
</item>
</publish>
</pubsub>
</iq>
]]></example>
</section2>
<!-- == Subscribing to Alarm Notifications =============================== -->
<section2 topic='Subscribing to Alarm Notifications' anchor='alarm-subscribe'>
<p>When an entity wishes to subscribe to a calendar node, it sends a subscription request to the calendar service using the &lt;subscribe/&gt; element described in section 6.1 of <cite>XEP-0060</cite>. To subscribe to alarm notifications, an entity MAY configure its subscription to have the "&SN;#notify_alarm" configuration option set to "true". The entity MAY subscribe and provide the subscription options in the same stanza (as described in 6.3.7 of <cite>XEP-0060</cite>), or configure the subscription at any time after subscribing (as described in section 6.3 of <cite>XEP-0060</cite>).</p>
<example caption='Entity subscribes to node and sets configuration options'><![CDATA[
<iq type='set'
from='francisco@denmark.lit/barracks'
to='pubsub.shakespeare.lit'
id='sub1'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<subscribe node='princely_musings' jid='francisco@denmark.lit'/>
<options>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>http://jabber.org/protocol/pubsub#subscribe_options</value>
</field>
<field var='pubsub#deliver'><value>1</value></field>
<field var='pubsub#digest'><value>0</value></field>
<field var='pubsub#include_body'><value>false</value></field>
<field var='calendar#notify_alarm'><value>true</value></field>
</x>
</options>
</pubsub>
</iq>
]]></example>
</section2>
<!-- == Receiving Alarm Notifications ==================================== -->
<section2 topic='Receiving Alarm Notifications' anchor='alarm-notify'>
<p>When an alarm is triggered, the calendar service MUST send one &MESSAGE; stanza containing a alarm notification to each entity that meets the criteria for receiving a alarm notification (typically to each approved subscriber who configured its subscription to have the "calendar#notify_alarm" configuration option set to "true"). Depending on the node configuration, the alarm notification either will or will not contain the payload, as shown below.</p>
<section3 topic='Notification With Payload' anchor='alarm-notify-withpayload'>
<p>If the node is configured to include payloads, the subscribers will receive payloads with the alarm notifications.</p>
<example caption='Subscribers receive alarm notifications with payloads'><![CDATA[
<message from='calendar.shakespeare.lit'
to='romeo@montague.net/orchard'
id='alarm1'>
<alarm xmlns='xmpp:tmp:calendar:0'>
<items node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<item id='4785a496-9200-43f7-ba32-53c58e03ba37'>
<vcalendar xmlns='urn:ietf:params:xml:ns:xcal'>
<prodid>-//ACME/DesktopCalendar//EN</prodid>
<version>2.0</version>
<vevent>
<organizer>xmpp:romeo@montague.net</organizer>
<dtstart>1997-07-01T20:00:00Z</dtstart>
<dtstamp>1997-06-11T19:00:00Z</dtstamp>
<summary>ST. PAUL SAINTS -VS- DULUTH-SUPERIOR DUKES</summary>
<uid>4785a496-9200-43f7-ba32-53c58e03ba37</uid>
<valarm>
<trigger value='date-time'>1997-03-17T13:30:00Z</trigger>
<repeat>4</repeat>
<duration>PT15M</duration>
<action>audio</action>
<attach fmttype='audio/basic'>ftp://host.com/pub/sounds/bell-01.aud</attach>
</valarm>
</vevent>
</vcalendar>
</item>
</items>
</alarm>
</message>
]]></example>
</section3>
<section3 topic='Notification Without Payload' anchor='alarm-notify-withoutpayload'>
<p>If the node is configured to not include payloads, the subscribers will receive alarm notifications only. (If payloads are not included, subscribers may request the calendar item via the protocol defined in the <link url='#retrieve'>Retrieving Calendar Entries</link> section of this document.)</p>
<example caption='Subscribers receive alarm notifications only'><![CDATA[
<message from='calendar.shakespeare.lit'
to='romeo@montague.net/orchard'
id='alarm2'>
<alarm xmlns='xmpp:tmp:calendar:0'>
<items node='ccfc0b59-b9d9-4d0f-ac2f-829e7077640e'>
<item id='4785a496-9200-43f7-ba32-53c58e03ba37' />
</items>
</alarm>
</message>
]]></example>
</section3>
</section2>
</section1>
<section1 topic='Examples' anchor='examples'>
<section2 topic='Published Event Examples' anchor='examples-event'>
<p>&TODO;</p>
<section3 topic='A Minimal Published Event'></section3>
<section3 topic='Changing A Published Event'></section3>
<section3 topic='Canceling A Published Event'></section3>
<!-- <section3 topic='A Rich Published Event'></section3> -->
<!-- <section3 topic='Anniversaries or Events attached to entire days'></section3> -->
<section3 topic='Retrieval of Events Only'></section3>
<section3 topic='Partial Retrieval of Events by Time Range'></section3>
<section3 topic='Retrieval of Event by UID'></section3>
</section2>
<section2 topic='Group Event Examples' anchor='examples-groupevent'>
<p>&TODO;</p>
<section3 topic='A Group Event Request'></section3>
<section3 topic='Reply To A Group Event Request'></section3>
<section3 topic='Update An Event'></section3>
<section3 topic='Countering an Event Proposal'></section3>
<section3 topic='Delegating an Event'></section3>
<section3 topic='Delegate Accepts the Meeting'></section3>
<section3 topic='Delegate Declines the Meeting'></section3>
<section3 topic='Forwarding an Event Request'></section3>
<section3 topic='Cancel A Group Event'></section3>
<section3 topic='Removing Attendees'></section3>
<section3 topic='Replacing the Organizer'></section3>
<section3 topic='Retrieval of Events by PARTSTAT'></section3>
</section2>
<section2 topic='Busy Time Examples' anchor='examples-freebusy'>
<p>&TODO;</p>
<!-- <section3 topic='Request Busy Time'></section3> -->
<!-- <section3 topic='Reply To A Busy Time Request'></section3> -->
<section3 topic='Partial Retrieval of Stored Free Busy Components'></section3>
<section3 topic='Retrieval of Free/Busy Time Information'></section3>
</section2>
<section2 topic='Recurring Event and Time Zone Examples' anchor='examples-recurringevent'>
<p>&TODO;</p>
<section3 topic='A Recurring Event Spanning Time Zones'></section3>
<section3 topic='Modify A Recurring Instance'></section3>
<section3 topic='Cancel an Instance'></section3>
<section3 topic='Cancel Recurring Event'></section3>
<section3 topic='Change All Future Instances'></section3>
<section3 topic='Add A New Instance To A Recurring Event'></section3>
<section3 topic='Add A New Series of Instances To A Recurring Event'></section3>
<section3 topic='Counter An Instance Of A Recurring Event'></section3>
<!-- <section3 topic='Error Reply To A Request'></section3> -->
<section3 topic='Partial Retrieval of Recurring Events'></section3>
<section3 topic='Expanded Retrieval of Recurring Events'></section3>
</section2>
<section2 topic='Group To-Do Examples' anchor='examples-grouptodo'>
<p>&TODO;</p>
<section3 topic='A To-Do Request'></section3>
<section3 topic='Reply to a To-Do Request'></section3>
<section3 topic='A To-Do Request for Updated Status'></section3>
<section3 topic='A Reply: Percent-Complete'></section3>
<section3 topic='A Reply: Completed'></section3>
<section3 topic='An Updated To-Do Request'></section3>
<section3 topic='Recurring To-Dos'>
<section4 topic='Request for a Recurring To-Do'></section4>
<section4 topic='Calculating due dates in recurring To-Dos'></section4>
<section4 topic='Replying to an instance of a recurring To-Do'></section4>
</section3>
<section3 topic='Retrieval of To-Dos by Alarm Time Range'></section3>
<section3 topic='Retrieval of All Pending To-Dos'></section3>
</section2>
<section2 topic='Journal Examples' anchor='examples-journal'>
<p>&TODO;</p>
</section2>
<section2 topic='Notification Examples' anchor='examples-notification'>
<p>&TODO;</p>
</section2>
</section1>
<section1 topic='Implementation Notes' anchor='impl'>
<p>&TODO;</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>This document introduces no additional security considerations above or beyond those defined in the documents on which it depends.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>This document does not require interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespaces:</p>
<ul>
<li>&NS;</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespaces to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>
<section2 topic='Namespace Versioning' anchor='registrar-versioning'>
<p>If the protocol defined in this specification undergoes a major revision that is not fully backward-compatible with an older version, or that contains significant new features, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of <cite>XEP-0053</cite>.</p>
</section2>
<section2 topic='Service Discovery Features' anchor='registrar-features'>
<p>&TODO;</p>
</section2>
<section2 topic='Field Standardization' anchor='registrar-formtypes'>
<p>&TODO;</p>
</section2>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='xmpp:tmp:calendar:0'
xmlns='xmpp:tmp:calendar:0'
elementFormDefault='qualified'>
<xs:annotation>
<xs:documentation>
The protocol documented by this schema is defined in
XEP-xxxx: http://www.xmpp.org/extensions/xep-xxxx.html
</xs:documentation>
</xs:annotation>
<xs:element name='alarm'>
<xs:complexType>
<xs:choice minOccurs='0'>
<xs:element ref='items'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name='items'>
<xs:complexType>
<xs:choice>
<xs:element ref='item' minOccurs='0' maxOccurs='unbounded'/>
</xs:choice>
<xs:attribute name='node' type='xs:string' use='required'/>
</xs:complexType>
</xs:element>
<xs:element name='item'>
<xs:complexType>
<xs:choice minOccurs='0'>
<xs:any namespace='##other'/>
</xs:choice>
<xs:attribute name='id' type='xs:string' use='optional'/>
</xs:complexType>
</xs:element>
</xs:schema>
]]></code>
</section1>
</xep>
Reference in New Issue Copy Permalink