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 |
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 Error Codes(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