Sun Java System Calendar Server 6.3 WCAP Developer's Guide

Chapter 1 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 Calendar Server. This chapter has the following sections:

Introduction to WCAP for Calendar Server

Calendar data is stored in a proprietary format in the various calendar databases. You retrieve calendar data using WCAP commands with the fmt-out parameter set to either text/calendar or text/xml.

Calendar Server communicates with Communications Express using the text/xml format.

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

WCAP commands consist of four general categories of usage:

User Configuration Information
Web Calendaring Data
Communication-sending for group scheduling
Miscellaneous commands

Calendar Server WCAP Command Overview

The following is a list of commands supported in WCAP. For a detailed description of each command, see Chapter 3, Calendar Server WCAP Command Reference

Table 1–1 WCAP Command Overview


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

For more information about how to configure authentication, see the Calendar Server Administration Guide: Sun Java System Calendar Server 6.3 Administration Guide.

Hosted (Virtual) Domain Mode

In earlier versions of Calendar Server, using domains was optional. Now all installations are configured with at least one domain and are considered to be in hosted domain mode. Therefore, all WCAP commands you issue must have fully qualified user ID's (uid) and calendar ID's (calid) to properly identify the domain, for example jdoe@example.com.

Command Formats

Plug-in architecture allows Calendar Server to support multiple command formats. Depending on your needs, you can use a variety of data formats for both clients and server.

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

Note –

The number of characters that can be passed in for each parameter is limited to 1024 characters.

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.

Command Format	Description
URI	Requests from client submitted using standard URI syntax.
HTML Form - `urlencoded`	Requests from client submitted as encoded URL's.
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.

URI Format

Use the following format to submit a URI request:

http://webcalendarserver/COMMAND?PARAM=VAL&PARAM=VAL...

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 ID's, use the following:

http://webcalendarserver/fetchcomponents_by_range.wcap?
               uid=abc;def;gh%3bi;jkl

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.

Note –

The maximum length for WCAP parameters is 1024 characters.

Client Side Event Notification

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 is invoked when the HTML response has completed loading.

When used with HTTP GET, commands are for data retrieval.

When used with HTTP POST, commands are for data modifications, including creation or deletion.

Server Response Formats

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