Subject: Proposed changed GET-CAPABILITY Command

From: [email-masked]
Date: Mon, 24 Feb 2003 13:06:04 -0500

A while back there was some WG discussion about the GET-CAPABILITY command 
and whether or not there should be defaulting or not and if the command 
should be required of all sides of the CAP protocol.  There seemed to be 
general agreement about some changes but no proposed change text.  I have 
taken the task of making the change text as I was the one who proposed 
much of the changes. 

Currently the GET-CAPABILITY command is proposed to be required of all CSs 
and optional of all CUAs.  However this is not a good design as a basis 
for CAP 1.0 and it does not factor in that we may eventually have CS <-> 
CS CAP where there is no CUA involved in the work (although one side may 
view the other as a CUA but thats not equivalent).  In addition, if some 
component values are not in the response for the command they are assumed 
defaulted.  This too is not a good design as defaults may change from CAP 
version to CAP version and thus incorrect assumptions could be made.

To avoid confusion and future interoperability problems I am proposing we 
change GET-CAPAIBLITY to the the text below.  I changed mainly the lead in 
text but I also made changes to the ABNF (to be consistant w/the rest of 
CAP and to the descriptions of the returned properties).

I did rework the ABNF to be more consistant and to have some more accurate 
comments.  I also removed PRODID and VERSION from the list of properties 
in the cap-vreply since its already specified in the cap-reply container 
and are therefore superfluous.

I changed the reference from "SQL support" to "CAP-QL support" since Im 
sure it was just a Freudian slip on someones part.

It was not dissucssed in the WG if we truely need to have bounded latency 
on GET-CAPABILITY or not.  Nor did we discuss the need to name the 
GET-CAPABILITY command.  If we remove bounded latency from GET-CAPAIBLITY 
then we can remove the id-param too from the capablitiyparam ABNF.

I did add IANA-PROP and X-PROP to the table since they actually make up 
the other-prop in the ABNF but have separate meanings.

Here is  my proposed revised version of the the GET-CAPAIBLITY command:

[I see that Doug put out a new draft but this is based on the 10Jan2003 
draft since that was what I started with (and this got filed in my Drafts 
folder instead of being sent over a week ago).  The vast majority should 
map just fine if you change the section number accordingly.]

======================================
10.3. GET-CAPABILITY Command 
CMD: GET-CAPABILITY 

Purpose: The "GET-CAPABILITY" command returns the capabilities of the 
other end point of the session. 

All CAP implemenations MUST support the "GET-CAPABLITY" command. 
Furthermore, the "GET-CAPABLITY" command SHOULD be issued early in the CAP 
session to properly detect restrictions or abilities of the other end 
point.

A CUA MUST send a "GET-CAPABILITY" command to a CS after the initial 
connection.  Another "GET-CAPABILITY" command subsequent to successful 
authentiation MAY be useful in case the CS alters the options allowed 
based on the authentication credentials provided.

The CS MUST send a "GET-CAPABILITY" command to a CUA after the initial 
connection.  Multiple "GET-CAPABILITY" commands to the CUA SHOULD NOT be 
necessary.

Formal Definition: A "GET-CAPABILITY" command is defined by the following 
notation: 

get-capability-cmd   = capibiltyparam ":" "GET-CAPABILITY"

capibiltyparam     = *(
                   ; The following are optional,
                   ; but MUST NOT occur more than once
                   ;
                   id-param / 
                   localize-param / 
                   latency-param /

                   ; The following MUST occur exactly once and only
                   ; when the latency-param has been supplied and
                   ; MUST NOT be supplied if the latency-param is
                   ; not supplied.
                   ;
                   action-param /

                   ; the following is optional,
                   ; and MAY occur more than once
                   ;
                   other-params
                   )

Response:

The "GET-CAPABILITY" command returns information about the other end of 
the session given the current state of the connection. The 
"GET-CAPABILITY" reply may return different results depending on the UPN 
and if the UPN is authenticated. 

