Sun Java System Calendar Server 6 2005Q4 Developer's Guide

Chapter 7 WCAP Command Reference

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:

In all other situations, you must provide the session ID in the id parameter.


Note –

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:

Command: check_id

Purpose

This administrator only command allows the administrator to verify that a session is still valid.

Parameters

Table 7–1 check_id Parameters

Parameter  

Type  

Purpose  

Required  

Default  

id

string 

The session identifier. 

N/A 

fmt-out

string 

The format for the returned data. 

The three format types: 

text/calendar

text/xml

text/calendar

Purpose

This command allows the administrator to verify that the session is still valid.

Returns

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.

Example

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

Command: createcalendar

Purpose

Create a new calendar.

Parameters

Table 7–2 createcalendar Parameter

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

1

calid

string 

The user’s calid, used to generate the new calendar’s calid.

N/A 

id

unique identifier string 

The session identifier. 

N/A 

fmt-out

string 

The format for the returned data. 

The three format types: 

text/calendar

text/xml

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.

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

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

1

Description

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.

Creating a Valid Calid

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:

Setting Calendar Properties

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 Command: set_calprops command.

Note that at calendar creation, if you do not specify calendar properties, the defaults set in the ics.conf file are used.

Returns

The returned output shows the calendar properties (retrieved with a call to the fetchcomponents_by_range command) formatted according to the fmt-out value.

Error Codes

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.

Example

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

Command: deletecalendar

Purpose

This command deletes a user’s calendar.

Parameters

Table 7–3 deletecalendars Parameter

Parameter  

Types  

Purposes  

Required  

Default  

calid

string 

The name of the calendar to delete. 

N/A 

id

unique identifier string 

The session identifier. 

N/A 

fmt-out

string 

The format for the returned data. 

Two format types: 

text/calendar

text/xml

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

1

Description

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

Returns

The returned output is the formatted output from a call to fetchcomponents_by_range.

Error Codes

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

Example

For example, sending this URL deletes the calendar named newcal.


http://calendarserver/deletecalendar.wcap
               ?id=b5q2o8ve2rk02nv9t6
               &calid=newcal

Command: deletecomponents_by_range

Purpose

Delete events and todos from a calendar in a specified range.


Note –

ENS notifications for appid are not yet implemented.


Parameters

Table 7–4 deletecomponents_by_range Parameters

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 System Communications Services 6 2005Q4 Event Notification Service Guide.

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: 

  • 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

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.

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.

0

fmt-out

string 

The format for the returned data. 

Two format types: 

text/calendar

text/xml

id

unique identifier string 

The session identifier. 

N/A 

smtp

integer (0, 1)

Send email cancellation to user with no calendar. 

0 = No

1 = Yes

1

Description

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.

Error Codes

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

Example

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

Command: deleteevents_by_id

Purpose

Deletes one or more events from a calendar by event identifier.

Parameters

Table 7–5 deleteevents_by_id Parameters

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 System Communications Services 6 2005Q4 Event Notification Service Guide

N/A 

calid

string 

Calendar identifier of event to delete. 

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/A 

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. Required unless the calendar is public. 

NULL

mod

integer 

1,2,3,4

A modifier indicating which recurrences to delete, or semicolon-separated list of modifiers. If a list, it must have same number of elements as uid list.

One of the following values: 

1 = THISINSTANCE2 = THISANDFUTURE3 = THISANDPRIOR 4 = THISANDALL

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.

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.

N/A 

smtp

integer (0, 1)

Send email cancellation to user with no calendar. 

0 = No

1 = Yes

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” 

server’s default time zone 

uid

string 

Unique Identifier of an event to be deleted, or semicolon-separated list of unique identifiers. 

N/A 

Description

Use this command to delete the specified event or events from the specified calendar.

Error Codes

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, Error Handling

Recurrences

