|
| |
| Sun Java System Calendar Server 6 2005Q1 Developer's Guide | |
Chapter 7
WCAP Command ReferenceThis chapter contains the WCAP command reference. Each command accepts various parameters, which are defined for each command in this chapter.
Unless otherwise noted, the maximum length value for any parameter accepted by WCAP commands is 1024 characters. While no input length checking is performed by WCAP, any parameter value longer than 1024 can produce unpredictable results.
For all commands that allow the id parameter (session ID), it is a required parameter. There are two exceptions to this rule. It is not required in order to grant anonymous access to a calendar, nor is it required in order to grant read access to a public calendar. In all other situations, you must provide the session ID in the id parameter.
Note
The server supports “anonymous” as a special principal name. The anonymous user can log in with any password. It is not associated with any particular domain.
The following is a list of the available WCAP commands:
addlink – deprecated
addlinkPurpose
This command has been deprecated. It is not used in the current version of Calendar Server and may be removed from the product in a future version.
Add links from one calendar’s events or todos to another calendar.
Parameters
Table 7-1 lists addlink parameters:
Description
Use this command to add links in the destination calendar to the specified events and/or todos in the source calendar.
You must specify the id parameter with the command unless the specified calendar is a public calendar.
The number of items in the uid and rid lists must match exactly, with each rid corresponding to the uid in the same position in the list. If an event or todo has no recurrence ID, use 0 in the rid list.
Unless the following three requirements are met, the transaction will fail:
Returns
If the transaction fails, an error of ADDLINK_FAILED(12) returns; otherwise, the return code is 0.
Example
This example shows how to add two event links to the calendar jdoe. The links should point to events in the pub calendar. The events are 1111 and 2222, (their uids). Neither event is recurring, so their recurrence-id is 0.
This URL executes the above transaction.
http://webcalendarserver/addlink.wcap?id=b5q2o8ve2rk02nv9t6&destCal=jdoe&s rcCal=pub&uid=1111;2222&rid=0;0
change_passwordPurpose
Change the password of the current user. This command is deprecated. It is here only for backward compatibility. See the “Administration Guide” for details on changing a password.
Parameters
Table 7-2 lists change_password parameters:
Purpose
This command changes a user’s password. Passwords are passed as plain text. Only users with administrative privilege may use this command unless the service.wcap.allowchangepassword preference is set.
You must specify the id parameter with the command unless the specified calendar is a public calendar.
Returns
A failure of the command will return the error CHANGE_PASSWORD_FAILED(27).
Example
This example URL requests a password change:
http://webcalendarserver/change_password.wcap?id=b5q2o8ve2rk02nv9t6&oldPas sword=abc&newPassword=def
check_idPurpose
This administrator only command allows the administrator to verify that a session is still valid.
Parameters
Table 7-2 lists check_id parameters:
Purpose
This command allows the administrator to verify that the session is still valid.
Returns
The server returns the property X-NSCP-WCAP-CHECK-ID. If the value of this property is 1 the session is valid. If a zero (0) is returned, the session is invalid. It has either timed out or is unrecognized.
Example
The following command returns whether the specified session is valid or not:
http://webcalendarserver/check_id.wcap?id=n3l0eeu6s3n3o3b8v&fmt-out=text/c alendar
The output returned is:
HTTP/1.1 200
Date: Thu, 14 Dec 2002 19:48:17 GMT
Content-type: text/calendar; charset=UTF-8
Content-length: 131
Last-modified: Thu, 14 Dec 2002 19:48:17 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache
Connection: Keep-AliveBEGIN:VCALENDAR
PRODID:-//SunJavaSystem/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-WCAP-CHECK-ID:1
END:VCALENDAR
createcalendarPurpose
Create a new calendar.
Parameters
Table 7-4 lists createcalendar parameters:
Description
Use this command to create a new calendar for the current user. To enable users who do not have administrative privileges to use this command, the service.wcap.allowcreatecalendars parameter in the ics.conf file must be set to “yes”, which is the default.
Creating a Valid Calid
The new calid of the created calendar is a combination of the user’s userid and the calid parameter passed in. The system retrieves the userid by doing a lookup on the session specified with the id parameter. The format for the new calendar’s calid is userid:calid. For example, if the user is jdoe, and the calid parameter is tv, the new calendar’s calid is jdoe:tv.
The server will attempt to truncate calid parameters that are too long or contain any illegal characters. If the server is unable to truncate the calid parameter, the error returned is ILLEGAL_CALID_NAME(30).
Valid characters for the calid parameter are:
For example, these are legal values for the calid parameter: calendar1, calendar-1, calendar_1, calendar.1
Setting Calendar Properties
You can set the calendar properties during creation. Pass in the set_calprops parameter with a value of 1. You can then pass in any additional parameters as defined for the set_calprops command for setting calendar properties.
For more information on calendar properties you can set, see the set_calprops command.
Note that at calendar creation, if you do not specify calendar properties, the defaults set in the ics.conf file will be used.
Returns
The returned output shows the calendar properties (retrieved with a call to the fetchcomponents_by_range command) formatted according to the fmt-out value.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If the newly created calid already exists in the database, an error code returns: CREATECALENDAR_ALREADY_EXISTS_FAILED(25)
Example
The following example URL creates a calendar with the ID jdoe:newcal for the user jdoe, sets the name to New-Calendar, and the categories to business and work:
http://webcalendarserver/createcalendar.wcap?id=b5q2o8ve2rk02nv9t6&calid=n ewcal&set_calprops=1&name=New-Calendar&categories=business;work
deletecalendarPurpose
This command deletes a user’s calendar.
Parameters
Table 7-5 lists deletecalendar parameters:
Description
Use this command to delete a user’s calendar. You must pass in the calid, which is the name of the calendar to delete.
Only users with administrative privilege may use this command unless the ics.conf parameter service.wcap.allowdeletecalendars is set to “yes” (which is the default).
Returns
The returned output is the formatted output from a call to fetchcomponents_by_range.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If the calid doesn’t exist in the database, the delete_layer_errno[x] value is set to 1, where x is the calendar’s index in the passed calid list. In addition, the errno variable contains the error: CALENDAR_DOES_NOT_EXIST(29).
Example
For example, sending this URL deletes the calendar named newcal.
http://webcalendarserver/deletecalendar.wcap?id=b5q2o8ve2rk02nv9t6&calid=n ewcal
deletecomponents_by_rangePurpose
Delete events and todos from a calendar in a specified range.
Parameters
Table 7-6 lists deletecomponents_by_range parameters:
Description.
Use this command to delete the events and todos that fall completely within the specified range from the specified calendars. If a range is not specified, it deletes all events and todos. The range parameters, dtstart and dtend, should be specified in UTC time (the ’Z’ must be on the end). Otherwise, results are unpredictable.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string, If an error occurs while deleting from the calendar, the delete_layer_errno[x] value is set to 1, where x is the calendar’s index in the passed calid list. In addition, errno contains the error: DELETECOMPONENTS_BY_RANGE_FAILED(21).
Example
For example, assuming the user has read access to the calendars jdoe and john, the following URL deletes all events and todos from those two calendars:
http://deletecomponents_by_range.wcap?id=2342347923479asdf
&calid=jdoe;john&dtstart=0&dtend=0
deleteevents_by_idPurpose
Deletes one or more events from a calendar by event identifier.
Parameters
Table 7-7 lists deleteevents_by_id parameters:
Description.
Use this command to delete the specified event or events from the specified calendar.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If the uid does not exist, the server returns error code 59. See also, Error Handling.
Recurrences
If the rid parameter is passed, the command also deletes recurrences, as specified by the mod parameter. (See Recurring Components – Deleting..) To delete multiple events, specify a semicolon-separated list for the uid, rid, and mod parameters. The three lists must have the same number of elements. Each list element corresponds to the same element in the other two lists.
Example
For example, there are two non-recurring events in the database with UIDs of uid-EVENT1 and uid-EVENT2. Since the events are non-recurring, the rid value for each event is set to 0 and mod value for each event is set to 1.
The following URL deletes the two events:
http://webcalendarserver/deleteevents_by_id.wcap?id=br6p3t6bh5po35r
&uid=uid-EVENT1;uid-EVENT2&rid=0;0&mod=0;0&fmt-out-text/calendarThe resulting data would look like this:
BEGIN:VCALENDAR
PRODID:-//SunJavaSystem/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
BEGIN:VEVENT
UID:uid-EVENT1
REQUEST-STATUS:2.0;Success. Delete successful.
END:VEVENT
BEGIN:VEVENT
UID:uid-EVENT2
REQUEST-STATUS:2.0;Success. Delete successful.
END:VEVENT
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
deleteevents_by_rangePurpose
Delete events from a calendar in a specified range.
Parameters
Table 7-8 lists deleteevents_by_range parameters:
Description.
Use this command to delete the events that fall completely within the specified range from the specified calendars. If a range is not specified (dtstart and dtend), it deletes all events from the specified calendars.
You must specify the id parameter with the command unless the specified calendar is a public calendar. The server returns data in the format specified by the fmt-out parameter. If this parameter is not passed, the data returns in the default text/calendar format.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string, errno. If the operation is not successful, the errno variable contains the error: DELETEEVENTS_BY_RANGE_FAILED(22).
See also, Error Handling.
Example
For example, assuming the user has read access to the calendars jdoe and john, the following URL would result in deleting all events from the calendars jdoe and john:
http://webcalendarserver/deleteevents_by_range.wcap?id=2342347923479asdf&c alid=jdoe;john&dtstart=0&dtend=0
deletetodos_by_idPurpose
Delete one or more todos from a calendar.
Parameters
Table 7-9 lists deletetodos_by_id parameters:
Description.
Use this command to delete the specified todo from the specified calendar.
You must specify the id parameter with the command unless the specified calendar is a public calendar. The server returns data in the format specified by the fmt-out parameter. If this parameter is not passed, the data returns in the default text/calendar format.
Error Codes
If the uid does not exist, returns error 59.
See also, Error Handling.
Recurrences
If the rid parameter is passed, the command also deletes recurrences, as specified by the mod parameter. See Recurring Components – Deleting.
To delete multiple todos, specify a semicolon-separated list for the uid, rid, and mod parameters. The three lists must have the same number of elements. Each list element corresponds to the same element in the other two lists.If the rid parameter is passed, the command also deletes recurrences, as specified by the mod parameter.
Example
For example, there are two non-recurring todos in the database with UIDs of uid-TODO1 and uid-TODO2. Since the todos are non-recurring, the rid value for each todo is set to 0 and mod value for each todo is set to 1.
The following URL deletes the two todos:
http://webcalendarserver/deletetodos_by_id.wcap?id=br6p3t6bh5po35r
&uid=uid-TODO1;uid-TODO2&rid=0;0&mod=1;1&fmt-out=text/calendarThe resulting data would look like this:
BEGIN:VCALENDAR
PRODID:-//SunJavaSystem/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
BEGIN:VTODO
UID:uid-TODO1
REQUEST-STATUS:2.0;Success. Delete successful.
END:VTODO
BEGIN:VTODO
UID:uid-TODO2
REQUEST-STATUS:2.0;Success. Delete successful.
END:VTODO
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
deletetodos_by_rangePurpose
Delete todos in a range from a calendar.
Parameters
Table 7-10 lists deletetodos_by_range parameters:
Description.
Use this command to delete the todos that fall completely within the specified range from the specified calendars. If a range is not specified, it deletes all todos. For example, the following URL would delete just the todos that occur on the date March 1, 2002.
http://webcalendarserver/deletetodos_by_range.wcap?id=23423423434abc&calid =jdoe&dtstart=20020301T000000Z&dtend=20020301T235959Z
You must specify the id parameter with the command unless the specified calendar is a public calendar. The server returns data in the format specified by the fmt-out parameter. If this parameter is not passed, the data is returned in the default text/calendar.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If an error occurs, the errno variable contains the error: DELETETODOS_BY_RANGE_FAILED(23).
See also, Error Handling.
exportPurpose
Export events and todos from a calendar to a file.
Parameters
Table 7-11 lists export parameters:
Description.
Use this command to export events and todos from one or more specified calendars to a file. The contents of the file can later be imported to a calendar using the import command. The command creates a file called export.ics or export.xml, depending on the value of the content-out parameter.
Range
If you do not specify either the starting or ending date, all events and todos in the calendars are added to the file. If you specify a starting and ending date, the command exports only events and todos in the calendars that fall within the time range. Specify starting and ending dates in UTC time (indicated by Z at the end of the datetime).
HTTP Post Examples
You must use this command with an HTTP POST (unlike other commands, which can be used with an HTTP GET).
Example 1
The following HTTP POST message exports all components of the calendars jdoe and john to an iCalendar file named export.ica:
POST
/export.wcap?id=t95qm0n0es3bo35r&calid=jdoe;john&dtstart=0&dtend=0
&content-out=text/calendar
Content-type: multipart/form-data;
boundary=---------------------------41091400621290
Content-Length: 47
-----------------------------41091400621290--
WinNT; U)
Host: jdoe:12345
Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, image/png
*/*
Accept-Encoding: gzip
Accept-Language: en
Accept-Charset: iso-8859-1,*,utf-8Example 2
The following HTML generates a POST message using the export command, producing files in both iCalendar and XML formats:
<form METHOD=POST ENCTYPE="multipart/form-data" NAME="john.ics"
ACTION="http://webcalendarserver:12345/export.wcap?id=t9u9m0eh8x5pu9b
&calid=jdoe;john&dtstart=0&dtend=0&content-out=text/calendar">
<ul>
<li>Press Export ICAL Now:<input type="submit" value="Export ICAL now">
</li> </ul> </form>
<form METHOD=POST ENCTYPE="multipart/form-data" NAME="john.xml"
ACTION="http://webcalendarserver:12345/export.wcap?id=t9u9m0eh8x5pu9b
&calid=jdoe;john&dtstart=0&dtend=0&content-out=text/xml">
<ul>
<li>Press Export XML Now:<input type="submit" value="Export XML now”>
</ul> </form>This is the output generated:
HTTP/1.0 200
Date: Thu, 03 Jun 2002 22:15:52 GMT
Content-type: text/calendar
Content-disposition: attachment; filename="export.ics"
Content-length: 7004BEGIN:VCALENDAR
METHOD:PUBLISH
VERSION:6.0
BEGIN:VEVENT
UID:tm-001
RECURRENCE-ID:20020519T010000Z
DTSTAMP:20020603T221548Z
SUMMARY:Calendar Staff
DTSTART:20020518T170000Z
DTEND:20020518T190000Z
CREATED:20020603T024254Z
LAST-MODIFIED:20020603T024254Z
PRIORITY:1
SEQ:1
GEO:37.463581;-121.897606
DESC:This is the description for event with UID = tm-001
URL:http://webcalendarserver/susan?uid=tm-001
LOCATION:Green Conference Room
STATUS:CONFIRMED
TRANSP:OPAQUE
END:VEVENT
BEGIN:VEVENT
UID:tm-001
RECURRENCE-ID:20020526T010000Z
DTSTAMP:20020603T221548Z
SUMMARY:Calendar Staff
DTSTART:20020525T170000Z
DTEND:20020525T190000Z
CREATED:20020603T024254Z
LAST-MODIFIED:20020603T024254Z
PRIORITY:1
SEQ:1
GEO:37.463581;-121.897606
DESC:This is the description for event with UID = tm-001
URL:http://webcalendarserver/susan?uid=tm-001
LOCATION:Green Conference Room
STATUS:CONFIRMED
TRANSP:OPAQUE
END:VEVENT
END:VCALENDAR
fetchcomponents_by_alarmrangePurpose
Retrieve calendar events and todos with alarm triggers.
Parameters
Table 7-12 lists fetchcomponents_by_alarmrange parameters:
Table 7-12 fetchcomponents_by_alarmrange Parameters
Parameter
Type
Purpose
Required
Default
calid
string
A semicolon-separated list of calendar identifiers.
The calid can be supplied in two formats:
N
Current user’s calid.
component-type
keyword (event, todo, all)
Indicates which components to return: event returns only events
todo returns only todos (tasks)
all returns both events and todosIf an invalid value is passed in, the system assumes all.
N
all
compressed
integer (0,1)
This parameter is deprecated in this release and may be deleted in future releases.
For compressed=0, returns less data. Specifically, it does not return the following parameters:
rrules
rdate
exrule
exdateFor compressed=1, all recurrence data is returned.
N
0
compstate
semicolon-
separated list of component state keywordsThe list of component states to fetch.
For compstate values, see Table 6-5.
N
ALL
dtend
DateTime string
End time and date of events and todos to be returned.
A value of 0 means fetch all events.
N
0
dtstart
DateTime string
Start time and date of events/todos with alarms ready to go off during the specified time.
A value of 0 means fetch all events from the beginning of time.
N
0
emailorcalid
integer (0, 1)
0 = The calid is returned in the cal-address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-EMAIL has the RFC 822 email address of the invitee or organization.
1 = The email address is returned in the cal-address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-CALID contains the calid value.
N
0
fetchorder
integer
Specifies the order in which the events and todos are returned.
The values are:
N
0
fmt-out
string
The format for the returned data.
The three format types:
text/calendar
text/xmlN
text/
calendarid
unique identifier string
The session identifier.
Y
N/A
maxResults
integer
The maximum number of events and todos to be returned. When 0, no maximum is applied and the command returns all events and todos found.
N
0
recurring
integer (0, 1)
Whether to return all components in compressed form (1) or not (0). (Compressed form has master entry plus exceptions.)
N
0 (not compressed)
relativealarm
integer (0, 4)
Return the alarm as relative or absolute.
0—Return alarm values as absolute.
4—Return alarms as originally created.N
0 (absolute)
tzid
time zone ID string
If dtstart and dtend parameters are not already in Zulu time, the time zone to use for translating them to Zulu time.
For example, “America/Los_Angeles”
N
server’s default time zone
tzidout
time zone ID string
Time zone to report returned data in.
N
Zulu time
Description.
This command returns a list of events and todos having alarms that are about to go off during the specified time.
Output Format
The server returns data in the format specified by the fmt-out parameter. If this parameter is not passed, the data is returned in the default text/calendar format.
maxResults Value
If you specify a maximum n, the command returns up to the first n events and first n todos in the specified range. For example, if you specify a maxResults value of 75, the returned data would contain the following variables
var maxResults=75 /* maximum cap passed in */
var size=75 /* event size is capped to 75 */
var todosize=28 /* todo size not affected since it is less than 75 */If the maxResults parameter is set to 0 or is not passed, then the returned data does not contain the var maxResults statement.
Returns
For each calendar specified in calid, the server returns the calendar's events and todos having alarms about to go off within the range specified by dtstart and dtend.
If the times specified in the dtstart and dtend parameters is not Zulu time, the system uses the time zone specified in the tzid parameter to translate the times into Zulu time for data retrieval. If the tzid parameter is missing, the system uses the server’s default time zone.
The system uses the tzidout parameter to determine what time zone to translate retrieved data into before returning it. If the tzidout parameter is missing, the system returns the data in Zulu time.
If neither the starting nor ending date-time is specified, the server returns all events and todos with alarms, up to the specified maximum.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If a calendar cannot be accessed or is missing, errno is FETCH_BY_ALARM_RANGE_FAILED(41).
Example
For example, suppose there are 3 events:
Here are two queries and their return values:
Example 1
This query fetches all events and todos that have alarms about to go off between Dec. 1, 2001 and Jan. 31, 2002.
http://webcalendarserver/fetchcomponents_by_alarmrange.wcap?id=abcdefg&dtstart=20011201T112233Z&dtend=20020131T112233Z&fmt-out=text/calendar
It returns eventA and todoA:
BEGIN:VCALENDAR
PRODID:-//SunJavaSystem/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:20011208T005613Z
X-NSCP-CALPROPS-CREATED:20010913T223336Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe
X-NSCP-CALPROPS-NAME:John Doe
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-TZID:America/Los_Angeles
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^WDEIC^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^RSF^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^c^dw^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^a^rs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^c^w^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^p^r^g
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VEVENT
UID:3c11625900005ffe00000011000010b7
DTSTAMP:20011208T011139Z
SUMMARY:eventA
DTSTART:20011225T133000Z
DTEND:20011225T143000Z
CREATED:20011208T004409Z
LAST-MODIFIED:20011208T010857Z
PRIORITY:0
SEQUENCE:4
ORGANIZER;SENT-BY="jdoe@sesta.com"
;X-NSCP-ORGANIZER-UID=jdoe
;X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe
STATUS:CONFIRMED
TRANSP:OPAQUE
ATTENDEE;ROLE=REQ-PARTICIPANT;CUTYPE=INDIVIDUAL
;PARTSTAT=ACCEPTED;CN="JOHN SMITH"
;RSVP=TRUE
;X-NSCP-ATTENDEE-GSE-STATUS=2
:jdoe
X-NSCP-ORIGINAL-DTSTART:20020210T190000Z
X-NSCP-LANGUAGE:en
BEGIN:VALARM
ACTION:EMAIL
TRIGGER;VALUE=DATE-TIME:20011225T123000Z
ATTENDEE:MAILTO:jsmith@company22.com
END:VALARM
X-NSCP-DTSTART-TZID:America/Los_Angeles
X-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0
X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com
X-NSCP-GSE-COMPONENT-STATE;X-NSCP-GSE-COMMENT="REQUEST-COMPLETED":
31074
END:VEVENT
BEGIN:VTODO
UID:3c1162e200207ff600000015000010b7
DTSTAMP:20011208T011139Z
SUMMARY:todoA
DTSTART:20011208T004626Z
DUE:20020120T141500Z
CREATED:20011208T004626Z
LAST-MODIFIED:20011208T011000Z
PRIORITY:0
SEQUENCE:3
PERCENT-COMPLETE:0
ORGANIZER;SENT-BY="jdoe@sesta.com"
;X-NSCP-ORGANIZER-UID=jdoe
;X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe
STATUS:NEEDS-ACTION
X-NSCP-ORIGINAL-DTSTART:20011208T004626Z
X-NSCP-LANGUAGE:en
BEGIN:VALARM
ACTION:EMAIL
TRIGGER;VALUE=DATE-TIME:20020120T131500Z
ATTENDEE:MAILTO:jdoe@sesta.com
END:VALARM
X-NSCP-DUE-TZID:America/Los_Angeles
X-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0
X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com
X-NSCP-GSE-COMPONENT-STATE;
X-NSCP-GSE-COMMENT="PUBLISH-COMPLETED":65538
END:VTODO
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
Example 2
This query fetches all events and todos that have alarms to go off between Jan. 1, 2002 and June 1, 2002.
http://webcalendarserver/fetchcomponents_by_alarmrange.wcap?id=abcdefg&dtstart=20020101T000000Z&dtend=20020601T000000Z&fmt-out=
text/calendarIt returns eventB and todoA:
BEGIN:VCALENDAR
PRODID:-//SunJavaSystem/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:20011208T005613Z
X-NSCP-CALPROPS-CREATED:20010913T223336Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe
X-NSCP-CALPROPS-NAME:John Doe
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-TZID:America/Los_Angeles
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^WDEIC^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^RSF^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^c^dw^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^a^rs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^c^w^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^p^r^g
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VEVENT
UID:3c1162b3000051c300000013000010b7
DTSTAMP:20011208T011645Z
SUMMARY:eventB
DTSTART:20020210T110000Z
DTEND:20020210T120020Z
CREATED:20011208T004539Z
LAST-MODIFIED:20011208T011638Z
PRIORITY:0
SEQUENCE:4
ORGANIZER;SENT-BY="jdoe@sesta.com"
;X-NSCP-ORGANIZER-UID=jdoe
;X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe
STATUS:CONFIRMED
TRANSP:OPAQUE
ATTENDEE;ROLE=REQ-PARTICIPANT;CUTYPE=INDIVIDUAL
;PARTSTAT=ACCEPTED;CN="John Smith";RSVP=TRUE
;X-NSCP-ATTENDEE-GSE-STATUS=2:jsmith
X-NSCP-ORIGINAL-DTSTART:20021225T213000Z
X-NSCP-LANGUAGE:en
BEGIN:VALARM
ACTION:EMAIL
TRIGGER;VALUE=DATE-TIME:20020210T100000Z
ATTENDEE:MAILTO:jsmith@company22.com
END:VALARM
X-NSCP-DTSTART-TZID:America/Los_AngelesX-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0
X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com
X-NSCP-GSE-COMPONENT-STATE;
X-NSCP-GSE-COMMENT="REQUEST-COMPLETED":131074
END:VEVENT
BEGIN:VTODO
UID:3c1162e200207ff600000015000010b7
DTSTAMP:20011208T011645Z
SUMMARY:todoA
DTSTART:20011208T004626Z
DUE:20020120T141500Z
CREATED:20011208T004626Z
LAST-MODIFIED:20011208T011000Z
PRIORITY:0
SEQUENCE:3PERCENT-COMPLETE:0
ORGANIZER;SENT-BY="jdoe@sesta.com"
;X-NSCP-ORGANIZER-UID=jdoe
;X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe
STATUS:NEEDS-ACTION
X-NSCP-ORIGINAL-DTSTART:20011208T004626Z
X-NSCP-LANGUAGE:en
BEGIN:VALARM
ACTION:EMAIL
TRIGGER;VALUE=DATE-TIME:20020120T131500Z
ATTENDEE:MAILTO:jdoe@sesta.com
END:VALARM
X-NSCP-DUE-TZID:America/Los_Angeles
X-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com
X-NSCP-GSE-COMPONENT-STATE;X-NSCP-GSE-COMMENT="PUBLISH-COMPLETED":
5538END:VTODO
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
fetchcomponents_by_attendee_errorPurpose.
Fetch a list of components that had errors while sending group scheduling messages.
Parameters.
Table 7-13 lists fetchcomponents_by_attendee_error parameters
Description.
Use this command to retrieve a list of events and todos that had errors when sending group scheduling messages. This command works almost like fetchcomponents_by_range.
Output Format
The server returns data in the format specified by the fmt-out parameter. If this parameter is not passed, the data is returned in the default text/calendar format.
maxResults Value
If you specify a maximum n, the command returns up to the first n events and first n todos in the specified range. For example, if you specify a maxResults value of 75, the returned data would contain the following variables
var maxResults=75 /* maximum cap passed in */
var size=75 /* event size is capped to 75 */
var todosize=28 /* todo size not affected since it is less than 75 */If the maxResults parameter is set to 0 or is not passed, then the returned data does not contain the var maxResults statement.
Returns
For each calendar specified in calid, the server returns the events and todos that had errors for the specified attendee while sending group scheduling messages.
For example, if the calid parameter specifies calendars cal1 and cal2, and the attendee parameter specifies jdoe, then both cal1 and cal2 would be searched for events with errors that had jdoe as an attendee. In the table that follows, cal1 and cal2 each have four events with associated attendees:
For attendee jdoe, the command returns: events 1c1 and 2c2.
The system uses the tzidout parameter to determine what time zone to translate retrieved data into before returning it. If the tzidout parameter is missing, the system returns the data in Zulu time.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If the command fails for any reason, errno is FETCH_BY_ATTENDEE_ERROR_FAILED(42).
fetchcomponents_by_lastmodPurpose.
Fetch a list of components that have changed during a specified time period.
Parameters.
Table 7-14 lists fetchcomponents_by_lastmod parameters
Table 7-14 fetchcomponents_by_lastmod Parameters
Parameter
Type
Purpose
Required
Default
calid
string
A semicolon-separated list of calendar identifiers.
The calid can be supplied in two formats:
N
Current user’s calid.
component-type
keyword (event, todo, all)
Indicates which components to return: event returns only events
todo returns only todos (tasks)
all returns both events and todosIf an invalid value is passed in, the system assumes all.
N
all
compressed
integer (0,1)
This parameter is deprecated in this release and may be deleted in future releases.
For compressed=0, returns less data. Specifically, it does not return the following parameters:
rrules
rdate
exrule
exdateFor compressed=1, all recurrence data is returned.
N
0
compstate
semicolon-
separated list of component state keywordsThe list of component states to fetch.
For compstate values, see Table 6-5.
N
ALL
dtend
DateTime string
End time and date of events to be returned.
A value of 0 means fetch all events.
N
0
dtstart
DateTime string
Start time and date of events to be returned.
A value of 0 means fetch all events from the beginning of time.
N
0
emailorcalid
integer (0, 1)
0 = The calid is returned in the cal-address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-EMAIL has the RFC 822 email address of the invitee or organization.
1 = The email address is returned in the cal-address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-CALID contains the calid value.
N
0
fetchorder
integer
Specifies the order in which the events and todos are returned.
The values are:
N
0
fmt-out
string
The format for the returned data.
The three format types:
text/calendar
text/xmlN
text/
calendarid
unique identifier string
The session identifier.
Y
N/A
maxResults
integer
The maximum number of events and todos to be returned. When 0, no maximum is applied and the command returns all events and todos found.
N
0
recurring
integer (0, 1)
Whether to return all components in compressed form (1) or not (0). (Compressed form has master entry plus exceptions.)
N
0 (not compressed)
relativealarm
integer (0, 4)
Return the alarm as relative or absolute.
0—Return alarm values as absolute.
4—Return alarms as originally created.N
0 (absolute)
tzid
time zone ID string
Time zone to use if dtstart, or dtend parameters are not in Zulu time.
For example, “America/Los_Angeles”
N
server’s default time zone
tzidout
time zone ID string
Time zone to report returned data in.
N
Zulu time
Description.
Use this command to retrieve a list of events and todos that have changed during a specific time period. This command works almost like fetchcomponents_by_range.
Output Format
The server returns data in the format specified by the fmt-out parameter. If this parameter is not passed, the data is returned in the default text/calendar format.
maxResults Value
If you specify a maximum n, the command returns up to the first n events and first n todos in the specified range. For example, if you specify a maxResults value of 75, the returned data would contain the following variables
var maxResults=75 /* maximum cap passed in */
var size=75 /* event size is capped to 75 */
var todosize=28 /* todo size not affected since it is less than 75 */If the maxResults parameter is set to 0 or is not passed, then the returned data does not contain the var maxResults statement.
Returns
For each calendar specified in calid, the server returns the calendar's the events and todos that changed during the range specified by dtstart and dtend.
If the times specified in the dtstart and dtend parameters is not Zulu time, the system uses the time zone specified in the tzid parameter to translate the times into Zulu time for data retrieval. If the tzid parameter is missing, the system uses the server’s default time zone.
The system uses the tzidout parameter to determine what time zone to translate retrieved data into before returning it. If the tzidout parameter is missing, the system returns the data in Zulu time.
If neither the starting nor ending date-time is specified, the server returns all events and todos that have changed, up to the specified maximum.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If a calendar cannot be accessed or is missing, the error number is appended to the error string.
Example
For example, the calendar jdoe has these three events:
Here are some queries and their return values:
http://webcalendarserver/fetchcomponents_by_lastmod.wcap?id=jdoe
&dtstart=0&dtend=0The above query would fetch all events and todos that have ever been modified. Thus eventA, eventB, and todoA would be returned.
http://webcalendarserver/fetchcomponents_by_lastmod.wcap?id=jdoe
&dtstart=20011201T112233Z&dtend=20020131T112233ZThe above query would fetch all modified events and todos between 12/1/2001 and 1/31/2002. Thus eventB and todoA would be returned.
http://webcalendarserver/fetchcomponents_by_lastmod.wcap?id=jdoe
&dtstart=20020101T112233Z&dtend=20020601T112233ZThe above query would fetch all events and todos that have been modified between 1/1/2002 and 6/1/2002. Thus eventA and todoA would be returned.
fetchcomponents_by_rangePurpose
Retrieve calendar events and todos.
Parameters
Table 7-15 lists fetchcomponents_by_range parameters:
Table 7-15 fetchcomponents_by_range Parameters
Parameter
Type
Purpose
Required
Default
attrset
integer (0, 1, 2)
Indicates to the server to retrieve the complete vEvent or vTask data, or if they just want a subset of the data for each matching component. (This can reduce the amount of processing a client must do.)
2 = Returns the full event and is the default.
1 = Returns the following fields only: UID, RRULE, DTSTART, DTEND, SUMMARY, CLASS, LOCATION, VALARM
0 = Returns the following fields only: UID, DTSTART, DTEND, SUMMARY
N
2
calid
string
A semicolon-separated list of calendar identifiers.
The calid can be supplied in two formats:
N
Current user’s calid.
component-type
keyword (event, todo, all)
Indicates which components to return: event returns only events
todo returns only todos (tasks)
all returns both events and todosIf an invalid value is passed in, the system assumes all.
N
all
compressed
integer (0,1)
This parameter is deprecated in this release and may be deleted in future releases.
For compressed=0, returns less data. Specifically, it does not return the following parameters:
rrules
rdate
exrule
exdateFor compressed=1, all recurrence data is returned.
N
0
compstate
semicolon-separated list of component state keywords
The list of component states to fetch.
For compstate values, see Table 6-5.
N
ALL
dtend
DateTime string
End time and date of events to be returned.
A value of 0 means fetch all events.
N
0
dtstart
DateTime string
Start time and date of events to be returned.
A value of 0 means fetch all events from the beginning of time.
N
0
emailorcalid
integer (0, 1)
0 = The calid is returned in the cal-address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-EMAIL has the RFC 822 email address of the invitee or organization.
1 = The email address is returned in the cal-address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-CALID contains the calid value.
N
0
fetchorder
integer
Specifies the order in which the events and todos are returned.
The values are:
N
0
filter
string
Name/value pair that represents a filter for an event. The left side is any valid property of an event or todo from RFC 2445. Only single valued filters are currently supported. For example: filter=(ATTENDEE=jdoe@sesta.com) where the left side of the value is a property from RFC 2445 and the right side is the value to match in the events and todos. The following are the only supported properties for filtering:
N
NULL
fmt-out
string
The format for the returned data. Either:
text/calendar
text/xmlN
text/
calendarid
unique identifier string
The session identifier.
Y
N/A
invitecount
integer (0, 1)
1 = Requests the server to return the open invitations count, that is, events where PARSTAT=needs-action. The integer count is returned in the X-Token X-S1CS-CALPROPS-INVITATION-COUNT.
if more than one calid is specified in the calid parameter, the open invitation count for each calendar is returned in the corresponding iCal or iCal XML block.
0 = Count not requested.
N
0
maxResults
integer
(currently not implemented) The maximum number of events and todos to be returned. When 0, no maximum is applied and the command returns all events and todos found.
N
0
recurring
integer (0, 1)
Whether to return all components in compressed form (1) or not (0). (Compressed form has master entry plus exceptions.)
N
0 (not compressed)
relativealarm
integer (0, 4)
Return the alarm as relative or absolute.
0—Return alarm values as absolute.
4—Return alarms as originally created.N
0 (absolute)
searchOpts
integer
0,1,2,3
How to perform the search. One of the following:
0 = CONTAINS
1 = BEGINS_WITH
2 = ENDS_WITH
3 = EXACTN
0
tzid
time zone ID string
Default time zone to use if dtstart, or dtend parameters are not in Zulu time.
For example, “America/Los_Angeles”
N
server’s default time zone
tzidout
time zone ID string
Time zone to report returned data in.
N
Zulu time
Description.
Use this command to retrieve properties, events, and todos from one or more specified calendars.
Output Format
The server returns data in the format specified by the fmt-out parameter. If this parameter is not passed, the data is returned in the default text/calendar format.
Returns
For each calendar specified in calid, the server returns the calendar's properties and the events and todos of that calendar that fall within the range specified by dtstart and dtend.
Tasks returned by this command:
If the times specified in the dtstart and dtend parameters is not Zulu time, the system uses the time zone specified in the tzid parameter to translate the times into Zulu time for data retrieval. If the tzid parameter is missing, the system uses the server’s default time zone.
The system uses the tzidout parameter to determine what time zone to translate retrieved data into before returning it. If the tzidout parameter is missing, the system returns the data in Zulu time.
If neither the starting nor ending date-time is specified, the server returns all events and todos, up to the specified maximum.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If a calendar cannot be accessed or is missing, the error number is appended to the error string.
Output Format
The server returns data in the format specified by the fmt-out parameter. If this parameter is not passed, the data is returned in the default text/calendar format.
maxResults Value
If you specify a maximum n, the command returns up to the first n events and first n todos in the specified range. For example, if you specify a maxResults value of 75, the returned data would contain the following variables
var maxResults=75 /* maximum cap passed in */
var size=75 /* event size is capped to 75 */
var todosize=28 /* todo size not affected since it is less than 75 */If the maxResults parameter is set to 0 or is not passed, then the command does not cap the number of returned components, and the returned data does not contain the var maxResults statement.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If a calendar cannot be accessed or is missing, the error number is appended to the error string.
Example
Example 1
This example fetches components for the current user from Dec. 1, 2001 to Jan. 31, 2002, using the following URL:
http://webcalendarserver/fetchcomponents_by_range.wcap?id=bes6bbe2mu98uw9& dtstart=20011201T000000Z&dtend=20020131T000000Z&fmt-out=text/calendar
It returns one event and one todo for this period:
BEGIN:VCALENDAR
PRODID:-//SunJavaSystem/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:20011208T005613Z
X-NSCP-CALPROPS-CREATED:20010913T223336Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe
X-NSCP-CALPROPS-NAME:John Doe
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-TZID:America/Los_Angeles
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^WDEIC^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^RSF^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^a^frs^
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^c^dw^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^a^rs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^c^w^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^p^r^g
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VEVENT
UID:3c11625900005ffe00000011000010b7
DTSTAMP:20011208T015014Z
SUMMARY:eventA
DTSTART:20011225T133000Z
DTEND:20011225T143000Z
CREATED:20011208T004409Z
LAST-MODIFIED:20011208T010857Z
PRIORITY:0
SEQUENCE:4
ORGANIZER;SENT-BY="jdoe@sesta.com"
;X-NSCP-ORGANIZER-UID=jdoe
;X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe
STATUS:CONFIRMED
TRANSP:OPAQUE
ATTENDEE;ROLE=REQ-PARTICIPANT;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED;
CN="John Smith";RSVP=TRUE;X-NSCP-ATTENDEE-GSE-STATUS=2:jsmith
X-NSCP-ORIGINAL-DTSTART:20020210T190000Z
X-NSCP-LANGUAGE:en
BEGIN:VALARM
ACTION:EMAIL
TRIGGER;VALUE=DATE-TIME:20011225T123000Z
ATTENDEE:MAILTO:jsmith@company22.com
END:VALARM
X-NSCP-DTSTART-TZID:America/Los_Angeles
X-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0
X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com
X-NSCP-GSE-COMPONENT-STATE;X-NSCP-GSE-COMMENT="REQUEST-COMPLETED":
31074
END:VEVENT
BEGIN:VTODO
UID:3c1162e200207ff600000015000010b7
DTSTAMP:20011208T015014Z
SUMMARY:todoA
DTSTART:20011208T004626Z
DUE:20020120T141500Z
CREATED:20011208T004626Z
LAST-MODIFIED:20011208T011000Z
PRIORITY:0
SEQUENCE:3
PERCENT-COMPLETE:0
ORGANIZER;SENT-BY="jdoe@sesta.com"
;X-NSCP-ORGANIZER-UID=jdoe
;X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe
STATUS:NEEDS-ACTION
X-NSCP-ORIGINAL-DTSTART:20011208T004626Z
X-NSCP-LANGUAGE:en
BEGIN:VALARM
ACTION:EMAIL
TRIGGER;VALUE=DATE-TIME:20020120T131500Z
ATTENDEE:MAILTO:jsmith@company22.com
END:VALARM
X-NSCP-DUE-TZID:America/Los_Angeles
X-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0
X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com
X-NSCP-GSE-COMPONENT-STATE;X-NSCP-GSE-COMMENT="PUBLISH-COMPLETED":
5538
END:VTODO
X-NSCP-WCAP-ERRNO:0
END:VCALENDARExample 2
The second example fetches all components for calendars jdoe and susan between Dec. 1, 2001 to Jan. 31, 2002.
http://webcalendarserver/fetchcomponents_by_range.wcap?id=bes6bbe2mu98uw9& calid=jdoe;susan&dtstart=20020101T000000Z&dtend=20020202T000000Z&fmt-out=t ext/calendar
The following events and todos are returned:
BEGIN:VCALENDAR
PRODID:-//SunJavaSystem/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:20011208T005613Z
X-NSCP-CALPROPS-CREATED:20010913T223336Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe
X-NSCP-CALPROPS-NAME:John Doe
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-TZID:America/Los_Angeles
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^WDEIC^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^RSF^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^c^dw^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^a^rs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^c^w^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^p^r^g
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VEVENT
UID:3c1162b3000051c300000013000010b7
DTSTAMP:20011208T011645Z
SUMMARY:Joe’s event
DTSTART:20020110T110000Z
DTEND:20020110T120020Z
CREATED:20011208T004539Z
LAST-MODIFIED:20011208T011638Z
PRIORITY:0
SEQUENCE:4
ORGANIZER;SENT-BY="jdoe@sesta.com";
X-NSCP-ORGANIZER-UID=jdoe;
X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe
STATUS:CONFIRMED
TRANSP:OPAQUE
ATTENDEE;ROLE=REQ-PARTICIPANT;CUTYPE=INDIVIDUAL;PARTSTAT=ACCEPTED;
CN="John Smith";RSVP=TRUE;X-NSCP-ATTENDEE-GSE-STATUS=2:jsmith
X-NSCP-ORIGINAL-DTSTART:20021225T213000Z
X-NSCP-LANGUAGE:en
BEGIN:VALARM
ACTION:EMAIL
TRIGGER;VALUE=DATE-TIME:20020210T100000Z
ATTENDEE:MAILTO:jsmith@company22.com
END:VALARM
X-NSCP-DTSTART-TZID:America/Los_Angeles
X-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0
X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com
X-NSCP-GSE-COMPONENT-STATE;
X-NSCP-GSE-COMMENT="REQUEST-COMPLETED":31074
END:VEVENT
BEGIN:VTODO
UID:3c1162e200207ff600000015000010b7
DTSTAMP:20011208T011645Z
SUMMARY:Joe’s Todo
DTSTART:20011208T004626Z
DUE:20020120T141500Z
CREATED:20011208T004626Z
LAST-MODIFIED:20011208T011000Z
PRIORITY:0
SEQUENCE:3
PERCENT-COMPLETE:0
ORGANIZER;SENT-BY="jdoe@sesta.com";
X-NSCP-ORGANIZER-UID=jdoe;
X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe
STATUS:NEEDS-ACTION
X-NSCP-ORIGINAL-DTSTART:20011208T004626Z
X-NSCP-LANGUAGE:en
BEGIN:VALARM
ACTION:EMAIL
TRIGGER;VALUE=DATE-TIME:20020120T131500Z
ATTENDEE:MAILTO:jdoe@sesta.com
END:VALARM
X-NSCP-DUE-TZID:America/Los_AngelesX-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:
X-NSCP-ORGANIZR-EMAIL:jdoe@sesta.com
X-NSCP-GSE-COPONENT-STATE;
X-NSCP-GSE-COMMENT="PUBLISH-COMPLETED":6538
END:VTODO
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
BEGIN:VCALENDAR
PRODID:-//SunJavaSystem/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:19700101T000000Z
X-NSCP-CALPROPS-CREATED:19700101T000000Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:susan
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VCALENDAR
PRODID:-//SunJavaSystem/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:20011010T001050Z
X-NSCP-CALPROPS-CREATED:20000929T180436Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:susan
X-NSCP-CALPROPS-NAME:default
X-NSCP-CALPROPS-PRIMARY-OWNER:susan
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^WDEIC^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^RSF^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:fred^a^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:fred^c^^g
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VEVENT
UID:3c1162b3000051c300000013000010b7
DTSTAMP:20011208T011645Z
SUMMARY: Susan’s event
DTSTART:20020110T110000Z
DTEND:20020110T120020Z
CREATED:20011208T004539Z
LAST-MODIFIED:20011208T011638Z
PRIORITY:0
SEQUENCE:4
ORGANIZER;SENT-BY="susan@sesta.com";
X-NSCP-ORGANIZER-UID=susan;
X-NSCP-ORGANIZER-SENT-BY-UID=susan:susan
STATUS:CONFIRMED
TRANSP:OPAQUE
ATTENDEE;ROLE=REQ-PARTICIPANT;CUTYPE=INDIVIDUAL;
PARTSTAT=ACCEPTED;CN="Mary Anderson";RSVP=TRUE;
X-NSCP-ATTENDEE-GSE-STATUS=2:marya
X-NSCP-ORIGINAL-DTSTART:20021225T213000Z
X-NSCP-LANGUAGE:en
BEGIN:VALARM
ACTION:EMAIL
TRIGGER;VALUE=DATE-TIME:20020210T100000Z
ATTENDEE:MAILTO:marya@company22.com
END:VALARM
X-NSCP-DTSTART-TZID:America/Los_Angeles
X-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0
X-NSCP-ORGANIZER-EMAIL:susan@seata.com
X-NSCP-GSE-COMPONENT-STATE;
X-NSCP-GSE-COMMENT="REQUEST-COMPLETED":131074
END:VEVENT
BEGIN:VTODO
UID:3c1162e200207ff600000015000010b7
DTSTAMP:20011208T011645Z
SUMMARY:susan’s todo
DTSTART:20011208T004626Z
DUE:20020120T141500Z
CREATED:20011208T004626Z
LAST-MODIFIED:20011208T011000Z
PRIORITY:0
SEQUENCE:3
PERCENT-COMPLETE:0
ORGANIZER;SENT-BY="susan@sesta.com";
X-NSCP-ORGANIZER-UID=crowe;
X-NSCP-ORGANIZER-SENT-BY-UID=susan:susa
STATUS:NEEDS-ACTION
X-NSCP-ORIGINAL-DTSTART:20011208T004626Z
X-NSCP-LANGUAGE:en
BEGIN:VALARM
ACTION:EMAIL
TRIGGER;VALUE=DATE-TIME:20020120T131500Z
ATTENDEE:MAILTO:susan@sesta.com
END:VALARM
X-NSCP-DUE-TZID:America/Los_Angeles
X-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0
X-NSCP-ORGANIZER-EMAIL:mailto:susan@sesta.com
X-NSCP-GSE-COMPONENT-STATE;
X-NSCP-GSE-COMMENT="PUBLISH-COMPLETED":65538
END:VTODO
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
fetch_deletedcomponentsPurpose.
Returns a list of deleted components from the deletelog.db for a specified time period.
Parameters.
Table 7-14 lists fetch_deletedcomponents parameters
Description.
Use this command to retrieve a list of events and todos that have been deleted during a specific time period. For recurring format components, this command should be used in conjunction with fetchcomponents_by_lastmod in order to return recurring instances that are still active.
Output Format
The server returns data in the format specified by the fmt-out parameter. If this parameter is not passed, the data is returned in the default text/calendar format.
maxResults Value
If you specify a maximum n, the command returns up to the first n events and first n todos in the specified range. For example, if you specify a maxResults value of 75, the returned data would contain the following variables
var maxResults=75 /* maximum cap passed in */
var size=75 /* event size is capped to 75 */
var todosize=28 /* todo size not affected since it is less than 75 */If the maxResults parameter is set to 0 or is not passed, then the returned data does not contain the var maxResults statement.
Returns
When this command is called in compressed mode (with recurring =1), the query interface goes through the Delete Log database and returns all the non-repeating entries and the master components deleted that match the criteria. This pass ignores the recurring instances that are stored in the database. This will not return any master entries associated with the deleted recurring instances that are still active. Those active master entries will be returned using the fetchcomponents_by_lastmod command. If all the instances in a recurring chain are deleted, the master component will return dtstart, dtend, rrules, rdates, exrules, exdates and uid.
When the command is called in expanded mode (with recurring=0), the query interface goes through the Delete Log database and returns all instances of recurring components. Specifically, it does not return the master component.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If a calendar cannot be accessed or is missing, the error number is appended to the error string.
The following failure codes can be returned:
- X-NSCP-WCAP-ERRNO:1 - Session ID timed out or Invalid session ID
- X-NSCP-WCAP-ERRNO:28 - Command failed; user denied access to a calendar
- X-NSCP-WCAP-ERRNO:29 - Command failed; calendar does not exist in the database
- X-NSCP-WCAP-ERRNO:56 - Fetch deleted components failed
- X-NSCP-WCAP-ERRNO:57 - Success but partial result
Example
Fetching Deleted Components (recurring defaults to 0)
http://webcalendarserver/fetch_deletedcomponents.wcap?d=8sh8ubh2rbl08u&fmt -out=text/calendar&calid=jdoe
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:2.0
X-NSCP-CALPROPS-LAST-MODIFIED:20030110T222754Z
X-NSCP-CALPROPS-CREATED:20030110T221814Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe
X-NSCP-CALPROPS-NAME:john doe
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-OWNERS:""
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^wdeic^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^sf^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VEVENT
UID:3e224e5b000041c6000000010000664b
DTSTAMP:20030113T055314Z
DTSTART:20030114T060000Z
DTEND:20030114T070000Z
LAST-MODIFIED:20030113T052800Z
X-NSCP-TRIGGERED_BY:jdoe
END:VEVENT
BEGIN:VTODO
UID:3e2254bd000041c600000001000066eb
DTSTAMP:20030113T055517Z
DTSTART:20030113T055509Z
DUE:20030114T060000Z
LAST-MODIFIED:20030113T055513Z
END:VTODO
X-NSCP-WCAP-ERRNO:0
END:VCALENDARFetching Deleted Components (In recurring format, recurring defaults to 0)
http://webcalendarserver/fetch_deletedcomponents.wcap?d=8sh8ubh2rbl08u&fmt -out=text/calendar&calid=jdoe
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:2.0
X-NSCP-CALPROPS-LAST-MODIFIED:20030110T222754Z
X-NSCP-CALPROPS-CREATED:20030110T221814Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe
X-NSCP-CALPROPS-NAME:john doe
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-OWNERS:""
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^wdeic^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^sf^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VEVENT
UID:3e224e5b000041c6000000010000664b
DTSTAMP:20030113T055314Z
DTSTART:20030114T060000Z
DTEND:20030114T070000Z
LAST-MODIFIED:20030113T052800Z
X-NSCP-TRIGGERED_BY:jdoe
END:VEVENTFetching Deleted Components (In recurring format, recurring=1)
http://webcalendarserver/fetch_deletedcomponents.wcap?d=8sh8ubh2rbl08u&fmt -out=text/calendar&calid=jdoe&recurring=1
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:2.0
X-NSCP-CALPROPS-LAST-MODIFIED:20030110T222754Z
X-NSCP-CALPROPS-CREATED:20030110T221814Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe
X-NSCP-CALPROPS-NAME:john doe
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-OWNERS:""
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^wdeic^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^sf^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VEVENT
UID:3e224e5b000041c6000000010000664b
DTSTAMP:20030113T055314Z
DTSTART:20030114T060000Z
DTEND:20030114T070000Z
LAST-MODIFIED:20030113T052800Z
X-NSCP-TRIGGERED_BY:jdoe
END:VEVENT
BEGIN:VEVENT
UID:3e2255380000278100000003000066eb
DTSTAMP:20030113T055758Z
DTSTART:20030114T060000Z
DTEND:20030114T070000Z
LAST-MODIFIED:20030113T055721Z
RRULE:FREQ=WEEKLY;INTERVAL=1;WKST=SU;COUNT=5
X-NSCP-TRIGGERED_BY:jdoe
END:VEVENT
BEGIN:VEVENT
UID:3e2255ed00000ff60000000a000066eb
DTSTAMP:20030113T060117Z
DTSTART:20030114T060000Z
DTEND:20030114T070000Z
LAST-MODIFIED:20030113T060107Z
EXDATE:20030116T060000Z
EXDATE:20030116T060000Z
EXDATE:20030116T060000Z
RRULE:FREQ=DAILY;INTERVAL=1;WKST=SU;COUNT=5
X-NSCP-TRIGGERED_BY:jdoe
END:VEVENT
BEGIN:VTODO
UID:3e2254bd000041c600000001000066eb
DTSTAMP:20030113T055517Z
DTSTART:20030113T055509Z
DUE:20030114T060000Z
LAST-MODIFIED:20030113T055513Z
END:VTODO
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
fetchevents_by_idPurpose
Retrieve specific calendar events.
Parameters
Table 7-17 lists fetchevents_by_id parameters:
Table 7-17 fetchevents_by_id Parameters
Parameter
Type
Purpose
Required
Default
calid
string
A semicolon-separated list of calendar identifiers.
The calid can be supplied in two formats:
N
Current user’s calid.
compressed
integer (0,1)
This parameter has been deprecated for this release and may be removed from future versions.
For compressed=0, returns less data. Specifically, it does not return the following parameters:
rrules
rdate
exrule
exdateFor compressed=1, all recurrence data is returned.
N
0
compstate
semicolon-
separated list of component state keywordsThe list of component states to fetch.
For compstate values, see Table 6-5.
N
ALL
emailorcalid
integer (0, 1)
0 = The calid is returned in the cal-address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-EMAIL has the RFC 822 email address of the invitee or organization.
1 = The email address is returned in the cal-address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-CALID contains the calid value.
N
0
fmt-out
string
The format for the returned data.
The three format types:
text/calendar
text/xmlN
text/
calendarid
unique identifier string
The session identifier.
Y
N/A
mod
integer
A modifier indicating which recurrences to retrieve. One of the following values:
1 = THISINSTANCE
2 = THISANDFUTURE
3 = THISANDPRIOR
4 = THISANDALLN
1
(THISINSTANCE)
recurring
integer (0, 1)
Whether to return all components in compressed form (1) or not (0). (Compressed form has master entry plus exceptions.)
N
0 (not compressed)
relativealarm
integer (0, 4)
Return the alarm as relative or absolute.
0—Return alarm values as absolute.
4—Return alarms as originally created.N
0 (absolute)
rid
ISO 8601 DateTime string
The recurrence identifier for the event. For a nonrecurring event, set to 0.
N
0
tzid
time zone ID string
Time zone to use if the rid parameter is not in Zulu time.
For example, “America/Los_Angeles”
N
server’s default time zone
tzidout
time zone ID string
Time zone that returned data should be translated to.
N
Returns data in Zulu time
uid
sting
The unique identifier for the event.
Y
N/A
Description.
Use this command to retrieve the specified events and recurrences from the specified calendar. You must specify the id parameter with the command unless the specified calendar is a public calendar. The command returns recurrences as specified by the mod parameter. See Recurring Components – Overview.
Output Format
The server returns data in the format specified by the fmt-out parameter. If this parameter is not passed, the data is returned in the default format.
Returns
The system uses the tzidout parameter to determine what time zone to translate retrieved data into before returning it. If the tzidout parameter is missing, the system returns the data in Zulu time.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If a calendar cannot be accessed or is missing, the error number is appended to the error string.
Example
This query retrieves an event with a specific id.
http://webcalendarserver/fetchevents_by_id.wcap?id=bes6bbe2mu98uw9&calid=j doe&uid=3c11625900005ffe00000011000010b7
&fmt-out=text/calendarIt returns one event:
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:20011208T005613Z
X-NSCP-CALPROPS-CREATED:20010913T223336Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe
X-NSCP-CALPROPS-NAME:John Doe
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-TZID:America/Los_Angeles
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^WDEIC^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^RSF^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^c^dw^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^a^rs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^c^w^gX-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^p^r^g
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VEVENT
UID:3c11625900005ffe00000011000010b7
DTSTAMP:20011208T015845Z
SUMMARY:eventA
DTSTART:20011225T133000Z
DTEND:20011225T143000Z
CREATED:20011208T004409Z
LAST-MODIFIED:20011208T010857Z
PRIORITY:0
SEQUENCE:4
ORGANIZER;SENT-BY="jdoe@sesta.com";
X-NSCP-ORGANIZER-UID=jdoe;
X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe
STATUS:CONFIRMED
TRANSP:OPAQUE
ATTENDEE;ROLE=REQ-PARTICIPANT;CUTYPE=INDIVIDUAL;
PARTSTAT=ACCEPTED;CN="John Smith";RSVP=TRUE;
X-NSCP-ATTENDEE-GSE-STATUS=2:jsmith
X-NSCP-ORIGINAL-DTSTART:20020210T190000Z
X-NSCP-LANGUAGE:en
BEGIN:VALARM
ACTION:EMAIL
TRIGGER;VALUE=DATE-TIME:20011225T123000Z
ATTENDEE:MAILTO:jdoe@sesta.com
END:VALARM
X-NSCP-DTSTART-TZID:America/Los_Angeles
X-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0
X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com
X-NSCP-GSE-COMPONENT-STATE;
X-NSCP-GSE-COMMENT="REQUEST-COMPLETED":31074
END:VEVENT
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
fetchtodos_by_idPurpose
Retrieve specific calendar todos.
Parameters
Table 7-18 lists fetchtodos_by_id parameters:
Table 7-18 fetchtodos_by_id Parameters
Parameter
Type
Purpose
Required
Default
calid
string
A semicolon-separated list of calendar identifiers.
The calid can be supplied in two formats:
N
Current user’s calid.
compressed
integer (0,1)
This parameter has been deprecated for the current release and may be removed from future releases.
For compressed=0, returns less data. Specifically, it does not return the following parameters:
rrules
rdate
exrule
exdateFor compressed=1, all recurrence data is returned.
N
0
compstate
semicolon-separated list of component state keywords
The list of component states to fetch.
For compstate values, see Table 6-5.
N
ALL
emailorcalid
integer (0, 1)
0 = The calid is returned in the cal-address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-EMAIL has the RFC 822 email address of the invitee or organization.
1 = The email address is returned in the cal-address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-CALID contains the calid value.
N
0
fmt-out
string
The format for the returned data.
The three format types:
text/calendar
text/xmlN
text/
calendarid
unique identifier string
The session identifier.
Y
N/A
mod
integer
A modifier indicating which recurrences to retrieve. One of the following values:
1 = THISINSTANCE
2 = THISANDFUTURE
3 = THISANDPRIOR
4 = THISANDALLN
1
(THISINSTANCE)
recurring
integer (0, 1)
Whether to return all components in compressed form (1) or not (0). (Compressed form has master entry plus exceptions.)
N
0 (not compressed)
relativealarm
integer (0, 4)
Return the alarm as relative or absolute.
0—Return alarm values as absolute.
4—Return alarms as originally created.N
0 (absolute)
rid
ISO 8601 DateTime string
The recurrence identifier for the todo. For a nonrecurring todo, set to 0.
N
0
tzid
time zone ID string
Time zone to use if the rid parameter is not in Zulu time.
For example, “America/Los_Angeles”
N
server’s default time zone
tzidout
time zone ID string
Time zone the returned data should be translated to.
N
Returns data in Zulu time
uid
sting
The unique identifier for the todo.
Y
N/A
Description
Use this command to retrieve the specified todo and its recurrences from the specified calendar. You must specify the id parameter with the command unless the specified calendar is a public calendar.
Output Format
The server returns data in the format specified by the fmt-out parameter. If this parameter is not passed, the data is returned in the default text/calendar format.
Returns
For each calendar specified in calid, the server returns the calendar's todos of that calendar. If the todo has recurrences, it returns them as specified by the rid and mod parameters. See Recurring Components – Overview.
If the times specified in the rid parameter is not Zulu time, the system uses the time zone specified in the tzid parameter to translate the times into Zulu time for data retrieval. If the tzid parameter is missing, the system uses the server’s default time zone.
The system uses the tzidout parameter to determine what time zone to translate retrieved data into before returning it. If the tzidout parameter is missing, the system returns the data in Zulu time.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If a calendar cannot be accessed or is missing, the error number is appended to the error string.
Example
For example, a todo "weekly todo B" that’s due weekly at 5:00pm starting on Feb 1, 2002 and ending on Mar 1, 2002.
Example 1
This query fetches just the first todo, on Feb 1, 2002, because the recurrence ID of the first item is specified (rid=20020201T170000Z) but no modifier is specified, so it defaults to 1 (THISINSTANCE):
http://webcalendarserver/fetchtodos_by_id.wcap?
id=n3o3m05sx9v6t98t8u2p&uid=3c15309d000037020020021400003189&
rid=20020201T170000Z&fmt-out=text/calendarThe following output is generated:
BEGIN:VCALENDARPRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLIS
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:20011208T005613Z
X-NSCP-CALPROPS-CREATED:20010913T223336Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe
X-NSCP-CALPROPS-NAME:John Doe
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-TZID:America/Los_Angeles
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^WDEIC^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^RSF^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^c^dw^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^a^rs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^c^w^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^p^r^g
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VTODO
UID:3c15309d000037020020021400003189
RECURRENCE-ID:20020201T170000Z
DTSTAMP:20011210T222131Z
SUMMARY:weekly todo B
DTSTART:20020201T170000Z
DUE:20020201T170000Z
CREATED:20011210T220101Z
LAST-MODIFIED:20011210T220101Z
PRIORITY:0
SEQUENCE:0
PERCENT-COMPLETE:0
ORGANIZER;SENT-BY="jdoe@sesta.com";
X-NSCP-ORGANIZER-UID=jdoe;
X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe
STATUS:NEEDS-ACTION
X-NSCP-ORIGINAL-DTSTART:20020201T170000Z
X-NSCP-LANGUAGE:en
X-NSCP-DUE-TZID:Europe/London
X-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0
X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com
X-NSCP-GSE-COMPONENT-STATE;
X-NSCP-GSE-COMMENT="PUBLISH-COMPLETED":65538
END:VTODO
X-NSCP-WCAP-ERRNO:0
END:VCALENDARExample 2
This query fetches the last two recurrences by specifying the recurrence ID of the second to last recurrence on Feb. 22, 2002 (rid=20020222T170000Z) and a modifier of 2 (mod=2) which means THISANDFUTURE recurrences:
http://webcalendarserver/fetchtodos_by_id.wcap?
id=n3o3m05sx9v6t98tu2p&uid=3c15309d000037020020021400003189&
rid=20020222T170000Z&mod=2&fmt-out=text/calendarThe results of the query are as follows:
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:20011208T005613Z
X-NSCP-CALPROPS-CREATED:20010913T223336Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe
X-NSCP-CALPROPS-NAME:John Doe
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-TZID:America/Los_Angeles
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^WDEIC^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^RSF^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^c^dw^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^a^rs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^c^w^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^p^r^g
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VTODO
UID:3c15309d000037020020021400003189
RECURRENCE-ID:20020222T170000Z
DTSTAMP:20011210T222757Z
SUMMARY:weekly todo B
DTSTART:20020222T170000Z
DUE:20020222T170000Z
CREATED:20011210T220101Z
LAST-MODIFIED:20011210T220101Z
PRIORITY:0
SEQUENCE:0
PERCENT-COMPLETE:0
ORGANIZER;SENT-BY="jdoe@sesta.com";
X-NSCP-ORGANIZER-UID=jdoe;
X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe
STATUS:NEEDS-ACTION
X-NSCP-ORIGINAL-DTSTART:20020222T170000Z
X-NSCP-LANGUAGE:en
X-NSCP-DUE-TZID:Europe/London
X-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0
X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com
X-NSCP-GSE-COMPONENT-STATE;
X-NSCP-GSE-COMMENT="PUBLISH-COMPLETED":65538
END:VTODO
BEGIN:VTODO
UID:3c15309d000037020020021400003189
RECURRENCE-ID:20020301T170000Z
DTSTAMP:20011210T222757Z
SUMMARY:weekly todo B
DTSTART:20020301T170000Z
DUE:20020301T170000Z
CREATED:20011210T220101Z
LAST-MODIFIED:20011210T220101Z
PRIORITY:0
SEQUENCE:0
PERCENT-COMPLETE:0
ORGANIZER;SENT-BY="jode@sesta.com";
X-NSCP-ORGANIZER-UID=jdoe;
X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe
STATUS:NEEDS-ACTION
X-NSCP-ORIGINAL-DTSTART:20020301T170000Z
X-NSCP-LANGUAGE:en
X-NSCP-DUE-TZID:Europe/London
X-NSCP-TOMBSTONE:0
X-NSCP-ONGOING:0
X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com
X-NSCP-GSE-COMPONENT-STATE;
X-NSCP-GSE-COMMENT="PUBLISH-COMPLETED":65538
END:VTODO
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
get_all_timezonesPurpose
Retrieve data about all timezones supported by the server.
Parameters
Table 7-19 lists get_all_timezones parameters:
Description.
Use this command to retrieve data about all timezones that are supported by the server. The crossover values are defined to be the dates when the timezone enters/exits daylight savings time. The odd index dates are the beginning of daylight-savings. The even index dates are the end of daylight-savings. If the timezone does not have daylight-savings, then this value will be set to the empty-string.
Returns
If you specify a range of years with the dtstart and dtend parameters, the command returns only the crossover dates for the years within the range. Otherwise, it returns all crossover dates from the first to the last known year (1987-2087).
The server returns data in the format specified by the fmt-out parameter. If you do not pass in the fmt-out parameter, the server uses the default text/calendar format.
Error Codes
If there was an error in getting the timezones, the server returns the error GET_ALL_TIMEZONES_FAILED(24).
Example
The first example shows the command output. The second example is a crossover array.
Example 1
This query gets all time zones.
http://calendarserver/get_all_timezones.wcap?
id=2m2ns6w9x9h2mr6p3b&fmt-out=text/calendarThis is the result of the query:
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:19700101T000000Z
X-NSCP-CALPROPS-CREATED:19700101T000000Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:default
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^wdeic^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^sf^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g
X-NSCP-CALPROPS-RESOURCE:0
BEGIN:VTIMEZONE
TZID:Africa/Amman
BEGIN:STANDARD
DTSTART:19950920T000000
TZOFFSETFROM:+0300
TZOFFSETTO:+0200
TZNAME:EEST
RRULE:FREQ=YEARLY;BYDAY=-1FR;BYMONTH=9
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:19930420T000000
TZOFFSETFROM:+0200
TZOFFSETTO:+0300
TZNAME:EEDT
RRULE:FREQ=YEARLY;BYDAY=-1FR;BYMONTH=4
END:DAYLIGHT
END:VTIMEZONE
BEGIN:VTIMEZONE
TZID:Africa/Cairo
BEGIN:STANDARD
DTSTART:19950924T000000
TZOFFSETFROM:+0300
TZOFFSETTO:+0200
TZNAME:EEST
COMMENT:this is a comment
RRULE:FREQ=YEARLY;BYDAY=-1FR;BYMONTH=9
END:STANDARD
BEGIN:DAYLIGHT
DTSTART:19950420T000000
TZOFFSETFROM:+0200
TZOFFSETTO:+0300
TZNAME:EEDT
RRULE:FREQ=YEARLY;BYDAY=-1FR;BYMONTH=4
END:DAYLIGHT
END:VTIMEZONE
BEGIN:VTIMEZONE...(other time zones omitted to conserve space)
BEGIN:VTIMEZONE
TZID:Pacific/Tongatapu
BEGIN:STANDARD
DTSTART:19970101T000000
TZOFFSETFROM:+1300
TZOFFSETTO:+1300
TZNAME:TOT
TZNAME:PHOT
END:STANDARD
END:VTIMEZONE
X-NSCP-WCAP-ERRNO:0
END:VCALENDARExample 2
The following is an example of a timezone array element where crossover dates have been limited to the years from mid-1998 to 2006:
timezoneList[20] = new TZ('America/Los_Angeles',
'PST',
'PDT',
'-0800',
'-0700',
new Array
('19981025T090000Z','20020404T100000Z','20021031T090000Z',
'20020402T100000Z','20021029T090000Z','20020401T100000Z',
'20021028T090000Z', '20020407T100000Z', '20021027T090000Z',
'20030406T100000Z', '20031026T090000Z', '20040404T100000Z',
'20041031T090000Z', '20050403T100000Z', '20051030T090000Z',
'20060402T100000Z', '20061029T090000Z'))The "America/Phoenix" timezone does not have daylight-savings. Thus the daylight elements exactly equal the standard elements. Also, the crossover strings are set to the empty string.
timezoneList[23] = new TZ(’America/Phoenix’,
’MST’,
’MST’,
’-0700’,
’-0700’,
new Array())
get_calpropsPurpose
Retrieve calendar properties.
Parameters
Table 7-20 lists get_calprops parameters:
Description.
Use this command to retrieve the calendar properties for the specified calendars.
Returns
The command returns a page with the following X-Tokens containing property information for the specified calendars:
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY
X-NSCP-CALPROPS-CALMASTER
X-NSCP-CALPROPS-CATEGORIES
X-NSCP-CALPROPS-CHARSET
X-NSCP-CALPROPS-CHILDREN
X-NSCP-CALPROPS-CREATED
X-NSCP-CALPROPS-DESCRIPTION
X-NSCP-CALPROPS-LANGUAGE
X-NSCP-CALPROPS-LAST-MODIFIED
X-NSCP-CALPROPS-NAME
X-NSCP-CALPROPS-OWNERS
X-NSCP-CALPROPS-PRIMARY-OWNER
X-NSCP-CALPROPS-READ
X-NSCP-CALPROPS-RELATIVE-CALID
X-NSCP-CALPROPS-RESOURCE
X-NSCP-CALPROPS-TZID
X-NSCP-CALPROPS-WRITE
X-S1CS-CALPROPS-ALLOW-DOUBLEBOOKING
X-S1CS-CALPROPS-COMMON-NAME
X-S1CS-CALPROPS-FB-INCLUDE
X-S1CS-CALPROPS-INVITATION-COUNTError Codes
If the calendar exists, but the user does not have READ access to it, errno is set to ACCESS_DENIED_TO_CALENDAR (28).
If the fetch fails for any calendar, its error number, errno, is set to GET_CALPROPS_FAILED(20).
Example
In the following example, you want to retrieve the calendar properties for the calendars jdoe, jsmith, and susan, in that order.
This is the URL:
http://webcalendarserver/get_calprops.wcap?id=2mu95r5so0hq68ts6q3
&calid=jdoe;jsmith;susan&fmt-out=text/calendarThis is the returned data:
BEGIN:VCALENDAR
PRODID:-//SunJavaSystem/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:2.0
X-NSCP-CALPROPS-LAST-MODIFIED:20030415T001028Z
X-NSCP-CALPROPS-CREATED:20030415T001028Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID;X-S1CS-EMAIL=room1a@netscape.com
:Room1A
X-NSCP-CALPROPS-NAME:Galaxy
X-NSCP-CALPROPS-PRIMARY-OWNER:calmaster
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^wdeic^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^rsf^g
X-NSCP-CALPROPS-RESOURCE:1
X-S1CS-CALPROPS-ALLOW-DOUBLEBOOKING:1
X-S1CS-CALPROPS-FB-INCLUDE:1
X-S1CS-CALPROPS-COMMON-NAME: Calendar Master
X-S1CS-CALPROPS-INVITATION-COUNT: 3
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
get_freebusyPurpose
Get the freebusy information for users.
Parameters
Table 7-21 lists get_freebusy parameters:
Description.
This command to retrieve the freebusy information for specified users. Freebusy information tells whether or not a user’s time has been scheduled. It does not indicate why the user is busy.
The component freebusy time will be calculated for a time period that can be specified in one of three ways:
If conflicting parameters are passed in, the duration parameter overrides the other two types.
For further information about how freebusy calendars are specified, see Freebusy Calendars and Freebusy Calculation for Private Events.
Error Codes
If this command fails for any reason, errno is set to GET_FREEBUSY_FAILED(39).
Example
For example, a calendar called jdoe has the following events:
The freebusy time for jdoe (from 9:00 to 6:00) would be the following:
The following URL generates freebusy information found in the calendar jdoe between May 1 2002 and July 1 2002.
The output is returned in text/calendar format.
http://webcalendarserver/get_freebusy.wcap?id=2mu95r5so0hq68ts6q3&calid=js un&dtstart=20020501T112233Z&dtend=20020701T112233Z&fmt-out=text/calendar
Here is the output:
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:20010517T012259Z
X-NSCP-CALPROPS-CREATED:20010517T012259Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-DESCRIPTION:Work Calendar for John Doe
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe
X-NSCP-CALPROPS-NAME:John Doe
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-OWNERS:susan
X-NSCP-CALPROPS-CATEGORIES:business
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^S^g
BEGIN:VFREEBUSY
DTSTART:20020501T112233Z
DTEND:20020701T112233Z
FREEBUSY;FBTYPE=FREE:20020501T112233Z/20020518T170000Z
FREEBUSY;FBTYPE=BUSY:20020518T170000Z/20020518T190000Z
FREEBUSY;FBTYPE=FREE:20020518T190000Z/20020525T170000Z
FREEBUSY;FBTYPE=BUSY:20020525T170000Z/20020525T190000Z
FREEBUSY;FBTYPE=FREE:20020525T190000Z/20020601T170000Z
FREEBUSY;FBTYPE=BUSY:20020601T170000Z/20020601T190000Z
FREEBUSY;FBTYPE=FREE:20020601T190000Z/20020608T170000Z
FREEBUSY;FBTYPE=BUSY:20020608T170000Z/20020608T190000Z
FREEBUSY;FBTYPE=FREE:20020608T190000Z/20020615T170000Z
FREEBUSY;FBTYPE=BUSY:20020615T170000Z/20020615T190000Z
FREEBUSY;FBTYPE=FREE:20020615T190000Z/20020622T170000Z
FREEBUSY;FBTYPE=BUSY:20020622T170000Z/20020622T190000Z
FREEBUSY;FBTYPE=FREE:20020622T190000Z/20020629T170000Z
FREEBUSY;FBTYPE=BUSY:20020629T170000Z/20020629T190000Z
FREEBUSY;FBTYPE=FREE:20020629T190000Z/20020701T112233Z
END:VFREEBUSY
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
get_guidsPurpose
Generate a set of globally unique identifiers.
Parameters
Table 7-22 lists get_guids parameters:
Description.
This command returns the specified number of globally unique identifiers (GUIDs). The client need not be authenticated to call this command.
Example
http://webcalendarserver/get_guids.wcap?guidCount=10
&fmt-out=text/calendarBEGIN:VCALENDAR
VERSION:6.0
PRODID:SunONE Calendar Server 6.0
X-NSCP-GUID0:e5e4b537465600000b000000c3000000
X-NSCP-GUID1:e5e4b537d47900000c000000c3000000
X-NSCP-GUID2:e5e4b537961400000d000000c3000000
X-NSCP-GUID3:e5e4b5373d3a00000e000000c3000000
X-NSCP-GUID4:e5e4b537f31400000f000000c3000000
X-NSCP-GUID5:e5e4b5378259000010000000c3000000
X-NSCP-GUID6:e5e4b537b026000011000000c3000000
X-NSCP-GUID7:e5e4b537c263000012002002c3000000
X-NSCP-GUID8:e5e4b537241f000013000000c3000000
X-NSCP-GUID9:e5e4b537e733000014000000c3000000
END:VCALENDAR
gettimePurpose
Gets the server time for the requested calendars.
Parameters
Table 7-21 lists gettime parameters:
Description
Calendars must have given read permission to the user requesting the server time. Returns the server time of the server where the calendar is stored.
Error Codes
Example
Valid session with tzidout
http://webcalendarserver/gettime.wcap?id=br6e8vx9ek02n2ow9&
calid=jdoe&tzidout=America/Los_AngelesBEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
VERSION:2.0
X-NSCP-WCAPTIME:20021021T082743
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
get_userprefsPurpose
Retrieve the calendar preferences for the current user.
Parameters
Table 7-24 lists get_userprefs parameters:
Description.
This command retrieves all the calendar preferences for the current user, and the following server preferences relating to this user:
- allowchangepassword–Users can change the password.
- allowcreatecalendars–Users can create calendars.
- allowdeletecalendars–Users can delete calendars.
- allowpublicwritablecalendars–Users can have publicly writable calendars.
- validateowners–If set to 1, the server must validate that each owner of a calendar exists in the directory (whether the directory is LDAP or a CSAPI compatible user mechanism).
- allowsetprefs–If set to 1, allow set_userprefs.wcap to modify the user preferences.
See the Sun Java System Calendar Server Administration Guide for more information about server preferences.
Access Control Information (ACI)
The Calendar Server configuration program adds new ACIs. If you are upgrading from an earlier version of Java Enterprise System, you must rerun the configuration program to have the new ACIs added. Or you can use the Directory Server ldapmodify command to add them yourself as follows.
On the root suffix (o=usergroup):
On the domain basedn node (o=sesta.com,o=usergroup):
dn: o=sesta.com,o=usergroup
changetype: modify
add: aci
aci:(targetattr="icscalendar || cn || givenName || sn || uid || mail")(targetfilter=(objectClass=icscalendaruser))(version 3.0; acl "Allow calendar users to read and search other users - product=ics,class=admin,num=3,version=1"; allow (search,read) userdn = "ldap:///uid=*, ou=People, o=sesta.com, o=usergroup";)
Note that if there is no domain basedn node, add the preceding ACI to the root suffix itself (change the dn: value to o=usergoup).
Note
All nodes under the basedn must be set to allow anyone read and search access rights in order for this command to work. For more information, see the Common Topic Access Control Entries.
Example
The following URL retrieves user preferences for the current user:
http://webcalendarserver/get_userprefs.wcap?id=b5q2o8ve2rk02nv9t6&
calid=jdoe&fmt-out=text/calendarThis is the data returned:
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-WCAP-PREF-cn:John Doe
X-NSCP-WCAP-PREF-givenName:John
X-NSCP-WCAP-PREF-mail:jdoe@sesta.com
X-NSCP-WCAP-PREF-preferredlanguage:
X-NSCP-WCAP-PREF-sn:Doe
X-NSCP-WCAP-PREF-icsCalendar:jdoe
X-NSCP-WCAP-PREF-icsTimezone:Europe/London
X-NSCP-WCAP-PREF-icsDefaultSet:
X-NSCP-WCAP-PREF-icsFirstDay:
X-NSCP-WCAP-PREF-icsSet:name=mygroup$calendar=lucy\;jjones\;jdoe
TimeZone$tzmode=specify$tz=America/Denver$mergeInDayView=true
$description=
X-NSCP-WCAP-PREF-icsSubscribed:lucy$,jjones$,jsmith:jdoe
X-NSCP-WCAP-PREF-icsFreeBusy:jdoe
X-NSCP-WCAP-PREF-ceInterval:PT0H30M
X-NSCP-WCAP-PREF-ceDayTail:19
X-NSCP-WCAP-PREF-ceDefaultView:overview
X-NSCP-WCAP-PREF-ceColorSet:pref_group4
X-NSCP-WCAP-PREF-ceToolText:1
X-NSCP-WCAP-PREF-ceToolImage:1
X-NSCP-WCAP-PREF-ceFontFace:PrimSansBT,Verdana,sans-serif
X-NSCP-WCAP-PREF-ceExcludeSatSun:0
X-NSCP-WCAP-PREF-ceGroupInviteAll:1
X-NSCP-WCAP-PREF-ceSingleCalendarTZID:0z
X-NSCP-WCAP-PREF-ceAllCalendarTZIDs:0
X-NSCP-WCAP-PREF-ceNotifyEnable:0
X-NSCP-WCAP-PREF-ceNotifyEmail:jdoe@sesta.com
X-NSCP-WCAP-PREF-ceDefaultAlarmStart:P15M
X-NSCP-WCAP-PREF-ceDefaultAlarmEmail:jdoe@sesta.com
X-NSCP-WCAP-PREF-nswcalCALID:jdoe
X-NSCP-WCAP-PREF-icsDWPHost:DWPserver1
X-NSCP-WCAP-PREF-icsCalendarOwned:jdoe$John’s Calendar,jdoe:personal$John’s Personal Calendar
X-NSCP-WCAP-SERVER-PREF-allowchangepassword:no
X-NSCP-WCAP-SERVER-PREF-allowcreatecalendars:yes
X-NSCP-WCAP-SERVER-PREF-allowdeletecalendars:
X-NSCP-WCAP-SERVER-PREF-allowpublicwritablecalendars:
X-NSCP-WCAP-SERVER-PREF-validateowners:no
X-NSCP-WCAP-ERRNO:0
END:VCALENDARThe following is a sample output of the following commands:
wc /get_userprefs.wcap?id=t95qm0n0es3bo35r&fmt-out=text/calendar&userid=jdoe
wc /get_userprefs.wcap?id=t95qm0n0es3bo35r&fmt-out=text/calendar&userid=mailt o:sue@sesta.com
wc /get_userprefs.wcap?id=t95qm0n0es3bo35r&fmt-out=text/calendar&userid=john1 23abcGET /get_userprefs.wcap?id=eo38ue2q2rq6r68u&fmt-out=text/calendar&userid=jdoe
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:2.0
X-NSCP-WCAP-PREF-cn:JohnDoe,TEST TEST-2
X-NSCP-WCAP-PREF-uid:jdoe
X-NSCP-WCAP-PREF-mail:jdoe@sesta.com
X-NSCP-WCAP-PREF-givenName:John
X-NSCP-WCAP-PREF-sn:Doe
X-NSCP-WCAP-PREF-icsCalendar:jdoe
X-NSCP-WCAP-ERRNO:0
END:VCALENDARGET /get_userprefs.wcap?id=eo38ue2q2rq6r68u&fmt-out=text/calendar&userid=mailt o:sue@sesta.com
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:2.0
X-NSCP-WCAP-PREF-cn:Sue Smith
X-NSCP-WCAP-PREF-uid:Sue
X-NSCP-WCAP-PREF-mail:sue@sesta.com
X-NSCP-WCAP-PREF-givenName:Sue
X-NSCP-WCAP-PREF-sn:Smith
X-NSCP-WCAP-PREF-icsCalendar:sue
X-NSCP-WCAP-ERRNO:0
END:VCALENDARGET /get_userprefs.wcap?id=eo38ue2q2rq6r68u&fmt-out=text/calendar&userid=john1 23abc
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISHx
VERSION:2.0
X-NSCP-WCAP-ERRNO:61
END:VCALENDAR
importPurpose
Import events and todos from a file to a calendar.
Parameters
Table 7-25 lists import parameters:
Table 7-25 import Parameters
Parameter
Type
Purpose
Required
Default
appid
string
A runtime parameter (not stored in the database) that specifies which application is making the request. ENS uses this parameter to determine which X-Tokens to return. Does not affect WCAP command output.
For more information on the ENS X-Tokens, see the SunONE Messaging and Collaboration Event Notification Service Manual.
N
N/A
calid
string
Identifier of a calendar to which to import event.
Y
N/A
content-in
string
Content type of input data. One of the following values:
text/calendar
text/xmlY
N/A
dtend
DateTime string
End time and date of the events and todos to import.
A value of 0 means import all components from the start date to the last date in the file.
N
0
dtstart
DateTime string
Start time and date of events and todos to import.
A value of 0 means import all components from the earliest date in the file to the end date.
N
0
id
unique identifier string
The session identifier. Required unless the calendar is public.
Y
N/A
Description.
Use this command to import to the specified calendar events and todos that have previously been exported to a file using the export command. You must specify the file’s MIME content type in the content-in parameter.
If you do not specify either the starting or ending date, or you pass in 0 as the value for dtstart and dtend, the command adds all events and todos in the file to the specified calendar. If you specify a starting and ending date, the command imports only events and todos in the file that fall within the time range. Specify starting and ending dates in UTC time (indicated by Z at the end of the datetime).
You must use this command with an HTTP POST message (unlike other commands, which can be used with an HTTP GET message). You attach the file containing the exported events and todos to the POST message. This file must be in either iCalendar (.ics) or XML (.xml) format.
Example
The following POST message imports the attached iCalendar file to the calendar jdoe using the import command (The session id is required.):
POST /import.wcap?id=t95qm0n0es3bo35r&calid=jdoe&dtstart=0&dtend=0
Content-type: multipart/form-data;
boundary=---------------------------33111928916708
Content-Length: 679
-----------------------------33111928916708
Content-Disposition: form-data; name="Upload";
filename="C:\TEMP\ical1.ics"
BEGIN:VCALENDAR
BEGIN:VEVENT
DTSTART:20020105T100000Z
DTEND:20020105T110000Z
DTSTAMP:20010104T120020Z
CREATED:20010105T110000Z
LAST-MODIFIED:20010104T120020Z
SUMMARY:Weekly QA Meeting
UID:random-uid001
END:VEVENT
BEGIN:VEVENT
DTSTART:20020106T100000
DTEND:20020106T110000
DTSTAMP:20010104T120020
CREATED:20010105T110000Z
LAST-MODIFIED:20010104T120020Z
SUMMARY:Weekly QA Meeting 2
UID:random-uid002
END:VEVENT
END:VCALENDAR
-----------------------------33111928916708--The following HTML form creates such a POST message, attaching a file that the user specifies:
<FORM METHOD=POST ENCTYPE="multipart/form-data"
ACTION="http://webcalendarserver:12345/import.wcap?id=t95qm0n0es3bo35r&cal id=jdoe&dtstart=0&dtend=0&content-in=text/calendar">
<ol>
<li>file to import:<input type="file" accept="text" name="Upload">
</li>
<li>Press Import Now:<input type="submit" value="Import Now"></li>
</ol>
</FORM>
listPurpose
List all calendars owned by current user.
Parameters
Table 7-25 lists list parameters:
Table 7-26 import Parameters
Parameter
Type
Purpose
Required
Default
id
unique identifier string
The session identifier. Required unless the calendar is public.
Y
N/A
userid
string
Specifies which user’s calendars to display.
Can only be used by an administrator, and only if the option is configured on the server.
N
N/A
Description
Returns only those calendars where the user is the primary owner.
Example
BEGIN:VCALENDAR
PRODID:-//SunJavaSystem/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:2.0
X-S1CS-CALPROPS-OWNED-CALENDAR:jdoe@example.com
X-S1CS-CALPROPS-OWNED-CALENDAR:jdoe@example.com:MySecondCalendar
X-S1CS-CALPROPS-OWNED-CALENDAR:jdoe@example.com:Vacation
X-S1CS-CALPROPS-OWNED-CALENDAR:jdoe@example.com:ProjectX
END:VCALENDAR
list_subscribedPurpose
List all calendars subscribed to by current user.
Parameters
Table 7-25 lists list_subscribed parameters:
Table 7-27 import Parameters
Parameter
Type
Purpose
Required
Default
id
unique identifier string
The session identifier. Required unless the calendar is public.
Y
N/A
userid
string
Specifies which user’s calendars to display.
Can only be used by an administrator, and only if the option is configured on the server.
N
N/A
Description
Returns calendars the user is subscribed to, including the ones for which the user is the primary owner.
Example
BEGIN:VCALENDAR
PRODID:-//SunJavaSystem/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:2.0
X-S1CS-CALPROPS-SUBSCRIBED-CALENDAR:jdoe@example.com
X-S1CS-CALPROPS-SUBSCRIBED-CALENDAR:jdoe@example.com:MySecondCalendar
X-S1CS-CALPROPS-SUBSCRIBED-CALENDAR:jdoe@example.com:Vacation
X-S1CS-CALPROPS-SUBSCRIBED-CALENDAR:jdoe@example.com:ProjectX
END:VCALENDAR
loginPurpose
Authenticate a specific user.
Parameters
Table 7-28 lists login parameters:
Table 7-28 login Parameters
Parameter
Type
Purpose
Required
Default
fmt-out
string
Specifies the desired output format.
Specify text/html to log in to the Calendar Express user interface. This format type is invalid in all other commands.
If you are not logging into the Calendar Express user interface, choose one of the other output format types that follows:
text/calendar
text/xmlN
text/
calendarlang
enum
The user’s preferred language.
N
NULL
password
string
The user’s password.
N
N/A
proxyauth
string
Used by calendar administrators to perform proxy authorization.
N
N/A
user
string
The user’s name.
N
NULL
Description.
This command logs a specific user into Calendar Server, authenticating the user to the server with a user name and password convention.
The user name is a plain text string that uniquely identifies the user to the server. This user name could, for example, be the same as a user's email address. The password is also plain text.
fmt-out=text/html
This data type is allowed in only one command in WCAP, login. It is for the express purpose of logging into the SHTML user interface. When fmt-out=text/html occurs in login, the command is redirected to command.shtml, which connects the user to the Calendar Server user interface. Since this data type is not the default for the parameter, you must specify it explicitly when logging in to the Calendar Server interface.
Authentication
Do internal authentication using either the default LDAP authentication, or your own CSAPI plug-in to link to an existing user authentication method (For more information on CSAPI authentication, see csIAccessControl). For more information on the Proxy Authentication SDK, see Chapter 3, "Proxy Authentication SDK Overview" for the overview and Chapter 4, "Proxy Authentication SDK Reference" for the API Reference.
If the user fails to authenticate correctly, the login window reappears with an error noting a failure to log in.
Example
For example, the following URL attempts to login user jdoe:
http://webcalendarserver/login.wcap?user=jdoe&password=mypword
Returns
The login command returns the information shown in this example:
HTTP/1.0 302 OK
Date: Tue, 11 May 2002 22:38:33 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache
Content-Length: 0
Last-modified: Tue, 11 May 2002 22:38:33 GMT
Location:
http://webcalendarserver/en/main.html?id=er6en05tv6n3bv9&lang=en
&host=http://webcalendarserver/
logoutPurpose
Terminate the current user’s session.
Parameters
Table 7-29 lists logout parameters:
Table 7-29 logout Parameters
Parameter
Type
Purpose
Required
Default
fmt-out
string
The format for the returned data.
The three format types:
text/calendar
text/xmlN
text
calendarid
unique identifier string
The session identifier.
Y
N/A
Description.
This command ends the specified session of the current user, and deletes the session instance of the user in the session table. The user is returned to the login screen.
The following is an example of a URL using this command:
http://webcalendarserver/logout.wcap?id=bu9p3eb8x5p2nm0q3
pingPurpose
Determine whether the calendar server is active.
Parameters
This command takes no parameters.
Description.
This command returns a minimal HTML page to indicate that the server responded.
Only users with administrative privilege can use this command.
Returns
For this example, the administrator’s userid and calid are both adminX.
HTTP/1.0 200
Date: Thu, 03 Jun 2002 21:31:42 GMT
Content-type: text/html; charset=iso-8859-1
Content-length: 190
Last-modified: Thu, 03 Jun 2002 21:31:42 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache
search_calpropsPurpose
Search for a calendar’s properties.
Parameters
Table 7-30 lists search_calprops parameters:
Table 7-30 search_calprops Parameters
Parameter
Type
Purpose
Required
Default
calid
integer (0,1)
A boolean indicating whether or not to search the calid property.
1 = Search the calid property
0 = Do not search it.N
0, unless both primary
Owner and name are 0id
unique identifier string
The session identifier.
Y
N/A
maxResults
integer
The maximum number of results to return.
N
200
name
integer (0,1)
A boolean indicating whether or not to search the name property.
1 = Search the name property
0 = Do not search it.N
0
primaryOwner
integer (0,1)
A boolean indicating whether or not to search the primaryOwner property.
1 = Search the primaryOwner property.
0 = Do not search it.N
0
searchOpts
integer
0,1,2,3
How to perform the search. One of the following:
0 = CONTAINS
1 = BEGINS_WITH
2 = ENDS_WITH
3 = EXACTN
0
search-string
string
The string to search for in calendars.
Y
N/A
Description.
This command searches for a calendar using the query type specified by searchOpts. It returns the calendar properties for all calendars where a value in the specified properties (primaryOwner, calid, name), exactly matches the search-string specified in the search-string parameter. If there are multiple matches, it returns all of them, up to the specified maximum number of matches (maxResults).
When searching for the primaryOwner, the internal search filter is set to find exact matches. If you wish to allow the system to perform wildcard searches such that the search string appears anywhere within the property value, then you must edit the ics.conf file.
To use the wildcard search, uncomment the following line:
!service.calendarsearch.ldap.primaryownersearchfilter = "(&(|(uid=*%s*)(cn=*%s*))(objectclass=icsCalendarUser))"
Enabling the wildcard search can negatively impact performance.
Search Properties
This command searches for a match in one of three properties:
To search for the value of a specific property, set that parameter to 1. If both primaryOwner and name are set to 0, calid defaults to 1 and the server assumes the search-string is a calid, regardless of the calid parameter setting.
Search Options
There are four search options:
- Return the calendar properties that contain the search-string (CONTAINS).
- Return the calendar properties that begin with the search-string (BEGINS_WITH).
- Return the calendar properties that ends with the search-string (ENDS_WITH).
- Return the calendar properties that exactly match the search-string (EXACT).
Example
The following example URL searches the primary owner property (primaryOwner=1) in all calendars to see if it contains (searchOpts=0) the string "jdoe"
http://webcalendarserver/search_calprops.wcap?id=n3o3m05sx9v6t98t8u2p&
search-string=jdoe&primaryOwner=1&searchOpts=0&maxResults=50&
fmt-out=text/calendarThe following data is a result of the example URL above:
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:20011208T005613Z
X-NSCP-CALPROPS-CREATED:20010913T223336Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe
X-NSCP-CALPROPS-NAME:John Doe
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-TZID:America/Los_Angeles
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^WDEIC^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^RSF^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^a^frs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^c^dw^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^a^rs^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^c^w^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^p^r^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^p^r^g
X-NSCP-CALPROPS-RESOURCE:0
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:6.0
X-NSCP-CALPROPS-LAST-MODIFIED:20010917T213724Z
X-NSCP-CALPROPS-CREATED:20010917T213724Z
X-NSCP-CALPROPS-READ:999
X-NSCP-CALPROPS-WRITE:999
X-NSCP-CALPROPS-RELATIVE-CALID:jdoe:sports
X-NSCP-CALPROPS-NAME:Sports Calendar
X-NSCP-CALPROPS-LANGUAGE:en
X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^WDEIC^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^RSF^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^^g
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g
X-NSCP-CALPROPS-RESOURCE:0
X-NSCP-WCAP-ERRNO:0
END:VCALENDAR
set_calpropsPurpose
Set the calendar properties of a calendar.
Parameters
Table 7-31 lists set_calprops parameters:
Table 7-31 set_calprops Parameters
Parameter
Type
Purpose
Required
Default
acl
string
A semicolon-separated list of strings specifying the new value of the access control entries.
N
,,,,
cal
encoded string
A list of parameters to decode.
There can be multiple instances of this parameter.
N
N/A
calid
string
Identifier of the calendar to modify.
Y
N/A
categories
string
A semicolon-separated list of strings containing the new categories the calendar belongs to.
N
N/A
charset
string
The character set for the calendar.
N
N/A
description
string
The description of the calendar.
N
N/A
doublebooking
integer
Allow or disallow doublebooking.
1 = Allow doublebooking.
0 = Disallow doublebooking.
N
N/A
fbinclude
integer
Specifies whether the calendar can be used in any free/busy lookup.
1 = Include the calendar.
0 = Do not include the calendar.
If you want to remove the calendar from the free/busy lookup list, pass in fbinclude=0.
N
N/A
fmt-out
string
The format for the returned data.
The three format types:
text/calendar
text/xmlN
text/
calendarid
unique identifier string
The session identifier.
Y
N/A
lang
string
The language of the calendar.
N
N/A
master
string
The email contact for the calendar.
N
N/A
multiple
integer
The number of calendars for which to set these preferences.
N
0
name
string
The new text name of the calendar.
N
N/A
owners
string
A semicolon-separated list of strings containing he new list non-primary owners.
N
N/A
tzid
string
The new timezone identifier for this calendar.
N
,,,,
Description.
This command is an update command, that is, it only changes the values of the parameters you specify. It is not necessary to supply all parameters in the command, only the ones you wish to change. Calendar properties are special states of a calendar, which includes the calendar's name, read and write permission values (acl parameter), the list of owners, and the list of categories.
Use set_calprops to do the following:
- Change the name of the calendar.
- Change owner of calendar.
- Change category of calendar.
- Change read permission of calendar’s event.
- Change write permission of calendar’s event.
- Change description of calendar.
- Change character set of calendar.
- Change language of calendar.
- Change email contact of this calendar.
- Change the timezone-identifier of the calendar.
- Allow or disallow doublebooking for this calendar.
Single Calendar Example
Here is a sample URL that sets calendar properties: (The calid parameter is required.)
http://webcalendarserver?set_calprops.wcap?id=dfasdfzd3ds&calid=jdoe&categ ories=business;meeting&name=John%39s%32Calendar
Multiple Calendars Example
To set properties of several calendars at one time, set the multiple parameter to the number of calendars to be set, then pass a cal parameter for each calendar. The cal parameter contains an encoded string with the complete property parameter list for the identified calendar. In this string, replace all special characters with a percent character (%), followed by the hexadecimal ASCII code for the special character. ASCII hex codes for common special characters are as follows:
For example, the following URL modifies three calendars with IDs xxxx, yyyy, and zzzz, setting the descriptions to X-Calendar, Y-Calendar, and Z-Calendar, respectively:
http://webcalendarserver?id=fasdfzd3ds
&multiple=3
&cal=calid%3Dxxxx%26description%3DX-Calendar
&cal=calid%3Dyyyy%26description%3DY-Calendar
&cal=calid%3Dzzzz%26description%3DZ-CalendarThis is the equivalent of the following three URLs:
http://webcalendarserver?id=fasdfzd3ds&calid=xxxx&desc=X-Calendar
http://webcalendarserver?id=fasdfzd3ds&calid=yyyy&desc=Y-Calendar
http://webcalendarserver?id=fasdfzd3ds&calid=zzzz&desc=Z-Calendar
In the example, notice that since the multiple parameter is set to 3, there are three instances of the cal parameter. The value of each cal parameter is an encoded list of parameters and their values. The server will decode each cal parameter and set the properties appropriately.
Access Control Entries
See Access Control Entries, in the Common Topics section at the front of this chapter. Note that due to limitations of the user interface, it is advisable to limit the number of individuals listed in the ACEs to a maximum of 75 per calendar.
Doublebooking
Double booking is allowed if the user.allow.doublebook parameter in the ics.conf file is set to “yes” (allows doublebooking) and the user’s calendar property, doublebooking, is set to allow doublebooking (that is, it is set to 1). Doublebooking is disallowed (command returns error 40 STORE_FAILED_DOUBLE_BOOKED) if the calendar doublebooking property is set to 0.
However, if the user.allow.doublebook parameter is set to “no”, then double booking is disallowed, no matter what the calendar property is set to.
Freebusy Access
See Freebusy Calendars, in the Common Topics section at the front of this chapter.
Choosing a Different Language or Character Set
See Changing Language or Character Set, in the Common Topics section at the front of this chapter.
set_userprefsPurpose
Modify the preferences or password for a session.
Parameters
Table 7-32 lists set_userprefs parameters:
Table 7-32 set_userprefs Parameters
Parameter
Type
Purpose
Required
Default
add_attrs
string
Add a new preference.
N
N/A
convertCalid
integer (0,1)
When set to 1 and setting the preferences icsSet or icsSubscribed, indicates to the server to convert the character “^” to “:” when storing the calid.
When set to 0, the parameter is ignored.
N
0
del_attrs
string
Delete an existing preference.
N
N/A
fmt-out
string
The format for the returned data.
The two format types:
text/calendar
text/xmlY
text/
calendarid
unique identifier string
The session identifier.
Y
N/A
set_attrs
string
Modify a preference value.
N
N/A
userid
string
Used only by administrators. Indicates which user’s preferences to set.
N
N/A
Description.
This command modifies the preferences for the current user. You may also modify the user’s password through LDAP.
Use of this parameter is only necessary when setting the subscribed list of calendars (icsSubscribed), or the subscribed list of groups (icsSet). The calid on incoming commands must have the colon, “:”, replaced with a caret, “^”. For example, if the calid is jdoe:personal, then WCAP must receive it as jdoe^personal in order for the command to work properly.
If the value of convertCalid is 1, then WCAP will convert the “^” back to a “:”. If the value of the convertCalid is 0, the conversion will not be done
When the administrator is logged in, and the ics.conf file preference service.admin.calmaster.wcap.allowgetmodifyuserprefs is set to “yes”, the userid parameter specifies which user’s preferences to set.
Returns
The function returns the text of get_userprefs.
Examples
Add a Preference
For example, the following URL adds a new preference, ceBgcolor, to the calendar and sets it to black:
http://webcalendarserver/set_userprefs.wcap?id=b5q2o8ve2rk02nv9t6
&add_attrs=ceBgcolor=blackDelete a Preference
This URL deletes the calendar preference ceBgcolor from the user’s preferences.
http://webcalendarserver/set_userprefs.wcap?id=b5q2o8ve2rk02nv9t6
&del_attrs=ceBgcolor
Note
If the attribute to be deleted is multi-valued and there are other instances of the preference, only the first instance encountered is deleted. To remove all of the instances of this preference, multiple set_userprefs commands must be issued, one for each instance.
For example: After running get_userprefs, you see there are two values listed for icsSubscribed. To clear both of them, two commands must be issued: /set_userprefs.wcap?id=${SESSIONID}&del_attrs=icsSubscribed
/set_userprefs.wcap?id=${SESSIONID}&del_attrs=icsSubscribed
Modify a Preference
This URL would modify the calendar preference ceBgcolor to have the value white:
http://webcalendarserver/set_useprefs.wcap?id=b5q2o8ve2rk02nv9t6
&set_attrs=ceBgcolor=whiteThis URL would allow the logged-in administrator to modify the calendar preference ceBgcolor to have the value black for user jdoe:
http://webcalendarserver/set_userprefs.wcap?id=b5q2o8ve2rk02nv9t6
&userid=jdoe&set_attrs=ceBgcolor=black
storeeventsPurpose
Add events to a calendar.
Parameters
Table 7-33 lists storeevents parameters:
Table 7-33 storeevents Parameters
Parameter
Type
Purpose
Required
Default
alarmAudio
ISO 8601 Date Time string
The time at which to sound an audio alarm.
N
N/A
alarmDescription
string
The message sent out with the alarm
N
“This is the alarm description”
alarmEmails
semicolon-
separated list of email addressesRecipients of alarm notifications for the event.
N
N/A
alarmFlashing
ISO 8601 Date Time string
The time at which to run flashing alarm.
N
N/A
alarmPopup
ISO 8601 Date Time string, or
ISO 8601 Duration string
The time at which to pop up a dialog alarm.
N
N/A
alarmStart
ISO 8601 Date Time string,
or ISO 8601 Duration string
The time at which to send the event alarm notification.
N
N/A
appid
string
A runtime parameter (not stored in the database) that specifies which application is making the request. ENS uses this parameter to determine which X-Tokens to return. Does not affect WCAP command output.
For more information on the ENS X-Tokens, see the SunONE Messaging and Collaboration Event Notification Service Manual.
N
N/A
attachments
semicolon-
separated list of stringsThis is for iCalendar interoperability only.
The strings are URLs.N
N/A
attendees
semicolon-
separated list of stringsAn event’s iCalendar RFC 2445 attendee properties. For a list of the properties understood by Calendar Server, see Table 6-6.
There is one optional property that is specific only to Calendar Server: SENT-STATUS, which can have the value of: NOT-SENT or SENT-SUCCEEDED.
The default for this property is NOT-SENT. If this property is set to SENT-SUCCEEDED, the the Group Scheduling Engine (GSE) will not process this attendee.
N
N/A
calid
string
Calendar identifier (or email address of calid) in which to store the event.
Y
N/A
categories
semicolon-
separated list of stringsThe event categories.
N
N/A
charset
string
The character set for the calendar.
N
N/A
compressed
integer (0,1)
This parameter has been deprecated for this release and may be removed from future releases.
For compressed=0, returns less data. Specifically, it does not return the following parameters:
rrules
rdate
exrule
exdateFor compressed=1, all recurrence data is returned.
N
0
contacts
semicolon-
separated list of stringsContacts for the event.
N
N/A
desc
string
Event purpose description. A string of any length. If not passed, desc is set to the summary value.
To include spaces in the string, use the code %20.
N
Value of summary parameter.
dtend
Date Time string
Event end time and date.
N
N/A
dtstart
Date Time string
Event start time and date.
Required to create or modify events.
Y
N/A
duration
ISO 8601 duration string
Event duration. If an event has both a duration and a dtend, the duration is ignored.
N
N/A
excludedtstart
integer (0, 1)
Whether or not to include the dtstart date in a recurring series if it does not fall within the rrules dates.
0 = include the dtstart date
1 = exclude the dtstart date
N
0
exdates
semicolon-
separated list of ISO 8601 Date Time Z stringsEvent exclusionary recurrence dates. To successfully create events, the rrules parameter must be used in conjunction with this parameter.
N
N/A
exrules
semicolon- separated list of ISO 8601 Date Time Z strings
Event exclusionary recurrence rules. A semicolon-separated list of recurrence-rule strings.
Each rule value must be enclosed in quotes. See Recurring Components – Overview.
N
N/A
fetch
integer (0,1)
A boolean indicating whether or not to fetch and return newly stored todos.
1 = Fetch and return newly stored todos.
0 = Do not fetch.N
0
fmt-out
string
The format for the returned data.
The three format types:
text/calendar
text/xmlN
text/
calendargeo
two semicolon-
separated floatsSemicolon-separated string of two float numbers representing the event’s geographical location (latitude and longitude).
For example, 37.31;-123.2.
N
0;0
icsClass
string
Event class.
One of the following values:
PUBLIC
PRIVATE
CONFIDENTIALN
PUBLIC
icsUrl
string
Event URL.
N
““
id
unique identifier string
The session identifier.
Y
N/A
isAllDay
integer (0,1)
A boolean indicating whether or not the event lasts all day.
1 = Lasts all day.
0 = Does not last all day.N
0
language
string
Language of event. (For example, “en”, “fr”, “de”)
N
N/A
location
string
Event location.
N
““
method
integer (1,2,4,8)
ITIP method for group scheduling.
1 = PUBLISH (organizer only uses this)
2 = REQUEST (organizer only uses this)
4 = REPLY (attendees only use this)
8 = CANCEL (organizer only uses this)Y
1 (PUBLISH)
mod
integer
Specifies the recurrences to modify.
Not required for creating events.
Required to modify events.
One of the following values:
1 = THISINSTANCE
2 = THISANDFUTURE
3 = THISANDPRIOR
4 = THISANDALL
N
Y
N/A
orgCalid
string
Calendar identifier of organizer.
One of the following parameters must be specified: orgCalid, orgEmail, or orgUID.
N
N/A
orgCN
string
Common name of the organizer.
N
N/A
orgEmail
email address
Email address of the event contact (usually the organizer).
One of the following parameters must be specified: orgCalid, orgEmail, or orgUID.
N
N/A
orgUID
userid
The userid of the organizer.
One of the following parameters must be specified: orgCalid, orgEmail, or orgUID.
N
N/A
priority
integer (0-9)
Event priority. Follows RFC 2445.
0 = undefined
1= highestt
9= lowestN
5
rchange
integer (0,1)
A boolean indicating whether or not to expand a recurring event.
1 = expand
0 = do not expandN
0
rdates
semicolon-
separated list of ISO 8601 Date Time Z stringsEvent recurrence dates. To successfully create events, the rrules parameter must also be specified.
N
N/A
relatedTos
semicolon-
separated list of quoted stringsOther events to which this event is related.
N
N/A
replace
Integer (0,1)
A boolean. For parameters with semicolon-separated values:
1 = update (replace the old values with the new passed-in values)
0 = append (add the new passed-in values to the old ones)
N
0
resources
semicolon-
separated list of stringsThe resources associated with the event.
N
N/A
rid
ISO 8601 DateTime string
Event recurrence identifier.
Not required to create events.
If this parameter is not set when trying to modify events, the whole series of events is modified.
N
N
N/A
rrules
semicolon-
separated list of stringsEvent recurrence rules. A semicolon-separated list of recurrence-rule strings.
Each rule value must be enclosed in quotes. See Recurring Components – Overview.
N
N/A
seq
integer
(Not implemented) Event sequence number.
N
0
smtp
integer (0, 1)
Clients that send out invitations themselves set the value to 0. Clients that require the server to send out invitations set the value to 1.
0—No
1—YesN
1
status
integer
The event status code. One of the following values:
0 CONFIRMED
1 CANCELLED
2 TENTATIVE
3 NEEDS_ACTION
4 COMPLETED
5 IN_PROCESS
6 DRAFT
7 FINALN
N/A
storetype
integer
Designates whether an explicit “create” or “modify” is attempted on an event. An error results if an attempt is made to create an event that already exists, or to modify an event that does not exist. The error returned is STOREEVENTS_FAILED (14)
The following values are valid:
0 WCAP_STORE_TYPE_NONE
1 WCAP_STORE_TYPE_CREATE
2 WCAP_STORE_TYPPE_MODIFYIf the attribute is not passed or has a value of 0, no error conditions are reported.
N
0
summary
string
Event summary. A string of any length.
Required for new events; not required for modifying events.
To include spaces in the string, use the code %20.
Y/N
Default summary available for new events
transparent
integer (0, 1)
Is the event transparent (1), or opaque (0)? If it is transparent, exclude this event from freebusy calculations. If opaque, then include it in freebusy calculations.
If the isAllDay parameter is set to 1, the default is transparent instead of opaque.
N
0 (opaque)
1 (transparent, if isAllDay=1)
tzid
time zone ID string
The time zone used to translate dates to Zulu time for storage.
If this parameter is missing, and the time string has no Z after it, the calendar server time zone ID is used.
N
Calendar server time zone ID.
tzidout
time zone ID string
Time zone returned data should be translated to.
N
Returns data in Zulu time
uid
string
Unique identifier of the event to be stored.
System generated for new events.
Required to modify events.
N
Y
Default uid available for new events.
X-property name
string
One or more X properties, in iCalendar 2445 format (note that WCAP uses ^ as the separator)
N
N/A
Description.
Use this command to creates or modify events with the specified attributes and stores them in the specified calendar in the database.
The command creates and stores recurrences as specified by the rrules,exrules, rid, mod, and rchange parameters. See Recurring Components – Overview.
Use the language parameter to specify the language of the event. See Changing Language or Character Set for a list of possible language codes.
For an explanation of how to use the attendee and method parameters to do group scheduling, see the Common Topics section Group Scheduling.
For an explanation of how to replace, append or delete a parameter, see the explanation in the Common Topics section Updating Parameter Values.
The server does not support attachments. The attachments parameter exists to support iCalendar interoperability only, and is not functional.
It is possible to delete an attendee in an existing meeting by assigning the value X-NSCP-WCAP-ATTENDEE-DELETE to the attendee parameter PARTSTAT. For example, to delete attendee jdoe, the attendee parameter would contain the following:
Required Parameters
This command creates new events and modifies existing events. You can not add and modify events in the same command. You must do one or the other.
There is a different set of parameter requirements for both cases:
Doublebooking
Double booking is allowed if the user.allow.doublebook parameter in the ics.conf file is set to “yes” (allows doublebooking) and the user’s calendar property, doublebooking, is set to allow doublebooking (that is, it is set to 1). Doublebooking is disallowed (command returns error 40 STORE_FAILED_DOUBLE_BOOKED) if the calendar doublebooking property is set to 0.
However, if the user.allow.doublebook parameter is set to “no”, then double booking is disallowed, no matter what the calendar property is set to.
Duration and Dtend
The ending date (dtend) overrides duration. If you specify both duration and dtend, the command ignores duration.
Duration strings can be used in three parameters: duration, alarmPopup and alarmStart.
Specify the duration in iCal format. For example:
Notice that the T in the string separates the date information (year, month, day) from the time information (hour, minute, second).
Returns
The command returns the error value. To have the command return the stored todo data, specify the fetch parameter (fetch=1). In addition, use the tzidout parameter to specify the time zone the returned data should be translated to. If the tzidout parameter is missing, the data will be returned in Zulu time.
Error Codes
This command cannot modify a linked event. The command will fail and return CANNOT_MODIFY_LINKED_EVENTS(31) in the errno array.
The command fails, and returns the error STORE_FAILED_DOUBLE_BOOKED(40), if doublebooking is disallowed, when it tries to store an event in a time slot that is already scheduled (double booking).
Example
For example, this URL would call storeevents.wcap and would result in storing an event in the calendar john,
http://webcalendarserver/storeevents.wcap?id=3423423asdfasf
&calid=john&dtstart=20020101T103000&dtend=20020101T113000&uid=001
&summary=new%20year%20eventThe above example results in the following entry in an iCalendar database:
BEGIN:VEVENT
DTSTART:20020101T183000Z
DTEND:20020101T193000Z
UID:001
SUMMARY:new year event
END:VEVENT
storetodosPurpose
Add one or more todos to a calendar.
Parameters
Table 7-34 lists storetodos parameters:
Table 7-34 storetodos Parameters
Parameter
Type
Purpose
Required
Default
alarmAudio
ISO 8601 Date Time
stringThe time at which to sound an audio alarm.
N
N/A
alarmDescription
string
The message send out with the alarm
N
“This is the alarm description”
alarmEmails
semicolon-separated list of email addresses
Recipients of alarm notifications for the todo.
N
N/A
alarmFlashing
ISO 8601 Date Time
stringThe time at which to run a flashing alarm.
N
N/A
alarmPopup
ISO 8601 Date Time
stringISO 8601 Duration string
The time at which to pop up a dialog alarm.
N
N/A
alarmStart
ISO 8601 Date Time
stringISO 8601 Duration string
The time at which to send an alarm notification of the todo.
N
N/A
appid
string
A runtime parameter (not stored in the database) that specifies which application is making the request. ENS uses this parameter to determine which X-Tokens to return. Does not affect WCAP command output.
For more information on the ENS X-Tokens, see the SunONE Messaging and Collaboration Event Notification Service Manual.
N
N/A
attachments
semicolon-separated list of strings
This parameter exists to support iCalendar interoperability only. The strings are URLs.
N
N/A
attendees
semicolon-separated list of strings
A todo’s iCalendar RFC 2445 attendee properties. For a list of the properties understood by Calendar Server, see Table 6-6
N
N/A
calid
string
Calendar identifier (or email address of calid) in which to store the todo.
Y
N/A
categories
semicolon-separated list of strings
The todo categories.
N
N/A
charset
string
The character set for the calendar.
N
N/A
completed
ISO 8601 Date Time
stringCompletion date of the todo. A value of 0 means the todo is not yet completed.
N
0
compressed
integer (0,1)
This parameter has been deprecated in this release and may be removed in future releases.
For compressed=0, returns less data. Specifically, it does not return the following parameters:
rrules
rdate
exrule
exdateFor compressed=1, all recurrence data is returned.
N
0
contacts
semicolon-separated list of strings
Contacts for the todo.
N
N/A
desc
string
Purpose of the todo. A string of any length.
If not passed, desc is set to the summary value.
To include spaces in the string, use the code %20.
N
Value in summary parameter.
dtstart
ISO 8601 Date Time string
Start time and date of the todo.
Not required to modify todos.
Required to create todos.
N
Y
N/A
due
ISO 8601 Date Time
stringEnd time and date of the todo.
N
N/A
duration
ISO 8601 duration string
Todo duration.
N
N/A
excludedtstart
integer (0, 1)
Whether or not to include the dtstart date in a recurring series if it does not fall within the rrules dates.
0 = include the dtstart date
1 = exclude the dtstart date
N
0
exdates
semicolon-separated list of ISO 8601 TimeDate strings
Exclusionary recurrence dates of the todo. To successfully create todos, the rrules parameter must also be specified.
N
N/A
exrules
semicolon-separated list strings
Todo exclusionary recurrence rules. A semicolon-separated list of recurrence-rule strings.
Each rule value must be enclosed in quotes. See Recurring Components – Overview.
N
N/A
fetch
integer (0,1)
A boolean indicating whether or not to fetch and return newly stored todos.
1 = Fetch and return newly stored todos.
0 = Do not fetch todos.N
0
fmt-out
string
The format for the returned data.
The three format types:
text/calendar
text/xmlN
text/
calendargeo
two semicolon-
separated floatsSemicolon-separated string of two float numbers representing the todo’s geographical location (latitude and longitude).
For example, 37.31;-123.2.
N
0;0
icsClass
string
Todo class. One of the following values:
PUBLIC
PRIVATE
CONFIDENTIALN
PUBLIC
icsUrl
string
Todo URL.
N
““
id
unique identifier string
The session identifier.
Y
N/A
isAllDay
integer (0,1)
A boolean indicating whether or not it is an all day todo.
1 = An all day todo.
0 = Not an all day todo.N
0
language
string
The language of the todo. (For example, “en”, “fr”, “de”.)
N
N/A
location
string
Todo location.
N
““
method
integer (1,2,4,8,16,32)
ITIP method for group scheduling.
One of the following:
1 = PUBLISH
2 = REQUEST
4 = REPLY
8 = CANCEL
16 = MOVE
32 = COUNTER (only attendees use this)Y
1 (PUBLISH)
mod
integer
Specifies the recurrences to store/modify.
Not required for new todos.
Required to modify todos.
One of the following values:
1 = THISINSTANCE
2 = THISANDFUTURE
3 = THISANDPRIOR
4 = THISANDALL
N
Y
N/A
orgCalid
string
Calendar identifier of organizer.
One of the following parameters must be specified: orgCalid, orgEmail, or orgUID.
N
N/A
orgCN
string
Common name of the organizer.
N
N/A
orgEmail
email address
The email address contact for the todo. (Usually the organizer’s email.)
One of the following parameters must be specified: orgCalid, orgEmail, or orgUID.
N
N/A
orgUID
userid
The userid of the organizer.
One of the following parameters must be specified: orgCalid, orgEmail, or orgUID.
N
N/A
percent
integer (0-100)
Percentage completion of the todo.
N
0
priority
integer (0-9)
Event priority. Follows RFC 2445.
0 = undefined
1= highestt
9= lowestN
5
rchange
integer (0,1)
A boolean indicating whether or not to replace the rrule:
1 = Replace the rule.
0 = Do not replace it.N
0
rdates
semicolon-separated list of ISO 8601 TimeDate Z strings
Recurrence dates of the todo. To successfully create todos, the rrules parameter must also be specified.
N
N/A
relatedTos
semicolon-separated list of quoted strings
Other todos to which this todo is related.
N
N/A
replace
Integer (0,1)
A boolean. For parameters with semicolon-separated values:
1 = update (replace the old values with the new passed-in values)
0 = append (add the new passed-in values to the old ones)
N
0
resources
semicolon-separated list of strings
The resources associated with the todo.
N
N/A
rid
ISO 8601 TimeDate string
Recurrence identifier of the todo.
Not required for new todos.
If this parameter is not specified the whole series is modified.
N
N/A
rrules
semicolon-separated list of strings
Todo recurrence rules. A semicolon-
separated list of recurrence-rule strings.Each rule value must be enclosed in quotes. See Recurring Components – Overview.
N
N/A
seq
integer
Sequence number of the todo.
N
0
status
integer
A code for the status of the todo. One of the following values:
0 CONFIRMED
1 CANCELLED
2 TENTATIVE
3 NEEDS_ACTION
4 COMPLETED
5 IN_PROCESS
6 DRAFT
7 FINALNote: Setting status=4 sets the status as COMPLETED, but does not set the COMPLETED_TIME_STAMP and PERCENT properties. All three parameters must be set if a task is completed.
N
N/A
storetype
integer
Designates whether an explicit “create” or “modify” is attempted on a todo. An error results if an attempt is made to create a todo that already exists, or to modify a todo that does not exist. The error returned is STORETODOS_FAILED (15)
The following values are valid:
0 WCAP_STORE_TYPE_NONE
1 WCAP_STORE_TYPE_CREATE
2 WCAP_STORE_TYPPE_MODIFYIf the attribute is not passed or has a value of 0, no error conditions are reported.
N
0
summary
string
Todo summary. A string of any length.
Required for new todos; not required for modifying todos.
To include spaces in the string, use the code %20.
Y/N
Default summary available for new todos
transparent
integer (0, 1)
Is the private todo transparent (1), or opaque (0)? If it is transparent, exclude this private todo from freebusy calculations. If opaque, then include it in freebusy calculations.
N
0 (opaque)
tzid
time zone ID string,
The timezone used to convert time parameter values to Zulu time for storage.
If this parameter is not present, and the string does not end in Z, then the calendar server tim zone ID is used.
N
Calendar server time zone ID
tzidout
time zone ID string
Time zone returned data should be translated to. Only valid when the fetch parameter is set to 1 (fetch=1).
N
Returns data in Zulu time
uid
string
Unique identifier of the todo to be stored.
System generated for new todos; required to modify todos.
N/Y
Default uid for new todos
Description.
Use this command to create and modify todos with the specified attributes and stores them in the specified calendar in the database.
The command creates and stores recurrences as specified by rrules, exrules, rid, mod, and rchange parameters. See Recurring Components – Overview.
For group scheduling, used the attendee and method parameters as explained in the Common Topics section Group Scheduling.
For an explanation of how to replace, append or delete a parameter, see the explanation in the Common Topics section Updating Parameter Values.
The server does not support attachments. The attachments parameter exists to support iCalendar interoperability only, and is not functional.
Required Parameters
This command creates new todos and modifies existing todos. There is a different set of parameter requirements for both cases:
Duration and Due
The due date (due) overrides duration. If you specify both duration and due, the command ignores duration.
Specify the duration in the ISO 8601 format. For example:
Notice that the T in the string separates the date information (year, month, day) from the time information (hour, minute, second).
Returns
The command returns the error value. To have the command return the stored todo data, specify the fetch parameter (fetch=1). In addition, use the tzidout parameter to specify the time zone the returned data should be translated to. If the tzidout parameter is missing, the data will be returned in Zulu time.
Error Codes
This command cannot modify a linked todo. The command will fail and return an error of CANNOT_MODIFY_LINKED_TODOS(32) in errno.
subscribe_calendarsPurpose
Add the specified calendars to the user’s calendar subscription list.
Parameters
Table 7-25 lists subscribe_calendars parameters:
Table 7-35 subscribe_calendars Parameters
Parameter
Type
Purpose
Required
Default
calid
string
A semi-colon separated list of calendar identifiers.
Y
N/A
id
unique identifier string
The session identifier. Required unless the calendar is public.
Y
N/A
userid
string
Specifies which user is subscribing.
Can only be used by an administrator, and only if the option is configured on the server.
N
N/A
Description
Adds the calendars specified in the calid parameter to the user’s subscription list. A check is made to see if the calendar exists. If not, an error code is returned.
Example
http://calendar.sesta.com/subscribe_calendars.wcap?id=br6p3t6bh5po35r&
calid=john@sesta.com;william@sesta.com:baseball
unsubscribe_calendarsPurpose
Remove the specified calendars to the user’s calendar subscription list.
Parameters
Table 7-25 lists subscribe_calendars parameters:
Table 7-36 subscribe_calendars Parameters
Parameter
Type
Purpose
Required
Default
calid
string
A semi-colon separated list of calendar identifiers.
Y
N/A
id
unique identifier string
The session identifier. Required unless the calendar is public.
Y
N/A
userid
string
Specifies which user is subscribing.
Can only be used by an administrator, and only if the option is configured on the server.
N
N/A
Description
Removes the calendars specified in the calid parameter to the user’s subscription list. No check is made to see if the calendar exists.
Example
http://calendar.sesta.com/unsubscribe_calendars.wcap?id=br6p3t6bh5po35r&
calid=john@sesta.com;william@sesta.com:baseball
verifyevents_by_idsPurpose
This command is used to verify if the event specified with the uid and rid pair exists in the database.
Parameters
Table 7-39 lists verifyevents_by_ids parameters:
Table 7-37 verifyevents_by_ids Parameters
Parameter
Type
Purpose
Required
Default
calid
string
Calendar from which to fetch events.
N
User’s default calendar
fmt-out
string
The format for the returned data.
The three format types:
text/calendar
text/xmlN
text/
calendarid
string
Uniquely identifies the session (session ID).
N*
null
rid
ISO 8601 DateTime string
Corresponding set of comma separated event rids.
If this is a non-recurring event, rid=0.
Y
N/A
tzid
time zone ID string
Time zone, such as “America/Los_Angeles”
N
Server’s default time zone
uid
string
Comma separated set of event uids.
Y
N/A
* The id must be specified with the command unless the calendar to fetch from is public calendar.
Description.
This command tries to fetch events matching the passed in uid-rid pairs.
Returns
If the events are found, the data is returned in the format specified by the fmt-out parameter. If no format was specified, the output defaults to text/calendar.
If the events are not found, if the rids were not zero (0), then the uids and rids are returned.
If the events are not found and the rids were zero (0), then only the uids are returned.
Example
Example 1 is in text/calendar format, and example 2 is in text/xml output.
Example 1
verifyevents_by_ids.wcap?id=$n3o2m05sx9v6t98t8u2p&calid=jdoe&uid=3bd9e72f0 00027cf0000000600002113;3bd9e717000045030000000100002113;3bd9e717000045030 000000100002113;3bd9cd4700002206000000010000202d&rid=0;20021027T230000Z;20 021026T230000Z;0&fmt-out=text/calendar
BEGIN:VCALENDAR
PRODID:-//SunONE/Calendar Hosting Server//EN
VERSION:6.0
BEGIN:VEVENT
UID:3bd9e717000045030000000100002113
RECURRENCE-ID:20021027T230000Z
END:VEVENTBEGIN:VEVENT
UID:3bd9cd4700002206000000010000202d
END:VEVENT
END:VCALENDARExample 2
verifyevents_by_ids.wcap?id=$n3o2m05sx9v6t98t8u2p&calid=savri&uid=3bd9e72f 000027cf0000000600002113;3bd9e717000045030000000100002113;3bd9e71700004503 0000000100002113;3bd9cd4700002206000000010000202d&rid=0;20021027T230000Z;2 0021026T230000Z;0&fmt-out=text/xml
<?xml version="1.0" encoding="UTF-8"?>
<iCalendar>
<iCal version="6.0" prodid="-//SunONE/Calendar Hosting Server//EN">
<EVENT>
<UID>3bd9e717000045030000000100002113</UID>
<RECURID>20021027T230000Z</RECURID>
</EVENT>
<EVENT>
<UID>3bd9cd4700002206000000010000202d</UID>
</EVENT>
</iCal>
</iCalendar>
verifytodos_by_idsPurpose
This command is used to verify if the todo specified with the uid and rid pair exists in the database.
Parameters
Table 7-38 lists verifytodos_by_ids parameters:
Table 7-38 verifytodos_by_ids Parameters
Parameter
Type
Purpose
Required
Default
calid
string
Calendar from which to fetch todos.
N
User’s default calendar
fmt-out
string
The format for the returned data.
The three format types:
text/calendar
text/xmlN
text/
calendarid
string
Uniquely identifies the session (session ID).
N*
null
rid
ISO 8601 DateTime string
Corresponding set of comma separated todo rids.
If this is a non-recurring todo, rid=0.
Y
N/A
tzid
time zone ID string
Time zone, such as “America/Los_Angeles”
N
Server’s default time zone
uid
string
Comma separated set of todo uids.
Y
N/A
* The id must be specified with the command unless the calendar to fetch from is public calendar.
Description.
This command tries to fetch todos matching the passed in uid-rid pairs.
Returns
If the todos are found, the data is returned in the format specified by the fmt-out parameter. If no format was specified, the output defaults to text/calendar.
If the todos are not found, if the rids were not zero (0), then the uids and rids are returned.
If the todos are not found and the rids were zero (0), then only the uids are returned.
Example
verifytodos_by_ids.wcap?id=bo35r2pr3e5po35r&calid=jdoe&uid=3bde188f0000472 d0000000b00000399&rid=20021029T200200Z&fmt-out=text/xml
<?xml version="1.0" encoding="UTF-8"?>
<iCalendar>
<iCal version="6.0" prodid="-//SunONE/Calendar Hosting Server//EN">
<TODO>
<UID>3bde188f0000472d0000000b00000399</UID>
<RECURID>20021029T200200Z</RECURID>
</TODO>
</iCal>
</iCalendar>
versionPurpose
To get the current WCAP version.
Parameters
Table 7-39 lists the version parameter:
Table 7-39 version Parameters
Parameter
Type
Purpose
Required
Default
fmt-out
string
The format for the returned data.
The three format types:
text/calendar
text/xmlN
text/
calendar
Description.
This command gets the current WCAP version. (Note: this is different from the server version as well as the HTTP version.)
Returns
The commands supports output types of iCal and XML, the variable X-NSCP-WCAPVERSION contains the WCAP version number.
Example
The following examples are for each of output data types.
- iCalendar: (URL: /version.wcap?fmt-out=text/calendar)
BEGIN:VCALENDAR
PRODID:-//iPlanet/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:2.0
X-NSCP-WCAPVERSION:2.0.0
END:VCALENDAR- XML: (URL: /version.wcap?fmt-out=text/xml)
<?xml version="1.0" encoding="UTF-8"?>
<iCalendar>
<iCal version="2.0" prodid="-//iPlanet/Calendar Hosting Server//EN">
<X-NSCP-WCAPVERSION>2.0.0</X-NSCP-WCAPVERSION>
</iCal>
</iCalendar>