This chapter contains topics of common interest that span multiple commands.
The topics are listed in alphabetical order. The table that follows lists and contains links to these topics:
Access Control Information (ACI) determines access control for calendars. Access Control Entries (ACE strings) are individual strings of control characters that are stored in LDAP as one of a calendar's properties. There can be multiple ACE strings that apply to a single calendar. Collectively, all the ACE strings that apply to a calendar are called an Access Control List (ACL). When someone has requested access to a calendar, the system searches the calendar's ACL list to check for access rights. The system uses the first ACE encountered that either grants of denies access. 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 WCAP Command: 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 can 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.
The Command: get_userprefs command fails if any node does not have “allow anyone” access rights for reading and searching. For example, the following LDAP modify record for an ACL entry gives the correct privileges to make the command work correctly.
dn: o=usergroup changetype: modify add: aci aci: (targetattr="icscalendar ||cn||givenName||sn||uid||mail") (targetfilter=(objectClass=icscalendaruser)) (version 3.0; acl "Allow calendar administrators to proxy-product=ics, class=admin,num=2,version=1" allow (proxy) groupdn="ldap:///cn=Calendar Administrators,ou=Groups,o=usergroup";) |
Here is an example of an ACE string:
jdoe^c^wd^g
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. The four types of classes for users are the following:
The second element of an ACE indicates what the ACE applies to.
The ACE can be applied to:
The entire calendar.
Applies to both components and calendar properties. To indicate the entire calendar, pass in the value a.
The components only.
Applies to calendar components, that is, events and todos. To indicate just the components, pass in the value c.
The calendar properties only.
Applies to calendar properties, for example, display name, or ownerlist. To indicate calendar properties only, pass in the value p.
The third element of an ACE indicates what access values the ACE applies to.
Multiple values can be specified at the same time. To do this, the caller must pass in a string to indicate which bits to check.
The table that follows lists the Access Control characters used in ACE strings. The third element contains a string with one or more of the Access Control characters.
Access Control Characters |
Description |
---|---|
d |
Grants the user delete access. |
f |
Grants the user free-busy access. |
r |
Grants the user read access. |
s |
Grants the user schedule access. This means that requests can be made, replies accepted, and other ITIP scheduling interactions honored. |
w |
Grants the user write access. This includes adding new items, deleting items, and modifying existing items. |
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 fourth element of an ACE indicates whether to grant or deny access.
The ACE can either grant or deny access.
Here is a quick summary of the order of an ACE:
who ^ flags ^ how ^ grant
Where:
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 Access Control Information.
grant = One of the characters g, or d
Here are some examples of circumstances and how the ACE would be set in the acl parameter for the jdoe 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:
set_calprops.wcap?id=${SESSIONID} &calid=jdoe&acl=john^a^r^g;susan^c^wd^g |
To grant all users in a domain schedule, free-busy, and read access to a calendar (@domainname a sfr g), to grant owners write and delete access to components only (@@o c wd g), to grant owners self-administration rights, and schedule, free-busy, 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=@domainname^a^sfr^g; @@o^c^wd^g; @@o^a^zsfr^g; susan^a^zfsdwr^d; @^c^r^g |
An administrator can override the access control of all WCAP commands if he is logged in as administrator and the server configuration preference service.admin.calmaster.overrides.accesscontrol is set to “yes” in the ics.conf file.
User Interface Operation |
ACL Required |
Example |
Description |
---|---|---|---|
Delete Events and Todos |
Modify Events and Todos, and Delete Components or, Delete Calendar |
c^d^g or, a^d^g |
To delete events or todos, you need modify permission, and either delete components or delete calendar permission. |
Free-busy |
Free-busy Components or Free-busy Calendar |
c^f^g a^f^g |
To view a free-busy representation of a calendar (the events and todos), you need free-busy components or free-busy calendar permission. |
Modify Events and Todos |
Read Events and Todos, and Write Components or, Write Calendar |
c^w^g a^w^g |
To modify components of a calendar (events and todos), you need read permission, and either write components or write calendar permission. |
Read Events on a Calendar |
Read Calendar |
a^r^g |
To read components, you must have read calendar permission. Note that read components permission (c^r^g) does not work. |
Schedule (Invite) |
Schedule Calendar |
a^s^g |
To invite someone, you need schedule calendar permission. |
Subscribe |
Read Properties |
p^r^g |
To subscribe to a calendar, you must have read properties permission. |
The following WCAP commands accept the appid parameter:
deletecomponents_by_range– (ENS notifications not yet implemented)
deleteevents_by_id
deleteevents_by_range– (ENS notifications not yet implemented)
deletetodos_by_id
deletetodos_by_range– (ENS notifications not yet implemented)
import– (ENS notifications not yet implemented)
storeevents
storetodos
This WCAP command parameter is used to set the value of an X-Token that ENS returns with notifications.
Applications passing this parameter in with the appropriate WCAP command can detect which ENS notifications they originated by checking the value of the X-Token X-NSCP-COMPONENT-SOURCE. Note that this X-Token is not returned by WCAP commands, only ENS notifications.
This parameter is a runtime parameter. That is, nothing is stored in the database.
If appid is present, the Event Notification Service (ENS) returns the value of appid as the value of the X-Token X-NSCP-COMPONENT-SOURCE. If the appid parameter is missing, ENS assigns the standard value to the X-Token (WCAP).
Application ID's (appid parameter) shows the effect of the presence of the appid parameter on the value of the X-Token X-NSCP-COMPONENT-SOURCE. For more information about ENS, see theSun Java System Communications Services 6 2005Q4 Event Notification Service Guide.
Table 6–2 Presence of appid and Value of X-Token X-NSCP-COMPONENT-SOURCE
appid Present? |
Value of X-Token X-NSCP-COMPONENT-SOURCE |
---|---|
no |
WCAP |
yes |
appid |
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 theSun Java System Calendar Server 6 2005Q4 Administration 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 might 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 RFC's referenced in Formatting Standards.
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 charsetdoes not change this.
Here is a list of the valid lang values:
de |
German |
en |
English (the default) |
es |
Spanish |
fr |
French |
it |
Italian |
ja |
Japanese |
ko |
Korean |
ru |
Russian |
sv |
Swedish |
zh_CN |
Chinese or Simplified Chinese |
zh_TW |
Taiwanese |
This does not mean that all of these languages are currently supported by the server. Please check with your Sun Java Enterprise System representative to find out which languages are currently supported by the server.
For example, enter the following if you want to insert an event into the calendar:
storeevents.wcap?id=${SESSIONID}&calid=id&summary=summary &location=location &desc=desc &charset=euc-jp |
As another example, suppose that the location value is two Japanese characters whose unicode values are \\u3068\\u30889. In this case, the location value is %A4%C8%A4%E9. Note that all non-ASCII characters should be URL-encoded according to the value of the charset parameter, which in this case is euc-jp. The following command is an example of same data sent in Shift_JIS:
storeevents.wcap?id=${SESSIONID}&calid=id &summary=summary &location=location &desc=desc &charset=Shift_JIS |
In the above example, the location value is %82%C6%82%E7.
WCAP uses the value of the charset parameter to convert the data from the URL-encoded value into UTF-8 before storing it into the database. It is stored internally in UTF-8.
The charset parameter in this command have the same role as in the storeevents.wcap because the set_calprops command takes non-ASCII data. The charset parameter in this command does not have any other special meaning.
If charset is not specified, WCAP expects the data to be URL-encoded in UTF-8.
In the example, the encoded list of parameters for cal includes some encoded characters. Here are some examples of characters and their encoding:
= |
%3D |
& |
%26 |
’”’ |
%22 |
The %xx string is the hexadecimal value of the character. For example, the & character is 26 in hexadecimal.
Each call to a WCAP command that returns component data (fetch, delete, and store commands) also returns an error number.
The error string, errno, returns the non-zero error number for the transaction. The value is 0 if the command succeeded.
Error Codes lists error codes returned by WCAP commands.
Table 6–3 Error Names, Values, and Meanings
The component_type parameter directs WCAP to return either only events, only todos, or both events and todos. The keyword arguments, respectively, are: event, todo, or all. The parameter is not required. Its default is all, returning both events and todos. If an unrecognized value is passed in, the default value is used.
This parameter is found in all the fetchcomponents_by_* commands.
In addition, deleted components can be retrieved from the deletelog.db in the calendar store using the fetch_deletedcomponents command.
All fetch commands, except fetchcomponents_by_attendee_error, have the ability to fetch by component state, using the parameter compstate. The default (compstate=ALL) is to fetch all component states, Use this parameter to limit the type of components fetched.
If the parameter is not specified, the default value is ALL.
The following table lists component state values. A component state pertains either to the attendee or the organizer.
Table 6–4 Component State Values
compstate Value |
Organizer or Attendee |
Comment |
---|---|---|
REPLY-DECLINED |
Attendee |
The event or todo is an invitation from another user and the current user has declined the invitation. |
REPLY-ACCEPTED |
Attendee |
The event or todo is an invitation from another user and the current user has accepted the invitation. |
REQUEST-COMPLETED |
Organizer |
The event or todo is an invitation from the current user to other invitees, and all invitees have replied. |
REQUEST_NEEDS-ACTION |
Attendee |
The event or todo is an invitation from another user and the current user has not replied to it yet. |
REQUEST-NEEDSNOACTION |
Attendee |
The event or todo is an invitation from another user and the current user is not required to reply. |
REQUEST-PENDING |
Organizer |
The event or todo is an invitation from the current user to other invitees, and is currently in the process of sending out invitations. |
REQUEST-WAITFORREPLY |
Organizer |
The event or todo is an invitation from the current user to other invitees, and is currently awaiting replies from all invitees. |
ALL |
N/A |
(Default) All event and todo component states. |
If you have deleted component data and need to reconstruct it, you can use the Command: fetch_deletedcomponents command, which causes the system to process the Delete Log Database (ics50deletelog.db in the csdb directory). However, it is not possible to recreate the entire component data since not all of it is logged.
When non-recurring components are deleted, the server removes it from the component database and writes it to the Delete Log database.
When individual instances of a recurring event or task are deleted, the server writes each deleted instance to the Delete Log database. When all instances of the recurring event or todo are deleted, the server deletes the master entry for the component from the component database and writes it to the Delete Log database. A master entry in the Delete Log database contains the following recurrence parameters: rrules, exrules, and exdates.
In a single fetch_deletedcomponents command, either individual instances can be retrieved, or the master entry with its exceptions, but not both.
For more information on the Delete Log database, see the .
The compressed parameter allows you to retrieve a reduced amount of recurrence data. The parameter defaults (compressed=0) to the compressed format, which returns data without the rrules, rdates, exrules, and exdates properties as the default. To receive all the recurrence data back from the following commands, use compressed=1.
This parameter is used by all the fetchcomponents_by_* commands, the fetchevents_by_id and fetchtodos_by_id commands, and the store* commands.
compressed has been deprecated for the current release, and is included for backwards compatibility only. It can be removed from the future releases.
Find the exact format and definition for all times, strings, parameters, and so forth, by referring to RFC 2445, RFC 2446, and RFC 2447. Unless otherwise noted, all WCAP commands follow these specifications.
The RFC’s can be found at the IETF web site:
http://www.ietf.org/rfc/rfc2445.txt
http://www.ietf.org/rfc/rfc2446.txt
http://www.ietf.org/rfc/rfc2447.txt
As a reminder, the maximum parameter value length is 1024 characters.
For more information on time zones, see Time Zoneswhich follows later in this section.
Calendars can be displayed in free-busy format instead of showing details of scheduled events and todos. Free-busy calendars are used to facilitate scheduling of events or todos in the event and todo creation dialogs in the user interface. They can also be used by calendar owners to prevent other users from viewing the details of their calendars.
This can be accomplished in two separate ways that are not mutually exclusive:
Free-busy access rights can be granted to users in the calendar’s properties.
Free-busy access can be assigned to the calendar as a whole using the calendar property fbinclude.
If fbinclude is set to 0, it overrides any access rights granted to users. That is, if fbinclude=0, then the calendar does not be included in free-busy calculations, no matter what the acl parameter specifies.
If fbinclude=1, which allows the use of the calendar for free-busy calculations, then the acl access rights are used to determine if the user can see the details of the calendar, the free-busy representation only, or neither.
In free-busy calendars, instead of event or todo details, 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:
10:00-11:00 |
first meeting |
12:00-1:00 |
lunch |
3:00-4:00 |
second meeting |
If user john has only free-busy access to the calendar jdoe, user john gets only a free-busy version of the calendar. The free-busy time for jdoe (from 9:00 to 6:00) would appear as the following:
9:00-10:00 |
Free |
10:00-11:00 |
Busy |
11:00-12:00 |
Free |
12:00-1:00 |
Busy |
1:00-3:00 |
Free |
3:00-4:00 |
Busy |
4:00-6:00 |
Free |
Notice that john does not know the details of why the user is busy, but knows when the user is busy.
The get_freebusy command allows selection of which calendars to use in the calculation in two ways: using the calid parameter, or the mail parameter. One of the parameters is required, but not both. If both are present, the calid value is used.
When an email address is passed in using the mail parameter, all calendars, for which this user is the primary owner and which have fbinclude=1 in their calendar properties settings, are included in the free-busy calculation.
When the calid parameter is used, specific calendars can be named rather than using all of owners calendars. Note that the calid parameter can take an email address (by specifying mailto:ref822address, where rfc822address is any valid email address that maps to a single calendar in the local LDAP directory).
The command returns the busy data only. The rest of the time slots are presumed to be free.
When a free-busy calendar rendition is requested using the get_freebusy command, private events and todos are included or excluded depending on the value of the transparent parameter stored with the events and todos when they were created or modified.
Using either storeevents or storetodos, to keep the event private, set the event or todo parameter to transparent=1. Set it to transparent=0 to allow the event or todo to be included in the free-busy calculation.
As opposed to regular events, all-day events (isAllDay=1) default to private and opaque (transparent=1). For the all-day event to be included in the free-busy calculation, set the parameter to transparent=0.
When you are using the storeevents command for scheduling a group event, there are two parameters that are required:
Each attendee entry can contain several parameters, such as invitation participation status, whether attendance is required or not, and so forth. 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. Some differences exist, such as, WCAP uses a different delimiter, “^”, to set apart these parameters. (However, 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 |
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 |
An attendee in an existing meeting can be marked for deletion by assigning X-NSCP-WCAP-ATTENDEE-DELETE to PARTSTAT. For example, if you want to delete attendee jdoe, the attendee parameter of the storeevents command would contain the following:
PARTSTAT=X-NSCP-WCAP-ATTENDEE-DELETE^jdoe |
The following table 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 is stored. For group scheduling, only the PARTSTAT and RSVP parameters are relevant.
Parameters |
Purpose |
---|---|
PARTSTAT |
The only required parameter. This shows the attendees participation status. |
CUTYPE |
Calendar user type. |
MEMBER |
List of groups the attendee is part of. WCAP has no understanding of these groups. |
ROLE |
Role of the attendee in this meeting. |
RSVP |
Attendee response required or not. |
DELEGATED-TO |
To whom the attendee delegates attendance. |
DELEGATED-FROM |
Attendee is a delegate for this person. |
SENT-BY |
The calendar user acting on behalf of the specified user. |
CN |
Display name of attendee. |
DIR |
Directory entry reference. |
LANG |
Language of the entry. |
In addition, WCAP allows the optional use of an additional parameter, SENT-STATUS, which is specific to Calendar Server and is not part of the iCalendar specification. Possible values for SENT-STATUS are: NOT-SENT, and SENT-SUCCEEDED. The default is NOT-SENT. The Group Scheduling Engine inside Calendar Server does not process an attendee with a SENT-STATUS value of SENT-SUCCEEDED.
The method parameter describes the type of message used: invitation, response, cancellation.
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. |
In addition to these ITIP methods, there is another method used by Calendar Server internally (a non-ITIP method):
256 |
UPDATE |
Used by attendee to update only the attendee’s copy of a group scheduled event. Does not affect anyone else’s calendar data. |
Even though the method parameter has a default value, it is a required parameter if you are trying to do anything other than PUBLISH. Leaving the parameter off the storeevents or storetodos commands causes the default (PUBLISH) to be the presumed action.
In an invitation, three types of messages can occur:
An organizer invites attendees.
When an organizer creates a meeting, there are two ways to invite people:
Send a PUBLISH message, creating or modifying a meeting. The method parameter is set to “1”. Note that everything except the attendee information is sent. (Attendees can see the event but not the other attendees.)
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”.
Only the organizer of the meeting can send a PUBLISH or REQUEST message.
Attendees respond to invitation.
An attendee sends a REPLY message, either accepting or declining the invitation. (The method parameter is set to “4”.)
Organizer cancels the meeting.
When an organizer cancels a meeting, attendees are notified by sending a CANCEL using one of the deleteevents commands. The method parameter is set to “8”.
The preferred way to handle a cancellation is to use one of the deleteevents commands, rather than storeevents.
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 the invitation. The uid for the meeting is “event_u1”. The event is created on both attendees’ calendars. Each responds to the event on their own calendar. The response is sent back to the organizer’s calendar by the Calendar Server Group Scheduling Engine.
The following is an example of an invitation:
storeevents.wcap?id=${SESSIONID of org}&calid=org &dtstart=20020201T200200Z &dtend=20020201T210000Z 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/xml |
The following is an example of the acceptance:
storeevents.wcap?id=${SESSIONID ofattA}&calid=attA &uid=event_u1 &method=4 &attendees=PARTSTAT=ACCEPTED^RSVP=TRUE^attA &fmt-out=text/xml |
The following is an example of a declined meeting:
storeevents.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 |
WCAP commands can request the output format in two content types: text/calendar and text/xml.
To change the output format, set fmt-out to the target value. If fmt-out is not specified, the default format of text/calendar is returned.
Recurrence handling occurs as follows:
A recurring series of events or todos has a master entry plus entries for exceptions.
Changing the rrules of a single instance returns an error. When rrules are modified for a recurring series, the whole series is deleted and recreated.
Changing dtstart of a recurring series entry causes the whole series to be recreated with the new dtstart, thereby losing all exceptions.
Inserting a rid that was not part of the original rule is not supported.
Multiple rrules for any component are not supported.
The following parameters are used with the storeevents and storetodos commands to create and modify components:
rrules - Semicolon-separated list of quoted recurrence-rule strings for recurring events.
rdates– Semicolon-separated list of ISO 8601 date strings listing recurrence dates.
exrules– Semicolon-separated list of quoted recurrence-rule strings for dates to exclude.
exdates– Semicolon-separated list of ISO 8601 date strings listing dates to exclude.
rid– ISO 8601 Date-Time String giving the recurrence ID of an event.
mod– Modifier telling which instances of the event to store.
rchange– A boolean specifying whether or not to replace the rrules parameter. If rchange=1, the store commands map all mod settings (2-4) are mapped to 4. This means that you can not change an rrules for only some of the components in a recurring series. To change the rrules parameter, all components in the recurring series must be changed.
excludedtstart– An integer specifying whether or not to include the dtstart date in a recurring series if the date does not follow the rrule.
The rrules, rdates, exrules, and exdates parameters always function in replace mode. That is, no matter what the replace parameter value is set to, the values passed in for the recurrence parameters always replace the old parameter values, rather being appended to them.
This means you can not have multiple rrules for the same component.
For more information on the replace parameter, see Updating Parameter Values
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. Many parameters are possible for recurrence rules. (See RFC 2445 for a complete description of the syntax.)
Three parameters used by Calendar Server for specifying recurrence are freq, count and until:
The freq parameter in a rule defines the periodicity of the event, and has the following possible values:
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 repeats. 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.
The until parameter in a rule specifies using an end date as opposed to using the count to limit the number of instances created. Instances are created up to the end date or until 60 instances are created, whichever occurs first.
In the event that neither the count nor the until parameter are specified, the default is 60 instances.
Using the storeevents.wcap command to create an event with only exdates or rdates values, without specifying an rrules results in no events being created. The same behavior can be observed with the storetodos.wcap command.
The following example shows an rrules parameter that specifies the event is to occur daily for 10 instances (COUNT=10;FREQ=DAILY):
rrules="count%3D10%3Bfreq%3Ddaily" |
The following example URL passes the example rrules parameter:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &rrules="count%3D10%3Bfreq%3Ddaily" &dtend=20020301T112233 &summary=uuuu |
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/02 11:22:33 and 5/31/02 11:22:33):
rdates=20020331T112233;20020531T112233 |
The following example URL passes the rdates parameter:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &rdates=20020331T112233;20020531T112233 &dtend=20020301T112233 &summary=uuuu |
If you want to the change the recurrence rule after a certain date, you must set rchange to 1.
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" |
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 (COUNT=10;FREQ=DAILY and FREQ=WEEEKLY;COUNT=4).
The following example URL passes the example exrules parameter:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &exrules="count%3D10%3Bfreq%3Ddaily"; "freq%3Dweekly%3Bcount%3D4" &rrules="count%3D100%3Bfreq%3Ddaily" &dtend=20020301T112233 &summary=uuuu |
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/02 11:22:33 and 5/31/02 11:22:33):
exdates=20020331T112233;20020531T112233 |
The following example URL passes the example exdates parameter:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &exdates=20020331T112233;20020531T112233 &rrules="count%3D200%3Bfreq%3Ddaily" &dtend=20020301T112233 &summary=uuuu |
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.
For example:
http://webcalendarserver/storecomponents.wcap ?id=b5q2o8ve2rk02nv9t6 &calid=jdoe &uid=333 &dtstart=20020301T112233Z &rid=20020331T112233 &dtend=20020301T112233 &summary=uuuu&mod=1 |
For a non-recurring event or todo, the rid is 0.
When modifying recurring components, this parameter specifies whether to apply the changes to one or more instances of the event or todo. The following settings are mapped, but currently only the values 1 and 4 are honored. If 2 or 3 are specified, in certain cases they are mapped to 4.
Value |
Option |
1 |
This instance only. |
2 |
This and all future instances. |
3 |
This and all prior instances. |
4 |
This and all instances. |
When creating or modifying a recurring component, if changing rrules is allowed (rchange is set to 1), the system assumes a setting of 4, which causes the entire series of events or todos to be deleted and rewritten. If 2 or 3 are specified when trying to change rules or start times, they are mapped to 4. If 2 or 3 is specified for changing a summary or description, the setting are honored, but no exceptions are created for errors.
The rchange parameter specifies whether recurrences are expanded in Command: storeevents, and Command: storetodos. Normally, events and todos calendar components are not expanded, so the parameter defaults to 0, which implies the series is recreated.
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, 2002. Use the following URL to change the summary of each event after Feb. 1, 2002 to changed-event.
The following 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=20020201T112233Z &rrules="byday%3Dfr%3Bfreq%3Dweekly" &summary=changed-event &rid=20020201T112233Z &mod=2 &rchange=0 |
Note that when you are modifying a recurrence series, do not pass in rrules unless you are trying to recreate the series with a new rule.
When creating a recurring series according to the rrule, this integer specifies whether to include the dtstart date if the date does not follow the rrules. For example, if on a Monday, you were creating a recurring series of meetings that were to be held every Wednesday, the dtstart would be Monday, but that does not fit the set of dates (all Wednesdays) generated using the rrules. Therefore the server must decide whether to include the dtstart date or not based on the value of excludedtstart.
A value of 0 indicates the dtstart date is included in the recurring series and a value of 1 indicates the dtstart date is not included in the recurring series. The default is 0.
When you delete a recurring component, specify the recurrence ID and whether to delete the recurrences as well as the original event or todo.
Use the mod parameter to select which occurrences to delete:
Value |
Option |
1 |
Delete or modify this instance only. |
2 |
Delete or modify this and all future recurrences. |
3 |
Delete or modify this and all prior recurrences. |
4 |
Delete or modify all instances. |
A setting of 2 deletes only as many instances as exist on the server.
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, 2002 11:22:33 AM GMT.
http://webcalendarserver/deleteevents_by_id.wcap ?id=23423423434abc &calid=jdoe &uid=001 &rid=20020301T112233Z &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, 2002 11:22:33 AM GMT and all future instances of this event (uid 001).
http://webcalendarserver/deleteevents_by_id.wcap ?id=23423423434abc &calid=jdoe &uid=001 &rid=20020301T112233Z &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, 200211:22:33 AM GMT and all prior instances of this event (uid 001).
http://webcalendarserver/deleteevents_by_id.wcap ?id=23423423434abc &calid=jdoe &uid=001 &rid=20020301T112233Z &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://webcalendarserver/deleteevents_by_id.wcap ?id=23423423434abc &calid=jdoe &uid=001 &rid=20020301T112233Z &mod=4 |
The following parameters are found in the fetchcomponents_by_* commands, and the fetchevents_by_id and fetchtodos_by_id commands:
compressed– A boolean specifying whether to return all of the recurring entry’s data, or to exclude the following parameters:rrules, rdates, exrules, exdates.
This parameter is deprecated in the current release, and is included only for backwards compatibility. It might be removed from future releases.
recurring– A boolean parameter specifying whether or not to return all components in compressed form (master entry and exceptions). This parameter is also present in the fetch_deletedcomponents command.
Fetch commands that support the fetchorder parameter allow you to specify the order in which the events and todos are returned.
Three sorting choices can be specified:
Ascending order
Descending order
Special (or legacy) sorting order–This sorting choice returns things in mostly ascending order.
The sorting logic is as follows:
For events, put in order according to dtstart. If two events have the same dtstart date, then compare dtend for the two events. Return the one that fits the desired sort order. If they are the same, compare uid and return the components from the least value to the highest.
For todos, all completed tasks are returned after all sorted not-due tasks. For two not-due tasks, compare dtdue. Return in the desired sort order. If they are the same, compare uid and return components from the least value to the highest. For descending sorts, some overdue tasks could be truncated because of the maxResults limit.
For recurring components sorted in ascending order, the master record is returned first and then the exceptions. Depending on the maxResults limit, some exceptions could be truncated. In this case, error 81 is given. (See Error Handling.)
For recurring components sorted in descending order, exceptions are returned first and then the master record. Depending on the maxResults limit, it is possible for a master record to be truncated. In this case, error 81 is given. (See Error Handling.)
To support a universal standard, Calendar Server uses the date and time strings in Greenwich Mean Time (GMT) or Coordinated Universal Time (UTC), called Zulu time. The server stores and returns all date and time strings from the database in Zulu time. WCAP converts the Zulu times to the appropriate time zone settings depending upon the value of the tzid and tzidout parameters.
The tzid parameter is used for date and time strings passed in with the dtstart, dtend, and rid parameters, which are not already in Zulu time. WCAP uses the value of the tzid parameter to calculate the Zulu time. If the tzid parameter is not passed in, the server’s default time zone is used to calculate Zulu time.
For commands that return events and todos, the data is returned in Zulu time, unless the tzidout parameter is passed in. In this case the Zulu time is translated into the time zone specified in the tzidout parameter.
For example, if the fetch_components_by range command specifies a date range of 20020506T100000 to 20020507T100000, with a tzid=America/Los_Angeles, WCAP translates that to Zulu time for database lookup. If the tzidout parameter was also passed in (for our example, tzidout=America/New_York), then the resulting output would be translated to that time zone and returned. If the tzidout parameter is missing, the component data is returned in Zulu time.
The tzidout parameter can be used with the storeevents and storetodos command when the fetch parameter is set to 1 (fetch=1).
The time zones information is kept in a plain text file (timezones.ics) in VTIMEZONE format.
The server never uses the system time zone information to calculate the current date and time. It uses the time elapsed in seconds since the Epoch (00:00:00 UTC, January 1, 1970) to calculate current date and time. Then depending on the user’s time zone settings, the date is displayed to reflect the correct time zone.
The following commands use both the tzid and tzidout parameters:
In addition, the following commands use the tzid parameter (but not the tzidout):
Two commands, storeevents and storetodos, allow you to update (replace, append, or delete) parameter values. When updating current values for a component, you can either replace the current values with the new ones being passed in, append the new values to the current values, or pass in empty parameter values to delete the parameter.
The ability to append parameter values applies only to parameters that can accommodate multiple values (that is, parameters that use semicolon-separated values, such as the attendees parameter). The default is to append (replace=0) the new values to the current values. If you want to replace the current values with the new values being passed in, include the replace parameter in the command, with the value set to 1 (replace=1). If you do not include the replace parameter in the command, the system assumes the default setting (replace=0) and appends the new values to the old values.
With one exception, the recurrence and alarm parameters can only be replaced, not appended. Specifically, the parameters are: rrules, rdates, exrules, exdates, alarmAudio, alarmDescription,alarmFlashing, alarmPopup, and alarmStart. The alarmEmails parameter is the only one that allows multiple values, and thus is the only exception. Therefore you can append an alarm email recipient to the list by specifying replace=0.
In all cases, a parameter can be deleted by passing in an empty parameter and setting replace to 1. For example, to delete the alarmPopup parameter, pass in the following: alarmPopup=&replace=1. Using replace=1 can also be used to delete string fields. For example, to delete the description, you would use desc=&replace=1.
Token Name |
Type |
WCAP Command |
---|---|---|
X-NSCP-ATTENDEE-GSE-STATUS |
integer |
all fetch commands |
X-NSCP-CALPROPS-ACCESS-CONTROL-ENTRY |
string |
all fetch commands |
X-NSCP-CALPROPS-CALMASTER |
string |
all fetch commands |
X-NSCP-CALPROPS-CATEGORIES |
string |
all fetch commands |
X-NSCP-CALPROPS-CHARSET |
string |
all fetch commands |
X-NSCP-CALPROPS-CHILDREN |
string |
all fetch commands |
X-NSCP-CALPROPS-CREATED |
string |
all fetch commands |
X-NSCP-CALPROPS-DESCRIPTION |
string |
all fetch commands |
X-NSCP-CALPROPS-LANGUAGE |
string |
all fetch commands |
X-NSCP_CALPROPS-LAST-MODIFIED |
string |
all fetch commands |
X-NSCP-CALPROPS-NAME |
string |
all fetch commands |
X-NSCP-CALPROPS-OWNERS |
string |
all fetch commands |
X-NSCP-CALPROPS-PARENT-CALID |
string |
all fetch commands |
X-NSCP-CALPROPS-PRIMARY-OWNER |
string |
all fetch commands |
X-NSCP-CALPROPS-READ |
integer |
all fetch commands |
X-NSCP-CALPROPS-RELATIVE-CALID |
string |
get_freebusy, all fetch commands |
X-NSCP-CALPROPS-RESOURCE |
string |
all fetch commands |
X-NSCP-CALPROPS-TZID |
string |
all fetch commands |
X-NSCP-CALPROPS-WRITE |
integer |
all fetch commands |
X-NSCP-CHARSET |
string |
all fetch commands |
X-NSCP-DTEND-TZID |
string |
all fetch commands |
X-NSCP-DTSTART-TZID |
string |
all fetch commands |
X-NSCP-DUE-TZID |
string |
all fetch commands |
X-NSCP-GSE-COMMENT |
string |
all fetch commands |
X-NSCP-GSE-COMPONENT-STATE |
string |
all fetch commands |
X-NSCP-GUID |
GUID integer |
get_guids |
X-NSCP-LANGUAGE |
string |
all fetch commands |
X-NSCP-LINK-CALID |
string |
all fetch commands |
X-NSCP-ONGOING |
integer |
all fetch commands |
X-NSCP-ORGANIZER-EMAIL |
string |
all fetch commands |
X-NSCP-ORGANIZER-SENT-BY-UID |
string |
all fetch commands |
X-NSCP-ORGANIZER-UID |
string |
all fetch commands |
X-NSCP-ORIGINAL-DTSTART |
Date Time Z string |
fetch commands |
X-NSCP-REQUEST-STATUS |
string |
deleteevents_by_range, deletetodos_by_range |
X-NSCP-TOMBSTONE |
integer |
all fetch commands |
X-NSCP-WCAP-CALENDAR-ID |
string | |
X-NSCP-WCAP-ERRNO |
integer |
all |
X-NSCP-WCAP-PREF-CN X-NSCP-WCAP-PREF-GIVENNAME X-NSCP-WCAP-PREF-PREFERREDLANGUAGE X-NSCP-WCAP-PREF-SN X-NSCP-WCAP-PREF-NSWCALCALID X-NSCP-WCAP-PREF-CEFONTSIZEDELTA X-NSCP-WCAP-PREF-CETABLESPACING X-NSCP-WCAP-PREF-CECOLORSET X-NSCP-WCAP-PREF-CEBGCOLOR X-NSCP-WCAP-PREF-CECALLIST X-NSCP-WCAP-PREF-CEAGENDALIST X-NSCP-WCAP-PREF-CEAGENDATZMODE_PERSONAL X-NSCP-WCAP-PREF-CECURSORCOLOR |
varies by preference |
get_userprefs |
X-NSCP-WCAP-SERVER-PREF-ALLOWCHANGEPASSWORD X-NSCP-WCAP-SERVER-PREF-ALLOWCREATECALENDARS X-NSCP-WCAP-SERVER-PREF-ALLOWDELETECALENDARS |
varies by preference |
get_userprefs |
X-NSCP-WCAP-SESSION-ID |
string |
check_id |
X-NSCP-WCAP-USER-ID |
string | |
X-NSCP-WCAP-VERSION |
string | |
X-S1CS-ATTENDEE-EXDATELIST |
string |
all fetch commands |
X-S1CS-ATTENDEE-RDATELIST |
string |
all fetch commands |
X-S1CS-CALID |
string |
all fetch commands |
X-S1CS-CALPROPS-ALLOW-DOUBLEBOOKING |
string |
get_calprops set_calprops |
X-S1CS-CALPROPS-COMMON-NAME |
string |
get_calprops |
X-S1CS-CALPROPS-FB-INCLUDE |
integer |
get_calprops |
X-S1CS-CALPROPS-INVITATION-COUNT |
string |
get_calprops |
X-S1CS-CALPROPS-OWNED-CALENDAR |
string |
list |
X-S1CS-CALPROPS-SUBSCRIBED-CALENDAR |
string |
list_subscribed |
X-NSCP-COMPONENT-SOURCE |
string |
all fetch commands |
X-S1CS-EMAIL |
string |
all fetch commands |
X-S1CS-EXPORTVERSION |
string |
all fetch commands |
X-S1CS-RECURRENCE-COUNT |
integer |
all fetch commands |
X-S1CS-RECURRENCE-EXDATELIST |
string |
all fetch commands |
X-S1CS-RECURRENCE-RDATELIST |
string |
all fetch commands |
X-S1CS-RECURRENCE-UNTIL |
string |
all fetch commands |
X-NSCP-TRIGGERED_BY |
string |
all fetch commands |
X-S1CS-TZID-ALIAS |
string |
all fetch commands |