Client implementations SHOULD NOT require any capability element beyond 
those defined in this specification, and MAY ignore any nonstandard, 
experimental capability elements. 

When sending a reply to a "GET-CAPABILITY" command, all of the properties 
below MUST BE supplied. All implementations MUST always send the full 
reply when queried.  Properties or property values MUST NOT be defaulted 
or assumed by either end point.  If the queried sided does not indicate a 
value or setting then it MAY NOT be defaulted; it is simply unavailable.

The following properties are returned in response to a "GET-CAPABILITY" 
command: 

cap-reply   = "BEGIN" ":" "VCALENDAR" CRLF
                  ; All properties may be in any order.
                  ;
                  ; The following are optional,
                  ; but MUST NOT occur more than once
                  ;
                  prodid /
                  version /

                  ; The following are optional,
                  ; but MAY occur more than once
                  ;

                  other-props /

                  ; The following are required and
                  ; MUST occur only once
                  ;

                  cap-vreply
                 "END" ":" "VCALENDAR" CRLF

cap-vreply     = "BEGIN" ":" "VREPLY" CRLF
                  ; All properties may be in any order.
                  ;
                  ; The following MUST occur only once
                  ;
                  cap-version /
                  car-level /
                  components /
                  stores-expanded /
                  maxdate /
                  mindate /
                  itip-version /
                  max-comp-size /
                  multipart /
                  query-level /
                  recur-accepted /
                  recur-expand /
                  recur-limit /

                  ; The following MAY occur more than once
                  ;
                  other-props
                  "END" ":" "VREPLY" CRLF

Name            Occurs  Description
 
------------------------------------------------------------------
  CAP-VERSION        1     Version of CAP. It MUST include at least "XX"
                           (NOTE 'XX' WILL BE REPLACED WITH THE RFC NUMBER
                           OF THIS DOCUMENT) for this version of CAP. This
                           is a multiple value property with values
                           separated with commas (,).  All values MUST be
                           positive integer values.

  CAR-LEVEL          1     Indicates level of CAR support. This version
                           of CAP defines the following possible values:
                           "CAR-NONE", "CAR-MIN" and "CAR-FULL-1". If 
                           "CAR-FULL-1" is supplied then "CAR-MIN" MUST BE 

                           assumed.  A "CAR-MIN" implementation only 
supports
                           the DEFAULT-VCARS listed in the VCALSTORE
                           and does not support the creation or
                           modification of VCARS.

   COMPONENTS        1     A comma separated list of the names of
                           components that are supported. This
                           includes any components inside of other 
components 
                           (ie: VALARMs).  For this version of CAP the 
list
                           MUST include at least "VCALSTORE", "VCALENDAR", 

                           "VREPLY", "VAGENDA" and at least one of 
"VEVENT",
                           "VTODO", "VJOURNAL" or "VTIMEZONE".  This 
version of
                           CAP defines the following possible values:
                           "VCALSTORE", "VCALENDAR", "VREPLY", "VAGENDA",
                           "VEVENT", "VJOURNAL", "VTODO", "VALARM",
                           "VTIMEZONE", "DAYLIGHT" and "STANDARD"

   STORES-EXPANDED    1    A boolean value of either "TRUE" or "FALSE".
                           If TRUE then it expands multiple instances
                           separately when they are stored (RRULEs
                           converted to RDATEs) and when sent. If
                           FALSE then it expands instances dynamically
                           during sending.

   MAXDATE            1    The datetime value in UTC beyond which the
                           end point cannot accept. The maximum value 
                           allowed is 99991231T235959Z.

   MINDATE          1      The datetime value in UTC prior to which
                           the end point cannot accept. The minimum value 
                           allowed is 00000101T000000Z.

   ITIP-VERSION      1     A comma separated list of the version(s) of 
                           ITIP supported.  The list MUST include at least 

                           the value of "2446"  to specify RFC-2446 
