Subject: Re: My proposal for STORE/FETCH/CREATE/DELETE/...

From: "Frank Dawson" <[email-masked]>
Date: Mon, 28 Sep 1998 09:13:19 -0400

Doug:

I think that the BEGIN:ACL, BEGIN:CALENDAR-PROPERTY, etc should be contained
within the BEGIN:/END:COMMAND component. Otherwise, you don't know what the
scope is, do you? After all, you should be able to group more than one
BEGIN:/END:COMMAND within one BEGIN:/END:VCALENDAR outter container.

- - Frank Dawson

---

From: "Alec Dun (Exchange)" <[email-masked]>
Date: Mon, 28 Sep 1998 14:34:27 -0700

Doug,

I'm kinda confused.  Is this a list of requirements? or a proposal for the
names of the verbs in the protocol?

If it is a requirements list, we should stick to the operations that we want
to perform rather than try to name the verbs, ie. we all agree that we
should be able to create, retrieve, delete appointments, etc.  Getting
closure on that seems pretty important.

Thanks,
Alec.

-----Original Message-----
From: Doug Royer [N6AAW] [mailto:[email-masked]]
Sent: Wednesday, September 23, 1998 7:15 PM
To: [email-masked]
Subject: My proposal for STORE/FETCH/CREATE/DELETE/...

Keep in mind that this may have some errors. Its simply my proposal
not a WG-draft. I ran out of time to document it all and I wanted
to get it out soon. I have spend time thinking it through, more
late next week.

This email describes my thoughts on how to issues commands over
the wire using iCalendar-ish containers.

I see it as a benefit over protocol specific/non-iCalendar-ish proposals.

	*** It can be transported over iMIP and iTIP.
	
	*** It can be designed and operated with almost no regard to
	    the transport used.

(notification and callbacks in separate email)

The idea is that the existing iTIP work could be leveraged by
adding a new component "COMMAND". This email describes my
proposal for the component.

1.0) "COMMAND" component.
This email discusses my ideas for the "COMMAND" component.
It would be used only within "REQUEST" and "REPLY" "METHOD"s.

Each "COMMAND" component requires an "OPERATION" property.

The "OPERATION"s are:

	(1) "CREATE"	Create - Calendar, Sub-Calendar

	(2) "DELETE"	Delete - Calendar, Sub-Calendar, ACL, properties.

	(3) "FETCH"	ACLs, Calendar Names, Capability, Contains search,
			Properties, entries.

	(4) "STORE"	ACLs, Capability, Properties, entries.
	
	(5) "REPLY"	Success and failure replies.

1.1) "CREATE" - Create a new calendar store.

1.1.1) Create a top level calendar.
User must have ability to create a new top level calendar. 
Authenticated user needs the "CREATE=CALENDAR" ACL.

For each calendar named in the "COMMAND", creates the
named top level calendar.

If an "ACL" component is also supplied, then each calendar will be
created with the ACLs as supplied in the "ACL" component.

If an "CALENDAR-PROPERTY" component is also supplied, then each calendar
will be created with the properties as supplied in the "CALENDAR-PROPERTY"
component.

Example:

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION:CREATE
	CALENDAR-NAME:County Governments
	CALENDAR-NAME:Office of Emergency Services
	END:COMMAND
	...
	BEGIN:CALENDAR-PROPERTY
	CALENDAR-LANGUAGE:en_us
	INHERITANCE:ACL=NO;PROPERTY=YES
	BEGIN:VTIMEZONE
	TZID:US/Pacific
	BEGIN:STANDARD
	DTSTART:19981025T020000
	RDATE:19981025T020000
	TZOFFSETFROM:-0700
	TZOFFSETTO:-0800
	TZNAME:EST
	END:STANDARD
	BEGIN:DAYLIGHT
	DTSTART:19990404T020000
	RDATE:19990404T020000
	TZOFFSETFROM:-0800
	TZOFFSETTO:-0700
	TZNAME:EDT
	END:DAYLIGHT
	END:VTIMEZONE
	MERGED-CALENDAR:State Holiday Schedule
	CALENDAR-OWNER:cal-admin
	END:CALENDAR-PROPERTY
	...
	BEGIN:ACL
	CALENDAR-ACL:anonymous:READ=ALL;CLASS=PUBLIC
	CALENDAR-ACL:state-Employee:READ=ALL;MODIFY=ALL;APPEND=ALL;
	 CREATE=SUB-CALENDAR;CLASS=PUBLIC,CONFIDENTIAL
	END:ACL
	...
	END:VCALENDAR	

