This chapter describes the Web Calendar Access Protocol 7.0 (WCAPbis), which is a high-level command-based protocol used to communicate with Oracle Communications Calendar Server.
Calendar data is stored in Standard iCal format in the calendar database. You can retrieve this calendar data by using WCAP commands with the fmt-out parameter set to text/calendar, text/json, or text/xml. The default format is text/calendar and data is output in Standard iCal format as defined in RFC5545.
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 to the commands.
WCAP commands consist of five general categories of usage:
Creating calendars
Storing, retrieving, and managing calendar properties
Storing, retrieving, and managing calendar data
Retrieving calendar Information of other users
Scheduling
Note:
WCAP 7.0 (WCAPbis) is based on WCAP in Calendar Server 6 and prior but has undergone many changes to increase usability, to better work with the new server model, and so on. For more information, see "Design Changes Between Calendar Server Versions".Topics in this section:
Table 1-1 describes the commands supported in WCAP 7.0.
Table 1-1 WCAP 7.0 Command Overview
WCAP 7.0 Command | Description |
---|---|
Checks session identifier for validity. |
|
Creates a new calendar. |
|
Deletes an existing calendar. |
|
Deletes events given a specific calid and uid or uid and rid pair. |
|
Deletes events in calendar(s) over a specific time period. |
|
Deletes todos given a specific calid and uid or uid and rid pair. |
|
Deletes todos in calendar(s) over a specific time period. |
|
Exports a calendar to a file. |
|
Fetches an attachment of specified attachid. |
|
Fetches a list of components that have changed since a specified time. |
|
Queries for components over a specific time period, with filtering attributes. |
|
Queries for one or more events by a unique identifier (UID, Recurrence ID, modifier). |
|
Queries for one or more todos by a unique identifier (UID, Recurrence ID, modifier). |
|
Returns account properties. |
|
Returns all the time zones the server supports. |
|
Returns properties of requested calendars. |
|
Determines if the attachment store been enabled for Calendar Server. |
|
Returns free/busy information of requested users. |
|
Imports a calendar from a file to a user's specified calendar. |
|
Lists all calendars owned by a user. |
|
Lists all subscribed calendars of a user. |
|
Authenticates a user and generates a session identifier. |
|
Logs out of a session. |
|
Searches for a user with the specified parameter values and returns his calendars. |
|
Sets the account properties of a user. |
|
Sets calendar properties. |
|
Creates or modifies events, including inviting attendees for the event. |
|
Creates or modifies todos. |
|
Adds calendars to a user's subscription list. |
|
Removes calendars from a user's subscription list. |
|
Prints server and WCAP version. |
See "Error Codes" for error codes returned by WCAP commands.
For most 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 identity information for authentication. 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 Calendar Server System Administrator's Guide.
WCAP commands work the same for users in default and non-default domains in a hosted domain environment. For non-default domains, WCAP commands you issue must have fully qualified login IDs to properly identify the domain of the user, for example, jdoe@example.com.
WCAP uses HTTP and follows the standards defined by the WC3 URL specifications.
Note:
On some HTTP client implementations, the request URI length is limited to 1024. Thus, always use HTTP POST (with an application/x-www-form-urlencoded body part containing all the parameters) when sending a request where the total size of parameters is unbounded (for example, in the case of storeevents.wcap).Topics in this section:
Clients submit command requests to the Calendar Server in Universal Resource Identifier (URI) data format.
Use the following format to submit a URI request:
http://webcalendarserver:port/wcap/COMMAND?PARAM=VAL&PARAM=VAL...
New lines in values must be represented by \n.
Semi-colons in values must be escaped: \;
Carats in a value can be used as is. No doubling is needed, as the other separator carats occur only in the parameter name part.
Property values can contain a colon. The code evaluates each PROPERTY_NAME:PROPERTY_VALUE up to the first ":" as PROPERTY_NAME (including parameters), and the rest as PROPERTY_VALUE.
The following example shows how to represent the string "gh;i" in a list of IDs:
http://webcalendarserver:port/wcap/fetchcomponents_by_range.wcap? uid=abc;def;gh\;i;jkl
Calendar Server responds to client requests in iCalendar, JSON, or XML objects. You can configure a response format preference per request by using the fmt-out parameter.
All JSON formatted output is prefixed by {}&&. This is to help combat JSON hijacking. You can change the prefix value by setting the davcore.serverdefaults.jsonprefix configuration parameter. The default value is {}&&.
Calendar Server accepts compressed requests (indicated by a "Content-Encoding:gzip" HTTP header in the request). Additionally, the server can return compressed responses (requested through an "Accept-Encoding:gzip" HTTP header in the request). This helps reduce overall network traffic between client and server.