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 |
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 |
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 = THISANDFUTURE 3 = THISANDPRIOR 4 = THISANDALL |
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 |
sting |
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– Overview
If the times specified in the rid parameter is not Zulu time, the system uses the time zone specified in the tzid parameter to translate the times into Zulu time for data retrieval. If the tzid parameter is missing, the system uses the server’s default time zone.
The system uses the tzidout parameter to determine what time zone to translate retrieved data into before returning it. If the tzidout parameter is missing, the system returns the data in Zulu time.
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 |
Example 2
This query fetches the last two recurrences by specifying the recurrence ID of the second to last recurrence on Feb. 22, 2002 (rid=20020222T170000Z) and a modifier of 2 (mod=2) which means THISANDFUTURE recurrences:
http://calendarserver/fetchtodos_by_id.wcap ?id=n3o3m05sx9v6t98tu2p &uid=3c15309d000037020020021400003189 &rid=20020222T170000Z &mod=2 &fmt-out=text/calendar
The results of the query are as follows:
BEGIN:VCALENDAR PRODID:-//SunONE/Calendar Hosting Server//EN METHOD:PUBLISH VERSION:6.0 X-NSCP-CALPROPS-LAST-MODIFIED:20011208T005613Z X-NSCP-CALPROPS-CREATED:20010913T223336Z X-NSCP-CALPROPS-READ:999 X-NSCP-CALPROPS-WRITE:999 X-NSCP-CALPROPS-RELATIVE-CALID:jdoe X-NSCP-CALPROPS-NAME:John Doe X-NSCP-CALPROPS-LANGUAGE:en X-NSCP-CALPROPS-PRIMARY-OWNER:jdoe X-NSCP-CALPROPS-TZID:America/Los_Angeles X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^c^WDEIC^g X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@@o^a^RSF^g X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^a^frs^g X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^c^^g X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^a^frs^g X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^c^dw^g X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^a^rs^g X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^c^w^g X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:@^p^r^g X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:lucy^p^r^g X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY:jjones^p^r^g X-NSCP-CALPROPS-RESOURCE:0 BEGIN:VTODO UID:3c15309d000037020020021400003189 RECURRENCE-ID:20020222T170000Z DTSTAMP:20011210T222757Z SUMMARY:weekly todo B DTSTART:20020222T170000Z DUE:20020222T170000Z CREATED:20011210T220101Z LAST-MODIFIED:20011210T220101Z PRIORITY:0 SEQUENCE:0 PERCENT-COMPLETE:0 ORGANIZER;SENT-BY="jdoe@sesta.com"; X-NSCP-ORGANIZER-UID=jdoe; X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe STATUS:NEEDS-ACTION X-NSCP-ORIGINAL-DTSTART:20020222T170000Z X-NSCP-LANGUAGE:en X-NSCP-DUE-TZID:Europe/London X-NSCP-TOMBSTONE:0 X-NSCP-ONGOING:0 X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com X-NSCP-GSE-COMPONENT-STATE; X-NSCP-GSE-COMMENT="PUBLISH-COMPLETED":65538 END:VTODO BEGIN:VTODO UID:3c15309d000037020020021400003189 RECURRENCE-ID:20020301T170000Z DTSTAMP:20011210T222757Z SUMMARY:weekly todo B DTSTART:20020301T170000Z DUE:20020301T170000Z CREATED:20011210T220101Z LAST-MODIFIED:20011210T220101Z PRIORITY:0 SEQUENCE:0 PERCENT-COMPLETE:0 ORGANIZER;SENT-BY="jode@sesta.com"; X-NSCP-ORGANIZER-UID=jdoe; X-NSCP-ORGANIZER-SENT-BY-UID=jdoe:jdoe STATUS:NEEDS-ACTION X-NSCP-ORIGINAL-DTSTART:20020301T170000Z X-NSCP-LANGUAGE:en X-NSCP-DUE-TZID:Europe/London X-NSCP-TOMBSTONE:0 X-NSCP-ONGOING:0 X-NSCP-ORGANIZER-EMAIL:jdoe@sesta.com X-NSCP-GSE-COMPONENT-STATE; X-NSCP-GSE-COMMENT="PUBLISH-COMPLETED":65538 END:VTODO X-NSCP-WCAP-ERRNO:0 END:VCALENDAR