The above example creates two calendars, One named "County Governments"
and the other "Office of Emergency Services".

The "CALENDAR-PROPERTY" component defines:

	The language for the calendars is "en_us".

	Any sub-calendar will NOT inherit the ACLs from
	these calendars as "ACL=NO" is set in the "INHERITANCE"
	property.

	Any sub-calendar will inherit the "PROPERTY" components
	from their parent and can be changed after that.

	The default time zone for these calendars is "US/Pacific",
	and its "VTIMEZONE" definition.

	The entries in the "State Holiday Schedule" calendar that would
	be visible if directly connected, are read-only and would seem
	to be part of these two new calendars.

	The calendar owner is authenticated user name "cal-admin". The
	"CALENDAR-OWNER" ACL allows the named users full access to the
	calendar.

The "ACL" component defines:

	The ACL list for the new calendars is that everyone can
	view all "PUBLIC" entries.

	Any authenticated user that is part of the "state-Employee" group
	has read access to all "PUBLIC" and "CONFIDENTIAL" entries.
	And can modify existing entries, and append new entries.
	(The name "state-Employee" could be an implementation specific
	 group name),

1.1.2) Create a sub-calendar.
Create a sub calendar off of an existing calendar.
Needs "CREATE=SUB-CALENDAR" ACL.

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION:CREATE
	CALENDAR-NAME:County Governments/Santa Cruz
	CALENDAR-NAME:County Governments/Monterey
	END:COMMAND
	...
	BEGIN:ACL
	CALENDAR-ACL:anonymous:READ=ALL;CLASS=PUBLIC
	END:ACL
	...
	BEGIN:COMMAND
	END:COMMAND
	OPERATION:STORE
	CALENDAR-NAME:County Governments/Santa Cruz
	BEGIN:ACL
	CALENDAR-ACL:cruz-Employee;READ=ALL;MODIFY=ALL;APPEND=ALL;
	 CREATE=SUB-CALENDAR;CLASS=PUBLIC
	CALENDAR-ACL:cruz-admin:
	 READ-ACL;MODIFY-ACL;APPEND-ACL;
	 READ-CAL-PROP;MODIFY-CAL-PROP;APPEND-ACL;
	 CREATE=SUB-CALENDAR;CLASS=PUBLIC
	END:ACL
	...
	BEGIN:COMMAND
	END:COMMAND
	OPERATION:STORE
	CALENDAR-NAME:County Governments/Monterey
	BEGIN:ACL
	CALENDAR-ACL:Monterey-Employee;READ=ALL;MODIFY=ALL;APPEND=ALL;
	 CREATE=SUB-CALENDAR;CLASS=PUBLIC
	CALENDAR-ACL:Monterey-admin;
	 READ-ACL;MODIFY-ACL;APPEND-ACL;
	 READ-CAL-PROP;MODIFY-CAL-PROP;APPEND-ACL;
	 CREATE=SUB-CALENDAR;CLASS=PUBLIC
	END:ACL
	...
	END:VCALENDAR	

Above two new calendars "Santa Cruz" and "Monterey" are created as
sub-calendars of the "County Governments" calendar.

There is NOT a "CALENDAR-PROPERTY" component, as the parent
calendar "County Governments" had "INHERITANCE" "PROPERTY=YES",
so this is the initial property for each of these two new
calendars. This includes time zone.

The "ACL" list for these is:

	Any user will have read access to all public entries.

	Only authenticated users in the "curz-Employee" group would
	be able to modify and append public and confidential entries.
	And they can create sub-calendars in the "County Governments/Cruz"
	calendar.

	Only authenticated users in the "cruz-admin" group would
	be able to modify, append, and create ACLs and PROPERTIES in the
	"County Governments/Santa Cruz" calendar.

	Only authenticated users in the "Monterey-Employee" group would
	be able to modify and append public and confidential entries.
	And they can create sub-calendars in the "County
Governments/Monterey"
	calendar.

	Only authenticated users in the "Monterey-admin" group would
	be able to modify, append, and create ACLs and PROPERTIES in the
	"County Governments/Monterey" calendar.

The authenticated user that sent this command would have to
have the "CREATE=SUB-CALENDAR" ACL or be in the "CALENDAR-OWNER" list
of the parent calendar.

1.2) "DELETE" - Delete an existing calendar store entry.

