Sun Java System Calendar Server 6.3 WCAP Developer's Guide

`fetchcomponents_by_lastmod.wcap`

Purpose.

Fetch a list of components that have changed during a specified time period.

Parameters.

Table 3–13 fetchcomponents_by_lastmod Parameters


Parameter	Type	Purpose	Required	Default
`calid`	string	A semicolon-separated list of calendar identifiers. The calid can be supplied in two formats: 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`	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`
`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-EMAI`L 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: `0` - Special legacy order- mostly ascending order. `1` - Ascending order `2` - Descending order See Sorting Order of Returned Events and Todos in Calendar Server WCAP	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

Fetching Attachments

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

Note –

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

Tip –

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.

Exporting Attachments

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).

Description

Use this command to retrieve a list of events and todos that have changed during a specific time period. This command works almost like fetchcomponents_by_range.

Output Format

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

maxResults Value

If you specify a maximum n, the command returns up to the first n events and first n todos in the specified range. For example, if you specify a maxResults value of 75, the returned data would contain the following variables

var maxResults=75 /* maximum cap passed in */
var size=75     /* event size is capped to 75 */
var todosize=28 /* todo size not affected since it is less than 75 */

If the maxResults parameter is set to 0 or is not passed, then the returned data does not contain the var maxResults statement.

Returns

For each calendar specified in calid, the server returns the calendar's the events and todos that changed during the range specified by dtstart and dtend.

If the times specified in the dtstart and dtend parameters is not Zulu time, the system uses the time zone specified in the tzid parameter to translate the times into Zulu time for data retrieval. If the tzid parameter is missing, the system uses the server’s default time zone.

The system uses the tzidout parameter to determine what time zone to translate retrieved data into before returning it. If the tzidout parameter is missing, the system returns the data in Zulu time.

If neither the starting nor ending date-time is specified, the server returns all events and todos that have changed, up to the specified maximum.

Error Codes

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

Example

For example, the calendar jdoe has these three events:

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.