Sun ONE Calendar Server 6.0 Programmer's Manual |
Chapter 5
Web Calendar Access Protocol (WCAP) OverviewThis 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:
IntroductionThe 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.
WCAP commands consist of four general categories of usage:
Command OverviewTable 5-1 describes the high level list of commands supported in WCAP. For a detailed description of each command, see Chapter 6, "WCAP Commands."
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.
You can customize the authentication mechanism to use a local or external authentication scheme. See Chapter 2, "CSAPI Reference," for the section "csIAccessControl."
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:
service.virtualdomain.support=”y”
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.
Not in hosted domain mode:
http://webcalendarserver/get_userprefs.wcap?id=b5q2o8ve2rk02nv9t6& calid=jdoe&fmt-out=text/calendar
In hosted domain mode:
http://webcalendarserver/get_userprefs.wcap?id=b5q2o8ve2rk02nv9t6& calid=jdoe@example.com&fmt-out=text/calendar
Command FormatsThe 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 of JavaScript objects formatted as XML or iCalendar, communicated as HTML documents over HTTP on both the client and server side. Refer to the Sun ONE Calendar Server 6.0 Release Notes for recommended browser versions for client interfaces.
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.
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
Use the following format to submit a URI request:
http://webcalenderserver/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 IDs, use the following:
http://webcalendarserver/fetchcomponents_by_range.wcap?uid=abc;def;gh%3bi;jkl
See also "Common Topics List", in Chapter 6, "WCAP Commands."
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
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 GET are simply for data retrieval.
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: