Subject: [CALSCH] draft-royer-dyn-query-00.txt

From: Doug Royer <[email-masked]>
Date: Sun, 21 Dec 2003 16:53:11 -0700

(attached)

-- 

Doug Royer                     |   http://INET-Consulting.com
-------------------------------|-----------------------------
[email-masked]                 | Office: (208)520-4044
http://Royer.com/People/Doug   |    Fax: (866)594-8574
                               |   Cell: (208)520-4044

               We Do Standards - You Need Standards

   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: [email-masked]
      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]