1.2.1) DELETE a top level calendar.
User must have ability to create a new top level calendar.
Needs "DELETE=CALENDAR" ACL.

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION:DELETE
	CALENDAR-NAME:Office of Emergency Services
	END:COMMAND
	...
	END:VCALENDAR

The authenticated user needs the "DELETE=CALENDAR" ACL.

Would remove the calendar "Office of Emergency Services" calendar,
all of its ACL lists, CALENDAR-PROPERTY lists, and all of its entries.

1.2.2) DELETE a sub-calendar.
Create a sub calendar off of an existing calendar.
Needs "DELETE=SUB-CALENDAR" ACL.

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION:DELETE
	CALENDAR-NAME:Office of Emergency Services/Monterey
	END:COMMAND
	...
	END:VCALENDAR

The authenticated user needs the "DELETE=SUB-CALENDAR" ACL in the
"Office of Emergency Services" calendar.

Would remove the calendar "Office of Emergency Services/Monterey" calendar,
all of its ACL lists, CALENDAR-PROPERTY lists, and all of its entries.

1.2.3) DELETE an ACL
Three issues:

	(1) Delete an CALENDAR-ACL content line.

	(2) Delete a user from an ACL.

	(3) Delete a specific ACL from a content line, keeping
	    the same user list.

After successful completion, the content line would be removed.
The authenticated user would need the "MODIFY-ACL" ACL as the 
ACL list would be modified.

The three subsections below assume a content line of:

	CALENDAR-ACL:Joe,Jane;READ=ALL;CLASS=PUBLIC,CONFIDENTIAL

1.2.3.1) Deleting an CALENDAR-ACL content line.

Simply supply the entire line to be deleted.

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION:DELETE
	CALENDAR-NAME:Company Holiday Schedule
	END:COMMAND:
	...
	BEGIN:ACL
	CALENDAR-ACL:Joe,Jane;READ=ALL;CLASS=PUBLIC,CONFIDENTIAL
	END:ACL

1.2.3.2) Delete a user from an ACL.

Simply supply a content line for what is to be deleted:

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION:DELETE
	CALENDAR-NAME:Company Holiday Schedule
	END:COMMAND:
	...
	BEGIN:ACL
	CALENDAR-ACL:Jane;READ=ALL;CLASS=PUBLIC,CONFIDENTIAL
	END:ACL

User "Jane" would no longer have access, "Joe" would still have access.

1.2.3.3) Delete a specific ACL from a content line, keeping
	 the same user list.

Simply supply what is to be removed:

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION:DELETE
	CALENDAR-NAME:Company Holiday Schedule
	END:COMMAND:
	...
	BEGIN:ACL
	CALENDAR-ACL:Joe,Jane;READ=ALL;CLASS=CONFIDENTIAL
	END:ACL

Users "Joe" and "Jane" would no longer have access to "CONFIDENTIAL"
entries in the "Company Holiday Schedule" calendar. They would
still have access to "PUBLIC" entries.

1.2.4) DELETE a CALENDAR-PROPERTY

Simply supply the property to be deleted.

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION:DELETE
	CALENDAR-NAME:Company Holiday Schedule
	END:COMMAND:
	...
	BEGIN:CALENDAR-PROPERTY
	X-FOO:some stuff unique to x-foo
	END:CALENDAR-PROPERTY

The "X-FOO" property that has a right hand side
of "some stuff unique to x-foo" will be deleted.

1.3) "FETCH" - Retrieve information from the server.

