Previous Contents Index Next |
iPlanet Calendar Server 5.0 Programmer's Reference |
Chapter 10 WCAP Commands
This chapter is divided into two parts: topics of common interest, and the individual WCAP commands.
Access Control Entries
Choosing a Different Language or Character Set
Formatting of Time, Strings, Parameters, Etc.
Commands
Table 10-1 lists the WCAP commands in alphabetical order.
Common Topics
This section discusses topics of common interest that apply to one or more commands. The topics are listed in alphabetical order.
Access Control Entries
Choosing a Different Language or Character Set
Formatting of Time, Strings, Parameters, Etc.
Access Control Entries
Access Control Entries (ACE strings) determine access control for calendars. There may be multiple ACE strings that apply to a calendar. Collectively, all the ACE strings that apply are called an Access Control List (ACL). As the system searches the ACL list, the first ACE encountered that either grants of denies access will be used. Thus, the ordering of an ACL is significant. ACE strings should be ordered such that the more specific ones appear before the more general ones.Some access is "built-in". For example, primary owners have access to everything in their calendars. The system does not need to perform access control checks for primary owners accessing their own calendars.
The set_calprops command uses the acl parameter to facilitate storing of ACE strings to a calendar. The acl parameter is a semicolon-separated list of ACE strings. You may set the default acl in the ics.conf file by changing the calstore.calendar.default.acl preference, or by using the cscal command line utility. See the "iPlanet Calendar Server Administration Guide" for further information on configuration settings.
Here is an example of an ACE string:
The string has four elements separated by three "^" characters. The four elements are:
The first element of an ACE tells who the ACE applies to.
- This could be an individual user (specified by user ID), a domain, or a class-type of user. There are four types of classes for users:
All users, represented by the string "@".
The second element of an ACE indicates what the ACE applies to.Primary owners of a calendar, represented by the string "@@p".
Owners of a calendar, represented by the string "@@o".
Non-owners of a calendar, represented by the string "@@n".
- The ACE can be applied to:
The entire calendar.
The third element of an ACE indicates what access values the ACE applies to.
The components of the calendar only.
- Applies to both components and calendar properties. To indicate the entire calendar, pass in the value a.
The calendar properties of the calendar only.
- Applies to calendar components (i.e events/todos). To indicate just the components, pass in the value c.
- Applies to calendar properties (i.e display name, ownerlist). To indicate calendar properties only, pass in the value p.
The fourth element of an ACE indicates whether to grant or deny access.
- Multiple values may be specified at the same time. To do this, the caller must pass in a string to indicate which bits to check.
- Table 10-2 lists the Access Control characters used in ACE strings. The third element contains a string with one or more of the Access Control characters.
- For example, to grant read access, the value r is passed in. To grant write and delete access, the value wd is passed in.
- The ACE can either grant or deny access.
ACE Summary
Here is a quick summary of the order of an ACE:
who = A string, type (str).
flags = One of the characters c, p, or a.
how = An access-string composed of one or more of the access control characters described earlier in Table 10-2.
Extended Examples
Here are some examples of circumstances and how the ACE would be set in the acl parameter for jdoe's calendar:
To grant john read access to both components and calendar properties (acl=john a r g), and to grant susan write and delete access to components only (acl=susan c wd g), the entire command is:
[Return to Common Topics]
To grant all users in a domain schedule, freebusy, and read access to components only (@domainname c sfr g), to grant owners to write and delete access to components only (@@o c wd g), to grant owners self-admin, schedule, freebusy, and read access to both components and calendar properties (@@o a zsfr g), to deny susan all access to both components and calendar properties (susan a zsfdwr d), and to grant read access to all users (@ c r g), the entire command is:
- set_calprops.wcap?id=${SESSIONID}&calid=jdoe&acl=john^a^r^g; susan^c^wd^g
- set_calprops.wcap?id=${SESSIONID}&calid=jdoe&acl=@domainname^c^sfr^g;@@o^c^wd^g;@@o^a^zsfr^g;susan^a^zfsdwr^d;@^c^r^g
Choosing a Different Language or Character Set
To insert a request for data to be returned in a language other than the system default, set either the lang or charset parameter. Note that the system default for language is now a server preference that you set in the ics.conf file. See the "Administrator's Guide" for details. The login command uses only the lang parameter.For the set_calprops command, in most cases, specifying the lang parameter is enough. However, it may be necessary, in some instances, to use the charset parameter instead of the lang parameter. For example, if the user wants the requested data returned in a specified character set, then the user must specify it using charset. One possible charset value is: iso-8859-1. For more information on formatting specifications, see the RFCs referenced in Formatting of Time, Strings, Parameters, Etc. in this chapter.
Please note that when the user requests data in iCalendar or XML format, data always returns in UTF-8 format, per the RFC specification. Setting charset will not change this.
Here is a list of the valid lang values:
[Return to Common Topics]
Deleting Recurring Components
When you delete a component, you can (and sometimes must) specify whether or not it is recurring, and, if it is, whether to delete the recurrences as well as the original event or todo.Use the mod parameter to choose which delete option you want:
For each option, the user must pass in the rid parameter which specifies the recurrence ID of the event, and the type of deletion to do.
To delete just the single instance of the event, the mod parameter should be set to 1. For example, this URL would delete just the event that occurs on the date March 1, 2000 11:22:33 AM GMT.
http://webcalendarserver/deleteevents_by_id.wcap?id=23423423434abc& calid=jdoe&uid=001&rid=20000301T112233Z&mod=1
To delete the event and all future instances of the event, the mod parameter should be set to 2. For example, this URL would delete the event that occurs on the date March 1, 2000 11:22:33 AM GMT and all future instances of this event (uid 001).
http://jdoe/deleteevents_by_id.wcap?id=23423423434abc&calid=jdoe&ui d=001&rid=20000301T112233Z&mod=2
To delete the event and all prior instances of the event, the mod parameter should be set to 3.
For example, this URL would delete the event that occurs on the date March 1, 200011:22:33 AM GMT and all prior instances of this event (uid 001).
http://jdoe/deleteevents_by_id.wcap?id=23423423434abc&calid=jdoe&ui d=001&rid=20000301T112233Z&mod=3
To delete all instances of the event, the mod parameter should be set to 4. For example, this URL would delete ALL instances of the event (uid 001).
http://jdoe/deleteevents_by_id.wcap?id=23423423434abc&calid=jdoe&ui d=001&rid=20000301T112233Z&mod=4
[Return to Common Topics]
Encoded Characters
In the example, the encoded list of parameters for cal includes some encoded characters. Here are some examples of encoded characters:
The %XX is the hexadecimal ASCII value of the character. For example, the '&' character is 26 in hex (38 in ASCII).
[Return to Common Topics]
Error Handling
Each call to a WCAP command that returns component data (fetch, delete, and store commands) also returns an array and an error string.
Error String
The error string, errno, returns the non-zero error number for the transaction. The value is 0 if the command succeeded.
Layer Error Number Array.
In addition to the possibility of the transaction failing, it is possible that one or more of the layers may have failed during the transaction. Layer refers to one of the multiple actions or items that are being requested. For example, in fetch_components_by_range, you may pass in a list of calendar IDs to fetch from; in this case, each calendar is a layer.The error number is specific to a layer. The index of the layer array maps to the index number of the layer passed in. Therefore, layer_errno[3], refers to the third item you passed in to the fetch command.
An error in one layer does not prevent the other layers from being processed.
There are three layer error arrays:
Layer Count Array.
In addition, for deleteevents_by_id and deletetodos_by_id, the commands return a second array, delete_event_count, or delete_todo_count respectively. This array contains the count of successful deletions before the error occurred. This is useful if the components passed have recurrences. As with the layer error number array, the index of the layer count array maps to the index number of the layer passed in to the command.For example, if you pass in three components to deleteevents_by_id and you get an error in the second event, you find the error code in delete_layer_errno[2]. You then look in delete_event_count[2] to see how many occurrences of the event were successfully deleted before the error occurred.
Error Codes
Table 10-4 list some of the error codes returned in the error number array.
[Return to Common Topics]
Formatting of Time, Strings, Parameters, Etc.
Find the exact format and definition for all times, strings, parameters, etc. by referring to RFC2445, RFC2446, and RFC2447. Unless otherwise noted, all WCAP commands follow these specifications.The RFC's may be found at the IETF web site:
http://www.ietf.org/rfc/rfc2445.txt
[Return to Common Topics]http://www.ietf.org/rfc/rfc2446.txt
http://www.ietf.org/rfc/rfc2447.txt
Note While there is no limit on the size of string parameters in WCAP, we recommend keeping the total parameter length to 1024 characters or less.
Freebusy Access
Freebusy access means that the user may see scheduled time on the calendar but is not allowed to see the event details. Instead, just the word "Busy" appears by the time block. Blocks of time without any scheduled events are listed also, with the word "Free" next to them.For example, a calendar called jdoe has the following events:
100:00-11:00
first meeting
12:00-1:00
lunch
3:00-4:00
second meeting
Suppose user john is given freebusy access to the calendar jdoe. The freebusy time for jdoe (from 9:00 to 6:00) would be the following:
9-10
:
Free
10-11
:
Busy
11-12
:
Free
12-1
:
Busy
1-3
:
Free
3-4
:
Busy
4-6
:
Free
Notice that john does not know why the user is busy, but simply knows when the user is busy.
[Return to Common Topics]
New in iPlanet Calendar Server 5.0
While the WCAP commands are backwards compatible with 2.x, many changes have been made to them. One very important change is that the set_calprops command now works in update mode rather than replace mode. That is, you no longer have to specify every parameter in the command as in 2.x. Any parameters not specified in your set_calprops command remain unchanged.This version adds several new commands and some new parameters for existing commands.
New Commands
The new commands are:
check_id
fetchcomponents_by_alarmrange
- Allows administrators to check if session is still valid.
fetchcomponents_by_attendee_error
- Queries for components that have alarms to trigger over a specific time period.
get_freebusy
- Queries for components that had errors while sending group scheduling messages.
- Returns calendar freebusy time.
New Parameters
The new parameters are:
acl
New for this version, some commands have added a parameter that previously only existed in other commands:
alarmAudio
- Added to set_calprops to record ACE strings for access control. See Access Control Entries.
alarmFlashing
- Added to storeevents and storetodos to enable audio reminders.
alarmPopup
- Added to storeevents and storetodos to enable flashing reminders.
compstate
- Added to storeevents and storetodos to enable popup dialog reminders.
convertCalid
- All fetch commands, except fetchcomponents_by_attendee_error, have the ability to fetch by component state, using the parameter compstate. Since all components are usually fetched with these commands, use this parameter to limit the type of components fetched.
- If the parameter is not specified, the default value is ALL.
- Table 10-5 lists component state values. A component state pertains either to the attendee or the organizer.
Table 10-5 Component State Values for compstate Parameter
Organizer's meeting sent. Not all attendees have been processed by the group scheduling engine yet.
language
- In set_userprefs, to allow setting the subscribed list of calendars (icsSubscribed), and the subscribed list of groups (icsSet).
- Added to set_userprefs as a workaround to overcome the server limitation that prohibits the use of the colon character, ":".
- WCAP only checks the value of this parameter when the preference to be set is either icsSet or icsSubscribed.
method
- Added to storeevents and storetodos to indicate which language a component is in.
orgUID
- For group scheduling, this parameter specifies the ITIP method used by the storeevents and storetodos commands.
userid
- Added to storeevents and storetodos. It holds the user ID for the organizer of the event or the originator of the todo.
- Added to get_userprefs and set_userprefs so that the administrator may retrieve or set any user's preferences.
fmt-out has been added to set_calprops.
[Return to Common Topics]orgEmail has been added to storetodos.
deleteevents_by_id
- In addition, tzid in storeevents and storetodos has been modified. The parameter now has the same type as in the above mentioned commands, that is, it is a time zone ID string, such as "America/Los_Angeles".
Output Format
The administrator can request the output format in three content types:To change the output format, set fmt-out to the target value. If fmt-out is not specified, the default format of text/js will be returned.
Condensed Output
The brief parameter allows for the printing of condensed event and todo data in JavaScript. The returned output is about half the size of the regular output and encompasses the following parameters:
Table 10-6 Output Parameters Included in brief Output
[Return to Common Topics]
Recurrence Handling
There are six parameters used to specify recurrence:
rrules. Semicolon-separated list of quoted recurrence-rule strings for recurring events.
rdates. Semicolon-separated list of ISO8601 date strings listing recurrence dates.
exrules. Semicolon-separated list of quoted recurrence-rule strings for dates to exclude.
exdates. Semicolon-separated list of ISO8601 date strings listing dates to exclude.
rid. ISO8601 DateTimeString giving the recurrence ID of an event.
mod. Numeric values 1-4. Modifier telling which instances of the event to store.
rchange. A boolean specifying whether or not to expand recurrences in storecomponents.
rrules
The rrules parameter takes a semicolon-separated list of quoted recurrence rule strings. Each string represents a recurrence rule of the event. Each string must be enclosed in quotes. There are many parameters possible for recurrence rules. See RFC2445 for a complete description of the syntax.Two very useful parameters for specifying recurrence are freq and count:
The freq parameter in a rule defines the periodicity of the event, and has the following possible values:
The following example shows an rrules parameter that specifies two recurrence rules:
DAILY
The event recurs daily.
WEEKLY
The event recurs weekly.
MONTHLY
The event recurs monthly.
YEARLY
The event recurs yearly.
The count parameter in a rule defines how many times the meeting will repeat. If you do not specify the count, the default is the maximum number of recurrences allowed.The default maximum is 60. To change the maximum number, set the server configuration preference calstore.recurrence.bound.
rrules="count%3D10%3Bfreq%3Ddaily";"freq%3Dweekly%3Bcount%3D4"
(COUNT=10;FREQ=DAILY and FREQ=WEEKLY;COUNT=4 encoded)
The first rule specifies that the event is to occur daily for 10 instances. The second rule specifies that the event is to occur weekly for 4 instances.
The following example URL passes the example rrules parameter:
http://webcalendarserver/storecomponents.wcap?id=b5q2o8ve2rk02nv9t6
&calid=jdoe&uid=333&dtstart=20000301T112233Z
&rrules="count%3D10%3Bfreq%3Ddaily";"freq%3Dweekly%3Bcount%3D4"
&dtend=20000301T112233&summary=uuuu
rdates
The rdates parameter takes a semicolon-separated list of date-time specifications where each date-time gives a recurrence date of the event.For example, the following rdates parameter specifies a recurring event with two recurrence dates (3/31/00 11:22:33 and 5/31/00 11:22:33):
rdates=20000331T112233;20000531T112233
The following example URL passes the example rdates parameter:
http://webcalendarserver/storecomponents.wcap?id=b5q2o8ve2rk02nv9t6
&calid=jdoe&uid=333&dtstart=20000301T112233Z
&rdates=20000331T112233;20000531T112233
&dtend=20000301T112233&summary=uuuuIf you want to the change the recurrence rule after a certain date, you must set rchange to 1.
exrules
The exrules parameter takes a semicolon-separated list of quoted recurrence rule strings where each rule is an excluded recurrence of the event.For example, the following exrules parameter specifies a recurring event that does not recur at the times specified by the two rules:
exrules="count%3D10%3Bfreq%3Ddaily";"freq%3Dweekly%3Bcount%3D4"
(COUNT=10;FREQ=DAILY and FREQ=WEEEKLY;COUNT=4 encoded)
The first rule is for the event not to occur daily for 10 instances. The second rule is for the event not to occur weekly for 4 instances.
The following example URL passes the example exrules parameter:
http://webcalendarserver/storecomponents.wcap?id=b5q2o8ve2rk02nv9t6
&calid=jdoe&uid=333&dtstart=20000301T112233Z
&exrules="count%3D10%3Bfreq%3Ddaily";"freq%3Dweekly%3Bcount%3D4"
&rrules="count%3D100%3Bfreq%3Ddaily"&dtend=20000301T112233&summary= uuuu
exdates
The exdates parameter takes a semicolon-separated list of date-time specifications. Each date-time represents an excluded date of the event.For example, the following exdates parameter specifies a recurring event that does not occur on the two specified dates (3/31/00 11:22:33 and 5/31/00 11:22:33):
exdates=20000331T112233;20000531T112233
The following example URL passes the example exdates parameter:
http://webcalendarserver/storecomponents.wcap?id=b5q2o8ve2rk02nv9t6
&calid=jdoe&uid=333&dtstart=20000301T112233Z
&exdates=20000331T112233;20000531T112233
&rrules="COUNT%3D200%3BFREQ=DAILY";dtend=20000301T112233&summary=uu uu
rid
This parameter specifies a unique recurrence date of an event or todo. Use rid in conjunction with the mod parameter to specify a range of events and todos to be modified.http://webcalendarserver/storecomponents.wcap?id=b5q2o8ve2rk02nv9t6
&calid=jdoe&uid=333&dtstart=20000301T112233Z
&rid=20000331T112233;dtend=20000301T112233&summary=uuuu&mod=1
mod
This parameter specifies whether to apply the changes to one or more instances of the event or todo. The mod values result in the following behavior:
For a non-recurring event or todo, the rid is 0.
rchange
The rchange parameter specifies whether recurrences are expanded in storecomponents. Normally, events and todo calendar components are expanded, so the parameter defaults to 1.However, you might not want to expand recurrences when you are modifying multiple events. For example, suppose a meeting recurs every Friday starting Jan. 1, 2000. Use the following URL to change the summary of each event after Feb. 1, 2000 to changed-event. This example sets the rchange parameter to 0, to make the modification without adding additional events:
http://webcalendarserver/storeevents.wcap?id=b5q2o8ve2rk02nv9t6
&calid=jdoe&uid=abcxyz&dtstart=20000201T112233Z
&rrules="byday%3Dfr%3Bfreq%3Dweekly"&summary=changed-event
&rid=20000201T112233Z&mod=2&rchange=0[Return to Common Topics]
Commands
For all commands that have the id parameter (session ID), it is a required parameter. There are two exceptions to this rule. It is not required in order to grant anonymous access to a calendar, nor is it required in order to grant read access to a public calendar. 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.
There are thirty-three WCAP commands:
Purpose
Add links from one calendar's events or todos to another calendar.
Parameters
Table 10-7 lists this command's five parameters:
Description
Use this command to add links in the destination calendar to the specified events and/or todos in the source calendar.You must specify the id parameter with the command unless the specified calendar is a public calendar.
The number of items in the uid and rid lists must match exactly, with each rid corresponding to the uid in the same position in the list. If an event or todo has no recurrence ID, use 0 in the rid list.
Unless the following three requirements are met, the transaction will fail:
The source calendar and destination calendar parameters must be valid calendar ID's.
The user must have write access to the destination calendar and read access to the source calendar.
The uid and rid lists must have the same number of elements.
Returns
If the transaction fails, an error of ADDLINK_FAILED(12) returns; otherwise, the return code is 0.
Example
This example shows how to add two event links to the calendar jdoe. The links should point to events in the pub calendar. The events are 1111 and 2222, (their uids). Neither event is recurring, so their recurrence-id is 0.This URL executes the above transaction.
http://webcalendarserver/addlink.wcap?id=b5q2o8ve2rk02nv9t6&destCal =jdoe&srcCal=pub&uid=1111;2222&rid=0;0
[Return to Commands List]
[Top of Chapter 10]
Purpose
Change the password of the current user. This command is deprecated in 5.0. It is here only for backward compatibility with 2.x. See the "Administrator's Guide" for details on changing a password.
Parameters
Table 10-8 lists this command's four parameters:
Table 10-8 change_password Parameters
Purpose
This command changes a user's password. Passwords are passed as plain text. Only users with administrative privilege may use this command unless the service.wcap.allowchangepassword preference is set.You must specify the id parameter with the command unless the specified calendar is a public calendar.
Returns
A failure of the command will return the error CHANGE_PASSWORD_FAILED(27).
Example
This example URL requests a password change:http://webcalendarserver/change_password.wcap?id=b5q2o8ve2rk02nv9t6 &oldPassword=abc&newPassword=def
[Return to Commands List]
[Top of Chapter 10]
Purpose
This administrator only command allows the administrator to verify that a session is still valid.
Parameters
Table 10-8 lists this command's four parameters:
Table 10-9 change_password Parameters
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://webcalendarserver/check_id.wcap?id=n3l0eeu6s3n3o3b8v&fmt-out =text/calendar
HTTP/1.1 200
Date: Thu, 14 Dec 2000 19:48:17 GMT
Content-type: text/calendar; charset=UTF-8
Content-length: 131
Last-modified: Thu, 14 Dec 2000 19:48:17 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache
Connection: Keep-AliveBEGIN:VCALENDAR
PRODID:-//iPlanet/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:2.0
X-NSCP-WCAP-CHECK-ID:1
END:VCALENDAR lendar
[Return to Commands List]
[Top of Chapter 10]
Purpose
Create a new calendar.
Parameters
Table 10-10 lists this command's four parameters:
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, set the service.wcap.allowcreatecalendars preference in the ics.conf file.
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 will attempt 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 ILLEGAL_CALID_NAME(30).
Valid characters for the calid parameter are:
Alphabet characters (A-Z, a-z)
For example, these are legal values for the calid parameter: calendar1, calendar-1, calendar_1, calendar.1
Setting Calendar Properties
New in 5.0, you may 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 set_calprops command.
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: CREATECALENDAR_ALREADY_EXISTS_FAILED(25)
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://webcalendarserver/createcalendar.wcap?id=b5q2o8ve2rk02nv9t6& calid=newcal&set_calprops=1&name=New-Calendar&categories=business;w ork
[Return to Commands List]
[Top of Chapter 10]
Purpose
This command deletes a user's calendar.
Parameters
Table 10-11 lists this command's three parameters:
Table 10-11 deletecalendars Parameters
Parameter
Types
Purposes
Required
Default
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 may use this command unless the service.wcap.allowdeletecalendars preference is set.
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: CALENDAR_DOES_NOT_EXIST(29).
Example
For example, sending this URL deletes the calendar named newcal.http://webcalendarserver/deletecalendar.wcap?id=b5q2o8ve2rk02nv9t6& calid=newcal
[Return to Commands List]
[Top of Chapter 10]
Purpose
Delete events and todos from a calendar in a specified range.
Parameters
Table 10-12 lists this command's six parameters:
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: 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
[Return to Commands List]
[Top of Chapter 10]
Purpose
Deletes one or more events from a calendar by event identifier.
Parameters
Table 10-13 lists this command's eight parameters:
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 there was an error, the server returns two error arrays, delete_layer_errno and delete_event_count, with each element in the arrays representing the corresponding event in the uid list. Each element in delete_layer_errno indicates the error number for the corresponding event. Each element in delete_event_count indicated the number of occurrences successfully deleted for the corresponding event.See also, Error Handling.
Notify
The notify parameter specifies whether or not to send an IMIP CANCEL message to the email attendees of the event. To send the cancellation message, set the notify value to 1.For example, here's a URL that sends the IMIP CANCEL message to all attendees of the event with uid=001.
http://webcalendarserver/deleteevents_by_id.wcap?id=3423423asdfasf& calid=jdoe&uid=001¬ify=1
Recurrences
If the rid parameter is passed, the command also deletes recurrences, as specified by the mod parameter. (See Deleting Recurring Components.) 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 UIDs 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://webcalendarserver/deleteevents_by_id.wcap?id=br6p3t6bh5po35r
&uid=uid-EVENT1;uid-EVENT2&rid=0;0&mod=1;1The resulting data would look like this:
HTTP/1.0 200
Date: Thu, 27 May 2000 18:40:24 GMT
Content-type: text/html; charset=iso-8859-1
Content-length: 4822
Last-modified: Thu, 27 May 2000 18:40:24 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache<html><head><script>
function color(s) { if (s) document.bgColor=s }
var id='br6p3t6bh5po35r'
var userid='jdoe'
var calid='jdoe'
var errno=new Array()
var delete_event_errno = new Array()
var delete_event_count = new Array()
delete_event_errno[0]=0
delete_event_count[0]=1
delete_event_errno[1]=0
delete_event_count[1]=1
errno[0]=0
...
...
parent.ceCB(window.name)
</script></head></html>
[Return to Commands List]
[Top of Chapter 10]
Purpose
Delete events from a calendar in a specified range.
Parameters
Table 10-14 lists this command's six parameters:
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 JavaScript format.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string, errno. 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, the errno variable contains the error: 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://webcalendarserver/deleteevents_by_range.wcap?id=234234792347 9asdf&calid=jdoe;john&dtstart=0&dtend=0
[Return to Commands List]
[Top of Chapter 10]
Purpose
Delete one or more todos from a calendar.
Parameters
Table 10-15 lists this command's eight parameters:
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 JavaScript format.
Error Codes
If there was an error, the server returns two error arrays, delete_layer_errno and delete_todo_count, with each element in the arrays representing the corresponding todo in the uid list. Each element in delete_layer_errno indicates the error number for the corresponding todo. Each element in delete_todo_count indicates the number of occurrences successfully deleted for the corresponding todo.See also, Error Handling.
Notify
The notify parameter specifies whether or not to send an IMIP CANCEL message to the email attendees of the todo. If notify is 1, an email cancellation message is sent.For example, here's a URL that sends the IMIP CANCEL message to all attendees of the todo with uid=001.
http://webcalendarserver/deletetodos_by_id.wcap?id=3423423asdfasf&c alid=jdoe&uid=001¬ify=1
Recurrences
If the rid parameter is passed, the command also deletes recurrences, as specified by the mod parameter. See Deleting Recurring Components.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 events in the database with UIDs of uid-TODO1 and uid-TODO2. 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://webcalendarserver/deletetodos_by_id.wcap?id=br6p3t6bh5po35r
&uid=uid-TODO1;uid-TODO2&rid=0;0&mod=1;1The resulting data would look like this:
HTTP/1.0 200
Date: Thu, 27 May 2000 18:40:24 GMT
Content-type: text/html; charset=iso-8859-1
Content-length: 4822
Last-modified: Thu, 27 May 2000 18:40:24 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache<html><head><script>
function color(s) { if (s) document.bgColor=s }
var id='br6p3t6bh5po35r'
var userid='jdoe'
var calid='jdoe'
var errno=new Array()
var delete_todo_errno = new Array()
var delete_todo_count = new Array()
delete_todo_errno[0]=0
delete_todo_count[0]=1
delete_todo_errno[1]=0
delete_todo_count[1]=1
errno[0]=0
...
...
parent.ceCB(window.name)
</script></head></html>
[Return to Commands List]
[Top of Chapter 10]
Purpose
Delete todos in a range from a calendar.
Parameters
Table 10-16 lists this command's six parameters:
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 event that occurs on the date March 1, 2000 11:22:33 AM GMT.http://webcalendarserver/deleteevents_by_id.wcap?id=23423423434abc& calid=jdoe&uid=001&rid=20000301T112233Z&mod=1
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 JavaScript format.
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, the errno variable contains the error: DELETETODOS_BY_RANGE_FAILED(23).See also, Error Handling.
[Return to Commands List]
[Top of Chapter 10]
Purpose
Export events and todos from a calendar to a file.
Parameters
Table 10-17 lists this command's five parameters:
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 (indicated by Z at the end of the datetime).
HTTP Post Examples
You must use this command with an HTTP POST (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://webcalendarserver:12345/export.wcap?id=t9u9m0eh8x5pu 9b
&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://webcalendarserver:12345/export.wcap?id=t9u9m0eh8x5pu 9b
&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>HTTP/1.0 200
Date: Thu, 03 Jun 2000 22:15:52 GMT
Content-type: text/calendar
Content-disposition: attachment; filename="export.ics"
Content-length: 7004BEGIN:VCALENDAR
METHOD:PUBLISH
VERSION:2.0
BEGIN:VEVENT
UID:tm-001
RECURRENCE-ID:20000519T010000Z
DTSTAMP:20000603T221548Z
SUMMARY:Calendar Staff
DTSTART:20000518T170000Z
DTEND:20000518T190000Z
CREATED:20000603T024254Z
LAST-MODIFIED:20000603T024254Z
PRIORITY:1
SEQ:1
GEO:37.463581;-121.897606
DESC:This is the description for event with UID = tm-001
URL:http://webcalendarserver/susan?uid=tm-001
LOCATION:Green Conference Room
STATUS:CONFIRMED
TRANSP:OPAQUE
END:VEVENT
BEGIN:VEVENT
UID:tm-001
RECURRENCE-ID:20000526T010000Z
DTSTAMP:20000603T221548Z
SUMMARY:Calendar Staff
DTSTART:20000525T170000Z
DTEND:20000525T190000Z
CREATED:20000603T024254Z
LAST-MODIFIED:20000603T024254Z
PRIORITY:1
SEQ:1
GEO:37.463581;-121.897606
DESC:This is the description for event with UID = tm-001
URL:http://webcalendarserver/susan?uid=tm-001
LOCATION:Green Conference Room
STATUS:CONFIRMED
TRANSP:OPAQUE
END:VEVENT
END:VCALENDAR
[Return to Commands List]
[Top of Chapter 10]
Purpose
Retrieve calendar events and todos with alarm triggers.
Parameters
Table 10-18 lists this command's seven parameters:
Table 10-18 fetchcomponents_by_alarmrange Parameters
A boolean indicating whether or not to print out a brief version of the JavaScript output.
Applies only when output type (fmt-out) is JavaScript (text/js).
Semicolon-separated list of calendar identifiers from which to retrieve components.
The list of component states to fetch.
For compstate values, see Table 10-5
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.
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.
Default time zone to use if the rid parameter does not have a time zone specified.
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 JavaScript format.For JavaScript output, events are divided into two arrays. Events that span a smaller range of time, most normal events, print out in the event array. All events that last longer than 24 hours, or are all-day events, print out in the eventD array. All day events are signified by having the isAllDay flag turned on.
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 JavaScript would contain the following variablesvar 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 JavaScript 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. Specify these in the ISO8601 DateTime Z string format.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 FETCH_BY_ALARM_RANGE_FAILED(41).
Example
For example, suppose there are 3 events:Here are three queries and their return values:
This query fetches all events and todos that have alarms.
This query fetches all events and todos that have alarms about to go off between 12/1/2000 and 1/31/2001.
- http://webcalendarserver/fetchcomponents_by_alarmrange.wcap?id=abcdefg&dtstart=0&dtend=0
- It returns eventA, eventB, and todoA.
This query fetches all events and todos that have alarms to go off between 1/1/2000 and 6/1/2000.
- http://webcalendarserver/fetchcomponents_by_alarmrange.wcap?id=abcdefg&dtstart=20001201T112233Z&dtend=20010131T112233Z
- It returns eventB and todoA.
- http://webcalendarserver/fetchcomponents_by_alarmrange.wcap?id=abcdefg&dtstart=20000101T112233Z&dtend=20000601T112233Z
- It returns eventA and todoA.
[Return to Commands List]
[Top of Chapter 10]
fetchcomponents_by_attendee_error
Fetch a list of components that had errors while sending group scheduling messages.
Table 10-19 lists this command's five parameters
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 JavaScript format.For JavaScript output, events are divided into two arrays. Events that span a smaller range of time, most normal events, print out in the event array. All events that last longer than 24 hours, or are all-day events, print out in the eventD array. All-day events are signified by having the isAllDay flag turned on.
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 JavaScript would contain the following variablesvar 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 JavaScript 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:
For attendee jdoe, the command returns: events 1c1 and 2c2.
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 FETCH_BY_ATTENDEE_ERROR_FAILED(42).
[Return to Commands List]
[Top of Chapter 10]
Purpose.
Fetch a list of components that have changed during a specified time period.Table 10-20 lists this command's seven parameters
Table 10-20 fetchcomponents_by_lastmode Parameters
A boolean indicating whether or not to print out a brief version of the JavaScript output.
Applies only when output type (fmt-out) is JavaScript (text/js).
Semicolon-separated list of calendar identifiers from which to retrieve components.
The list of component states to fetch.
For compstate values, see Table 10-5
Start time and date of events to be returned.
A value of 0 means fetch all events from the beginning of time.
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.
Default time zone to use if the rid parameter does not have a time zone specified.
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 JavaScript format.For JavaScript output, events are divided into two arrays. Events that span a smaller range of time, most normal events, print out in the event array. All events that last longer than 24 hours, or are all-day events, print out in the eventD array. All-day events are signified by having the isAllDay flag turned on.
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 JavaScript would contain the following variablesvar 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 JavaScript 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. Specify these in the ISO8601 DateTime Z string format.If neither the starting nor ending date-time is specified, the server returns all events and todos that have changed, up to the specified maximum.
Error Codes
If the operation is successful, the error number of 0 is appended to the error string. If a calendar cannot be accessed or is missing, the error number is appended to the error string.
Example
For example, the calendar jdoe has these three events:
eventA: last-modified on Feb 10 2000, 10:00 AM GMT.
Here are some queries and their return values:http://webcalendarserver/fetchcomponents_by_lastmod.wcap?id=jdoe
&dtstart=0&dtend=0The above query would fetch all events and todos that have ever been modified. Thus eventA, eventB, and todoA would be returned.
http://webcalendarserver/fetchcomponents_by_lastmod.wcap?id=jdoe
&dtstart=20001201T112233Z&dtend=20000131T112233ZThe above query would fetch all modified events and todos between 12/1/2000 and 1/31/2000. Thus eventB and todoA would be returned.
http://webcalendarserver/fetchcomponents_by_lastmod.wcap?id=jdoe
&dtstart=20000101T112233Z&dtend=20000601T112233ZThe above query would fetch all events and todos that have been modified between 1/1/2000 and 6/1/2000. Thus eventA and todoA would be returned.
[Return to Commands List]
[Top of Chapter 10]
Purpose
Retrieve calendar events and todos.
Parameters
Table 10-21 lists this command's seven parameters:
Table 10-21 fetchcomponents_by_range Parameters
A boolean indicating whether or not to print out a brief version of the JavaScript output.
Applies only when output type (fmt-out) is JavaScript (text/js).
Semicolon-separated list of calendar identifiers from which to retrieve components.
The list of component states to fetch.
For compstate values, see Table 10-5
Start time and date of events to be returned.
A value of 0 means fetch all events from the beginning of time.
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.
Default time zone to use if the rid parameter does not have a time zone specified.
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 JavaScript format.For JavaScript output, events are divided into two arrays. Events that span a smaller range of time, most normal events, print out in the event array. All events that last longer than 24 hours, or are all day events, print out in the eventD array. All day events are signified by having the isAllDay flag turned on.
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. Specify these in the ISO8601 DateTime Z string format.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.
Example
For example, to get the events for calendars jdoe and susan from Jan. 1, 2000 to Feb. 1, 2000, use the following URL:http://webcalendarserver:81/fetchcomponents_by_range.wcap?id=b5q2o8 ve2rk02nv9t6&calid=jdoe
Tip If a calendar does not have a valid timezone (tzid) associated with it, the GMT timezone is used. timezoneList[0]=new TZ('GMT',
`GMT',
'GMT',
'+0000',
'+0000',
new Array())
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 JavaScript format.For JavaScript output, events are divided into two arrays. Events that span a smaller range of time, most normal events, print out in the event array. All events that last longer than 24 hours, or are all-day events, print out in the eventD array. All-day events are signified by having the isAllDay flag turned on.
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 JavaScript would contain the following variablesvar 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 JavaScript 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.
Examples
For example to fetch the events and todos for calendars jdoe and john, from Jan. 1,2000 to Feb. 1, 2001, this URL could be used:http://webcalendarserver/fetchcomponents_by_range.wcap?id=asdfasdf3 2424&calid=jdoe;john&dtstart=20000101T000000&dtend=20010101T000000
If you do not specify the start and end date, it returns all events and todos in the calendar, as in this example:
http://webcalendarserver/fetchcomponents_by_range.wcap?id=b5q2o8ve2 rk02nv9t6&calid=jdoe
HTTP/1.0 200
Date: Tue, 28 Jul 2000 22:43:01 GMT
Content-type: text/html; charset=iso-8859-1
Content-length: 5504
Last-modified: Tue, 15 Jun 2000 22:43:01 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache<html><head><script>
function color(s) { if (s) document.bgColor=s }
var id='bb2ot68wp0t95q'
var userid='jdoe'
var calid='jdoe'
var errno=new Array()
var timezoneList = new Array()
var calprops = new Array()
var layer_errno = new Array()function iso(p) {
if (!p) return null;
var y = p.substring(0,4)
var m = p.substring(4,6)
var d = p.substring(6,8)
var h = p.substring(9,11)
var i = p.substring(11,13)
var s = p.substring(13,15)
return new Date(y, m - 1, d, h, i, s, 0)
}
function
E(a1,a2,a3,a4,a5,a6,a7,a8,a9,a10,a11,a12,a13,a14,a15,a16,a17,a18,a1 9,a20,a21,a22,a23,a24,a25,a26,a27,a28,a29,a30,a31,a32,a33){this.uid=a1
this.rid=a2
this.calid=a3
this.dtstart=iso(a4)
this.dtend=iso(a5)
this.status=a6
this.isAllDay=a7
this.summary=a8
this.created=iso(a9)
this.lastMod=iso(a10)
this.seq=a11
this.geo=new Array(a12,a13)
this.desc=a14
this.icsUrl=a15
this.icsClass=a16
this.location=a17
this.alarmStart=a18
this.alarmEmails=a19
this.rrules=a20
this.rdates=a21
this.exrules=a22
this.exdates=a23
this.tzid=a24
this.priority=a25
this.relatedTos=a26
this.resources=a27
this.categories=a28
this.attachments=a29
this.contacts=a30
this.attendees=a31
this.orgEmail=a32
this.linkCalid=a33
}function
T(a1,a2,a3,a4,a5,a6,a7,a8,a9,a10,a11,a12,a13,a14,a15,a16,a17,a18,a1 9,a20,a21,a22,a23,a24,a25,a26,a27,a28,a29,a30,a31,a32,a33,a34,a35){this.uid=a1
this.rid=a2
this.calid=a3
this.dtstart=iso(a4)
this.due=iso(a5)
this.status=a6
this.isAllDay=a7
this.summary=a8
this.created=iso(a9)
this.lastMod=iso(a10)
this.seq=a11
this.geo=new Array(a12,a13)
this.desc=a14
this.icsUrl=a15
this.icsClass=a16
this.location=a17
this.alarmStart=a18
this.alarmEmails=a19
this.rrules=a20
this.rdates=a21
this.exrules=a22
this.exdates=a23
this.completed=iso(a24)
this.percent=a25
this.tzid=a26
this.priority=a27
this.relatedTos=a28
this.resources=a29
this.categories=a30
this.attachments=a31
this.contacts=a32
this.attendees=a33
this.orgEmail=a34
this.linkCalid=a35
}
function TZ(a1,a2,a3,a4,a5,a6) {
this.tzid=a1
this.sName=a2
this.dName=a3
this.sOffset=a4
this.dOffset=a5
this.crossOver=a6
}
function
CP(a1,a2,a3,a4,a5,a6,a7,a8,a9,a10,a11,a12,a13,a14,a15) {
this.calid=a1
this.name=a2
this.parent=a3
this.tzid=a4
this.read=a5
this.write=a6
this.charset=a7
this.lang=a8
this.master=a9
this.desc=a10
this.lastMod=iso(a11)
this.created=iso(a12)
this.primaryOwner=a13
this.owners=a14
this.categories=a15
}
var event=new Array()
var event=new Array()
var todo=new Array()
var status_types=new Array('confirmed', 'tentative',
'cancelled')
calprops[0] = new CP('John Doe',
'jdoe',
'',
'',
'0',
'0',
'',
'',
'',
'Work Calendar for John Doe',
'20000615T164146Z',
'20000615T164146Z',
'jdoe',
new Array('john'),
new Array(),
new Array('business'))
event[0]=new E('52452531427158444',
'0',
'jdoe',
'20001223T233000',
'20001224T023000',
0,0,'jdoe event 3',
'20000615T222725','20000615T222725',
'1',
'37.463581','-121.897606',
'This is the description for event with UID =
52452531427158444',
'http://webcalendarserver/'+'john?uid=52452531427158444',
'',
'Green Conference Room',
0,
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),'GMT','1',
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),
'',
'')
event[1]=new E('51452531524178674', '0',
'jdoe',
'20001223T130000',
'20001223T123000',
0,0,'jdoe event 2',
'20000615T222725','20000615T222725',
'1',
'37.463581','-121.897606',
'This is the description for event with UID =
51452531524178674',
'http://webcalendarserver/'+'john?uid=51452531524178674',
'',
'Green Conference Room',
0,
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),'GMT','1',
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),
'',
'')
event[2]=new E('tm-001',
'20000519T010000Z',
'jdoe',
'20000518T170000',
'20000518T190000',
0,0,'Calendar Staff',
'20000615T222725','
20000615T222725',
'1',
'37.463581','-121.897606',
'This is the description for event with UID = tm-001',
'http://webcalendarserver/'+'john?uid=tm-001',
'',
'Green Conference Room',
0,
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),'GMT','1',
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),
'',
'')
event[3]=new E('tm-001',
'20000526T010000Z',
'jdoe',
'20000525T170000',
'20000525T190000',
0,0,'Calendar Staff',
'20000615T222725','20000615T222725',
'1',
'37.463581','-121.897606',
'This is the description for event with UID = tm-001',
'http://webcalendarserver/'+'john?uid=tm-001',
'',
'Green Conference Room',
0,
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),'GMT','1',
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),
'',
'')
event[4]=new E('tm-001',
'20000602T010000Z',
'jdoe',
'20000601T170000',
'20000601T190000',
0,0,'Calendar Staff',
'20000615T222725','20000615T222725',
'1',
'37.463581','-121.897606',
'This is the description for event with UID = tm-001',
'http://webcalendarserver/'+'john?uid=tm-001',
'',
'Green Conference Room',
0,
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),'GMT','1',
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),
'',
'')
todo[0]=new T('abctodo',
'0',
'jdoe',
'20000304T143000',
'20000620T222725',
3,0,'Fix the bugs',
'20000615T222725','20000615T222725',
'1',
'37.463581','-121.897606',
'This is the description for event with UID = abctodo',
'http://webcalendarserver/'+'john?uid=TODO1',
'',
'Green Conference Room',
0,
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),'19700101T000000',
'-1',
'GMT','1',
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),
new Array(),
'',
'')
layer_errno[0]=0
var size=5
var todosize=1
var dtstartrange="0"
var dtendrange="0"
errno[0]=0
parent.ceCB(window.name)
</script></head></html>
[Return to Commands List]
[Top of Chapter 10]
Purpose
Retrieve specific calendar events.
Parameters
Table 10-22 lists this command's seven parameters:
Table 10-22 fetchevents_by_id Parameters
A boolean indicating whether or not to print out a brief version of the JavaScript output.
Applies only when output type (fmt-out) is JavaScript (text/js).
The unique identifier for the calendar from which to retrieve events.
The list of component states to fetch.
For compstate values, see Table 10-5
A modifier indicating which recurrences to retrieve. One of the following values:
1 = THISINSTANCE
2 = THISANDFUTURE
3 = THISANDPRIOR
4 = THISANDALLThe recurrence identifier for the event. For a nonrecurring event, set to 0.
Default time zone to use if the rid parameter does not have a time zone specified.
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 Recurrence Handling
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 JavaScript format.For JavaScript output, events are divided into two arrays. Events that span a smaller range of time, most normal events, print out in the event array. All events that last longer than 24 hours, or are all-day events, print out in the eventD array. All-day events are signified by having the isAllDay flag turned on.
Returns
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 JavaScript format.
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.
[Return to Commands List]
[Top of Chapter 10]
Purpose
Retrieve specific calendar todos.
Parameters
Table 10-23 lists this command's seven parameters:
Table 10-23 fetchtodos_by_id Parameters
A boolean indicating whether or not to print out a brief version of the JavaScript output.
Applies only when output type (fmt-out) is JavaScript (text/js).
The unique identifier for the calendar from which to retrieve todos.
The list of component states to fetch.
For compstate values, see Table 10-5
A modifier indicating which recurrences to retrieve. One of the following values:
1 = THISINSTANCE
2 = THISANDFUTURE
3 = THISANDPRIOR
4 = THISANDALLThe recurrence identifier for the todo. For a nonrecurring todo, set to 0.
Default time zone to use if the rid parameter does not have a time zone specified.
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 JavaScript format.For JavaScript output, events are divided into two arrays. Events that span a smaller range of time, most normal events, print out in the event array. All events that last longer than 24 hours, or are all-day events, print out in the eventD array. All-day events are signified by having the isAllDay flag turned on.
Returns
For each calendar specified in calid, the server returns the calendar's todos of that calendar. If the todo has recurrences, it returns them as specified by the rid and mod parameters. See Recurrence Handling.
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.
[Return to Commands List]
[Top of Chapter 10]
Purpose
Retrieve data about all timezones supported by the server.
Parameters
Table 10-24 lists this command's four parameters:
Description.
Use this command to retrieve data about all timezones that are supported by the server. The crossover values are defined to be the dates when the timezone 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 timezone does not have daylight-savings, then this value will be 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 JavaScript format.
Error Codes
If there was an error in getting the timezones, the server returns the error GET_ALL_TIMEZONES_FAILED(24).
Example
The following is an example of a timezone array element where crossover dates have been limited to the years from mid-1998 to 2006:timezoneList[20] = new TZ('America/Los_Angeles',
'PST',
'PDT',
'-0800',
'-0700',
new Array
('19981025T090000Z','20000404T100000Z','20001031T090000Z',
'20000402T100000Z','20001029T090000Z','20010401T100000Z',
'20011028T090000Z', '20020407T100000Z', '20021027T090000Z',
'20030406T100000Z', '20031026T090000Z', '20040404T100000Z',
'20041031T090000Z', '20050403T100000Z', '20051030T090000Z',
'20060402T100000Z', '20061029T090000Z'))The"America/Phoenix" timezone does not have daylight-savings. Thus the daylight elements exactly equal the standard elements. Also, the crossover strings in set to the empty string.
timezoneList[23] = new TZ('America/Phoenix',
'MST',
'MST',
'-0700',
'-0700',
new Array())
[Return to Commands List]
[Top of Chapter 10]
Purpose
Retrieve calendar properties.
Parameters
Table 10-25 lists this command's three parameters:
Table 10-25 get_calprops Parameters
A list of calendar identifiers for the calendars from which to retrieve properties.
Description.
Use this command to retrieve the calendar properties for the specified calendars.
Returns
The command returns a page with the following property information for the specified calendars:
relative ID
read-access value (0 = cannot read, 1 = can read)
write-access value (0 = cannot read, 1 = can read)
character set (if empty, default is us-ascii)
language (if empty string, default is en = English)
cal-master (contact information, usually email address of primary owner)
Error Codes
If the calendar exists, but the user does not have READ access to it, layer_errno[x] is set to the value 1 for that calendar's index.If the calendar is not found, the server sets layer_errno[x] to the value 2 for that calendar's index.
If the fetch fails for any calendar, its error number, errno, is set to GET_CALPROPS_FAILED(20).
Example
In the following example, you want to retrieve the calendar properties for the calendars jdoe, susan, pub, john, and hasdf in that order.The following conditions apply:
The user has read access the calendars jdoe, pub, and john, but not to the calendar susan.
You get the following results:
The call to get_calprops.wcap returns data for the calendars jdoe, pub, and john, and the layer_errno[] value for their indexes is 0.
This is the URL and the returned data:No data is returned for the calendar susan, and the layer_errno[1] value is set to 1, indicating that the user does not have access to that calendar.
No data is returned for the calendar hasdf, and the layer_errno[5] value is set to 2, indicating that the calendar does not exist.
If the fetch fails for any calendar, its error number is set to the GET_CALPROPS_FAILED(20) value.
http://webcalendarserver/get_calprops.wcap?id=2mu95r5so0hq68ts6q3
&calid=jdoe;susan;pub;john;hasdfHTTP/1.0 200
Date: Wed, 16 Jun 2000 22:21:27 GMT
Content-type: text/html; charset=iso-8859-1
Content-length: 1624
Last-modified: Wed, 16 Jun 2000 22:21:27 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache
<html><head><script>
function color(s) { if (s) document.bgColor=s }
var id='bu9p3eb8x5p2nm0q3'
var userid='jsun'
var calid='jsun'
var errno=new Array()
var timezoneList = new Array()
var calprops = new Array()function iso(p)
{
if (!p) return null;
var y = p.substring(0,4)
var m = p.substring(4,6)
var d = p.substring(6,8)
var h = p.substring(9,11)
var i = p.substring(11,13)
var s = p.substring(13,15)
return new Date(y, m - 1, d, h, i, s, 0)
}function
CP(a1,a2,a3,a4,a5,a6,a7,a8,a9,a10,a11,a12,a13,a14,a15) {
this.calid=a1
this.name=a2
this.parent=a3
this.tzid=a4
this.read=a5
this.write=a6
this.charset=a7
this.lang=a8
this.master=a9
this.desc=a10
this.lastMod=iso(a11)
this.created=iso(a12)
this.primaryOwner=a13
this.owners=a14
this.categories=a15
}calprops[0] = new CP('jdoe',
'John Doe',
'',
'',
'0',
'0',
'',
'',
'',
'Work Calendar for John Doe',
'20000615T222725Z',
'20000615T222725Z',
'jdoe',
new Array('susan'),
new Array(),
new Array('business'))layer_errno[0]=0
calprops[1] = new CP('susan')
layer_errno[1]=1
calprops[2] = new CP('pub',
'Public Calendar',
'',
'',
'1',
'1',
'',
'',
'',
'Public Calendar, Anyone can read and write',
'20000615T222725Z',
'20000615T222725Z',
'susan',
new Array(),
new Array(),
new Array('group','business'))
layer_errno[2]=0
calprops[3] = new CP('john',
'John Calendar Hosting Server',
'',
'',
'0',
'0',
'',
'',
'',
'John Project Calendar',
'20000615T222725Z',
'20000615T222725Z',
'susan',
new Array('smith','jones','fred','jdoe'),
new Array(),
new Array('group','business'))
layer_errno[3]=0
calprops[4] = new CP('hasdf')
layer_errno[4]=2
errno[0]=0
parent.ceCB(window.name)
[Return to Commands List]
[Top of Chapter 10]
Purpose
Get the freebusy information for users.
Parameters
Table 10-26 lists this command's five parameters:
Table 10-26 get_freebusy Parameters
A list of calendar identifiers for the calendars from which to retrieve properties.
Description.
This command to retrieve the freebusy information for specified users. Freebusy information tells whether or not a user's time has been scheduled. It does not indicate why the user is busy.
Error Codes
If this command fails for any reason, errno is set to GET_FREEBUSY_FAILED(39).
Example
For example, a calendar called jdoe has the following events:
100:00-11:00
first meeting
12:00-1:00
lunch
3:00-4:00
second meeting
The freebusy time for jdoe (from 9:00 to 6:00) would be the following:
9-10
:
Free
10-11
:
Busy
11-12
:
Free
12-1
:
Busy
1-3
:
Free
3-4
:
Busy
4-6
:
Free
The following URL generates freebusy information found in the calendar jdoe between May 1 2000 and July 1 2000.
The output is returned in text/calendar format.
http://webcalendarserver/get_freebusy.wcap?id=2mu95r5so0hq68ts6q3&c alid=jsun&dtstart=20000501T112233Z&dtend=20000701T112233Z&fmt-out=t ext/calendar
HTTP/1.1 200
Date: Wed, 17 May 2000 01:23:23 GMT
Content-type: text/calendar; charset=UTF-8
Content-length: 1430
Last-modified: Wed, 17 May 2000 01:23:23 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache
Connection: Keep-AliveBEGIN:VCALENDAR
PRODID:-//iPlanet/Calendar Hosting Server//EN
METHOD:PUBLISH
VERSION:2.0
X-NSCP-CALPROPS-LAST-MODIFIED:20000517T012259Z
X-NSCP-CALPROPS-CREATED:20000517T012259Z
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:20000501T112233Z
DTEND:20000701T112233Z
FREEBUSY;FBTYPE=FREE:20000501T112233Z/20000518T170000Z
FREEBUSY;FBTYPE=BUSY:20000518T170000Z/20000518T190000Z
FREEBUSY;FBTYPE=FREE:20000518T190000Z/20000525T170000Z
FREEBUSY;FBTYPE=BUSY:20000525T170000Z/20000525T190000Z
FREEBUSY;FBTYPE=FREE:20000525T190000Z/20000601T170000Z
FREEBUSY;FBTYPE=BUSY:20000601T170000Z/20000601T190000Z
FREEBUSY;FBTYPE=FREE:20000601T190000Z/20000608T170000Z
FREEBUSY;FBTYPE=BUSY:20000608T170000Z/20000608T190000Z
FREEBUSY;FBTYPE=FREE:20000608T190000Z/20000615T170000Z
FREEBUSY;FBTYPE=BUSY:20000615T170000Z/20000615T190000Z
FREEBUSY;FBTYPE=FREE:20000615T190000Z/20000622T170000Z
FREEBUSY;FBTYPE=BUSY:20000622T170000Z/20000622T190000Z
FREEBUSY;FBTYPE=FREE:20000622T190000Z/20000629T170000Z
FREEBUSY;FBTYPE=BUSY:20000629T170000Z/20000629T190000Z
FREEBUSY;FBTYPE=FREE:20000629T190000Z/20000701T112233Z
END:VFREEBUSY
X-NSCP-WCAP-ERRNO:0
END:VCALENDARThis example shows the output when the fmt-out specifies text/xml.
http://webcalendarserver/get_freebusy.wcap?id=2mu95r5so0hq68ts6q3&c alid=jdoe&dtstart=20000501T112233Z&dtend=20000701T112233Z&fmt-out=t ext/xml
The output returned for text/xml:
HTTP/1.1 200
Date: Wed, 17 May 2000 01:24:58 GMT
Content-type: text/xml; charset=UTF-8
Content-length: 1868
Last-modified: Wed, 17 May 2000 01:24:58 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache
Connection: Keep-Alive<?xml version="1.0" encoding="UTF-8"?>
<iCalendar>
<iCal version="2.0" prodid="-//iPlanet/Calendar Hosting
Server//EN" METHOD="PUBLISH">
<X-NSCP-CALPROPS-LAST-MODIFIED>20000517T012259Z</X-NSCP-CALPR
PS-LAST-MODIFIED>
<X-NSCP-CALPROPS-CREATED>20000517T012259Z</X-NSCP-CALPROPS-CREATED>
<X-NSCP-CALPROPS-READ>999</X-NSCP-CALPROPS-READ>
<X-NSCP-CALPROPS-WRITE>999</X-NSCP-CALPROPS-WRITE>
<X-NSCP-CALPROPS-DESCRIPTION>Work Calendar for John Doe
</X-NSCP-CALPROPS-DESCRIPTION>
<X-NSCP-CALPROPS-RELATIVE-CALID>jdoe</X-NSCP-CALPROPS-RELATIVE-CALI D>
<X-NSCP-CALPROPS-NAME>John Doe</X-NSCP-CALPROPS-NAME>
<X-NSCP-CALPROPS-PRIMARY-OWNER>jdoe</X-NSCP-CALPROPS-PRIMARY-OWNER>
<X-NSCP-CALPROPS-OWNERS>susan</X-NSCP-CALPROPS-OWNERS>
<X-NSCP-CALPROPS-CATEGORIES>business</X-NSCP-CALPROPS-CATEGORIES>
<X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY>@^a^S^g</X-NSCP-CALPROPS-ACCE SS-CONTROL-ENTRY><FREEBUSY>
<START>20000501T112233Z</START>
<END>20000701T112233Z</END>
<FB FBTYPE="FREE">20000501T112233Z/20000518T170000Z</FB>
<FB FBTYPE="BUSY">20000518T170000Z/20000518T190000Z</FB>
<FB FBTYPE="FREE">20000518T190000Z/20000525T170000Z</FB>
<FB FBTYPE="BUSY">20000525T170000Z/20000525T190000Z</FB>
<FB FBTYPE="FREE">20000525T190000Z/20000601T170000Z</FB>
<FB FBTYPE="BUSY">20000601T170000Z/20000601T190000Z</FB>
<FB FBTYPE="FREE">20000601T190000Z/20000608T170000Z</FB>
<FB FBTYPE="BUSY">20000608T170000Z/20000608T190000Z</FB>
<FB FBTYPE="FREE">20000608T190000Z/20000615T170000Z</FB>
<FB FBTYPE="BUSY">20000615T170000Z/20000615T190000Z</FB>
<FB FBTYPE="FREE">20000615T190000Z/20000622T170000Z</FB>
<FB FBTYPE="BUSY">20000622T170000Z/20000622T190000Z</FB>
<FB FBTYPE="FREE">20000622T190000Z/20000629T170000Z</FB>
<FB FBTYPE="BUSY">20000629T170000Z/20000629T190000Z</FB>
<FB FBTYPE="FREE">20000629T190000Z/20000701T112233Z</FB>
</FREEBUSY>
<X-NSCP-WCAP-ERRNO>0</X-NSCP-WCAP-ERRNO>
</iCal>
</iCalendar>
[Return to Commands List]
[Top of Chapter 10]
Purpose
Generate a set of globally unique identifiers.
Parameters
Table 10-27 lists this command's two parameters:
Table 10-27 get_guids Parameters
Description.
This command returns the specified number of globally unique identifiers (GUIDs). The client need not be authenticated to call this command.
Example
The following example URLs and their return output show the three formats:
iCalendar Format
http://webcalendarserver/get_guids.wcap?guidCount=10
&fmt-out=text/calendarBEGIN:VCALENDAR
VERSION:2.0
PRODID:iPlanet Calendar Server 5.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:e5e4b537c263000012000000c3000000
X-NSCP-GUID8:e5e4b537241f000013000000c3000000
X-NSCP-GUID9:e5e4b537e733000014000000c3000000
END:VCALENDAR
XML Format
http://webcalendarserver/get_guids.wcap?guidCount=10&fmt-out=text/x ml<?xml version="1.0" encoding="UTF-8"?>
<iCalendar>
<iCal>
<X-NSCP-GUID0>fde4b537d604000015000000c3000000<X-NSCP-GUID0>
<X-NSCP-GUID1>fde4b5379478000016000000c3000000<X-NSCP-GUID1>
<X-NSCP-GUID2>fde4b5372a6d000017000000c3000000<X-NSCP-GUID2>
<X-NSCP-GUID3>fde4b537a355000018000000c3000000<X-NSCP-GUID3>
<X-NSCP-GUID4>fde4b5377768000019000000c3000000<X-NSCP-GUID4>
<X-NSCP-GUID5>fde4b5376e2e00001a000000c3000000<X-NSCP-GUID5>
<X-NSCP-GUID6>fde4b537a07700001b000000c3000000<X-NSCP-GUID6>
<X-NSCP-GUID7>fde4b537744700001c000000c3000000<X-NSCP-GUID7>
<X-NSCP-GUID8>fde4b537ab1f00001d000000c3000000<X-NSCP-GUID8>
<X-NSCP-GUID9>fde4b5371d2200001e000000c3000000<X-NSCP-GUID9>
</iCal>
</iCalendar>
JavaScript Format
In the final example, the fmt-out parameter defaults to text/js:http://webcalendarserver/get_guids.wcap?guidCount=10
<html><head><script>
function color(s) { if (s) document.bgColor=s }
var id='0'
var userid=''
var calid=''
var errno=new Array()
var guid=new Array()
guid[0]=9ee4b5375778000001000000c3000000
guid[1]=9ee4b5376a52000002000000c3000000
guid[2]=9ee4b5375a47000003000000c3000000
guid[3]=9ee4b537bf01000004000000c3000000
guid[4]=9ee4b537e05e000005000000c3000000
guid[5]=9ee4b537be5a000006000000c3000000
guid[6]=9ee4b537d544000007000000c3000000
guid[7]=9ee4b5372867000008000000c3000000
guid[8]=9ee4b5375731000009000000c3000000
guid[9]=9ee4b537830600000a000000c3000000
parent.ceCB(window.name)
</script></head></html>
[Return to Commands List]
[Top of Chapter 10]
Purpose
Retrieve the calendar preferences for the current user.
Parameters
Table 10-28 lists this command's two parameters:
Table 10-28 get_userprefs Parameters
Used only by administrators. Indicates which user's preferences to get.
Description.
This command retrieves all the calendar preferences for the current user, and the following server preferences relating to this user:
allowchangepassword. Users can change the password.
To use the parameter userid, two conditions must be met. The server configuration preference service.admin.calmaster.wcap.allowcreatecalendars. Users can create calendars.
allowdeletecalendars. Users can delete calendars.
allowpublicwritablecalendars. Users can have publicly writable calendars.
validateowners. If set to 1, the server must validate that each owner of a calendar exists in the directory (whether the directory is LDAP or a CSAPI compatible user mechanism).
allowsetprefs. If set to 1, allow set_userprefs.wcap to modify the user preferences.
allowgetmodifyuserprefs must be set to "yes" in the ics.conf file, and the requestor must be logged in as an administrator, using the login.wcap command.See the "Administrator's Guide" for detailed information about server preferences.
Example
The following URL retrieves user preferences for the current user:http://webcalendarserver/get_userprefs.wcap?id=b5q2o8ve2rk02nv9t6
<html><head><script>
function A (name, readonly)
{this.name=name
this.readonly=readonly
this.vals=new Array (A.arguments.length - 2)
for (var i = 2; i < A.arguments.length; i++)
this.vals[i - 2]=A.arguments[i]
}
var usrattrval=new Array()
usrattrval[0]=new A('cn',true,'John Doe')
usrattrval[1]=new A('givenName',true,'John')
usrattrval[2]=new A('mail',true,'jdoe@mailserver')
usrattrval[3]=new A('preferredlanguage',false)
usrattrval[4]=new A('sn',true,'Doe')
usrattrval[5]=new A('cebgcolor',false,'black')
usrattrval[6]=new A('ceFgcolor',false,'green')
usrattrval[7]=new A('ceBFgcolor',false,'black')
function M(name, flags, msgs, size)
{this.name=name
this.msgs=msgs
this.flags=flags
this.size=size
}
var flags=new Array ('//noinferiors', '//hasnochildren',
'//haschildren', '//noselect')
var flag=new Array(flags.length)
flag['//noinferiors']=1
flag['//hasnochildren']=2
flag['//haschildren']=4
flag['//noselect']=8
var allowchangepassword="no"
var allowcreatecalendars="yes"
var allowdeletecalendars="yes"
var allowexpungecalendar="yes"
var errno=new Array()
errno[0]=0
var errstr=''
</script></head> </script></head>
<body bgcolor=#FFFFFF>
<br><form action=set_userprefs.wcap method=post name=form>
cmd<input name=cmd>
old<input name=oldPassword>
new<input name=newPassword>
<input name=add_attrs>
<input name=del_attrs>
<input name=set_attrs>
<input name=id value='e2np3w9o0v6k0u9v9b'>
<input name=bgcolor>
<input name=security>
<input type=submit>
</form>
</body>
<script>var form=document.form
parent.cfgCB()</script>
[Return to Commands List]
[Top of Chapter 10]
Purpose
Import events and todos from a file to a calendar.
Parameters
Table 10-29 lists this command's five parameters:
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 (indicated by Z at the end of the datetime).
You must use this command with an HTTP POST message (unlike other commands, which 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:20000105T100000
DTEND:20000105T110000
DTSTAMP:20000104T120000
CREATED:20000105T110000Z
LAST-MODIFIED:20000104T120000Z
SUMMARY:Weekly QA Meeting
UID:random-uid001
END:VEVENT
BEGIN:VEVENT
DTSTART:20000106T100000
DTEND:20000106T110000
DTSTAMP:20000104T120000
CREATED:20000105T110000Z
LAST-MODIFIED:20000104T120000Z
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://webcalendarserver:12345/import.wcap?id=t95qm0n0es3bo 35r&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>
[Return to Commands List]
[Top of Chapter 10]
Purpose
Authenticate a specific user.
Parameters
Table 10-30 lists this command's five parameters:
Description.
This command logs a specific user into iPlanet 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 csIAuthentication). For more information on the Proxy Authentication SDK, see Chapter 6 for the overview and Chapter 7 for the API Reference.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://webcalendarserver/login.wcap?user=jdoe&password=mypword
Returns
If you do not pass in the refresh parameter, and fmt-out specifies text/js, the default value is 0. If fmt-out specifies one of the two other styles, text/calendar or text/xml, the default value is 1.If you specify 1 in the refresh parameter, the returned page contains only the session identifier in a line such as the following:
This is the value that you pass to many WCAP commands in order to gain access to private calendars. It is also a required parameter for certain commands, such as logout.
If you specify 0 for the refresh parameter, the command returns JavaScript output containing the location of the entry page to the iPlanet Calendar Server's user interface.
With the parameter set to 0, the login command returns everything, including the default html file:
HTTP/1.0 302 OK
Date: Tue, 11 May 2000 22:38:33 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache
Content-Length: 0
Last-modified: Tue, 11 May 2000 22:38:33 GMT
Location:
http://webcalendarserver/en/main.html?id=er6en05tv6n3bv9&lang=en
&host=http://webcalendarserver/<html><head><script>
function color(s) { if (s) document.bgColor=s }
var id='er6en05tv6n3bv9'
var userid='jdoe'
var calid='jdoe'
var errno=new Array()
var errstr=''
</script></head>
<body bgcolor='9999CC' onLoad=parent.ceCB(window.name)>
[Return to Commands List]
[Top of Chapter 10]
Purpose
Terminate the current user's session.
Parameters
Table 10-31 lists this command's two parameters:
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://webcalendarserver/logout.wcap?id=bu9p3eb8x5p2nm0q3
[Return to Commands List]
[Top of Chapter 10]
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 2000 21:31:42 GMT
Content-type: text/html; charset=iso-8859-1
Content-length: 190
Last-modified: Thu, 03 Jun 2000 21:31:42 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache<html><head><script>
function color(s) { if (s) document.bgColor=s }var id='bb5rt6eb5pu9v9w9'
var userid='adminX'
var calid='adminX'
var errno=new Array()
parent.ceCB(window.name)
</script></head></html>
[Return to Commands List]
[Top of Chapter 10]
Purpose
Search for a calendar's properties.
Parameters
Table 10-32 lists this command's seven parameters:
Description.
This command searches for a calendar using the query type specified by searchOpts. It returns the calendar properties for all calendars where a string in the specified properties (primaryOwner, calid, name), matches the search-string, using the specified seachOpts, up to the specified maximum number of matches (maxResults).
Search Properties
This command searches for a matching string 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
There are four search options:
Return the calendar properties that contain the search-string (CONTAINS).
Return the calendar properties that begin with the search-string (BEGINS_WITH).
Return the calendar properties that ends with the search-string (ENDS_WITH).
Return the calendar properties that exactly match the search-string (EXACT).
Example
The following example URL searches the primary owner property (primaryOwner=1) in all calendars to see if it contains (searchOpts=0) the string "susan".http://webcalendarserver/search_calprops.wcap?id=b2nehr3eq6bh5s
&search-string=susan&primaryOwner=1&searchOpts=0&maxResults=50In the returned data, the calsize variable specifies the number of calendars returned in the output.
The following data is a result of the example URL above:
HTTP/1.0 200
Date: Fri, 30 Apr 2000 23:49:19 GMT
Content-type: text/html; charset=iso-8859-1
Content-length: 10113
Last-modified: Fri, 30 Apr 2000 23:49:19 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache<html><head><script>
function color(s) { if (s) document.bgColor=s }var id='bu9p3eb8x5p2nm0q3'
var userid='jdoe'
var calid='jdoe'
var errno=new Array()
var timezoneList = new Array()
var calprops = new Array()
var layer_errno = new Array()
function iso(p) {
if (!p) return null;
var y = p.substring(0,4)
var m = p.substring(4,6)
var d = p.substring(6,8)
var h = p.substring(9,11)
var i = p.substring(11,13)
var s = p.substring(13,15)
return new Date(y, m - 1, d, h, i, s, 0)
}
function
CP(a1,a2,a3,a4,a5,a6,a7,a8,a9,a10,a11,a12,a13,a14,a15)
{
this.calid=a1
this.name=a2
this.parent=a3
this.tzid=a4
this.read=a5
this.write=a6
this.charset=a7
this.lang=a8
this.master=a9
this.desc=a10
this.lastMod=iso(a11)
this.created=iso(a12)
this.primaryOwner=a13
this.owners=a14
this.categories=a15
}
calprops[0] = new CP('hockey',
'',
'',
'',
'1',
'1',
'',
'',
'',
'',
'20000615T222725Z',
'20000615T222725Z',
'susan',
new Array(),
new Array(),
new Array('Sports'))
var calsize=1
var maxReturnSize=50
errno[0]=0
parent.ceCB(window.name)
</script></head></html>
[Return to Commands List]
[Top of Chapter 10]
Purpose
Set the calendar properties of a calendar.
Parameters
Table 10-33 lists this command's fifteen parameters:
Description.
This command only changes the values of the parameters you specify. In this way, then, it is an update command, rather than a replace command as it was in 2.x. It is not necessary to supply all parameters in the command, only the ones you wish 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.The read and write parameters have been deprecated in 5.0. The functionality has been replaced with the acl parameter. They are included for backwards compatibility with 2.x only.
Use set_calprops to do the following:
Change the name of the calendar.
Change read permission of calendar's event.
Change write permission of calendar's event.
Change description of calendar.
Change character set of calendar.
Single Calendar Example
Here is a sample URL that sets calendar properties: (The calid parameter is required.)http://webcalendarserver?set_calprops.wcap?id=dfasdfzd3ds&calid=jdo e&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:
For example, the following URL modifies three calendars with IDs xxxx, yyyy, and zzzz, setting the descriptions to X-Calendar, Y-Calendar, and Z-Calendar, respectively:
http://webcalendarserver?id=fasdfzd3ds
&multiple=3
&cal=calid%3Dxxxx%26description%3DX-Calendar
&cal=calid%3Dyyyy%26description%3DY-Calendar
&cal=calid%3Dzzzz%26description%3DZ-CalendarThis is the equivalent of the following three URLs:
http://webcalendarserver?id=fasdfzd3ds&calid=xxxx&desc=X-Calendar
http://webcalendarserver?id=fasdfzd3ds&calid=yyyy&desc=Y-Calendar
http://webcalendarserver?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 will decode each cal parameter and set the properties appropriately.
Access Control Entries
See Access Control Entries, in the Common Topics section at the front of this chapter.
Freebusy Access
See Freebusy Access, in the Common Topics section at the front of this chapter.
Choosing a Different Language or Character Set
See Choosing a Different Language or Character Set, in the Common Topics section at the front of this chapter.
[Return to Commands List]
[Top of Chapter 10]
Purpose
Modify the preferences or password for a session.
Parameters
Table 10-34 lists this command's five parameters:
Description.
This command modifies the preferences for the current user. You may also modify the user's password through LDAP.Use of this parameter is only necessary when setting the subscribed list of calendars (icsSubscribed), or the subscribed list of groups (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 will convert the "^" back to a ":". If the value of the convertCalid is 0, the conversion will not be done
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
For example, the following URL adds a new preference, ceBgcolor, to the calendar and sets it to black:http://webcalendarserver/set_userprefs.wcap?id=b5q2o8ve2rk02nv9t6
&add_attrs=ceBgcolor=blackThis URL deletes the calendar preference ceBgcolor from the user's preferences.
http://webcalendarserver/set_userprefs.wcap?id=b5q2o8ve2rk02nv9t6
&del_attrs=ceBgcolorThis URL would modify the calendar preference ceBgcolor to have the value white:
http://webcalendarserver/set_useprefs.wcap?id=b5q2o8ve2rk02nv9t6
&set_attrs=ceBgcolor=whiteThis URL would allow the logged-in administrator to modify the calendar preference ceBgcolor to have the value black for user jdoe:
http://webcalendarserver/set_userprefs.wcap?id=b5q2o8ve2rk02nv9t6&u serid=jdoe&set_attrs=ceBgcolor=black
[Return to Commands List]
[Top of Chapter 10]
Purpose
Add events to a calendar.
Parameters
Table 10-35 lists this command's forty-three parameters:
Table 10-35 storeevents Parameters
This is for iCalendar interoperability only.
The strings are URLs.A boolean indicating whether or not to print out a brief version of the JavaScript output.
Applies only when output type (fmt-out) is JavaScript (text/js).
Event purpose description. A string of any length. If not passed, desc is set to the summary value.
Event duration. If an event has both a duration and a dtend, the duration is ignored.
Event exclusionary recurrence rules. A semicolon-separated list of recurrence-rule strings.
Each rule value must be enclosed in quotes. See Recurrence Handling.
A boolean indicating whether or not to fetch and return newly stored todos.
Semicolon-separated string of two float numbers representing the event's geographical location (latitude and longitude).
A boolean indicating whether or not the event lasts all day.
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)
16 = MOVE
32 = COUNTER (attendees only use this)Specifies the recurrences to store/modify.
Not required for creating events.
1 = THISINSTANCE
2 = THISANDFUTURE
3 = THISANDPRIOR
4 = THISANDALLThis has been deprecated in 5.0 and remains only for 2.x compatibility. The Group Scheduling Engine (GSE) module takes care of all email notifications.
A boolean indicating whether or not to notify attendees of a change to an event.
A boolean indicating whether or not to expand a recurring event.
Event recurrence rules. A semicolon-separated list of recurrence-rule strings.
Each rule value must be enclosed in quotes. See Recurrence Handling.
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 FINALEvent summary. A string of any length.
The timezone with which to interpret all dates passed in to, or returned by, the server.
The default is coordinated universal time (UTC or Z format).
Unique identifier of the event to be stored.
Description.
This command creates or modifies 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 Recurrence Handling.
When the notify value is 1, it sends an IMIP PUBLISH message to all attendees of the event.
Use the language parameter to specify the language of the event. See Choosing a Different Language or Character Set for a list of possible language codes.
The server does not support attachments. The attachments parameter exists to support iCalendar interoperability only, and is not functional.
Returns
If the fmt-out parameter is set to text/calendar or text/xml, the command returns only the error value in an HTML comment; for example:If the fmt-out parameter is set to, or defaults to, text/js, the command returns the JavaScript from a fetchcomponents_by_range.wcap command on all data.
Error Codes
This command cannot modify a linked event. The command will fail and return CANNOT_MODIFY_LINKED_EVENTS(31) in the errno array.The command fails, and returns the error STORE_FAILED_DOUBLE_BOOKED(40), when it tries to store an event in a time slot that is already scheduled (double booking).
Required Parameters
This command creates new events and modifies existing events. There is a different set of parameter requirements for both cases:
To create new events requires only two parameters:
To modify existing events requires three parameters:
- Every other parameter is optional. The server generates the uid.
- All other parameters are optional. If a parameter is not specified, the event will retain the previous value of the property.
Duration
Specify the duration in ISO8601 format. For example:
P1Y2M3DT1H30M10S represents a duration of 1 year, 2 months, 3 days, 1 hour, 30 minutes, 10 seconds
Notice that the T in the string separates the date information (year, month, day) from the time information (hour, minute, second).PT1H30M represents a duration of 1 hour, 30 minutes
Tip The ending date and time (dtend) overrides duration. If you specify both duration and dtend, the command ignores duration.
Example
For example, this URL would call storeevents.wcap and would result in storing an event in the calendar john,http://webcalendarserver/storeevents.wcap?id=3423423asdfasf
&calid=john&dtstart=20000101T103000&dtend=20000101T113000&uid=001
&summary=new%20year%20eventThe above example results in the following entry in an iCalendar database:
BEGIN:VEVENT
DTSTART:20000101T183000Z
DTEND:20000101T193000Z
UID:001
SUMMARY:new year event
END:VEVENT
Group Scheduling - Attendee Parameter
The two most important parameters for creating a group-scheduled event are attendee and method. The attendee parameter is a semicolon separated list of attendee entries. The attendee entry is explained in the section below.Each attendee entry may contain several parameters, such as invitation participation status, whether attendance is required or not, etc. All such parameters are encapsulated in a syntax very similar to the ATTENDEE property defined in the iCalendar Specification (RFC 2445). Reading the entire document is recommended in order to have the necessary background information to understand the WCAP attendee syntax. There are some differences, such as, WCAP uses a different delimiter, "^", to set apart these parameters. (WCAP uses the standard iCalendar semicolon delimiter for separating attendees.)
For example, where iCalendar would have the following:
PARSTAT=ACCEPTED;RSVP=TRUE:mailto:abc@xyz.com
WCAP would format it this way:
PARSTAT=ACCEPTED^RSVP^=TRUE^mailto:abc@xyz.com
Examples of WCAP Attendee Entries
If attendee A (attA) accepts an invitation, the WCAP command would contain:PARTSTAT=ACCEPTED^RSVP=TRUE^attA
If attendee B (attB) declines an invitation, the WCAP command would contain:
PARTSTAT=DECLINED^RSVP=TRUE^attB
If the email attendee jdoe@xyz.com has not yet decided to attend and is not required to respond, the WCAP command would contain:
PARTSTAT=NEEDS-ACTION^RSVP=FALSE:mailto:jdoe@xyz.com
Table 10-36 lists the parameters in the iCalendar ATTENDEE property understood by WCAP. Most of the parameters are optional. Not all are fully supported by Calendar Server, although the information will be stored. For group scheduling, only the PARTSTAT and RSVP parameters are relevant.
Group Scheduling - Method Parameter
The method parameter describes the type of message used: invitation, response, cancellation.In an invitation, three types of messages may occur:
An organizer invites attendees.
The following set of examples demonstrates the WCAP commands for an organizer "org" to invite attendees "attA" and "attB" to a meeting. Attendee "attA" accepts the invitation; attendee "attB" declines it. The uid for the meeting is "event_u1". The event will be created on both attendees' calendars. Each will respond to the event on their own calendar. The response will be sent back to the organizer's calendar by the iPlanet Calendar Server 5.0 Group Scheduling Engine.
- When an organizer creates a meeting, there are two ways to invite people:
Send a PUBLISH message, creating or modifying a meeting, and notify the attendees. The method parameter is set to "1".
Send a REQUEST message, creating or modifying a meeting, and requesting a response to the invitation from attendees. The method parameter is set to "2".
Attendees respond to invitation.
- Only the organizer of the meeting can send a PUBLISH or REQUEST message.
Organizer cancels the meeting.
- An attendee sends a REPLY message, either accepting or declining the invitation. (The method parameter is set to "4".)
storeevents.wcap?id=${SESSIONID of org}&calid=org&dtstart=
20010201T200000Z&dtend=20010201T210000Z&summary=invite_attA_attB
&method=2&attendees=PARTSTAT=ACCEPTED^RSVP=TRUE^org;PARTSTAT=
NEEDS-ACTION^RSVP=TRUE^attA;PARTSTAT=NEEDS-ACTION^RSVP=
TRUE^attB&fmt-out=text/xmlstoreevents.wcap?id=${SESSIONID ofattA}&calid=attA&uid=event_u1
&method=4&attendees=PARTSTAT=ACCEPTED^RSVP=TRUE^attA
&fmt-out=text/xmlstoreevents.wcap?id=${SESSIONID ofattB}&calid=attB&uid=event_u1
&method=4&attendees=PARTSTAT=DECLINED^RSVP=TRUE^attA
&comments=I_cannot_make_it_Sorry&fmt-out=text/xml
[Return to Commands List]
[Top of Chapter 10]
Purpose
Add one or more todos to a calendar.
Parameters
Table 10-37 lists this command's the forty-four parameters:
Table 10-37 storetodos Parameters
The time at which to send an alarm notification of the todo.
This parameter exists to support iCalendar interoperability only. The strings are URLs.
A boolean indicating whether or not to print out a brief version of the JavaScript output.
Applies only when output type (fmt-out) is JavaScript (text/js).
Completion date of the todo. A value of 0 means the todo is not yet completed.
Purpose of the todo. A string of any length.
Todo exclusionary recurrence rules. A semicolon-separated list of recurrence-rule strings.
Each rule value must be enclosed in quotes. See Recurrence Handling.
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.Semicolon-separated string of two float numbers representing the todo's geographical location (latitude and longitude).
ITIP method for group scheduling.
1 = PUBLISH
2 = REQUEST
4 = REPLY
8 = CANCEL
16 = MOVE
32 = COUNTERSpecifies the recurrences to store/modify.
1 = THISINSTANCE
2 = THISANDFUTURE
3 = THISANDPRIOR
4 = THISANDALLThis parameter has been deprecated in 5.0. It remains to provide 2.x 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.The email address contact for the todo. (Usually the organizer's email.)
A boolean indicating whether or not to expand a recurring todo.
Todo recurrence rules. A semicolon-
separated list of recurrence-rule strings.Each rule value must be enclosed in quotes. See Recurrence Handling.
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 FINALTodo summary. A string of any length.
A timezone. All dates are interpreted with reference to this timezone.
If not passed, all dates are interpreted as being in coordinated universal time (UTC or Z format).
Unique identifier of the todo to be stored.
Description.
Use this command to create and modifies 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 Recurrence Handling.
When the notify value is 1, it sends an IMIP PUBLISH message to the email attendees of the todo.
The server does not support attachments. The attachments parameter exists to support iCalendar interoperability only, and is not functional.
method Parameter
For group scheduling, specify one of the following ITIP methods:
1
PUBLISH
Used only by the organizer.
2
REQUEST
Used only by the organizer.
4
REPLY
Used only by attendees.
8
CANCEL
Used only by the organizer.
16
MOVE
N/A
32
COUNTER
Used only by attendees.
Returns
If the fmt-out parameter is set to text/calendar or text/xml, the command returns only the error value in an HTML comment; for example:If the fmt-out parameter is set to, or defaults to, text/js, the command returns the JavaScript from a fetchcomponents_by_range.wcap command on all data.
Error Codes
This command cannot modify a linked todo. The command will fail and return an error of CANNOT_MODIFY_LINKED_TODOS(32) in errno.The command fails, and returns the error STORE_FAILED_DOUBLE_BOOKED(40), when it tries to store a todo in a time slot that is already scheduled (double booking).
Required Parameters
This command creates new todos and modifies existing todos. There is a different set of parameter requirements for both cases:
To create new todos requires only two parameters:
To modify existing todos requires three parameters:
- Every other parameter is optional. The server generates the uid.
- All other parameters are optional. If a parameter is not specified, the todo will retain the previous value of the property.
Duration
The due date and time (due) overrides duration. If you specify both duration and due, the command ignores duration.Specify the duration in the ISO8601 format. For example:
P1Y2M3DT1H30M10S represents a duration of 1 year, 2 months, 3 days, 1 hour, 30 minutes, 10 seconds
Notice that the T in the string separates the date information (year, month, day) from the time information (hour, minute, second).PT1H30M represents a duration of 1 hour, 30 minutes
[Return to Commands List]
[Top of Chapter 10]
Purpose
Uploads a file to the server. Used in conjunction with write_file for file import.
Parameters
Table 10-38 lists this command's one parameter:
Table 10-38 upload_file Parameters
Description.
This command used in conjunction with write_file, handles file importing for iPlanet Calendar Server 2.0 compatibility. It only works through a POST command since a file is attached with it.File import is handled in the following way through the UI:
Upload the user's files from the user's computer to the server using the upload_file command. The upload_file command must be a POST.
The reason for this separation is that the UI cannot combine both parameters' values and file attachment through the JavaScript UI. Also, this separation allows for uploading multiple files to the server before actually writing them to the database.Take the uploaded file(s) and write them to the database using the write_file command.
upload_file Example
The data sent to upload_file should look exactly like import.wcap data. The only files that can be supported are iCalendar and XML files. Although the user can upload any file, only iCalendar and XML files can be successfully added to the database.The returned JavaScript from upload.wcap looks like the following:
Completed sending of import HTTP/1.1 200
Date: Tue, 05 Oct 2000 23:37:51 GMT
Content-type: text/html; charset=iso-8859-1
Content-length: 301
Last-modified: Tue, 05 Oct 2000 23:37:51 GMT
Pragma: no-cache
Expires: 0
Cache-Control: no-cache
Connection: Keep-Alive<html><head><script>
function color(s) { if (s) document.bgColor=s
}
var filename='s://ns//server//msg//calendar//core//parser//test//ical1. ics'var uniquefilename='cf8bfa37b347000001000000ef000000'
var size=640
var errno=0
var errstr=''
</script></head>
<body onLoad=parent.uploadCB()>
</body></html>
write_file Example
Notice the bold line containing the uniquefilename JavaScript variable in the previous example. This variable should be used as the input to the uniquefilename parameter in the write_file command.After the UI has uploaded the appropriate files using upload_file, the UI should call write_file to actually write the file to the database.
For example, use this URL to write the previous example's upload call to the calendar jdoe. Notice that the uniquefilename parameter matches the uniquefilename JavaScript variable returned in upload_file.wcap.
http://webcalendarserver/write_file.wcap?id=abc&calid=jdoe&dtstart= 0&dtend=0&content-in=text/calendar&uniquefilename=cf8bfa37b34700000 1000000ef000000
To write two files to the server, put semicolons between the unique filenames. The files must be of the same content-type.
http://webcalendarserver/write_file.wcap?id=abc&calid=jdoe&dtstart= 0&dtend=0&content-in=text/calendar&uniquefilename=cf8bfa37b34700000 1000000ef000000;dg9cgb48c458000001000000ab000000
[Return to Commands List]
[Top of Chapter 10]
Purpose
To get the current WCAP version.
Parameters
Table 10-39 lists this command's one parameter:
Table 10-39 version Parameters
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 of iCalendar, XML, and JavaScript. In iCal and XML, the variable X-NSCP-WCAPVERSION contains the WCAP version number. In JavaScript, the variable wcapversion returns the version number.
Example
The following examples are for each of output data types.
JavaScript: (URL:/version.wcap)
<html><head><script>
function color(s) { if (s) document.bgColor=s
}
var id='0'
var userid=''
var calid=''
var errno=new Array()
var wcapversion=1.0.0
parent.ceCB(window.name)
</script></head></html>iCalendar: (URL: /version.wcap?fmt-out=text/calendar)
BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//iPlanet/Calendar Hosting Server//EN
X-NSCP-WCAPVERSION:WCAP
END:VCALENDARXML: (URL: /version.wcap?fmt-out=text/xml)
<?xml version="1.0" encoding="UTF-8">
<iCalendar>
<iCal>
<X-NSCP-WCAPVERSION>1.0.0</X-NSCP-WCAPVERSION>
</iCal>
</iCalendar>
[Return to Commands List]
[Top of Chapter 10]
Purpose
Writes a file to the database.
Parameters
Table 10-40 lists this command's six parameters:
Description.
The write_file command, used in conjunction with the upload_file command, handles importing files. The parameters correspond exactly to those of the import command. See upload_file for an example and a detailed description of the file import process.
[Return to Commands List]
[Top of Chapter 10]
Previous Contents Index Next
Copyright © 2000 Sun Microsystems, Inc. Some preexisting portions Copyright © 2000 Netscape Communications Corp. All rights reserved.
Last Updated February 20, 2001