If the rid parameter is passed, the command also deletes recurrences, as specified by the mod parameter. (See 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.

Example

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

Command: deleteevents_by_range

Purpose

Delete events from a calendar in a specified range.


Note –

ENS notifications for appid are not yet implemented.


Parameters

Table 7–6 deleteevents_by_range Parameters

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 System Communications Services 6 2005Q4 Event Notification Service Guide

N/A 

calid

string 

Semicolon-separated list of calendar identifiers from which to delete events. 

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

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.

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.

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 

smtp

integer (0, 1)

Send email cancellation to user with no calendar. 

0 = No

1 = Yes

1

Description

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.

Error Codes

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, Error Handling

Example

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

Command: deletetodos_by_id

Purpose

Delete one or more todos from a calendar.

Parameters

Table 7–7 deletetodos_by_id Parameters

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 System Communications Services 6 2005Q4 Event Notification Service Guide

N/A 

calid

string 

Calendar identifier of the todos to delete. 

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/A 

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 delete, or semicolon-separated list of modifiers. If a list, must have same number of elements as uid list.

One of the following values: 

1 = THISINSTANCE

2 = THISANDFUTURE

3 = THISANDPRIOR

4 = THISANDALL

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.

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.

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” 

server’s default time zone 

uid

string 

The unique identifier of a todo to be deleted, or a semicolon-separated list of unique identifiers. 

N/A 

Description

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.

Error Codes

If the uid does not exist, returns error 59.

See also, Error Handling

Recurrences

If the rid parameter is passed, the command also deletes recurrences, as specified by the mod parameter. See 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.

Example

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

Command: deletetodos_by_range

Purpose

Delete todos in a range from a calendar.


Note –

ENS notifications for appid are not yet implemented.


Parameters

Table 7–8 deletetodos_by_range Parameters

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 System Communications Services 6 2005Q4 Event Notification Service Guide

N/A 

calid

string 

Semicolon-separated list of calendar identifiers from which to delete todos. 

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

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.

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.

0

id

unique identifier string 

The session identifier. 

N/A 

smtp

integer (0, 1)

Send email cancellation to user with no calendar. 

0 = No

1 = Yes

1

Description

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.

Error Codes

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, Error Handling

Command: export

Purpose

Export events and todos from a calendar to a file.

Parameters

Table 7–9 export Parameters

Parameter  

Type  

Purpose  

Required  

Default  

calid

string 

A semicolon-separated list of calendar identifiers from which to export events and todos. The user must have read access to all calendars in the list. 

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 de fault calendar ID is used. Returns: X-SICS-EMAIL and X-NSCP-CALPROPS-RELATIVE-CALID

Current user’s calid

content-out

string 

Content type for output file. One of the following: 

text/calendarx

text/xml

N/A 

dtend

Date Time string 

End time and date of the events and todos to export. A value of 0 means export all components from the start date to the latest date.

0

dtstart

Date Time string 

Start time and date of events and todos to export. A value of 0 means export all components from the earliest date to the end date.

0

id

unique identifier string (uid)

The session identifier. 

NULL

Description

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.

Range

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.

HTTP Post Examples

You must use this command with an HTTP POST. This is unlike other commands, which can be used with an HTTP GET.

Example 1

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

Example 2

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

Command: fetchcomponents_by_alarmrange

Purpose

Retrieve calendar events and todos with alarm triggers.

Parameters

Table 7–10 fetchcomponents_by_alarmrange 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

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.

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.

0

compstate

semicolon-separated list of component state keywords 

The list of component states to fetch. 

For compstate values, see Fetching Component State Data

ALL

dtend

Date Time string 

End time and date of events and todos to be returned. 

A value of 0 means fetch all events.

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.

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.

0

fetchorder

integer 

Specifies the order in which the events and todos are returned. 

The values are: 

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.

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 

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.

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.

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)

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” 

server’s default time zone 

tzidout

time zone ID string 

Time zone to report returned data in. 

Zulu time 

Description

This command returns a list of events and todos having alarms that are about to go off during the specified time.

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

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, errno is Error Codes(41).

Example

For example, suppose there are 3 events:

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

Command: fetchcomponents_by_attendee_error

Purpose.

Fetch a list of components that had errors while sending group scheduling messages.

Parameters.

Table 7–11 fetchcomponents_by_attendee_error Parameters

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. 

N/A 

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

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.

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.

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.

0

fetchorder 

integer 

Specifies the order in which the events and todos are returned. 

The values are: 

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.

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 

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.

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.

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)

tzidout

standard time zone string 

The time zone returned data is translated to. 

Returns data in Zulu time 

Description

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.

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

Error Codes

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 Error Codes(42).

Command: fetchcomponents_by_lastmod

Purpose.

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

Parameters.

Table 7–12 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

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.

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.

0

compstate

semicolon-separated list of component state keywords 

The list of component states to fetch. 

For compstate values, see Fetching Component State Data

ALL

dtend

Date Time string 

End time and date of events to be returned. 

A value of 0 means fetch all events.

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.

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.

0

fetchorder

integer 

Specifies the order in which the events and todos are returned. 

