Sun Java System Calendar Server 6.3 WCAP Developer's Guide

fetchtodos_by_id.wcap

Purpose

Retrieve specific calendar todos.

Parameters

Table 3–17 fetchtodos_by_id Parameters

Parameter  

Type  

Purpose  

Required 

Default 

calid

string 

A semicolon-separated list of calendar identifiers. 

The calid can be supplied in two formats: 

  • string - calendar identifier

  • mailto:rfc822addr - An email address appended to “mailto:”. The address is mapped to a user with an LDAP lookup, and then the user’s default calendar ID is used. Returns: X-SICS-EMAIL and X-NSCP-CALPROPS-RELATIVE-CALID

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.

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

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.

0

fetchattach

integer (0, 1)

0 = Returns information about the attachments.

1 = Returns the attachment itself.

0

fmt-out

string 

The format for the returned data. 

Two format types: 

text/calendar

text/xml

text/calendar

id

unique identifier string 

The session identifier. 

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.


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.

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.

0 (absolute)

rid

ISO 8601 Date Time string 

The recurrence identifier for the todo. For a nonrecurring todo, set to 0.

0

tzid

time zone ID string 

Time zone to use if the rid parameter is not in Zulu time.

For example, “America/Los_Angeles” 

server’s default time zone 

tzidout

time zone ID string 

Time zone the returned data should be translated to. 

Returns data in Zulu time 

uid

string 

The unique identifier for the todo. 

N/A 

Description

Use this command to retrieve the specified todo and its recurrences from the specified calendar. You must specify the id parameter with the command unless the specified calendar is a public calendar.

Output Format

The server returns data in the format specified by the fmt-out parameter. If this parameter is not passed, the data is returned in the default text/calendar format.

Returns

For each calendar specified in calid, the server returns the calendar's todos. 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.

Error Codes

If the operation is successful, the error number of 0 is appended to the error string. If a calendar cannot be accessed or is missing, the error number is appended to the error string.

Example

For example, a todo “weekly todo B” that’s due weekly at 5: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