Application Working Group Doug Royer/INET-Consulting LLC Internet Draft December 21, 2003 Expires: May 2004 Variables in Dynamic Queries for iCalendar draft-royer-dyn-query-00.txt 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. This Internet-Draft will expire May 2004. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. ABSTRACT This is a proposal to allow iCalendar dynamic query the ability to be passed down optional values to be used stored queries. 1. New parameters [CAP] allows for stored queries. Using the existing stored queries (VQUERY) as defined in [CAP], this describes a standard way to pass down variables to those queries. 1.1 DT-RANGE Parameter Name: DT-RANGE Purpose: This property specifies a period of time for which the query Royer Expires: May 2004 [Page 1] Internet Draft iCal Dynamic Query Variables December 21, 2003 should apply. Value Type: PERIOD Format Definition: The property is defined by the following notation: dt-range = "DT-RANGE" "=" period Examples: QUERYID;DT-RANGE="19971015T050000Z/PT8H30M":GET-OBJECTS QUERYID;DT-RANGE="19980314T233000Z/19980315T003000Z":GET-OBJECTS 1.2 MAX-OCTETS The "MAX-OCTETS" parameter is added to the "QUERYID" property value to signify the maximum number of octets to be returned in the query. The CS will trim the returned valued down so that only complete objects will be sent. Each time that "MAX-OCTETS" is supplied it sets the default for that named "QUERYID" for the current session only and the results set back will be the first (0th) set. Use the "GET-SET" parameter to get sets greater then zero. Parameter Name: MAX-OCTETS Purpose: The property indicates the largest reply size allowed for this query by the CUA. If supplied the first reply always get the first set of components that fit within the limit. See the "GET-SET" parameter for information on how to get the following sets of components. Value Type: INTEGER Format Definition: The property is defined by the following notation: max-octets = "MAX-OCTETS" "=" integer Example: QUERYID;MAX-OCTETS=10240:GET-OBJECTS 1.3 GET-SET The "GET-SET" parameter is added to the "QUERYID" property value request the next set of components be returned for the last query performed with the same name. Supplied is the set number to be fetched. The set Royer Expires: May 2004 [Page 2] Internet Draft iCal Dynamic Query Variables December 21, 2003 numbers start with zero. The original query must have suppled a "MAX- OCTETS" parameter and value. Parameter Name: GET-SET Purpose: Added by the CUA to inform the CS to return the next set of components to the CUA. The first set is ZERO and continues up until no more data is returned (See the "SETS" parameter). Requesting a set larger than the number of sets available will return a "VREPLY" with a "REQUEST-STATUS" value of "3.15" invalid set number. Value Type: INTEGER Format Definition: The property is defined by the following notation: get-set = "GET-SET" "=" integer The following example gets the 15th set of components that match the QUERYID;GET-SET=15:GET-OBJECTS 1.4 SETS The "SETS" parameter MUST BE added to the "REQUEST-STATUS" property in a "VREPLY" that is the result of a "VQUERY" that had the "MAX-OCTETS" parameter added to the "QUERYID" property. It specifies the current and maximum set numbers available. Parameter Name: SETS Purpose: Added by the CS to inform the CUA that of the current and maximum number of sets of data available. Value Type: INTEGER multivalued. Format Definition: The property is defined by the following notation: sets = "SETS" "=" current-set "," max-set current-set = integer max-set = integer The following example tells the CUA that set '4' of '20' is being returned. Royer Expires: May 2004 [Page 3] Internet Draft iCal Dynamic Query Variables December 21, 2003 REQUEST-STATUS;SETS=4,20:2.0;Success And an example of an error: REQUEST-STATUS;SETS=4,20:3.15;Invalid set number. 1.5 GET-COMP The "GET-COMP" parameter is added to the "QUERYID" property value to signify the component types to be returned in the query. Parameter Name: GET-COMP Purpose: Added by the CUA to inform the CS the component types to be returned in the query. Value Type: text multivalued. Format Definition: The property is defined by the following notation: get-comp = "GET-COMP" "=" comp-name *["," comp-name ] comp-name = ; any valid component name including ; x- components. The following example tells the CS only to return "VEVENT" and "VTODO" components. QUERYID;GET-COMP=VEVENT,VTODO=10240:GET-OBJECTS 1.6 Bibliography [iCAL] Dawson, F. and Stenerson, D., "Internet Calendaring and Scheduling Core Object Specification (iCalendar)", RFC 2445, November 1998 ftp://ftp.isi.edu/in-notes/rfc2445.txt [iTIP] Silverberg, S., Mansour, S., Dawson, F. and Hopson, R., "iCalendar Transport-Independent Interoperability Protocol (iTIP) Events, BusyTime, To-dos and Journal Entries", RFC 2446, November 1998 ftp://ftp.isi.edu/in-notes/rfc2446.txt [iMIP] Dawson, F., Mansour, S. and Silverberg, "iCalendar Message-Based Interoperability Protocol (iMIP)", RFC 2447, November 1998 ftp://ftp.isi.edu/in-notes/rfc2447.txt Royer Expires: May 2004 [Page 4] Internet Draft iCal Dynamic Query Variables December 21, 2003 [CAP] Royer, D., Babics, G., Hill, P. Mansour, S. "Calendar Access Protocol (CAP)", work in progress, draft-ietf-calsch-cap-12.txt 2. Author's Address Doug Royer http://INET-Consulting.com 1795 W. Broadway #266 Idaho Falls, Idaho 83402 US Phone: 208-520-4044 Fax: 866-594-8574 EMail: Doug@Royer.com URI: http://Royer.com/People/Doug Royer Expires: May 2004 [Page 5] Internet Draft iCal Dynamic Query Variables December 21, 2003 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on the IETF's procedures with respect to rights in standards-track and standards-related documentation can be found in BCP-11. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification can be obtained from the IETF Secretariat. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to practice this standard. Please address the information to the IETF Executive Director. Full Copyright Statement Copyright (C) The Internet Society (2003). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than nglish. The limited permissions granted above are perpetual and will not be revoked by the Internet Society or its successors or assignees. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgment Royer Expires: May 2004 [Page 6] Internet Draft iCal Dynamic Query Variables December 21, 2003 Funding for the RFC Editor function is currently provided by the Internet Society. Royer Expires: May 2004 [Page 7]