Chapter 5 Web Calendar Access Protocol Overview

This chapter describes the Web Calendar Access Protocol (WCAP), which is a high level command-based protocol used to communicate with the Calendar Server. This chapter has the following sections:

Introduction

The default client UI protocol for Calendar Server is an SHTML protocol, and is private. To retrieve calendar data in text/calendar and text/xml formats, use WCAP commands with the fmt-out parameter set to text/calendar or text/xml.

WCAP is a command based system consisting of client requests and server responses for transmitting calendaring data. WCAP returns calendaring data via HTTP. In most cases, Calendar Server receives data through URL-encoded arguments.

WCAP returns output in an HTTP message. The returned content body of the HTTP messages can consist of calendar data in the following formats:


Note	In order to start the Calendar Server user interface (Calendar Express), you must specify fmt-out=text/html in the login command. This is the only instance of this format type.

Command Overview

Table 5-1 WCAP Command Overview
WCAP Command	Description
addlink	Add event links from one calendar to another.
change_password	Change the user’s password.
check_id	Administrator only: Check if user’s session ID is valid.
createcalendar	Create a new calendar.
deletecalendar	Delete an existing calendar.
deletecomponents_by_range	Delete both events and todos in a calendar(s) over a specific time period.
deleteevents_by_id	Delete events given a specific calid and uid/recurrence-ID pair.
deleteevents_by_range	Delete events in a calendar(s) over a specific time period.
deletetodos_by_id	Delete todos given a specified calid and userid/recurrence-ID pair.
deletetodos_by_range	Deletes todos in a calendar(s) over a specific time period.
export	Exports a calendar to a file.
fetchcomponents_by_alarmrange	Queries for components that have alarms to trigger over a specific time period.
fetchcomponents_by_attendee_error	Queries for components that had errors while sending group scheduling messages.
fetchcomponents_by_lastmod	Queries for components that have changed, during the specified time range.
fetch_deletedcomponents	Queries the deletelog database for deleted components.
fetchcomponents_by_range	Queries for components over a specific time period, with filtering attributes.
fetchevents_by_id	Queries for one or more events by a unique identifier (UID, Recurrence ID, modifier).
fetchtodos_by_id	Queries for one or more todos by a unique identifier (UID, Recurrence ID, modifier).
get_all_timezones	Returns all the timezones the server supports.
get_calprops	Returns calendar properties.
get_freebusy	Returns calendar freebusy time.
get_guids	Returns a set of random UIDs.
gettime	Returns the server times for the requested calids.
get_userprefs	Returns user preferences and some server settings.
import	Imports a calendar from a file to a user’s calendar.
list	Lists all calendars owned by a user.
list_subscribed	Lists all calendars subscribed to by a user.
login	Authenticates a user and redirects to first HTML view.
logout	Terminates the current user’s session and return to login screen.
ping	Administrator only: Pings the calendar server.
search_calprops	Searches for a calendar with the specified parameter values.
set_calprops	Sets calendar properties.
set_userprefs	Sets user preferences.
storeevents	Stores events that are specified in application/urlencoded manner. For storing an even by passing properties in a URL.
storetodos	Stores todos that are specified in the application/urlencoded manner.
subscribe_calendars	Adds calendars to a users subscription list.
unsubscribe_calendars	Removes calendars from a user’s subscription list.
verifyevents_by_ids	Fetches events and returns the uid/rid of events not in the database.
verifytodos_by_ids	Fetches todos and returns the uid/rid of events not in the database.
version	Returns the WCAP version that the server supports.

Session Identifiers

For many WCAP commands, you must specify the session identifier (id) that is returned by the login command. The session identifier ensures that data is accessible only to authenticated users with the required level of privilege or ownership.

When logging into the system, a user provides authentication of identity. The default authentication mechanism uses plain-text passwords and user names. Calendar Server generates the session identifier only when authentication is successful. The identifier then serves as proof of authentication in subsequent calendaring operations.

Hosted (Virtual) Domain Mode

If your LDAP is set up to use hosted (virtual) domains, all WCAP commands you issue must have fully qualified user IDs and calendar IDs (calid), for example jdoe@example.com.

In order to be in hosted domain mode, the following ics.conf parameter must be set as shown:

See your Calendar Server administrator if you do not know whether you are using hosted domains.

The following two example WCAP commands demonstrate the difference between calid values for non-hosted domain mode and hosted domain mode.

http://webcalendarserver/get_userprefs.wcap?id=b5q2o8ve2rk02nv9t6& calid=jdoe&fmt-out=text/calendar

http://webcalendarserver/get_userprefs.wcap?id=b5q2o8ve2rk02nv9t6& calid=jdoe@example.com&fmt-out=text/calendar

Command Formats

The plug-in architecture of Calendar Server allows it to support multiple command formats. Both client and server can use a variety of data formats to meet various ISP needs.

The command protocol uses HTTP, and follows the standards defined by the WC3 URL specifications.

WCAP in Calendar Server consists calendar data formatted as XML or iCalendar, communicated as HTML documents over HTTP on both the client and server side. Refer to the Calendar Server Release Notes for recommended browser versions for client interfaces.

Client Request Formats

Clients submit command requests to the Calendar Server in either Universal Resource Identifier (URI) data format, or with one of three HTML forms.

URI Format


Note	There is a limit to the number of characters that may be passed in for each parameter. The limit per parameter is 1024 characters.

Command Format	Description
URI	Requests from client submitted using standard URI syntax.
HTML Form - urlencoded	Requests from client submitted as encoded URLs.
HTML Form - text/xml	Requests from client submitted using objects formatted as XML.
HTML Form - text/calendar	Requests from client submitted using objects formatted as iCalendar.

Multiple items are delimited by semicolons. If a string contains a semicolon character, replace the semicolon with its quoted-printable equivalent, %3B. For example, to represent the string “gh;i” in a list of IDs, use the following:

HTML Form

Submit a form with method=[GET|POST] and action=command (where command is the command to execute). Parameters need to be formatted as specified in the encoding.

Client Side Event Notification


Note	The maximum length for WCAP parameters is 1024 characters.

All client side JavaScript code in the parent frame of the response page is required to implement a method called CalcommandCallback(), where command is the name of the command requested. This callback will be invoked when the HTML response is completed loading.

The above commands when used with HTTP POST are for data modifications (including creation/deletion).

Server Response Formats

Calendar Server responds to client requests by serving HTML containing JavaScript objects. You can configure a response format preference for a server, a user, or an individual request.

The client may request output in either text/calendar or text/xml formats. The following table gives a brief description of each response format:

Previous Contents Index Next
Sun Java System Calendar Server 6 2005Q1 Developer's Guide

Response Format	Description
text/calendar	Responses are in HTML, containing data formatted as iCalendar objects. This is the default format.
text/xml	Responses are formatted as XML objects