The values are: 

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.

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 

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.

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.

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)

tzid

time zone ID string 

Time zone to use if dtstart, or dtend parameters are not in Zulu time.

For example, “America/Los_Angeles” 

server’s default time zone 

tzidout

time zone ID string 

Time zone to report returned data in. 

Zulu time 

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:

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.

Command: fetchcomponents_by_range

Purpose

Retrieve calendar events and todos.

Parameters

Table 7–13 fetchcomponents_by_range Parameters

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.

2

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

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.

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.

0

compstate

semicolon-separated list of component state keywords 

The list of component states to fetch. 

For compstate values, see Fetching Component State Data

ALL

dtend

Date Time string 

End time and date of events to be returned. 

A value of 0 means fetch all events.

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.

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.

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:

  • For contains: *string*

  • For begins with: string*

  • For ends with: *string

    For the name-value pair ALL=string, the following components are checked for a match to string: description, summary, attendee, location, organizer.

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.

0

fetchorder

integer 

Specifies the order in which the events and todos are returned. 

The values are: 

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:

  • ATTENDEE

  • ORGANIZER

  • SUMMARY

  • DESCRIPTION

  • LOCATION

  • CLASS

  • CATEGORY

NULL

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 

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.

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. 

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.

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.

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)

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

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” 

server’s default time zone 

tzidout

time zone ID string 

Time zone to report returned data in. 

Zulu time 

Description

Use this command to retrieve properties, events, and todos from one or more specified calendars.

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 properties and the events and todos of that calendar that fall within the range specified by dtstart and dtend.

Tasks returned by this command:

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.

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.

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 command does not cap the number of returned components, and the returned data does not contain the var maxResults statement.

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

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

Command: fetch_deletedcomponents

Purpose.

Returns a list of deleted components from the deletelog.db for a specified time period.

Parameters.

Table 7–14 fetch_deletedcomponents 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

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.

all

dtend

Date Time string 

End time and date of events to be returned. 

A value of 0 means fetch all deleted components in the deletelog database until the end of time. The return value has the server time that is used in the next fetch.

0

dtstart

Date Time string 

Start time and date of events to be returned. 

A value of 0 means fetch all deleted components in the deletelog database from the beginning of time.

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 

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.

0

recurring

integer (0, 1)

1 = Return all components in compressed form. WCAP does not return the expanded instances of the recurring components. Instead, WCAP returns the master entry plus exceptions. If all the instances of the recurring series have been deleted, WCAP returns dtstart, dtend, rrules, rdates, exrules, exdates, and uid.

0 = Return components as expanded instances, but no master record.

0 (not compressed)

tzid

time zone ID string 

Time zone to use if dtstart, or dtend parameters are not in Zulu time.

For example, “America/Los_Angeles” 

Server’s default time zone 

tzidout

time zone ID string 

Time zone to report returned data in. 

Zulu time 

Description

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.

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

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.

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.

The following failure codes can be returned:

Examples

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.

Fetching Deleted Components


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

Fetching Deleted Components as Master Record Plus Exceptions


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

Command: fetchevents_by_id

Purpose

Retrieve specific calendar events.

Parameters

Table 7–15 fetchevents_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

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

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.

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 = THISANDFUTURE

3 = THISANDPRIOR

4 = THISANDALL

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.

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 event. For a nonrecurring event, 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 that returned data should be translated to. 

Returns data in Zulu time 

uid

sting 

The unique identifier for the event. 

N/A 

Description

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– Overview

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

Returns

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

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

Command: fetchtodos_by_id

Purpose

Retrieve specific calendar todos.

Parameters

Table 7–16 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

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

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.

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 = THISANDFUTURE

3 = THISANDPRIOR

4 = THISANDALL

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

sting 

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

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

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

Command: get_all_timezones

Purpose

Retrieve data about all time zones supported by the server.

Parameters

Table 7–17 get_all_timezones Parameters

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

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

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 

Description

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.

Returns

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.

Error Codes

If there was an error in getting the time zones, the server returns the error FAILED: GET_ALL_TIMEZONES_FAILED (24).

Example

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

Command: get_calprops

Purpose

Retrieve calendar properties.

Parameters

Table 7–18 get_calprops Parameters

Parameter  

Type  

Purpose  

Required  

Default  

calid

semicolon-separated list of strings 

Semicolon-separated list of calendar identifiers from which to retrieve properties. 

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

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 

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 iCal XML block.

0 = Count not requested.

0

invitecount

integer (0, 1)

0 = Do not return a count of the open invitations, meaning 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. 

0

Description

Use this command to retrieve the calendar properties for the specified calendars.

Returns

The command returns a page with the following X-Tokens containing property information for the specified calendars:

Error Codes

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

Example

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

Command: get_freebusy

Purpose

Get the free-busy calendar information for users.

Parameters

Table 7–19 get_freebusy Parameters

Parameter  

Type  

Purpose  

Required  

Default  

busyonly

Integer (0, 1)

0 = return both busy and free periods1 = return only busy periods

1

calid

string 

The calendar identifier. 

he 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 default calendar 

dtstart

Date Time string 

Start time of free-busy search. 

N/A 

dtend

Date Time string 

End time of free-busy search. 

N/A 

duration

Integer 

Free busy duration time in number of days. 

60 or Default taken from ics.conf

fmt-out

string 

The format for the returned data. 

Two format types: 

text/calendar

text/xml

text/calendar

freebusybegin

integer 

Offset in number of days from the value of ics.conf setting service.wcap.freebusybegin. Backs off the date range by the value of this parameter. For example, a value of 30 would start the free-busy range 30 days before the current time found in the ics.conf parameter.

Default ics.conf value is 30 (days)

freebusyend

integer 

Offset in number of days from the value of ics.conf setting service.wcap.freebusyend to calculate the end of the free-busy range. Extends the date found in the ics.conf parameter. For example, a value of 30 would put the end date 30 days beyond the current setting.

Default ics.conf value is 30 (days)

id

unique identifier string 

The session identifier. 

N/A 

mail

email address 

An email address used to compute free/busy time. The address must be present in the LDAP. When an email address is passed in, all of the user's eligible calendars are used in computing free-busy time. Eligible calendars are those for which this user is the primary owner and havefbinclude=1.

Y/N 

Either calid or mail must be specified

noredirect

boolean (0, 1)

Parameter passed in with command. When calendar can’t be found in the Calendar Server database, if this parameter is set to 0, the server passes back the redirect URL, if one is present, in the ics.conf parameter service.wcap.freebusy.redirecturl

If this parameter is set to 1, the server does not check for the redirect URL, instead, it returns an error.

0

mail

RFC 822 address 

Can be specified instead of calid. But must be a valid user or group email address in the Calendar Server’s LDAP.

For free-busy lookup, all calendars that have this user as primary owner and have the fbinclude calendar property set to 1 are used in computing free-busy time.

Y/N 

No default. But must be specified if the calid is not specified 

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” 

Server’s default time zone 

tzidout

time zone ID string 

Time zone to report returned data in. 

Zulu time 

Description

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:

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

Error Codes

If this command fails for any reason, errno is set to Error Codes(39).

Example

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

Command: get_guids

Purpose

Generate a set of globally unique identifiers.

Parameters

Table 7–20 get_guids Parameters

Parameter  

Type  

Purpose  

Required  

Default  

fmt-out

string 

The format for the returned data. 

Two format types: 

text/calendar

text/xml

text/calendar

guidCount

integer 

Number of GUID's to return.

1

Description

This command returns the specified number of globally unique identifiers, GUID's. The client need not be authenticated to call this command.

Example


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

Command: gettime

Purpose

Gets the server time for the requested calendars.

Parameters

Table 7–21 gettime Parameters

Parameter  

Type  

Purpose  

Required  

Default  

calid

semicolon-separated list of strings 

A list of calendar identifiers. 

Current user’s calid 

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 

tzidout

time zone ID string 

Time zone to report returned data in. 

Zulu time 

Description

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.

Error Codes

Example

Valid session with tzidout


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

Command: get_userprefs

Purpose

Retrieve the calendar preferences for the current user.

Parameters

Table 7–22 get_userprefs Parameters

Parameter  

Type  

Purpose  

Required  

Default  

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 

userid

string 

Indicates which user’s preferences to get. 

N/A 

Description

This command retrieves all the calendar preferences for the current user, and the following server preferences relating to this user:

See theSun Java System Calendar Server 6 2005Q4 Administration Guide for more information about server preferences.

Access Control Information (ACI)

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:


Note –

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 Access Control Information



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";)

Note –

If there is no basedn domain node, add the preceding ACI to the root suffix itself by changing the dn: value to o=usergoup.


Example

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

Command: import

Purpose

Import events and todos from a file to a calendar.

Parameters

Table 7–23 import Parameters

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 System Communications Services 6 2005Q4 Event Notification Service Guide.

N/A 

calid

string 

Identifier of a calendar to which to import event. 

N/A 

content-in

string 

Content type of input data. One of the following values:text/calendartext/xml

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.

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.

0

id

unique identifier string 

The session identifier. Required unless the calendar is public. 

N/A 

Description

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.

Example

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\>

Command: list

Purpose

List all calendars owned by current user.

Parameters

Table 7–24 import Parameters

Parameter  

Type  

Purpose  

Required  

Default  

id

unique identifier string 

The session identifier. Required unless the calendar is public. 

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/A 

Description

Returns only those calendars where the user is the primary owner.

Example

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

Command: list_subscribed

Purpose

List all calendars subscribed to by current user.

Parameters

Table 7–25 list_subscribed Parameters

Parameter  

Type  

Purpose  

Required  

Default  

id

unique identifier string 

The session identifier. Required unless the calendar is public. 

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/A 

Description

Returns calendars the user is subscribed to, including the ones for which the user is the primary owner.

Example

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

Command: login

Purpose

Authenticate a specific user.

Parameters

Table 7–26 login Parameters

Parameter  

Type  

Purpose  

Required  

Default  

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

text/calendar

lang

enum 

The user’s preferred language. 

NULL

password

string 

The user’s password. 

N/A 

proxyauth

string 

Used by calendar administrators to perform proxy authorization. 

N/A 

user

string 

The user’s name. 

NULL

Description

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.

Authentication

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, see API: csIAccessControl. For more information on the Proxy Authentication SDK, see Chapter 3, Proxy Authentication SDK Overview.

If the user fails to authenticate correctly, the login window reappears with an error noting a failure to log in.

Example

For example, the following URL attempts to login user jdoe:

http://calendarserver/login.wcap
                     ?user=jdoe&password=mypword

Returns

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/

Command: logout

Purpose

Terminate the current user’s session.

Parameters

Table 7–27 logout Parameters

Parameter  

Type  

Purpose  

Required  

Default  

fmt-out

string 

The format for the returned data. 

The three format types: 

text/calendartext/xml

textcalendar

id

unique identifier string 

The session identifier. 

N/A 

Description

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 command:

http://calendarserver/logout.wcap
                     ?id=bu9p3eb8x5p2nm0q3

Command: ping

Purpose

Determine whether the calendar server is active.

Parameters

This command takes no parameters.

Description

This command returns a minimal HTML page to indicate that the server responded.

Only users with administrative privilege can use this command.

Returns

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

Command: search_calprops

Purpose

Search for a calendar’s properties.

Parameters

Table 7–28 search_calprops Parameters

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.

0, unless both primaryOwner and name are 0

id

unique identifier string 

The session identifier. 

N/A 

maxResults

integer 

The maximum number of results to return. 

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.

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.

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

0

search-string

string 

The string to search for in calendars. 

N/A 

Description

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


Caution – Caution –

Enabling the wildcard search can negatively impact performance.


Search Properties

This command searches for a match in one of three properties:

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.

Search Options

The four search options are the following:

Example

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

Command: set_calprops

Purpose

Set the calendar properties of a calendar.

Parameters

Table 7–29 set_calprops Parameters

Parameter  

Type  

Purpose  

Required  

Default  

acl 

string 

A semicolon-separated list of strings specifying the new value of the access control entries. 

""

cal

encoded string 

A list of parameters to decode. 

There can be multiple instances of this parameter. 

N/A 

calid

string 

Identifier of the calendar to modify. 

N/A 

categories

string 

A semicolon-separated list of strings containing the new categories the calendar belongs to. 

N/A 

charset

string 

The character set for the calendar. 

N/A 

description

string 

The description of the calendar. 

N/A 

doublebooking

integer 

Allow or disallow double booking. 

1 = Allow double booking.

0 = Disallow double booking.

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/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/A 

fmt-out

string 

The format for the returned data. 

The three format types: 

text/calendartext/xml

text/calendar

id

unique identifier string 

The session identifier. 

N/A 

lang

string 

The language of the calendar. 

N/A 

master

string 

The email contact for the calendar. 

N/A 

multiple

integer 

The number of calendars for which to set these preferences. 

0

name

string 

The new text name of the calendar. 

N/A 

owners

string 

A semicolon-separated list of strings containing he new list non-primary owners. 

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/A 

tzid

string 

The new time zone identifier for this calendar. 

""

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/A 

Description

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:

Single Calendar Example

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

Multiple Calendars Example

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.