support.

   MAX-COMPONENT-SIZE
                     1     A non-negative integer value that specifies
                           the size of the largest iCalendar object
                           that can be accepted in octets.  Objects
                           larger than this will be rejected. A
                           value of zero (0) means no limit.
                           This is also the maximum value of any [BEEP]
                           payload that will be accepted or sent.

   MULTIPART         1     A comma separated list of lower cased MIME 
                           multipart subtypes that the sender supports.
                           If multipart is not supported then the property
                           has no value (ie: an empty list). Example: 
                           MULTIPART:related,alternate

   QUERY-LEVEL       1     Indicates level of CAP-QL support. This version 
of
                           CAP defines the following possible values:
                           "CAL-QL-1" and "CAL-QL-NONE".  "CAL-QL-NONE" is 

                           for end points that allow ITIP methods only to 
                           be deposited and nothing else.
 
   RECUR-ACCEPTED    1     A boolean value to indicate whether recurrence 
                           rules are acceptable.

   RECUR-EXPAND      1     A boolean value to indicate whether or not the
                           end point supports the expansion of recurrence 
rules.

   RECUR-LIMIT       1     A non-negative integer value that indicates the 
maximum 
                           number of occurrences of a recurrence rule that 
are expanded.
                           A value of zero (0) means unlimited.

   RECUR-ACCEPTED    1     A boolean value to indicate whether recurrence 
                           rules are acceptable.

   IANA-PROPS        0+    Zero or more IANA defined properties. 

   X-PROPS           0+    Zero or more experimental properties supported 
by 
                           a particular implementation. 

   -------------------------------------------------------

   Example:

   I: Content-Type: text/calendar
   I:
   I: BEGIN:VCALENDAR
   I: VERSION:2.0
   I: PRODID:-//someone's prodid
   I: CMD;ID=unique-per-cua-125:GET-CAPABILITY
   I: END:VCALENDAR

   L: Content-Type: text/calendar
   L:
   L: BEGIN:VCALENDAR
   L: VERSION:2.0
   L: PRODID:-//someone's prodid
   L: CMD;ID=unique-per-cua-125:REPLY
   L: BEGIN:VREPLY
   L: CAP-VERSION:1.0
   L: PRODID:The CS prodid
   L: QUERY-LEVEL:CAL-QL-1
   L: CAR-LEVEL:CAR-FULL-1
   L: MAXDATE:99991231T235959Z
   L: MINDATE:00000101T000000Z
   L: MAX-COMPONENT-SIZE:0
   L: COMPONENTS:VCALENDAR,VTODO,VJOURNAL,VEVENT,VCAR,
   L:  VALARM,VFREEBUSY,VTIMEZONE,STANDARD,DAYLIGHT,VREPLY
   L: ITIP-VERSION:2447
   L: RECUR-ACCEPTED:TRUE
   L: RECUR-EXPAND:TRUE
   L: RECUR-LIMIT:0
   L: STORES-EXPANDED:FALSE
   L: X-INET-PRIVATE-COMMANDS:1.0
   L: END:VREPLY
   L: END:VCALENDAR

===========================================

The big changes in my proposal were already covered in the WG, I just put 
some prose to the changes (mainly the text under "Purpose") but I did make 
some minor changes to the rest as I already noted in the text above.

I would like to propose that we remove bounded latency from GET-CAPAIBLITY 
for 2 reasons:

1: It should not require any great number of cycles for any implementation 
to actually implement and perform compared to most other commands.
2: It needs to be done before any other commands are done and once done 
does not need to be performed again (after authentication that is).

As such we can simplify the command a bit by removing the latency related 
properties and trimming down the example above.  After all, its somewhat 
foolhearty to NOT wait for this relatively quick command to complete 
before doing other commands like C&S workflow...

Comments?

Bruce
===========================================================================
Bruce Kahn                                INet: 
[email-masked]
Messaging & Collaboration                 Phone: 978.399.6496
IBM Software Group                         FAX: and nothing but the FAX...
Standard disclaimers apply, even where prohibited by law...

---

From: Doug Royer <[email-masked]>
Date: Mon, 24 Feb 2003 11:58:19 -0700