To fetch all components for 1997 in calendars "Doug Royer" and
any sub-calendars under "Doug Royer".

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION;COMPONENTS;EXPAND=YES:FETCH
	CALENDAR-NAME:Doug Royer
	CALENDAR-NAME:Doug Royer/*
	DTSTART:19970101T000000Z
	DTEND:19971231T000000Z
	END:COMMAND
	...
	END:VCALENDAR

Will return all entries for 1997 as it was bound by "DTSTART" and "DTEND".

Any entries that have any recurrence rules will be expanded into
multiple instances. Only instances that fall into 1997 will be
returned.

To "FETCH" by "UID":

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION;COMPONENTS;EXPAND=YES:FETCH
	CALENDAR-NAME:Doug Royer
	UID:[email-masked]
	END:COMMAND
	...
	END:VCALENDAR

To get all entries in from the calendar.

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION;COMPONENTS;EXPAND=NO:FETCH
	CALENDAR-NAME:Doug Royer
	CALENDAR-NAME:Doug Royer/*
	END:COMMAND
	...
	END:VCALENDAR

Note that "EXPAND=NO" MUST be set to avoid attempting to expand
recurring entries that go on forever.

1.3.1) "FETCH" - ACLs.
Retrieve the ACL list on the currently named calendars.
Results will only be successful for each calendar the
authenticated user has  the "READ-ACL" ACL.

1.3.1.1) To fetch all ACLs:

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION;ACLS:FETCH
	CALENDAR-NAME:Doug Royer
	END:COMMAND
	...
	END:VCALENDAR

1.3.1.2) To fetch all ACLs for user "dougr":

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION;ACLS:FETCH
	CALENDAR-NAME:Doug Royer
	CALENDAR-USER:dougr
	END:COMMAND
	...
	END:VCALENDAR

1.3.2) "FETCH" - by content.

To look for the string 'cat' in all calendars that start with "D".

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION;CONTENT:FETCH
	CALENDAR-NAME:D*
	CDS-FIELD:cat
	END:COMMAND
	...
	END:VCALENDAR

The "CDS-FIELD" looks in the "COMMENT", "DESCRIPTION", and "SUMMARY"
fields for the supplied string.

1.3.3) "FETCH" - Calendar Names.
Retrieve a list of calendar names that match the wild card string.
A server implementation may return a subset of calendar names
subject to the servers administrative rules.

To get a list of all calendars names that start with "Doug" or "Frank".

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION;CALENDAR-NAMES:FETCH
	CALENDAR-NAME:Doug*
	CALENDAR-NAME:Frank*
	END:COMMAND
	...
	END:VCALENDAR

1.3.4) "FETCH" - Capabilities.
Retrieve a list of capabilities from the server.

To get a list of the capabilities of the server:

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION;CAPABILITIES:FETCH
	END:COMMAND
	...
	END:VCALENDAR

1.3.5) "FETCH" - Calendar Properties.
Retrieve the calendar properties on the named calendars.
Returns the properties for the named calendars where the user
has the "READ-CAL-PROP" ACL.

To get a list of all calendars names that start with "Doug" or "Frank":

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION;CALENDAR-PROPERTY:FETCH
	CALENDAR-NAME:Doug Royer
	END:COMMAND
	...
	END:VCALENDAR

1.4) "STORE"
For iCalendar components - simply follow the rules as outlined
in iTIP.

1.4.1) "STORE" ACLs

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION;:STORE
	CALENDAR-NAME:Doug Royer
	END:COMMAND
	...
	BEGIN:ACL
	...	<include the ACLs to send to the server>
	END:ACL
	...
	END:VCALENDAR

1.4.2) For CALENDAR-PROPERTYs:

	BEGIN:VCALENDAR
	METHOD:REQUEST
	...
	BEGIN:COMMAND
	OPERATION;:STORE
	CALENDAR-NAME:Doug Royer
	END:COMMAND
	...
	BEGIN:CALENDAR-PROPERTIES
	...	<include the ACLs to send to the server>
	END:CALENDAR-PROPERTIES
	...
	END:VCALENDAR

1.5)
<TBD>

1.6) Wild cards.

	; A simple wild card match:
	;
	;	'*'		Zero or more of any character
	;	'?'		Any single character.
	;
	;	Zero or more '*'s may exist.
	;	Zero or more '?'s may exist.
	;
	;	a*		All names that start with 'a'.
	;
	;	?a*		All names that have 'a' as the 2nd
character.
	;
	;	*a*		All names that have 'a' in them.
	;
	;	?a?		All three character names where the
	;			 2nd character is an 'a'.
	;

2.0) "COMMAND" ABFN

This is not exhaustive, as in not all combinations below are valid.
You get the idea of what I mean.

	begin-vcal =		"BEGIN" ":" "VCALENDAR" CRLF
	end-vcal =		"END" ":" "VCALENDAR" CRLF

	begin-command = 	"BEGIN" ":" "COMMAND" CRLF
	end-command =		"END" ":" "COMMAND" CRLF

	command =		create-command
				delete-calendars-command
				fetch-command
				store-command
				reply-command

	create-command =	begin-vcal
				<ical-required-properties>
				<METHOD-request>
				begin-command
				"OPERATION" *( ";" param ) ":" "CREATE" CRLF
				1*calendar-name
				end-command
				*cal-acls
				*cal-props
				end-ical

	; <note the CAPABILITIES detail will be sent in a separate email>
	;
	fetch-command =		begin-vcal
				<ical-required-properties>
				<METHOD-request>
				begin-command
				"OPERATION" 
				*( ";" expand-rrule)
				*( ";" "CAPABILITIES" )
				*( ";" "COMPONENTS" )
				*( ";" "ACLS" )
				*( ";" "CALENDAR-PROPERTY" )
				*( ";" "CALENDAR-NAMES" )
				*( ";" param) ":" "FETCH" CRLF
				*calendar-name-with-wildcards
				*( dtstart ( dtend / duration) )
				*uid
				*calendar-user-with-wildcards
				*cds-filed
				component-type
				end-command
				end-ical	

	delete-command =	begin-vcal
				<ical-required-properties>
				<METHOD-request>
				begin-command
				"OPERATION" *( ";" param) ":" "FETCH" CRLF
				1*calendar-name-with-wildcards
				1*( cal-acls cal-props)
				end-command
				end-ical

	store-command =		begin-vcal
				<ical-required-properties>
				<METHOD-request>
				begin-command
				"OPERATION" *( ";" param) ":" "STORE" CRLF
				1*calendar-name-with-wildcards
				1*( cal-acls cal-props)
				end-command
				end-ical

	; 'component' is defined in iCalendar 3.2
	;
	component-type =	"COMPONENT" *( ";" param) ":" component CRLF

	calendar-name-with-wildcards =	( calendar-name / wildcards )

	; CDS stands for "COMMENT", "DESCRIPTION", "SUMMARY".
	; Look for <text> within these properties.
	;
	cds-field =		"CDS-FIELD" *( ";" case-ignore)
				*(param) ":" text CRLF

	case-ignore =		"CASE-IGNORE" "=" ( "YES" / "NO" )

	wildcards =		( <ABNF - to be done> )

3.0) Examples.

To get all "VEVENT" and "VTODO" entries between Jan 1, 1990 <-> Jan 2, 2000.
Do not "EXPAND" the recurrence rules into multiple entries:

BEGIN:VCALENDAR
METHOD:REQUEST
...
BEGIN:COMMAND
OPERATION;EXPAND=NO:FETCH
CALENDAR-NAME:Teams Baseball Schedule
DTSTART:01019990T000000Z
DTEND:01012000T000000Z
COMPONENT:VEVENT,VTODO
END:COMMAND
...
END:VCALENDAR

The same as above, except generate new instances (RECURRENCE-ID) for
the entries with recurrence rules:

BEGIN:VCALENDAR
METHOD:REQUEST
...
BEGIN:COMMAND
OPERATION;EXPAND=YES:FETCH
CALENDAR-NAME:Teams Baseball Schedule
DTSTART:01019990T000000Z
DTEND:01012000T000000Z
COMPONENT:VEVENT,VTODO
END:COMMAND
...
END:VCALENDAR

To get an entire calendar, from beginning to end.

If "EXPAND" were set to "YES" and there was one or more unbound
recurrence rules, the reply would fail if there are unbound recurrence
rules.

BEGIN:VCALENDAR
METHOD:REQUEST
...
BEGIN:COMMAND
OPERATION;EXPAND=NO:FETCH
CALENDAR-NAME:Company Holiday Schedule
END:COMMAND
...
END:VCALENDAR

To get the name of all calendars the server knows about that
start with 'a', 'A', or 'z'. (Subject to access control):

BEGIN:VCALENDAR
METHOD:REQUEST
...
BEGIN:COMMAND
OPERATION:LIST-CALENDARS
CALENDAR-NAME;CASE-IGNORE=YES:a*
CALENDAR-NAME:z*
END:COMMAND
...
END:VCALENDAR

To find all entries that contain the string 'cat' or 'dog' in the
"COMMENT", "DESCRIPTION", or "SUMMARY" properties.

BEGIN:VCALENDAR
METHOD:REQUEST
...
BEGIN:COMMAND
OPERATION:CONTAINS
CALENDAR-NAME:Company Holiday Schedule
CDS-FIELD;CASE-IGNORE=YES:cat
CDS-FIELD;CASE-IGNORE=YES:dog
END:COMMAND
...
END:VCALENDAR

-Doug
-------------------------------------------------------------------
[email-masked]		http://www.royer.com/dougr.html
801 W. El Camino #131		Work:   (650)786-7599
Mountain View, CA 94040		Ham Radio: N6AAW, Aviation: PP-ASEL