Access Control Entries

See Access Control Information, 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.

Double Booking

If the ics.conf parameter user.allow.doublebook is set to “yes”, then:

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.

Freebusy Access

See Free-busy Calendars, in the Common Topics section at the front of this chapter.

Choosing a Different Language or Character Set

See Changing Language or Character Set, in the Common Topics section at the front of this chapter.

Command: set_userprefs

Purpose

Modify the preferences or password for a session.

Parameters

Table 7–30 set_userprefs Parameters

Parameter  

Type  

Purpose  

Required  

Default  

add_attrs

string 

Add a new preference. 

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.

0

del_attrs

string 

Delete an existing preference. 

N/A 

fmt-out

string 

The format for the returned data. 

The two format types: 

text/calendartext/xml

text/calendar

id

unique identifier string 

The session identifier. 

N/A 

set_attrs

string 

Modify a preference value. 

N/A 

userid

string 

Used only by administrators. Indicates which user’s preferences to set. 

N/A 

Description

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.

Returns

The function returns the text of get_userprefs.

Examples

Add a Preference

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

Delete a Preference

This URL deletes the calendar preference ceBgcolor from the user’s preferences.

http://calendarserver/set_userprefs.wcap
                     ?id=b5q2o8ve2rk02nv9t6
                     &del_attrs=ceBgcolor

Note –

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:


Modify a Preference

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

Command: storeevents

Purpose

Add events to a calendar.

Parameters

Table 7–31 storeevents Parameters

Parameter  

Type  

Purpose  

Required  

Default  

alarmAudio

ISO 8601 Date Time string 

The time at which to sound an audio alarm. 

N/A 

alarmDescription

string 

The message sent out with the alarm 

“This is the alarm description” 

alarmEmails

semicolon-separated list of email addresses 

Recipients of alarm notifications for the event. 

N/A 

alarmFlashing

ISO 8601 Date Time string 

The time at which to run flashing alarm. 

N/A 

alarmPopup

ISO 8601 Date Time string, or ISO 8601 Duration string 

The time at which to pop up a dialog alarm. 

N/A 

alarmStart

ISO 8601 Date Time string, or ISO 8601 Duration string 

The time at which to send the event alarm notification. 

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 System Communications Services 6 2005Q4 Event Notification Service Guide.

N/A 

attachments

semicolon-separated list of strings 

This is for iCalendar interoperability only. The strings are URL's. 

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 Examples of WCAP Attendee Entries.

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/A 

calid

string 

Calendar identifier, or email address of the calendar, in which to store the event. 

N/A 

categories

semicolon-separated list of strings 

The event categories. 

N/A 

charset

string 

The character set for the calendar. 

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.

0

contacts

semicolon-separated list of strings 

Contacts for the event. 

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.

Value of summary parameter.

dtend

Date Time string 

Event end time and date. 

N/A 

dtstart

Date Time string 

Event start time and date. 

Required to create or modify events. 

N/A 

duration

ISO 8601 duration string 

Event duration. If an event has both a duration and a dtend, the duration is ignored.

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

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/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– Overview

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.

0

fmt-out

string 

The format for the returned data. 

The three format types: 

text/calendartext/xml

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.

0;0

icsClass

string 

Event class. 

One of the following values: 

PUBLICPRIVATECONFIDENTIAL

PUBLIC

icsUrl

string 

Event URL. 

""

id

unique identifier string 

The session identifier. 

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.

0

language

string 

Language of a component record. For example, en, fr, de.

N/A 

location

string 

Event location. 

""

method

integer (1,2,4,8)

ITIP methods for group scheduling. 

The organizer issues the following ITIP methods: 

  • 1 = PUBLISH

  • 2 = REQUEST

  • 8 = CANCEL

The attendee issues this ITIP method: 

4 = REPLY

1 (PUBLISH)

mod

integer 

Specifies the recurrences to modify. 

Not required for creating events. 

Required to modify events. 

One of the following values: 

1 = THISINSTANCE

2 = THISANDFUTURE

3 = THISANDPRIOR

4 = THISANDALL

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.

0

orgCalid

string 

Calendar identifier of organizer. 

One of the following parameters must be specified: orgCalid, orgEmail, or orgUID.

N/A 

orgCN

string 

Common name of the organizer. 

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/A 

orgUID

userid

The userid of the organizer.

One of the following parameters must be specified: orgCalid, orgEmail, or orgUID.

N/A 

priority

integer (0-9)

Event priority. Follows RFC 2445. 