[email-masked] wrote:
> 
> A while back there was some WG discussion about the GET-CAPABILITY 
> command and whether or not there should be defaulting or not and if the 
> command should be required of all sides of the CAP protocol.

yes - I think we did agree - I simply forgot it.

> The big changes in my proposal were already covered in the WG, I just 
> put some prose to the changes (mainly the text under "Purpose") but I 
> did make some minor changes to the rest as I already noted in the text 
> above.
> 
> I would like to propose that we remove bounded latency from 
> GET-CAPAIBLITY for 2 reasons:
> 
> 1: It should not require any great number of cycles for any 
> implementation to actually implement and perform compared to most other 
> commands.

I don't follow (not that I agree or disagree).

> does not need to be performed again (after authentication that is).

Not true it says (And has said for a while):

10.3 ...

    The "GET-CAPABILITY" command returns information about the Calendar
    other end of the session given the current state of the connection.
    The values returned may differ depending on current user identify and
    the security level of the connection.

So the values reutured AFTER authentication and INDENTIFY might
be more or less restrictive than before authentication and change
of identity.

-- 

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

                 We Do Standards - You Need Standards

---

From: Andrea Campi <[email-masked]>
Date: Tue, 25 Feb 2003 11:07:54 +0100

> taken the task of making the change text as I was the one who proposed 

Thanks for doing this, and I like your proposed text in general. I do have
a couple minor notes.

> session to properly detect restrictions or abilities of the other end 

OK.

> based on the authentication credentials provided.

I'm not sure I follow you here. We don't have a CAP (application-layer)
authentication phase, rather, we rely on SASL as mandated by BEEP. So
basically this means, when a channel is established and the peers are
able to exchange commands, authentication has already occurred in all
cases (even if the peer is anonymous).
You are thinking of INDENTIFY, right? so the sentence above is still
relevant but should probably be reworded as:

  A CUA MUST send a "GET-CAPABILITY" command to a CS after the initial 
  connection.  Another "GET-CAPABILITY" command subsequent to a change of
  credentials MAY be useful in case the CS alters the options allowed 
  based on the authorization credentials provided. This may happen when
  an IDENTIFY command is sent.

> connection.  Multiple "GET-CAPABILITY" commands to the CUA SHOULD NOT be 

Now that I look at this more closely: you still explicitely identify
exchanges as going from the CUA to the CS or from the CS to the CUA. Is
this right? I thought what you had in mind was more like:

  A CUA MUST send a "GET-CAPABILITY" command after the initial  ...

  The CS MUST send a "GET-CAPABILITY" command after the initial 

>                            MULTIPART:related,alternate

How would an empty list appear?

MULTIPART:

