This 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. Two exceptions to this rule are as follows:
You do not need it 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.
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:
This command allows you to verify whether a session is still valid or not.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
id |
string |
The session identifier. |
Y |
N/A |
fmt-out |
string |
The format for the returned data. The three format types: text/calendar text/xml |
N |
text/calendar |
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.
The following command returns whether the specified session is valid or not:
http://calendarserver/check_id.wcap? id=n3l0eeu6s3n3o3b8v &fmt-out=text/calendar
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-Alive BEGIN:VCALENDAR PRODID:-//SunJavaSystem/Calendar Hosting Server//EN METHOD:PUBLISH VERSION:6.0 X-NSCP-WCAP-CHECK-ID:1 END:VCALENDAR
Create a new calendar.
Parameter |
Types |
Purposes |
Required |
Default |
---|---|---|---|---|
allowdoublebook |
integer (0,1) |
Allows a user to determine whether or not to allow double booking on user’s calendars. 0 = Disallow double booking1 = Allow double booking |
N |
1 |
calid |
string |
The user’s calid, used to generate the new calendar’s calid. |
Y |
N/A |
id |
unique identifier string |
The session identifier. |
Y |
N/A |
fmt-out |
string |
The format for the returned data. The three format types: text/calendar text/xml |
Y |
text/calendar |
set_calprops |
integer (0,1) |
A boolean indicating whether to set the properties of the new calendar. 1 = Set properties.0 = Do not set properties. |
N |
0 |
subscribe |
integer (0 or 1) |
Allows a user to specify if the newly created calendar should be added to the user’s subscribed calendar list. 1 = Subscribe to the calendar 0 = Do not subscribe to the calendar |
N |
0 |
subscribe |
integer (0,1) |
Allows a user to determine if a newly created calendar should be added to the user’s subscribed calendar list. 0 = Do not subscribe 1 = Subscribe |
N |
1 |
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.
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 attempts 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 FAILED: ILLEGAL_CALID_NAME.
Valid characters for the calid parameter are:
Alphabet characters (A-Z, a-z)
Numeric characters (0-9)
Three special characters
Dash (-)
Underscore (_)
Period (.)
For example, these are legal values for the calid parameter: calendar1, calendar-1, calendar_1, calendar.1
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.wcap command.
Note that at calendar creation, if you do not specify calendar properties, the defaults set in the ics.conf file are used.
The returned output shows the calendar properties (retrieved with a call to the fetchcomponents_by_range command) formatted according to the fmt-out value.
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: FAILED: CREATECALENDAR_ALREADY_EXISTS_FAILED.
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:/calendarserver/createcalendar.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=newcal &set_calprops=1 &name=New-Calendar &categories=business;work
This command deletes a user’s calendar.
Parameter |
Types |
Purposes |
Required |
Default |
---|---|---|---|---|
calid |
string |
The name of the calendar to delete. |
Y |
N/A |
id |
unique identifier string |
The session identifier. |
Y |
N/A |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
unsubscribe |
integer (0,1) |
Determines if deleted calendars should be removed from the user’s subscribed calendar list. 0 = Do not unsubscribe 1 = Unsubscribe deleted calendars |
N |
1 |
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 can use this command, unless the ics.conf parameter service.wcap.allowdeletecalendars is set to “yes” (which is the default).
The returned output is the formatted output from a call to fetchcomponents_by_range.
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: FAILED: CALENDAR_DOES_NOT_EXIST (29).
For example, sending this URL deletes the calendar named newcal.
http://calendarserver/deletecalendar.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=newcal |
Delete events and todos from a calendar in a specified range.
ENS notifications for appid are not yet implemented.
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 Sun Java Communications Suite 5 Event Notification Service Guide. |
N |
N/A |
calid |
string |
Semicolon-separated list of calendar identifiers from which to delete events and todos. The calid can be supplied in two formats:
|
N |
Current user’s calid |
dtend |
Date-Time string |
End time and date of events or todos to be deleted. A value of 0 means delete all events and todos up to the end of time. This value must be in coordinated universal time. |
N |
0 |
dtstart |
Date-Time string) |
Start time and date of events or todos to be deleted. A value of 0 means delete all events and todos from the beginning of time. This value must be in coordinated universal time. |
N |
0 |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
N |
c |
id |
unique identifier string |
The session identifier. |
Y |
N/A |
smtp |
integer (0, 1) |
Send email cancellation to user with no calendar. 0 = No 1 = Yes |
N |
1 |
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.
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: FAILED: DELETECOMPONENTS_BY_RANGE_FAILED (21).
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 |
Deletes one or more events from a calendar by event identifier.
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 theSun Java Communications Suite 5 Event Notification Service Guide |
N |
N/A |
calid |
string |
Calendar identifier of event to delete. The calid can be supplied in two formats:
|
Y |
N/A |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
id |
unique identifier string |
The session identifier. Required unless the calendar is public. |
Y |
NULL |
mod |
integer 1,2,3,4 |
A modifier indicating which recurrences to retrieve. One of the following values: 1 = THISINSTANCE 2 = Deprecated, see note. 3 = Deprecated, see note. 4 = THISANDALL Note – Values 2 and 3 were deprecated. Using these values results in undetermined behavior. |
Y |
N/A |
notify |
integer 0,1 |
A boolean indicating whether or not to notify attendees of this change. 1 = Notify attendees. 0 = Do not notify attendees. |
N |
0 |
rid |
string |
Recurrence identifier of the event, or semicolon-separated list of recurrence identifiers. If a list, it must have same number of elements as the uid list. If there are no recurrences, the value is 0. |
Y |
N/A |
smtp |
integer (0, 1) |
Send email cancellation to user with no calendar. 0 = No 1 = Yes |
N |
1 |
tzid |
time zone ID string |
Default time zone to use if the rid parameter does not have a time zone specified. For example, “America/Los_Angeles” |
N |
server’s default time zone |
uid |
string |
Unique Identifier of an event to be deleted, or semicolon-separated list of unique identifiers. |
Y |
N/A |
Use this command to delete the specified event or events from the specified calendar.
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, Calendar Server WCAP Error Handling
If the rid parameter is passed, the command also deletes recurrences, as specified by the mod parameter. (See Calendar Server WCAP 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.
For example, there are two non-recurring events in the database with UID's 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://calendarserver/deleteevents_by_id.wcap ?id=br6p3t6bh5po35r &uid=uid-EVENT1;uid-EVENT2 &rid=0;0&mod=0;0 &fmt-out-text/calendar
The 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
Delete events from a calendar in a specified range.
ENS notifications for appid are not yet implemented.
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 theSun Java Communications Suite 5 Event Notification Service Guide |
N |
N/A |
calid |
string |
Semicolon-separated list of calendar identifiers from which to delete events. The calid can be supplied in two formats:
|
N |
Current user’s calid |
dtend |
Date Time string |
End time and date of events to be deleted. A value of 0 means delete all events until the end of time. |
N |
0 |
dtstart |
Date Time string |
Start time and date of events to be deleted. A value of 0 means delete all events from the beginning of time. |
N |
0 |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
id |
unique identifier string |
The session identifier. |
Y |
N/A |
smtp |
integer (0, 1) |
Send email cancellation to user with no calendar. 0 = No 1 = Yes |
N |
1 |
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.
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: FAILED: DELETEEVENTS_BY_RANGE_FAILED (22).
See also, Calendar Server WCAP Error Handling
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://calendarserver/deleteevents_by_range.wcap ?id=2342347923479asdf &calid=jdoe;john &dtstart=0 &dtend=0
Delete one or more todos from a calendar.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
appid |
string |
A runtime parameter that is not stored in the database. This parameter 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 theSun Java Communications Suite 5 Event Notification Service Guide |
N |
N/A |
calid |
string |
Calendar identifier of the todos to delete. The calid can be supplied in two formats:
|
Y |
N/A |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
id |
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 = Deprecated, see note. 3 = Deprecated, see note. 4 = THISANDALL Note – Values 2 and 3 were deprecated. Using these values results in undetermined behavior. |
Y |
N/A |
notify |
integer (0,1) |
A boolean telling whether or not to notify attendees of this change. 1 = Notify attendees. 0 = Do not notify attendees. |
N |
0 |
rid |
string |
The recurrence identifier of the todo, or a semicolon-separated list of recurrence identifiers. If a list, it must have the same number of elements as the uid list. If there are no recurrences, the value is 0. |
Y |
N/A |
tzid |
time zone ID string |
Default time zone to use if dtstart, or dtend parameters do not have a time zone specified. For example, “America/Los_Angeles” |
N |
server’s default time zone |
uid |
string |
The unique identifier of a todo to be deleted, or a semicolon-separated list of unique identifiers. |
Y |
N/A |
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.
If the uid does not exist, returns error 59.
See also, Calendar Server WCAP Error Handling
If the rid parameter is passed, the command also deletes recurrences, as specified by the mod parameter. See Calendar Server WCAP 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.
For example, there are two non-recurring todos in the database with UID's 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://calendarserver/deletetodos_by_id.wcap ?id=br6p3t6bh5po35r &uid=uid-TODO1;uid-TODO2 &rid=0;0 &mod=1;1 &fmt-out=text/calendar
The 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
Delete todos in a range from a calendar.
ENS notifications for appid are not yet implemented.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
appid |
string |
A runtime parameter that is not stored in the database. The parameter 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 theSun Java Communications Suite 5 Event Notification Service Guide |
N |
N/A |
calid |
string |
Semicolon-separated list of calendar identifiers from which to delete todos. The calid can be supplied in two formats:
|
N |
Current user’s calid |
dtstart |
Date Time string |
Start time and date of todos to be deleted. A value of 0 means delete all todos from the beginning of time. |
N |
0 |
dtend |
Date Time string |
End time and date of todos to be deleted. A value of 0 means delete all todos up to the latest time. |
N |
0 |
id |
unique identifier string |
The session identifier. |
Y |
N/A |
smtp |
integer (0, 1) |
Send email cancellation to user with no calendar. 0 = No 1 = Yes |
N |
1 |
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://calendarserver/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.
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: FAILED: DELETETODOS_BY_RANGE_FAILED (23).
See also, Calendar Server WCAP Error Handling
Export events and todos from a calendar to a file.
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.
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, which is indicated by Z at the end of the date-time string.
You must use this command with an HTTP POST. This is unlike other commands, which can be used with an HTTP GET.
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-8
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://calendarserver: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://calendarserver: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: 7004 BEGIN: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://calendarserver/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://calendarserver/susan?uid=tm-001 LOCATION:Green Conference Room STATUS:CONFIRMED TRANSP:OPAQUE END:VEVENT END:VCALENDAR
Retrieves attachments for a specific event or todo.
This command retrieves attachments using the attachment ID created when the attachment was stored.
Returns attachments in the form of mime type multipart/mixed data as part of the http reponse message body.
In the following example, the attachment output is generated in response to the command shown:
/fetchattachment.wcap?id=${SESSIONID}&calid=savri&uid=10122&rid=0 &attachid=20051012005&fmt-out=text/calendar
The output for this command is as follows:
HTTP/1.1 200 Date: Wed, 12 Oct 2005 22:04:35 GMT Content-type: multipart/mixed; boundary= -------------------abcdefghij Content-length: 347 Last-modified: Wed, 12 Oct 2005 22:04:35 GMT Pragma: no-cache Expires: 0 Cache-Control: no-cache Connection: Keep-Alive <>-------------------------------abcdefghij Content-Disposition:attachment; filename=/home/jane/cal.txt Content-Transfer-Encoding: base64 Content-Type: text/plain W2FrYW5rc2hhOi9ob21lL3NhdnJpXSUgY2FsIDExIDIwMDIKICAgTm92ZW1iZXIgMjAwMgog UyAgTSBUdSAgVyBUaCAgRiAgUwogICAgICAgICAgICAgICAgMSAgMgogMyAgNCAgNSAgNiAg NyAgOCAgOQoxMCAxMSAxMiAxMyAxNCAxNSAxNgoxNyAxOCAxOSAyMCAyMSAyMiAyMwoyNCAy NSAyNiAyNyAyOCAyOSAzMAoKW2FrYW5rc2hhOi9ob21lL3NhdnJpXSUgY2FsIDEyIDIwMDIK ICAgRGVjZW1iZXIgMjAwMgogUyAgTSBUdSAgVyBUaCAgRiAgUwogMSAgMiAgMyAgNCAgNSAgN iAgNwogOCAgOSAxMCAxMSAxMiAxMyAxNAoxNSAxNiAxNyAxOCAxOSAyMCAyMQoyMiAyMyAyNC AyNSAyNiAyNyAyOAoyOSAzMCAzMQo= -------------------------------abcdefghij--
Retrieve calendar events and todos with alarm triggers.
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 eventstodo returns only todos all returns both events and todos If an invalid value is passed in, the system assumes all. |
N |
all |
compressed |
integer (0,1) |
This parameter is deprecated in this release and might be deleted in future releases. For compressed=0, returns less data. Specifically, it does not return the following parameters:rrules, rdates, exrules, and exdates. For 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 Fetching Component State Data Using Calendar Server WCAP |
N |
ALL |
dtend |
Date Time string |
End time and date of events and todos to be returned. A value of 0 means fetch all events. |
N |
0 |
dtstart |
Date Time 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 calendar 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 calendar 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 |
emailorcalid |
integer (0, 1) |
0 = Returns calid in calendar address part of the ATTENDEE or ORGANIZER property and returns the RFC 822 address of the invitee or organizer in X-S1CS-EMAIL. 1 = Returns the RFC 822 compliant email address in the calendar address part of the ATTENDEE or ORGANIZER property, and returns the calid in X-S1CS-CALID. |
N |
0 |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
id |
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) |
1= Return all components in compressed form. Compressed form has master entry plus exceptions. 0 = Do not return components in compressed form. |
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 |
This command returns a list of events and todos having alarms that are about to go off during the specified time.
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.
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.
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.
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 41.
For example, suppose there are 3 events:
eventA: alarm on Dec. 25, 2001, 12:30 PM GMT
eventB: alarm on Feb. 10, 2002, 10:00 AM GMT
todoA: alarm on Jan. 20, 2002, 1:15 PM GMT
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://calendarserver/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://calendarserver/fetchcomponents_by_alarmrange.wcap ?id=abcdefg &dtstart=20020101T000000Z &dtend=20020601T000000Z &fmt-out=text/calendar |
It 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_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":131074 END:VEVENT BEGIN:VTODO UID:3c1162e200207ff600000015000010b7 DTSTAMP:20011208T011645Z 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": 5538 END:VTODO X-NSCP-WCAP-ERRNO:0 END:VCALENDAR
Fetch a list of components that had errors while sending group scheduling messages.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
attendee |
string |
The attendee’s calid to search on. The command searches the calendars specified in the calid parameter for all errors in events for this attendee. If this parameter is not specified, the command searches the primary owner’s calendars for all event errors for any attendee. Refer to Calendar Server WCAP Attendee Overview for a list of possible sub-parameters to pass-in. |
N |
N/A |
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 all returns both events and todos If an invalid value is passed in, the system assumes all. |
N |
all |
compressed |
integer (0,1) |
This parameter is deprecated in this release and might be deleted in future releases. For compressed=0, returns less data. Specifically, it does not return the following parameters:rrules, rdates, exrules, and exdates. For compressed=1, all recurrence data is returned. |
N |
0 |
emailorcalid |
integer (0, 1) |
0 = The calid is returned in the calendar 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 calendar 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 |
emailorcalid |
integer (0, 1) |
0 = Returns calid in calendar address part of the ATTENDEE or ORGANIZER property and returns the RFC 822 address of the invitee or organizer in X-S1CS-EMAIL. 1 = Returns the RFC 822 compliant email address in the calendar address part of the ATTENDE or ORGANIZER property, and returns the calid in X-S1CS-CALID. |
N |
0 |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
id |
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) |
1 = Returns all components in compressed form. Compressed form has master entries plus exceptions. 0 = Returns components expanded, but without master record and 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) |
tzidout |
standard time zone string |
The time zone returned data is translated to. |
N |
Returns data in Zulu time |
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.
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.
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.
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:
cal1 Events |
cal2 Events |
---|---|
event - 1c1 attendee: jdoe status: error |
event - 1c2 attendee: john status: OK |
event - 2c1 attendee: susan status: error |
event - 2c2 attendee: jdoe status: error |
event - 3c1 attendee: jdoe status: OK |
event - 3c2 attendee: susan status: OK |
event - 4c1 attendee: john status: OK |
event - 4c2 attendee: susan status: error |
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.
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 42.
Fetch a list of components that have changed during a specified time period.
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 eventstodo returns only todos all returns both events and todos If an invalid value is passed in, the system assumes all. |
N |
all |
compressed |
integer (0,1) |
This parameter is deprecated in this release and might be deleted in future releases. For compressed=0, returns less data. Specifically, it does not return the following parameters:rrules, rdates, exrules, and exdates. For 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 Fetching Component State Data Using Calendar Server WCAP |
N |
ALL |
dtend |
Date Time string |
End time and date of events to be returned. A value of 0 means fetch all events. |
N |
0 |
dtstart |
Date Time 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 calendar 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 calendar address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-CALID contains the calid value. |
N |
0 |
fetchattach |
integer (0, 1) |
0 = Returns information about the attachments. 1 = Returns the attachment itself. |
N |
0 |
fetchorder |
integer |
Specifies the order in which the events and todos are returned. The values are:
|
N |
0 |
emailorcalid |
integer (0, 1) |
0 = Returns calid in calendar address part of the ATTENDEE or ORGANIZER property and returns the RFC 822 address of the invitee or organizer in X-S1CS-EMAIL. 1 = Returns the RFC 822 compliant email address in the calendar address part of the ATTENDEE or ORGANIZER property, and returns the calid in X-S1CS-CALID. |
N |
0 |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
id |
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) |
1 = Returns all components in compressed form. Compressed form has master entry plus exceptions. 0 = Returns all components expanded with individual instances, not with a master record 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 |
Attachments can be output from the server through multiple ways.
Fetch_by_* commands : All commands that you can use to fetch the event will now have an extra argument to fetch attachment within the event itself.
fetchattach = 0/1 : A value of '0' does not return the attachment within the ical event structure but only return information about the event as follows:
<>BEGIN:VEVENT UID:uid1 RECURRENCE-ID:rid1 DTSTAMP:20050919T165229Z SUMMARY:Calendar Server Engineering meeting DTSTART:20050919T223000Z DTEND:20050919T233000Z CREATED:20050627T184431Z LAST-MODIFIED:20050829T221947Z PRIORITY:5 SEQUENCE:5 CLASS:PUBLIC ORGANIZER;CN="Your Name" ;X-NSCP-ORGANIZER-UID=Short Name ;X-S1CS-EMAIL=firstname.lastname@email.com :savri ATTACH;X-S1CS-ATTACH-ID=attach-id1 ;X-S1CS-CLIENT-ATTACH-ID=client-attach-id1 ;FMTTYPE=text/plain ;X-S1CS-FILENAME=test.txt ;X-S1CS-FILESIZE=347 :http://host:port/fetchattachments.wcap?uid=uid1&rid=rid1 &attach-id=attach-id1 ATTACH;X-S1CS-ATTACH-ID=attach-id2 ;FMTTYPE=image/jpeg X-S1CS-FILENAME=pic.jpeg ;X-S1CS-FILESIZE=4355 <>:http://host:port/fetchattachments.wcap?uid=uid1&rid=rid1 &attach-id=attach-id2 STATUS:CONFIRMED TRANSP:OPAQUE X-NSCP-ORIGINAL-DTSTART:20050919T223000Z X-NSCP-LANGUAGE:en X-NSCP-DTSTART-TZID:America/Los_Angeles X-NSCP-TOMBSTONE:0 X-NSCP-ONGOING:0 X-NSCP-ORGANIZER-EMAIL:firstname.lastname@email.com X-NSCP-GSE-COMPONENT-STATE;X-NSCP-GSE-COMMENT= "REQUEST-PENDING":131073 END:VEVENT |
The X-S1CS-CLIENT-ATTACH-ID will be emitted out only if the client had supplied its own id while storing the attachment. The URI is a WCAP URL that can be used by clients in conjunction with the session id to fetch the actual attachment.
A value of '1' to the fetchattachment command yields the actual attachment within the event itself as follows:
BEGIN:VEVENT UID:uid1 RECURRENCE-ID:rid1 DTSTAMP:20050919T165229Z SUMMARY:Calendar Server Engineering meeting DTSTART:20050919T223000Z DTEND:20050919T233000Z CREATED:20050627T184431Z LAST-MODIFIED:20050829T221947Z PRIORITY:5 SEQUENCE:5 CLASS:PUBLIC ORGANIZER;CN="Your Name" ;X-NSCP-ORGANIZER-UID=Short Name ;X-S1CS-EMAIL=firstname.lastname@email.com :savri ATTACH;;X-S1CS-ATTACH-ID=attach-id1 ;X-S1CS-CLIENT-ATTACH-ID=client-attach-id1 ;X-S1CS-FILENAME=pic.jpeg ;FMTTYPE=image/basic;ENCODING=BASE64;VALUE=BINARY: MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE <...remainder of "BASE64" encoded binary data...> ATTACH;;X-S1CS-ATTACH-ID=attach-id2 ;X-S1CS-FILENAME=pic2.jpeg ;FMTYPE=IMAGE/JPEG;ENCODING=BASE64;VALUE=BINARY:MIICajC CAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBhMCVVMxLDA qBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIENvcnBvcmF0aW9uMRw <...remainder of "BASE64" encoded binary data...> STATUS:CONFIRMED TRANSP:OPAQUE X-NSCP-ORIGINAL-DTSTART:20050919T223000Z X-NSCP-LANGUAGE:en X-NSCP-DTSTART-TZID:America/Los_Angeles X-NSCP-TOMBSTONE:0 X-NSCP-ONGOING:0 X-NSCP-ORGANIZER-EMAIL:firstname.lastname@email.com X-NSCP-GSE-COMPONENT-STATE;X-NSCP-GSE-COMMENT="REQUEST-PENDING":131073 END:VEVENT |
It is advisable to specify fetchattach=0, to accelerate the response of fetch command in case there are lots of attachments. Instead, use the URL in the VEVENT to fetch the actual attachment when requested by the end user.
Export by default emits attachment information similar to fetchevents commands. It takes the same additional argument fetchattach and emits either the URL or the actual attachment itself depending on the value of fetchattach (0/1).
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.
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.
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.
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.
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.
For example, the calendar jdoe has these three events:
eventA: last-modified on Feb. 10, 2002, 10:00 AM GMT.
eventB: last-modified on Dec. 25, 2001, 12:30 PM GMT.
todoA: last-modified on Jan. 20, 2002, 1:15 PM GMT.
Here are some queries and their return values:
http://calendarserver/fetchcomponents_by_lastmod.wcap ?id=jdoe &dtstart=0 &dtend=0
The above query would fetch all events and todos that have ever been modified. Thus eventA, eventB, and todoA would be returned.
http://calendarserver/fetchcomponents_by_lastmod.wcap ?id=jdoe &dtstart=20011201T112233Z &dtend=20020131T112233Z
The 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://calendarserver/fetchcomponents_by_lastmod.wcap ?id=jdoe &dtstart=20020101T112233Z &dtend=20020601T112233Z
The 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.
Retrieve calendar events and todos.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
attrset |
integer (0,1) |
Allows the user to indicate to the server if they want to retrieve the complete event or task data from the server, or if they only want a subset of the data for each matching component returned. Intended to minimize the amount of data returned and thereby the amount of processing a client must do. 0 = Returns the following parameters: uid, dtstart, dtend, summary. 1 = Returns the following parameters: uid, rrule, dtstart, dtend, summary, class, location, valarm. 2 = Returns the full event. |
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 eventstodo returns only todosall returns both events and todos If an invalid value is passed in, the system assumes all. |
N |
all |
compressed |
integer (0,1) |
This parameter is deprecated in this release and might be deleted in future releases. For compressed=0, returns less data. Specifically, it does not return the following parameters:rrules, rdates, exrules, and exdates. For 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 Fetching Component State Data Using Calendar Server WCAP |
N |
ALL |
dtend |
Date Time string |
End time and date of events to be returned. A value of 0 means fetch all events. |
N |
0 |
dtstart |
Date Time 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 = Returns calid in calendar address part of the ATTENDEE or ORGANIZER property and returns the RFC 822 address of the invitee or organizer in X-S1CS-EMAIL. 1 = Returns the RFC 822 compliant email address in the calendar address part of the ATTENDEE or ORGANIZER property, and returns the calid in X-S1CS-CALID. |
N |
0 |
filter |
string |
A string containing a name-value pair representing a filter for an event or todo. The name can be any valid event or todo RFC 2445 compliant property. The value is what to match in the component. Only single valued filters are supported. For example: CATEGORY=birthday Various partial matches are allowed using *, for example:
|
N |
NULL |
emailorcalid |
integer (0, 1) |
0 = The calid is returned in the calendar 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 calendar address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-CALID contains the calid value. |
N |
0 |
fetchattach |
integer (0, 1) |
0 = Returns information about the attachments. 1 = Returns the attachment itself. |
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. Two format types: text/calendar text/xml |
Y |
text/calendar |
id |
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 XML block. 0 = Count not requested. |
N |
0 |
invitecount |
integer (0, 1) |
0 = Do not return a count of the open invitations. Open invitations are events and todos where PARTSTAT=needs-action. 1 = Returns the count of open invitations in X-S1CS-CALPROPS-INVITATION-COUNT If more than one calid is specified, the open invitation count for each calendar is returned in the corresponding iCal or XML block. |
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) |
1 = Return all components in compressed form. The compressed form has master entry plus exceptions. 0 = Return components as individual instances, without master record and 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 = EXACT |
N |
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 |
Use this command to retrieve properties, events, and todos from one or more specified calendars.
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.
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 WCAP Command:
Tasks due within the date range
Overdue tasks
Tasks completed within the date range
Tasks that are never due but have a start date within the range
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.
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 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.
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.
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 1
This example fetches components for the current user from Dec. 1, 2001 to Jan. 31, 2002, using the following URL:
http://calendarserver/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:VCALENDAR
Example 2
The second example fetches all components for calendars jdoe and susan between Dec. 1, 2001 to Jan. 31, 2002.
http://calendarserver/fetchcomponents_by_range.wcap ?id=bes6bbe2mu98uw9 &calid=jdoe;susan &dtstart=20020101T000000Z &dtend=20020202T000000Z &fmt-out=text/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
Returns a list of deleted components from the deletelog.db for a specified time period.
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.
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.
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.
When this command is called in compressed mode, that is, 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 does not return any master entries associated with the deleted recurring instances that are still active. Those active master entries are returned using the fetchcomponents_by_lastmod command. If all the instances in a recurring chain are deleted, the master component returns dtstart, dtend, rrules, rdates, exrules, exdates and uid.
When the command is called in expanded mode, that is, 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.
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. The 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
The first example shows the command defaulting to recurring=0, which returns components expanded to individual instances. The second example shows the command using recurring=1, which returns the master record plus exceptions.
http://calendarserver/fetch_deletedcomponents.wcap ?id=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
http://calendarserver/fetch_deletedcomponents.wcap ?id=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
Retrieve specific calendar events.
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 is deprecated in this release and might be deleted in future releases. For compressed=0, returns less data. Specifically, it does not return the following parameters:rrules, rdates, exrules, and exdates. For 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 Fetching Component State Data Using Calendar Server WCAP |
N |
ALL |
emailorcalid |
integer (0, 1) |
0 = The calid is returned in the calendar 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 calendar address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-CALID contains the calid value. |
N |
0 |
emailorcalid |
integer (0, 1) |
0 = Returns calid in calendar address part of the ATTENDEE or ORGANIZER property and returns the RFC 822 address of the invitee or organizer in X-S1CS-EMAIL. 1 = Returns the RFC 822 compliant email address in the calendar address part of the ATTENDEE or ORGANIZER property, and returns the calid in X-S1CS-CALID. |
N |
0 |
fetchattach |
integer (0, 1) |
0 = Returns information about the attachments. 1 = Returns the attachment itself. |
N |
0 |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
id |
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 = Deprecated, see note. 3 = Deprecated, see note. 4 = THISANDALL Note – Values 2 and 3 were deprecated. Using these values results in undetermined behavior. |
N |
1 (THISINSTANCE) |
recurring |
integer (0, 1) |
1 = Returns all components in compressed form , which contains a master entry plus exceptions 0 = Returns components expanded into individual instances. |
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 Date Time 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 |
string |
The unique identifier for the event. |
Y |
N/A |
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 in Calendar Server WCAP
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.
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 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.
This query retrieves an event with a specific id.
http://calendarserver/fetchevents_by_id.wcap ?id=bes6bbe2mu98uw9 &calid=jdoe &uid=3c11625900005ffe00000011000010b7 &fmt-out=text/calendar |
It 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^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: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
Retrieve specific calendar todos.
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 is deprecated in this release and might be deleted in future releases. For compressed=0, returns less data. Specifically, it does not return the following parameters:rrules, rdates, exrules, and exdates. For 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 Fetching Component State Data Using Calendar Server WCAP |
N |
ALL |
emailorcalid |
integer (0, 1) |
0 = The calid is returned in the calendar 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 calendar address part of the ATTENDEE and ORGANIZER properties. The X-Token X-S1CS-CALID contains the calid value. |
N |
0 |
fetchattach |
integer (0, 1) |
0 = Returns information about the attachments. 1 = Returns the attachment itself. |
N |
0 |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
id |
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 = Deprecated, see note. 3 = Deprecated, see note. 4 = THISANDALL Note – Values 2 and 3 were deprecated. Using these values results in undetermined behavior. |
N |
1 (THISINSTANCE) |
recurring |
integer (0, 1) |
1 = Returns all components in compressed form, with a master entry plus exceptions. 0 = Returns components in expanded form as individual instances. |
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 Date Time 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 |
string |
The unique identifier for the todo. |
Y |
N/A |
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.
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.
For each calendar specified in calid, the server returns the calendar's todos. If the todo has recurrences, it returns them as specified by the rid and mod parameters. See Recurring Components in Calendar Server WCAP
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.
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.
For example, a todo “weekly todo B” that’s due weekly at 5:00 PM 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, rid=20020201T170000Z, of the first item is specified, but no modifier is specified. Therefore, it defaults to 1 THISINSTANCE:
http://calendarserver/fetchtodos_by_id.wcap? id=n3o3m05sx9v6t98t8u2p &uid=3c15309d000037020020021400003189 &rid=20020201T170000Z &fmt-out=text/calendar
The 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:VCALENDAR |
Retrieve data about all time zones supported by the server.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
dtend |
Date Time string |
End date of the crossover values to retrieve. A value of 0 means get all crossover dates until the last known year (2087). |
N |
0 |
dtstart |
Date Time string |
Start date of crossover values to retrieve. A value of 0 means get all crossover dates from the first known year (1987). |
N |
0 |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
id |
unique identifier string |
The session identifier. |
Y |
N/A |
Use this command to retrieve data about all time zones that are supported by the server. The crossover values are defined to be the dates when the time zone 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 time zone does not have daylight-savings, then this value is set to the empty-string.
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.
If there was an error in getting the time zones, the server returns the error FAILED: GET_ALL_TIMEZONES_FAILED (24).
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/calendar
This 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:VCALENDAR
Example 2
The following is an example of a time zone array element where crossover dates have been limited to the years from mid-1998 to 2006:
timezoneList[20] = new TZ(\qAmerica/Los_Angeles\q, \qPST\q, \qPDT\q, \q-0800\q, \q-0700\q, new Array (\q19981025T090000Z\q,\q20020404T100000Z\q,\q20021031T090000Z\q, \q20020402T100000Z\q,\q20021029T090000Z\q,\q20020401T100000Z\q, \q20021028T090000Z\q, \q20020407T100000Z\q, \q20021027T090000Z\q, \q20030406T100000Z\q, \q20031026T090000Z\q, \q20040404T100000Z\q, \q20041031T090000Z\q, \q20050403T100000Z\q, \q20051030T090000Z\q, \q20060402T100000Z\q, \q20061029T090000Z\q))
The “America/Phoenix” time zone 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())
Retrieve calendar properties.
Use this command to retrieve the calendar properties for the specified calendars.
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-COUNT
If the calendar exists, but the user does not have READ access to it, errno is set to FAILED: ACCESS_DENIED_TO_CALENDAR (28).
If the fetch fails for any calendar, its error number, errno, is set to FAILED: GET_CALPROPS_FAILED (20).
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://calendarserver/get_calprops.wcap ?id=2mu95r5so0hq68ts6q3 &calid=jdoe;jsmith;susan &fmt-out=text/calendar
This 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 the free-busy calendar information for users.
This command retrieves the free-busy calendar information for specified users. Free-busy calendar information indicates which times have been scheduled on the user's calendar. Free-busy calendar information does not include any details of the scheduled time.
Free-busy time is calculated for a time period that can be specified in one of three ways:
duration parameter
The default value of the duration parameter is taken from the ics.conf setting service.wcap.freebusyduration. The standard default is 60 days. This is the default taken if none of the time period parameters are passed in.
dtstart and dtend parameters
The absolute start and end times to use for this free-busy calculation. These parameters have no default values.
freebusybegin and freebusyend parameters.
The relative beginning and end times to include in the free-busy calculation. If these are specified with no value, the default is 30 for each.
If conflicting parameters are passed in, the duration parameter overrides the other two types.
For further information about how free-busy calendars are specified, see Free-Busy Calendars in Calendar Server WCAP
At fetch time, the server looks at the free-busy value in the event structure. If the value exists, it emits it as X-S1CS-FBTYPE. If the value does not exist, that is, the value was not stored with the event, the server calculates the value for X-S1CS-FBTYPE using the algorithm shown in the following table.
PARSTAT Value |
TRANSPARENCY Value |
|
---|---|---|
None specified, or OPAQUE |
TRANSPARENT |
|
TENTATIVE |
Busy-tentative |
Free |
ACCEPTED |
Busy |
Free |
DECLINED |
Free |
Free |
NEEDS-ACTION |
Busy-tentative |
Free |
For overlapping events that do not have the same free-busy types, the system returns the value based on the following precedence rules: Busy overrides Busy-tentative, Busy-tentative overrides Free.
If this command fails for any reason, errno is set to 39.
For example, a calendar called jdoe has the following events:
10:00-11:00 |
first meeting |
12:00-1:00 |
lunch |
3:00-4:00 |
second meeting |
The free-busy time for jdoe (from 9:00 to 6:00) would be the following:
9:00-10:00 |
Free |
10:00-11:00 |
Busy |
11:00-12:00 |
Free |
12:00-1:00 |
Busy |
1:00-3:00 |
Free |
3:00-4:00 |
Busy |
4:00-6:00 |
Free |
The following URL generates free-busy information found in the calendar jdoe between May 1, 2002 and July 1, 2002.
The output is returned in text/calendar format.
http://calendarserver/get_freebusy.wcap ?id=2mu95r5so0hq68ts6q3 &calid=jsun &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
Generate a set of globally unique identifiers.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
guidCount |
integer |
Number of GUID's to return. |
N |
1 |
This command returns the specified number of globally unique identifiers, GUID's. The client need not be authenticated to call this command.
http://calendarserver/get_guids.wcap ?guidCount=10 &fmt-out=text/calendar |
BEGIN: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
Gets the server time for the requested calendars.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
calid |
semicolon-separated list of strings |
A list of calendar identifiers. |
N |
Current user’s calid |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
id |
unique identifier string |
The session identifier. |
Y |
N/A |
tzidout |
time zone ID string |
Time zone to report returned data in. |
N |
Zulu time |
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.
X-NSCP-WCAP-ERRNO:1 - Session ID timed out or Invalid session ID
X-NSCP-WCAP-ERRNO:28 - Command failed. The system denies access to the calendar
X-NSCP-WCAP-ERRNO:29 - Command failed. The calendar does not exist in the database
X-NSCP-WCAP-ERRNO:55 - Get Server time Failed
http://calendarserver/gettime.wcap ?id=br6e8vx9ek02n2ow9 &calid=jdoe &tzidout=America/Los_Angeles |
BEGIN:VCALENDAR PRODID:-//SunONE/Calendar Hosting Server//EN VERSION:2.0 X-NSCP-WCAPTIME:20021021T082743 X-NSCP-WCAP-ERRNO:0 END:VCALENDAR
Retrieve the calendar preferences for the current user.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
id |
unique identifier string |
The session identifier. |
Y |
N/A |
userid |
string |
Indicates which user’s preferences to get. |
N |
N/A |
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 LDAP directory.
allowsetprefs– If set to 1, allow set_userprefs.wcap to modify the user preferences.
See theSun Java System Calendar Server 6.3 Administration Guide for more information about server preferences.
The Calendar Server configuration program adds new ACI's. If you are upgrading from an earlier version of Java Enterprise System, you must rerun the configuration program to have the new ACI's added. Or you can use the Directory Server ldapmodify command to add them yourself as follows.
In this example, the ACI is added to the root suffix, o=usergroup:
dn: o=usergroup changetype: modify add: aci aci: (targetattr="icscalendar || cn || givenName || sn || uid || mail") (targetfilter=(objectClass=icscalendaruser)) (version 3.0; acl "Allow calendar administrators to proxy-product=ics, class=admin,num=2,version=1"; allow (proxy) groupdn="ldap:///cn=Calendar Administrators,ou=Groups,o=usergroup";) |
In the following example, the ACI is added to the basedn domain node, o=sesta.com,o=usergroup:
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 Calendar Access Control Information (ACI)
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";) |
If there is no basedn domain node, add the preceding ACI to the root suffix itself by changing the dn: value to o=usergoup.
The following URL retrieves user preferences for the current user:
http://calendarserver/get_userprefs.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &fmt-out=text/calendar
This 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:VCALENDAR
The following string of commands generates the output shown:
http://calendarserver/get_userprefs.wcap ?id=t95qm0n0es3bo35r &fmt-out=text/calendar &userid=jdoe http://calendarserver/get_userprefs.wcap ?id=t95qm0n0es3bo35r &fmt-out=text/calendar &userid=mailto:sue@sesta.com http://calendarserver/get_userprefs.wcap ?id=t95qm0n0es3bo35r &fmt-out=text/calendar &userid=john123abc |
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:VCALENDAR GET /get_userprefs.wcap?id=eo38ue2q2rq6r68u &fmt-out=text/calendar&userid=mailto: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:VCALENDAR GET /get_userprefs.wcap?id=eo38ue2q2rq6r68u &fmt-out=text/calendar&userid=john123abc BEGIN:VCALENDAR PRODID:-//SunONE/Calendar Hosting Server//EN METHOD:PUBLISHx VERSION:2.0 X-NSCP-WCAP-ERRNO:61 END:VCALENDAR
Import events and todos from a file to a calendar.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
appid |
string |
A runtime parameter that is not stored in the database. This parameter 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 Sun Java Communications Suite 5 Event Notification Service Guide. |
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/calendartext/xml |
Y |
N/A |
dtend |
Date Time 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 |
Date Time 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 |
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, which is indicated by the Z at the end of the date-time string.
You must use this command with an HTTP POST message, unlike other commands that 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.
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://calendarserver:12345/import.wcap ?id=t95qm0n0es3bo35r &calid=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\>
List all calendars owned by current user.
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 |
Returns only those calendars where the user is the primary owner.
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 all calendars subscribed to by current user.
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 |
Returns calendars the user is subscribed to, including the ones for which the user is the primary owner.
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
Authenticate a specific user.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
appid |
string |
A runtime parameter that is not stored in the database. The parameter 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 Sun Java Communications Suite 5 Event Notification Service Guide. |
N |
N/A |
applyauthfilter |
integer |
1 = Use the authfilter for login. Note – Communications Express requires this to be turned off (0). |
No |
1 |
fmt-out |
string |
The format for the returned data. Two format types: text/calendar text/xml |
Y |
text/calendar |
lang |
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 |
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.
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 and proxy authentication APIs, see Sun Java System Calendar Server 6.3 WCAP Developer’s Guide.
If the user fails to authenticate correctly, the login window reappears with an error noting a failure to log in.
For example, the following URL attempts to login user jdoe:
http://calendarserver/login.wcap ?user=jdoe&password=mypword
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://calendarserver/en/main.html?id=er6en05tv6n3bv9 &lang=en &host=http://calendarserver/
Terminate the current user’s session.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
fmt-out |
string |
The format for the returned data. The three format types: text/calendartext/xml |
N |
textcalendar |
id |
unique identifier string |
The session identifier. |
Y |
N/A |
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 WCAP Command:
http://calendarserver/logout.wcap ?id=bu9p3eb8x5p2nm0q3
Determine whether the calendar server is active.
This command takes no parameters.
This command returns a minimal HTML page to indicate that the server responded.
Only users with administrative privilege can use this command.
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 for a calendar’s properties.
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 primaryOwner and name are 0 |
id |
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 property0 = 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 = EXACT |
N |
0 |
search-string |
string |
The string to search for in calendars. |
Y |
N/A |
This command requests a search for a calendar using the query type specified by searchOpts. WCAP returns the calendar properties for all calendars where a value in the one of the properties, primaryOwner, calid, name, exactly matches the search-string given in the search-string parameter. If there are multiple matches, it returns all of them, up to the maximum number of matches specified in maxResults.
When searching for the primary owner, the internal search filter is set to find exact matches. If you want 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 by uncommenting the following line:
!service.calendarsearch.ldap.primaryownersearchfilter = "(&(|(uid=*%s*)(cn=*%s*))(objectclass=icsCalendarUser))"
Enabling the wildcard search can negatively impact performance.
This command searches for a match in one of three properties:
calid. The calendar’s unique identifier.
name. The calendar’s common name.
primaryOwner. The calendar’s primary owner.
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.
The four search options are the following:
CONTAINS = Returns the calendar properties that contain the search-string.
BEGINS_WITH = Returns the calendar properties that begin with the search-string.
ENDS_WITH = Returns the calendar properties that ends with the search-string.
EXACT = Returns the calendar properties that exactly match the search-string.
The following example URL searches all calendars for the primary owner property, primaryOwner=1 to see if it contains (searchOpts=0) the string jdoe:
http://calendarserver/search_calprops.wcap ?id=n3o3m05sx9v6t98t8u2p &search-string=jdoe &primaryOwner=1 &searchOpts=0 &maxResults=50 &fmt-out=text/calendar |
The 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 the calendar properties of a calendar.
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 double booking. 1 = Allow double booking. 0 = Disallow double booking. |
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 |
fbinclude |
integer (0,1) |
Specifies whether the calendar is used for calculating the free-busy time for this user. 0 = Do not include this calendar in the free-busy lookup calculation. 1 = Include this calendar in the free-busy calculation. |
N |
N/A |
fmt-out |
string |
The format for the returned data. The three format types: text/calendartext/xml |
N |
text/calendar |
id |
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 |
read |
integer |
This parameter has been deprecated in favor of the acl parameter. It remains here only for backwards compatibility. The new read-access value of the calendar. The value can be one of the following: 0 PRIVATE1 PUBLIC 4 PRIMARY_OWNER_ONLY |
N |
N/A |
tzid |
string |
The new time zone identifier for this calendar. |
N |
"" |
write |
integer |
This parameter has been deprecated in favor of the acl parameter. It remains here only for backwards compatibility. The new write-access value of the calendar. The value can be one of the following: 0 PRIVATE1 PUBLIC 4 PRIMARY_OWNER_ONLY |
N |
N/A |
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 want 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 time zone-identifier of the calendar.
Allow or disallow double booking for this calendar.
Here is a sample URL that sets calendar properties: (The calid parameter is required.)
http://calendarserver?set_calprops.wcap ?id=dfasdfzd3ds &calid=jdoe &categories=business;meeting &name=John%39s%32Calendar
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:
Character |
Code |
---|---|
= |
%3D |
& |
%26 |
"" |
%22 |
For example, the following URL modifies three calendars with ID's xxxx, yyyy, and zzzz, setting the descriptions to X-Calendar, Y-Calendar, and Z-Calendar, respectively:
http://calendarserver?id=fasdfzd3ds &multiple=3 &cal=calid%3Dxxxx%26description%3DX-Calendar &cal=calid%3Dyyyy%26description%3DY-Calendar &cal=calid%3Dzzzz%26description%3DZ-Calendar
This is the equivalent of the following three URL's:
http://calendarserver?id=fasdfzd3ds&calid=xxxx&desc=X-Calendar http://calendarserver?id=fasdfzd3ds&calid=yyyy&desc=Y-Calendar http://calendarserver?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 decodes each cal parameter and set the properties appropriately.
See Calendar Access Control Information (ACI), 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 ACE's to a maximum of 75 per calendar.
If the ics.conf parameter user.allow.doublebook is set to “yes”, then:
Allowed — Double booking is allowed if the user’s doublebookingcalendar property is set to 1).
Disallowed — Double booking is disallowed if the calendar doublebooking property is set to 0. The command returns error 40 STORE_FAILED_DOUBLE_BOOKED.
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.
See Free-Busy Calendars in Calendar Server WCAP, in the Common Topics section at the front of this chapter.
See Changing Language or Character Set for Calendar Server WCAP, in the Common Topics section at the front of this chapter.
Modify the preferences or password for a session.
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/calendartext/xml |
Y |
text/calendar |
id |
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 |
This command modifies the preferences for the current user. You might also modify the user’s password through LDAP.
Use of this parameter is only necessary when setting the subscribed list of calendars, in icsSubscribed, or the subscribed list of groups, in 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 converts the ^ back to a :. If the value of the convertCalid is 0, the conversion does not happen.
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.
The function returns the text of get_userprefs.
For example, the following URL adds a new preference, ceBgcolor, to the calendar and sets it to black:
http://calendarserver/set_userprefs.wcap ?id=b5q2o8ve2rk02nv9t6 &add_attrs=ceBgcolor=black
This URL deletes the calendar preference ceBgcolor from the user’s preferences.
http://calendarserver/set_userprefs.wcap ?id=b5q2o8ve2rk02nv9t6 &del_attrs=ceBgcolor
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
This URL would modify the calendar preference ceBgcolor to have the value white:
http://calendarserver/set_useprefs.wcap?id=b5q2o8ve2rk02nv9t6 &set_attrs=ceBgcolor=white
This URL would allow the logged-in administrator to modify the calendar preference ceBgcolor to have the value black for user jdoe:
http://calendarserver/set_userprefs.wcap ?id=b5q2o8ve2rk02nv9t6 &userid=jdoe &set_attrs=ceBgcolor=black
Add events to a calendar.
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 addresses |
Recipients 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 that is not stored in the database. The parameter 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 Sun Java Communications Suite 5 Event Notification Service Guide. |
N |
N/A |
attendees |
semicolon-separated list of strings |
An event’s iCalendar RFC 2445 attendee properties. For a list of the properties understood by Calendar Server, see Calendar Server WCAP Attendee Overview. One optional property 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 Group Scheduling Engine (GSE) does not process this attendee. |
N |
N/A |
calid |
string |
Calendar identifier, or email address of the calendar, in which to store the event. |
Y |
N/A |
categories |
semicolon-separated list of strings |
The event categories. |
N |
N/A |
charset |
string |
The character set for the calendar. |
N |
N/A |
compressed |
integer (0,1) |
This parameter is deprecated in this release and might be deleted in future releases. For compressed=0, returns less data. Specifically, it does not return the following parameters:rrules, rdates, exrules, and exdates. For compressed=1, all recurrence data is returned. |
N |
0 |
contacts |
semicolon-separated list of strings |
Contacts for the event. |
N |
N/A |
deleteattach |
semicolon-separated list of strings |
Attachment IDs of the attachments to be deleted. |
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 strings |
Event 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 in Calendar Server WCAP |
N |
N/A |
fbtype |
integer (0-4) |
A free-busy calculation is performed when the event is created. The value derived is stored in this parameter. The integer values have the following meaning: 0 — None 1 — Free 2 — Busy 3 — Busy-tentative 4 — Busy-unavailable |
N |
0 |
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/calendartext/xml |
N |
text/calendar |
geo |
two semicolon-separated floats |
Semicolon-separated string of two float numbers representing the event’s geographical location as latitude and longitude. For example, 37.31;-123.2. |
N |
0;0 |
icsClass |
string |
Event class. One of the following values: PUBLIC— Others can see time and text only PRIVATE — Others can see time and date only CONFIDENTIAL — Others can see nothing. (Set transparent = 1 to make it invisible). |
N |
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 a component record. For example, en, fr, de. |
N |
N/A |
location |
string |
Event location. |
N |
"" |
method |
integer (1,2,4,8,256) |
ITIP methods for group scheduling. The organizer issues the following ITIP methods:
The attendee issues this ITIP method: 4 = REPLY |
Y |
1 (PUBLISH) |
mod |
integer |
A modifier indicating which recurrences to retrieve. One of the following values: 1 = THISINSTANCE 2 = Deprecated, see note. 3 = Deprecated, see note. 4 = THISANDALL Note – Values 2 and 3 were deprecated. Using these values results in undetermined behavior. |
N Y |
N/A |
notify |
integer (0,1) |
This has been deprecated. It remains only for backward compatibility. The Group Scheduling Engine (GSE) module now takes care of all email notifications. A boolean indicating whether or not to notify attendees of a change to an event. 1 = Notify attendees. 0 = Do not notify attendees. |
N |
0 |
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, who is 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= highest 9= lowest |
N |
5 |
rchange |
integer (0,1) |
A boolean indicating whether or not to expand a recurring event. 1 = expand 0 = do not expand |
N |
0 |
rdates |
semicolon-separated list of ISO 8601 Date Time Z strings |
Event recurrence dates. To successfully create events, the rrules parameter must also be specified. |
N |
N/A |
relatedTos |
semicolon-separated list of quoted strings |
Other events to which this event is related. |
N |
N/A |
replace |
integer (0,1) |
A boolean. For parameters with semicolon-separated values: 1 = updateReplace the old values with the new passed-in values. 0 = append Adds the new passed-in values to the old ones. |
N |
0 |
resources |
semicolon-separated list of strings |
The resources associated with the event. |
N |
N/A |
rid |
ISO 8601 Date Time 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 strings |
Event recurrence rules. A semicolon-separated list of recurrence-rule strings. Each rule value must be enclosed in quotes. See Recurring Components in Calendar Server WCAP |
N |
N/A |
sendattach |
integer (0, 1) |
0 = Sends information about the attachments in an iTIP message. 1 = Sends the attachment itself. |
N |
0 |
seq |
integer |
(Not implemented) Event sequence number. |
N |
0 |
smtp |
integer (0, 1) |
Send email cancellation to user with no calendar. 0 = No 1 = Yes |
N |
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 FINAL |
N |
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_MODIFY If 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) |
1= transparent. Exclude this event from free-busy calculations. 0 = opaque. Include it in free-busy 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-Token properties, in iCalendar RFC 2445 format. For more information on X-Tokens, see X-Tokens Used by Calendar Server WCAP. |
N |
N/A |
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 in Calendar Server WCAP
Use the language parameter to specify the language of the event. See Changing Language or Character Set for Calendar Server WCAP
For an explanation of how to use the attendee and method parameters to do group scheduling, see the Common Topics section Calendar Server WCAP Attendee Parameter.
For an explanation of how to replace, append or delete a parameter, see the explanation in the Common Topics section Updating Parameter Values in Calendar Server WCAP
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:
PARTSTAT=X-NSCP-WCAP-ATTENDEE-DELETE^jdoe |
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.
Each case requires a different set of parameters :
To create new events requires only the dtstart parameter.
Every other parameter is optional. The server generates the uid.
To modify existing events requires two parameters:
uid
mod
All other parameters are optional. If a parameter is not specified, the event retains the previous value of the property.
Attachments can be stored as data for an event. Use the sendattach parameter to specify whether an actual attachment is being sent as part of the iTIP invitation data, "0" for none, and "1" for attachment present in data.
Attachments can be stored as part of the event on the Calendar Server through the storeevents.wcap command. This command is enhanced with following new arguments:
deleteattach=attach-id1;attach-id2;attach-id3 : Deletes existing attachments from an event using the parameter without deleting the event itself. The attachid1, attachid2, and so on should be the attachment id values emitted in the X-S1CS-ATTACH-ID x-token as part of the VEVENT returned for a fetch command. You can use the delete_by_* commands to delete the events as well as the associated attachments.
sendattach = 0/1 : Determines whether the actual attachments are sent as part of the iTIP invitation or not.
In earlier versions of Calendar Server, attachments could only be sent as a reference (URL) to a Web location. The attachments parameter was used to hold the URL.
The attachments parameter has been deprecated. It remains functional in this release only for backward compatibility. Change any scripts you have that use the old parameter to the new attachment model.
The currently existing attachments argument in WCAP can be used for specifying URL (web locations of documents) as reference, these attachments will not be stored onto the server, but the reference would be returned to the client.
The actual attachments will follow as multipart mixed data for the POST. Following example shows how attachments can be stored by passing arguments to storeevents in the URI itself and the actual attachments in the data.
<>POST /storeevents.wcap?id=${SESSIONID}&calid=savri &uid=111&dtstart=20050927T150000Z&duration=PT1H=0&sendattach=0 HTTP/1.1 Connection: Keep-Alive Content-type: multipart/mixed; boundary=------------abcdefghij Content-Length: 2381 -----------------------------abcdefghij Content-Type: image/jpeg Content-Transfer-Encoding: base64 Content-Disposition:attachment ; filename=birthday.jpeg MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIEMII CajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEB hMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIEMIIC ajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBh MCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIE -------------------------------abcdefghij content-type: image/GIF content-disposition:attachment ; filename=birthday.GIF Content-Transfer-Encoding: base64 MIICajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1U EBhMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIEMII CajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEB hMCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIEMIIC ajCCAdOgAwIBAgICBEUwDQYJKoZIhvcNAQEEBQAwdzELMAkGA1UEBh MCVVMxLDAqBgNVBAoTI05ldHNjYXBlIENvbW11bmljYXRpb25zIEFEFF -------------------------------abcdefghij |
When someone outside the Calendar Server is invited to an event as a mailto attendee, an iTIP invitation is usually sent to the attendee using the iMIP protocol. If there are any attachments attached to the event, they will be send depending on the value of sendattach parameter (0 or 1). This provides the organizer, the granularity of deciding whether it is a minor update to the event which does not require sending the attachments, or a major update where new attachments might have been added and requires sending the attachments to the end user.
If sendattach=0, the VEVENT information sent out as an iTIP does not have any information regarding the attachment, or might behave similar to fetchattach=0. If sendattach=1, the URI in the VEVENT structure uses the 'CID' URI scheme to identify the attachments in the multipart mime message that is sent out using iMIP.
The example below shows an iMIP message. Note that the values of the CID URI are the values of content-id mime header field in the attachment.
This is a multi-part message in MIME format. boundary="----_=_NextPart_002_01C5BAFF.DAA83C14" ------_=_NextPart_002_01C5BAFF.DAA83C14 Content-Type: text/calendar; method=REQUEST; name="meeting.ics" Content-Transfer-Encoding: 8bit BEGIN:VCALENDAR BEGIN:VEVENT UID:uid1 RECURRENCE-ID:rid1 DTSTAMP:20050919T165229Z SUMMARY:Calendar Server Engineering meeting DTSTART:20050919T223000Z DTEND:20050919T233000Z CREATED:20050627T184431Z LAST-MODIFIED:20050829T221947Z PRIORITY:5 SEQUENCE:5 CLASS:PUBLIC ORGANIZER;CN="Asavari Ukidve" ;X-NSCP-ORGANIZER-UID=ShortName ;X-S1CS-EMAIL=FirstName.LastName@email.com :savri ATTACH:CID:uid1rid1attachid-1 ATTACH:CID:uid1rid1attachid-2 STATUS:CONFIRMED TRANSP:OPAQUE X-NSCP-ORIGINAL-DTSTART:20050919T223000Z X-NSCP-LANGUAGE:en X-NSCP-DTSTART-TZID:America/Los_Angeles X-NSCP-TOMBSTONE:0 X-NSCP-ONGOING:0 X-NSCP-ORGANIZER-EMAIL:FirstName.LastName@email.com X-NSCP-GSE-COMPONENT-STATE;X-NSCP-GSE-COMMENT="REQUEST-PENDING":131073 END:VEVENT END:VCALENDAR ------_=_NextPart_001_01C5BAFF.DAA83C14 Content-Type: application/octet-stream; name="All day event.ics" Content-Transfer-Encoding: base64 Content-ID: <uid1rid1attachid-1> Content-Description: All day event.ics Content-Disposition: attachment; filename="Alldayevent.ics" QkVHSU46VkNBTEVOREFSDQpQUk9ESUQ6LS8vTWljcm9zb2Z0IENvcnBvcmF0aW9uLy9PdXRsb29r IDkuMCBNSU1FRElSLy9FTg0KVkVSU0lPTjoyLjANCk1FVEhPRDpQVUJMSVNIDQpCRUdJTjpWRVZF TlQNCk9SR0FOSVpFUjpNQUlMVE86c3YxMzQ1MTJAaXBsYW5ldC5jb20NCkRUU1RBUlQ7VkFMVUU9 REFURToyMDAzMDEyOA0KRFRFTkQ7VkFMVUU9REFURToyMDAzMDEyOQ0KVFJBTlNQOlRSQU5TUEFS RU5UDQpTRVFVRU5DRTowDQpVSUQ6MDQwMDAwMDA4MjAwRTAwMDc0QzVCNzEwMUE4MkUwMDgwMDAw MDAwMEEwQTc5MEQ2QzBDNkMyMDEwMDAwMDAwMDAwMDAwMDAwMTAwDQogMDAwMDBBRDNEMEVDQUU2 MTAwNDQ2OEYwQjAyQUEyQTcxNTZCQQ0KRFRTVEFNUDoyMDAzMDEyOFQxOTMxNDVaDQpTVU1NQVJZ OkFsbCBkYXkgZXZlbnQNClBSSU9SSVRZOjUNCkNMQVNTOlBVQkxJQw0KRU5EOlZFVkVOVA0KRU5E OlZDQUxFTkRBUg0K ------_=_NextPart_001_01C5BAFF.DAA83C14 Content-Type: text/html; name="dayviewhtml.htm" Content-Transfer-Encoding: base64 Content-ID: <uid1rid1attachid-2> Content-Description: dayviewhtml.htm Content-Disposition: attachment; filename="dayviewhtml.htm" PEhUTUw+PEhFQUQ+PFNDUklQVD4gdmFyIGptYWluID0gcGFyZW50OyB2YXIgZm9ybV9zdWJtaXR0 ZWQgPSAnMCc7IGZ1bmN0aW9uIGltYWdlc29mZigpIHsgaWYgKGRvY3VtZW50LmltYWdlcykgeyBk b2N1bWVudC5ob21lcGFnZS5zcmMgPSBob21lcGFnZW9mZi5zcmM7IGRvY3VtZW50LmRvY3VtZW50 YXRpb24uc3JjID0gZG9jdW1lbnRhdGlvbm9mZi5zcmM7IGRvY3VtZW50LnVzZXJsb2dvdXQuc3Jj ID0gdXNlcmxvZ291dG9mZi5zcmM7IH0gfSBmdW5jdGlvbiBpbWFnZW9uKGltZ05hbWUpIHsgaWYg KGRvY3VtZW50LmltYWdlcykgeyBkb2N1bWVudFtpbWdOYW1lXS5zcmMgPSBldmFsKGltZ05hbWUg KyAib24uc3JjIik7IH0gfSBmdW5jdGlvbiBvdmVyKGltZ05hbWUpIHsgZG9jdW1lbnRbaW1nTmFt ZV0uc3JjPSBldmFsKGltZ05hbWUgKyAib3Zlci5zcmMiKTsgfSBmdW5jdGlvbiBvdXQoaW1nTmFt ZSkgeyBkb2N1bWVudFtpbWdOYW1lXS5zcmM9IGV2YWwoaW1nTmFtZSArICJvZmYuc3JjIik7IH0g PC9TQ1JJUFQ+PHNjcmlwdD4gdmFyIG9wZW5lciA9IGptYWluLm9wZW5lcjsgdmFyIGFjY2VwdF9m dW5jcyA9IG5ldyBBcnJheSgpOyBmdW5jdGlvbiBnZXRhcnJheSgpIHsgcmV0dXJuIG5ldyBBcnJh eSgpOyB9IGZ1bmN0aW9uIGFjY2VwdChuZXdkYXRhKSB7IHZhciBzdWJtaXRfZm9ybSA9IGZhbHNl OyB2YXIgeDsgZm9yICggeCA9IDA7IHggPCBhY2NlcHRfZnVuY3MubGVuZ3RoOyB4KyspIHsgdmFy IGZ1bmMgPSBhY2NlcHRfZnVuY3NbeF07IGlmIChmdW5jKG5ld2RhdGEpKSBzdWJtaXRfZm9ybSA9 IHRydWU7IH0gaWYgKHN1Ym1pdF9mb3JtKSB7IGptYWluLmZyYW1lc1sxXS5kb2N1bWVudC5mb3Jt LnN1Ym1pdCgpOyB9IH0gZnVuY3Rpb24gY2xvc2VfYWxsKCkgeyBqbWFpbi5jbG9zZV9hbGwoKTsg fSBmdW5jdGlvbiBpY3NOb3JtYWxpemUoYSkgeyB2YXIgYiA9ICcnOyBmb3IgKGkgPSAwOyBpIDwg YS5sZW5ndGg7IGkrKykgeyB2YXIgYyA9IGEuc3Vic3RyaW5nKGksIGkgKyAxKTsgaWYgKGMgPT0g JyAnIHx8IGMgPT0gJ1x0JyB8fCBjID09ICdccicgfHwgYyA9PSAnXG4nKSB7IGIgKz0gJ34nOyB9 IGdmFaXBZT0iMSI+PC9URD48L1RSPjwvVEFCTEU+PC9mb3JtPjwvYm9keT48L0hUTUw+ ------_=_NextPart_001_01C5BAFF.DAA83C14-- |
If the ics.conf parameter user.allow.doublebook is set to "yes", then:
Allowed — Double booking is allowed if the user’s doublebookingcalendar property is set to 1).
Disallowed — Double booking is disallowed if the calendar doublebooking property is set to 0. WCAP returns error 40 STORE_FAILED_DOUBLE_BOOKED.
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.
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:
P1Y2M3DT1H30M10S represents a duration of 1 year, 2 months, 3 days, 1 hour, 30 minutes, 10 seconds
PT1H30M represents a duration of 1 hour, 30 minutes
P1D represents a duration of 1 day
PT15M represents a duration of 15 minutes
Notice that the T in the string separates the date information from the time information.
The command returns the error value. To have the command return the stored todo data, specify 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 is returned in Zulu time.
This command cannot modify a linked event. If you attempt to issue the command, it fails and returns: FAILED: CANNOT_MODIFY_LINKED_EVENTS (31) in the errno array.
If double booking is disallowed, when you try to store an event in a time slot that is already scheduled, the command fails, and returns: FAILED: STORE_FAILED_DOUBLE_BOOKED(40).
For example, this URL would call storeevents.wcap and would result in storing an event in the calendar john,
http://calendarserver/storeevents.wcap ?id=3423423asdfasf &calid=john &dtstart=20020101T103000 &dtend=20020101T113000&uid=001 &summary=new%20year%20event
The 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
Add one or more todos to a calendar.
storetodos.wcap lists storetodos parameters:
Table 3–33 storetodos 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 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 string |
The time at which to run a flashing alarm. |
N |
N/A |
alarmPopup |
ISO 8601 Date Time string ISO 8601 Duration string |
The time at which to pop up a dialog alarm. |
N |
N/A |
alarmStart |
ISO 8601 Date Time string ISO 8601 Duration string |
The time at which to send an alarm notification of the todo. |
N |
N/A |
appid |
string |
A runtime parameter that is not stored in the database. The parameter 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 Sun Java Communications Suite 5 Event Notification Service Guide. |
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 Calendar Server WCAP Attendee: CUTYPE Parameter |
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 string |
Completion 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 might be removed in future releases. For compressed=0, returns less data. Specifically, it does not return the following parameters:rrules, rdates, xrule, and exdates. For compressed=1, all recurrence data is returned. |
N |
0 |
contacts |
semicolon-separated list of strings |
Contacts for the todo. |
N |
N/A |
deleteattach |
semicolon-separated list of strings |
Attachment ids of the attachments to be deleted. |
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 string |
End 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 Date Time 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 in Calendar Server WCAP |
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/calendartext/xml |
N |
text/calendar |
geo |
two semicolon-separated floats |
Semicolon-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 — Others can see time and text only PRIVATE — Others can see time and date only CONFIDENTIAL — Others can see nothing. (Set transparent = 1 to make it invisible.) |
N |
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 |
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 |
A modifier indicating which recurrences to retrieve. One of the following values: 1 = THISINSTANCE 2 = Deprecated, see note. 3 = Deprecated, see note. 4 = THISANDALL Note – Values 2 and 3 were deprecated. Using these values results in undetermined behavior. |
N Y |
N/A |
notify |
integer 0,1 |
This parameter has been deprecated. It remains to provide backward compatibility. The Group Scheduling Engine (GSE) handles sending of email notifications. A boolean indicating whether or not to notify attendees of a changed todo. 1 = Notify attendees of the change. 0 = Do not notify attendees. |
N |
0 |
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= highest 9= lowest |
N |
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 Date Time 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 Date Time 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 in Calendar Server WCAP |
N |
N/A |
sendattach |
integer (0,1) |
0 = Sends information about the attachments in an iTIP message. 1 = Sends the attachment itself. |
N |
0 |
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 FINAL Note: 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_TYPE_MODIFY If 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) |
1 = private todos transparent. Exclude private todos from free-busy calculations. 0 = opaque. Include private todos in free-busy calculations. |
N |
0 (opaque) |
tzid |
time zone ID string, |
The time zone 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 time-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 |
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 in Calendar Server WCAP.
For group scheduling, use the attendee and method parameters as explained in Calendar Server WCAP Attendee Parameter.
For an explanation of how to replace, append or delete a parameter, see Updating Parameter Values in Calendar Server WCAP.
Attachments can be added to tasks when issuing a storetodos command. Use the sendattach parameter to specify whether an actual attachment is being sent as part of the iTIP data, "0" for none, and "1" for attachment present in data.
In addition, you can delete existing attachments from a task using the deleteattach parameter. The task is not deleted. The deleteattach values are the attachment ID's emitted in the X-S1CS-ATTACH-ID X-Token as part of the VEVENT returned for a fetch command.
In earlier versions of Calendar Server, attachments could only be sent as a reference (URL) to a Web location. The attachments parameter was used to hold the URL.
The attachments parameter has been deprecated. It remains functional in this release only for backward compatibility. Change any scripts you have that use the old parameter to the new attachment model.
This command creates new todos and modifies existing todos. Each case requires a different set of parameters:
To create new todos requires the dtstart parameter.
Every other parameter is optional. The server generates the uid.
To modify existing todos requires two parameters:
uid
mod
All other parameters are optional. If a parameter is not specified, the todo retains the previous value of the property.
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:
P1Y2M3DT1H30M10S represents a duration of 1 year, 2 months, 3 days, 1 hour, 30 minutes, 10 seconds
PT1H30M represents a duration of 1 hour, 30 minutes
P1D represents a duration 1 day
PT15M represents a duration of 15 minutes
Notice that the T in the string separates the date information (year, month, day) from the time information (hour, minute, second).
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 is returned in Zulu time.
This command cannot modify a linked todo. The command fails and returns: FAILED: CANNOT_MODIFY_LINKED_TODOS (32).
Add the specified calendars to the user’s calendar subscription list.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
calid |
string |
A semicolon 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 |
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.
http://calendar.sesta.com/subscribe_calendars.wcap ?id=br6p3t6bh5po35r &calid=john@sesta.com;william@sesta.com:baseball
Remove the specified calendars to the user’s calendar subscription list.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
calid |
string |
A semicolon 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 |
Removes the calendars specified in the calid parameter to the user’s subscription list. No check is made to see if the calendar exists.
http://calendar.sesta.com/unsubscribe_calendars.wcap ?id=br6p3t6bh5po35r &calid=john@sesta.com;william@sesta.com:baseball
This command is used to verify if the event specified with the uid and rid parameters exists in the database.
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/calendartext/xml |
N |
text/calendar |
id |
string |
Uniquely identifies the session (session ID). The id must be specified with the command unless the calendar to fetch from is a public calendar. |
N |
null |
rid |
ISO 8601 Date Time 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 |
This command tries to fetch events matching the passed in uid-rid pairs.
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 1 is in text/calendar format, and example 2 is in text/xml output.
Example 1
http://calendarserver/verifyevents_by_ids.wcap ?id=$n3o2m05sx9v6t98t8u2p &calid=jdoe &uid=3bd9e72f000027cf0000000600002113; 3bd9e717000045030000000100002113; 3bd9e717000045030000000100002113; 3bd9cd4700002206000000010000202d &rid=0;20021027T230000Z;20021026T230000Z;0 &fmt-out=text/calendar
BEGIN:VCALENDAR PRODID:-//SunONE/Calendar Hosting Server//EN VERSION:6.0 BEGIN:VEVENT UID:3bd9e717000045030000000100002113 RECURRENCE-ID:20021027T230000Z END:VEVENT BEGIN:VEVENT UID:3bd9cd4700002206000000010000202d END:VEVENT END:VCALENDAR
Example 2
http://calendarserver/verifyevents_by_ids.wcap ?id=$n3o2m05sx9v6t98t8u2p &calid=savri &uid=3bd9e72f000027cf0000000600002113; 3bd9e717000045030000000100002113; 3bd9e717000045030000000100002113; 3bd9cd4700002206000000010000202d &rid=0;20021027T230000Z;20021026T230000Z;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\>
This command is used to verify if the todo specified with the uid and rid pair exists in the database.
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/xml |
N |
text/calendar |
id |
string |
Uniquely identifies the session (session ID). The id must be specified with the command unless the calendar to fetch from is public calendar. |
N |
"" |
rid |
ISO 8601 Date Time 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 |
This command tries to fetch todos matching the passed in uid-rid pairs.
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, and if the rids were not zero, 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.
http://calendarserver/verifytodos_by_ids.wcap ?id=bo35r2pr3e5po35r &calid=jdoe &uid=3bde188f0000472d0000000b00000399 &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\>
To get the current WCAP version.
Parameter |
Type |
Purpose |
Required |
Default |
---|---|---|---|---|
fmt-out |
string |
The format for the returned data. The three format types: text/calendar text/xml |
N |
text/calendar |
This command gets the current WCAP version. (Note: this is different from the server version as well as the HTTP version.)
The commands supports output types iCal and XML. The variable X-NSCP-WCAPVERSION contains the WCAP version number.
The following examples are for each of output data types.
iCalendar:
http://calendarserver/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:
http://calendarserver/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\>