0 = undefined

1= highest

9= lowest

5

rchange

integer (0,1)

A boolean indicating whether or not to expand a recurring event. 

1 = expand

0 = do not expand

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/A 

relatedTos

semicolon-separated list of quoted strings 

Other events to which this event is related. 

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.

0

resources

semicolon-separated list of strings 

The resources associated with the event. 

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/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– Overview

N/A 

seq

integer 

(Not implemented) 

Event sequence number. 

0

smtp

integer (0, 1)

Send email cancellation to user with no calendar. 

0 = No

1 = Yes

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

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.

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. 

Calendar server time zone ID 

tzidout 

time zone ID string 

Time zone returned data should be translated to. 

Returns data in Zulu time 

uid

string 

Unique identifier of the event to be stored. 

System generated for new events. 

Required to modify events. 

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.

N/A 

Description

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– Overview

Use the language parameter to specify the language of the event. See Changing Language or Character Set

For an explanation of how to use the attendee and method parameters to do group scheduling, see the Common Topics section Group Scheduling.

For an explanation of how to replace, append or delete a parameter, see the explanation in the Common Topics section Updating Parameter Values

The server does not support attachments. The attachments parameter exists to support iCalendar interoperability only, and is not functional.

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

Required Parameters

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 :

Double Booking

If the ics.conf parameter user.allow.doublebook is set to “yes”, then:

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.

Duration and dtend

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:

Notice that the T in the string separates the date information from the time information.

Returns

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.

Error Codes

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

Example

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

Command: storetodos

Purpose

Add one or more todos to a calendar.

Parameters

Command: storetodos lists storetodos parameters:

Table 7–32 storetodos Parameters

Parameter  

Type  

Purpose  

Required  

Default  

alarmAudio

ISO 8601 Date Time string 

The time at which to sound an audio alarm. 

N/A 

alarmDescription

string 

The message send out with the alarm 

“This is the alarm description” 

alarmEmails

semicolon-separated list of email addresses 

Recipients of alarm notifications for the todo. 

N/A 

alarmFlashing

ISO 8601 Date Time string 

The time at which to run a flashing alarm. 

N/A 

alarmPopup

ISO 8601 Date Time string 

ISO 8601 Duration string 

The time at which to pop up a dialog alarm. 

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/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 System Communications Services 6 2005Q4 Event Notification Service Guide.

N/A 

attachments

semicolon-separated list of strings 

This parameter exists to support iCalendar interoperability only. The strings are URL's. 

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 Examples of WCAP Attendee Entries

N/A 

calid

string 

Calendar identifier (or email address of calid) in which to store the todo.

N/A 

categories

semicolon-separated list of strings 

The todo categories. 

N/A 

charset

string 

The character set for the calendar. 

N/A 

completed

ISO 8601 Date Time string 

Completion date of the todo. A value of 0 means the todo is not yet completed.

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.

0

contacts

semicolon-separated list of strings 

Contacts for the todo. 

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.

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/A 

due

ISO 8601 Date Time string 

End time and date of the todo. 

N/A 

duration

ISO 8601 duration string 

Todo duration. 

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

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/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– Overview

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.

0

fmt-out

string 

The format for the returned data. 

The three format types: 

text/calendartext/xml

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.

0;0

icsClass

string 

Todo class. One of the following values: 

PUBLICPRIVATECONFIDENTIAL

PUBLIC

icsUrl

string 

Todo URL. 

""

id

unique identifier string 

The session identifier. 

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.

0

language

string 

Language of event. (For example, en, fr, de)

N/A 

location

string 

Event location. 

""

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)

1 (PUBLISH)

mod

integer 

Specifies the recurrences to modify. 

Not required for creating events. 

Required to modify events. 

One of the following values: 

1 = THISINSTANCE

2 = THISANDFUTURE

3 = THISANDPRIOR

4 = THISANDALL

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.

0

orgCalid

string 

Calendar identifier of organizer. 

One of the following parameters must be specified: orgCalid, orgEmail, or orgUID.

N/A 

orgCN

string 

Common name of the organizer. 

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/A 

orgUID

userid

The userid of the organizer.

One of the following parameters must be specified: orgCalid, orgEmail, or orgUID.

N/A 

percent

integer (0-100)

Percentage completion of the todo. 

0

priority

integer (0-9)

Event priority. Follows RFC 2445. 

0 = undefined

1= highest

9= lowest

5

rchange

integer (0,1)

A boolean indicating whether or not to replace the rrule:

1 = Replace the rule.0 = Do not replace it.

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/A 

relatedTos

semicolon-separated list of quoted strings 

Other todos to which this todo is related. 

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)

0

resources

semicolon-separated list of strings 

The resources associated with the todo. 

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/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– Overview

N/A 

seq

integer 

Sequence number of the todo. 

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

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.

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. 

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

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

Description

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– Overview.

For group scheduling, use the attendee and method parameters as explained in Group Scheduling.

For an explanation of how to replace, append or delete a parameter, see Updating Parameter Values.

The server does not support attachments. The attachments parameter exists to support iCalendar interoperability only, and is not functional.

Required Parameters

This command creates new todos and modifies existing todos. Each case requires a different set of parameters:

Duration and Due

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:

Notice that the T in the string separates the date information (year, month, day) from the time information (hour, minute, second).

Returns

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.

Error Codes

This command cannot modify a linked todo. The command fails and returns: FAILED: CANNOT_MODIFY_LINKED_TODOS (32).

Command: subscribe_calendars

Purpose

Add the specified calendars to the user’s calendar subscription list.

Parameters

Table 7–33 subscribe_calendars Parameters

Parameter  

Type  

Purpose  

Required  

Default  

calid

string 

A semicolon separated list of calendar identifiers. 

N/A 

id

unique identifier string 

The session identifier. Required unless the calendar is public. 

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/A 

Description

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.

Example

http://calendar.sesta.com/subscribe_calendars.wcap
                    ?id=br6p3t6bh5po35r
                    &calid=john@sesta.com;william@sesta.com:baseball

Command: unsubscribe_calendars

Purpose

Remove the specified calendars to the user’s calendar subscription list.

Parameters

Table 7–34 subscribe_calendars Parameters

Parameter  

Type  

Purpose  

Required  

Default  

calid

string 

A semicolon separated list of calendar identifiers. 

N/A 

id

unique identifier string 

The session identifier. Required unless the calendar is public. 

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/A 

Description

Removes the calendars specified in the calid parameter to the user’s subscription list. No check is made to see if the calendar exists.

Example

http://calendar.sesta.com/unsubscribe_calendars.wcap
                    ?id=br6p3t6bh5po35r
                    &calid=john@sesta.com;william@sesta.com:baseball

Command: verifyevents_by_ids

Purpose

This command is used to verify if the event specified with the uid and rid parameters exists in the database.

Parameters

Table 7–35 verifyevents_by_ids Parameters

Parameter  

Type  

Purpose  

Required  

Default  

calid

string 

Calendar from which to fetch events.  

User’s default calendar 

fmt-out

string 

The format for the returned data. 

The three format types: 

text/calendartext/xml

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.

null 

rid

ISO 8601 Date Time string 

Corresponding set of comma separated event rids.

If this is a non-recurring event, rid=0.

N/A 

tzid

time zone ID string 

Time zone, such as “America/Los_Angeles” 

Server’s default time zone 

uid

string 

Comma separated set of event uids.

N/A 

Description

This command tries to fetch events matching the passed in uid-rid pairs.

Returns

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

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\>

Command: verifytodos_by_ids

Purpose

This command is used to verify if the todo specified with the uid and rid pair exists in the database.

Parameters

Table 7–36 verifytodos_by_ids Parameters

Parameter  

Type  

Purpose  

Required  

Default  

calid

string 

Calendar from which to fetch todos. 

User’s default calendar 

fmt-out

string 

The format for the returned data. 

The three format types: 

text/calendar

text/xml

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.

""

rid

ISO 8601 Date Time string 

Corresponding set of comma separated todo rids.

If this is a non-recurring todo, rid=0.

N/A 

tzid

time zone ID string 

Time zone, such as “America/Los_Angeles” 

Server’s default time zone 

uid

string 

Comma separated set of todo uids.

N/A 

Description

This command tries to fetch todos matching the passed in uid-rid pairs.

Returns

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.

Example

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\>

Command: version

Purpose

To get the current WCAP version.

Parameters

Table 7–37 version Parameters

Parameter  

Type  

Purpose  

Required  

Default  

fmt-out

string 

The format for the returned data. 

The three format types: 

text/calendar

text/xml

text/calendar

Description

This command gets the current WCAP version. (Note: this is different from the server version as well as the HTTP version.)

Returns

The commands supports output types iCal and XML. The variable X-NSCP-WCAPVERSION contains the WCAP version number.

Example

The following examples are for each of output data types.