Is this even allowed by the ABNF? Should we use an explicit `none' instead?

>    RECUR-ACCEPTED    1     A boolean value to indicate whether recurrence 
[...]
>    RECUR-ACCEPTED    1     A boolean value to indicate whether recurrence 

You have this twice.

> before doing other commands like C&S workflow...

I absolutely agree.

Bye,
	Andrea

-- 
Andrea Campi                              mailto:[email-masked]
I.NET S.p.A. - BT Ignite                  http://www.inet.it
Technical Dept. - R&D			  phone: +39 02 32863 ext 1
v. Darwin, 85 - I-20019			  fax: +39 02 32863 ext 7705
Settimo Milanese (MI), Italy

---

From: Doug Royer <[email-masked]>
Date: Tue, 25 Feb 2003 09:22:42 -0700

> command should be required of all sides of the CAP protocol.  There 
> seemed to be general agreement about some changes but no proposed change 
> text.  I have taken the task of making the change text as I was the one 
> who proposed much of the changes.  

The 'cap-17-FEB-2003' version already has them as mandatory:

    A CUA MUST send a "GET-CAPABILITY" command to a CS after the initial
    connection.  The "GET-CAPABILITY" command and reply MUST BE
    implemented by all CSs and CUAs.

I went to edit the draft and noticed that I had in fact already
done that. Is what I have not done is removed the word 'default'
and it associated text from some of the properties descriptions.
	
--

---

From: [email-masked]
Date: Fri, 28 Feb 2003 14:51:35 -0500

> I don't follow (not that I agree or disagree).

The text as of the Jan-2003 draft was that it was optional for CUAs to 
implement and the argument by some was that it was for performance 
reasons. 

The GET-CAPABILITY command should be very quick to perform compared to 
something like the SEARCH command or GENERATE-UIDs.  The command should 
not take tons of time to perform either so bounded latency should not be 
an issue here.  In the interest of simplifying the command I suggested 
that we remove bounded latency from it as well.

> be more or less restrictive than before authentication and change

That citation does NOT require or strongly suggest that GET-CAPABILITY be 
performed both before and certainly after authentication.   Nor does it 
say that GET-CAPABILITY SHOULD be performed before other commands like 
DELETE or SEARCH. 

I was trying to tighten up the design so that it really SHOULD be done 
before ANY other commands (except perhaps IDENTIFY).  The real changes 
though were to the lead in text of the command and so far I dont see any 
complaints about that (since we already all agreed in principal to them).

Bruce

---

From: [email-masked]
Date: Fri, 28 Feb 2003 15:29:51 -0500

>   an IDENTIFY command is sent.

I used that text pretty much as is from the Jan 2003 draft but I did 
juggle some bits from later in the section.  I combined:

connection. 

and the bit under "Response" that says:

The "GET-CAPABILITY" command returns information about the Calendar other 
end of the session given the current state of the connection. The values 
returned may differ depending on current user identify and the security 
level of the connection. 

into the block you questioned.   Since there is no credentials on the 
intiail connection Im not sure your phrasing is accurate. 

However I think we all agree on the intent: the values returned in 
response to GET-CAPABILITIY MAY change based on the "authentication 
credentials" (See Section 4.1. Calendar User and UPNs of the 12-Jan-2003 
draft) in effect when the command is issued.  I leave it to Dougs 
wordsmithing skills to hone this text as necessary (assuming its not 
already covered in the latest 17-Feb-2003 draft).

>   The CS MUST send a "GET-CAPABILITY" command after the initial 

Mea culpa.  I did not change all references and remove them.  I did this 
because A) we do not yet have the context of CS<->CS over CAP (at least 
the WG isnt focused on it) and B) in the current CUA<->CS context we have 
no way to distinguish a CUA from a CS on an end point.  As such I couldn't 
easily remove all references to CUA or CS in the lead in "Purpose" area. I 
did however clean it from the response property blocks.

> Is this even allowed by the ABNF? Should we use an explicit `none' 
instead?

I only changed this bit very minorly from the original:

   MULTIPART         1     A comma separated list of MIME multipart
                           the sender supports in lower case. The
                           default is no multipart support (empty
                           list). Example: MULTIPART:related,alternate

to be consistant w/my other prose format.  If you look at the ABNF for 
2445, you will see that an empty value is 100% legal for type text (which 
is what the comma separated list is here):

     text       = *(TSAFE-CHAR / ":" / DQUOTE / ESCAPED-CHAR)

The * Rule is defined in RFC 2234 as:

3.6  Variable Repetition                                *Rule

   The operator "*" preceding an element indicates repetition. The full
   form is:

        <a>*<b>element

   where <a> and <b> are optional decimal values, indicating at least
   <a> and at most <b> occurrences of element.

   Default values are 0 and infinity so that *<element> allows any
   number, including zero; 1*<element> requires at  least  one;
   3*3<element> allows exactly 3 and 1*2<element> allows one or two.

Therefore any property of type TEXT can have an empty value legally.  Your 
MULTIPART example is therefore accurate.  By the way, this is how you can 
get NULL properties as described in the iTIP restriction tables ("Can be 
NULL").

> >    RECUR-ACCEPTED    1     A boolean value to indicate whether 
recurrence 

Sorry, it was that way in the original 12Jan2003 draft and I didnt notice 
it.

Bruce