| Oracle Calendar API Developer's Guide Release 2.5 Part Number B10097-01 |
|
| View PDF |
| Oracle Calendar API Developer's Guide Release 2.5 Part Number B10097-01 |
|
| View PDF |
This chapter discusses a variety of factors to be taken into consideration in your Oracle Calendar API (CAPI) implementations:
CAPI only supports text encoded in UTF-8. Strings passed to CAPI_Logon and CAPI_GetHandle must be in UTF-8. All output data is in UTF-8. Input must be in UTF-8; this means that MIME entities which specify a character set must specify UTF-8 or US-ASCII (MIME defaults to US-ASCII if no character set is specified).
CAPI uses the iCalendar format (as specified in RFC 2445) for dealing with calendar data. iCalendar information saved via CAPI can be retrieved later. However, not all iCalendar data is actively supported by this revision of CAPI. In particular, VTODO, VFREEBUSY and VJOURNAL components are not supported.
The essential iCalendar data is mapped to native data structures. Data for these properties will not always be completely preserved. Some properties are stored only per event, rather than per instance, so only one value is preserved. The following are affected:
If DTEND is present, it will be used to calculate the event duration; the actual end time is not stored. As event times are measured in minutes, the start time and duration will have their 'seconds' component set to zero.
This property is mapped to the event title. When using a 5.0 calendar server this value will be truncated to 64 bytes.
This property is mapped to one of the calendar server's 5 priority values. This property is stored per event.
This property is mapped to access level. The mapping between iCalendar and the calendar server's access levels is as follows:
From iCalendar to calendar server:
From calendar server to iCalendar:
This property is stored per event.
A value of TENTATIVE indicates a tentative event. Any other value (even CANCELLED) will indicate a non-tentative event.
This is stored in the location field. When using a 5.0 calendar server, this value will be truncated to 32 bytes.
When storing "ATTENDEE" properties an attempt will be made to correlate attendee properties with the people to whom they refer by comparing them with the supplied handles. If an attendee property represents a calendar user and there is no corresponding handle for that user then the calendar user will not be invited to the event.
Currently this property is ignored.
This is set to the Event's details. It will be truncated if it is longer than 32 Kb. This property is stored per event.
This is mapped to the event's type. Possible values are "APPOINTMENT", "DAILY NOTE", "DAY EVENT", and "HOLIDAY". The event type is stored per event.
Alarms are preserved separately for each attendee of an event. Users will not be able to see each other's alarms.
If a UID is not specified in stored data the server will assign a UID. These assigned UIDs are accessible through the CAPI_GetLastStoredUIDs function described below.
Other iCalendar data will be preserved and returned unchanged.
When data created with Oracle calendar clients is output, the following is a list of available properties, and how they are obtained. Other properties stored with CAPI are also available.
Instances of an event are all returned in separate VEVENT objects.
The event owner.
The event access level.
The event priority.
A tentative event will have a TENTATIVE status. Non-tentative events will be marked as CONFIRMED. No other STATUS values are generated.
The event details.
The event type.
The duration of the event.
The event title.
The start time of the event, in GMT.
An id generated from internal ids.
A property is generated for each ATTENDEE. The parameters PARTSTAT, ROLE, CUTYPE, and CN are obtained from the attendee and user information.
Converted from native resource attendees.
Converted from native reminders.
There are two parts to the security model: storing and fetching events. These are handled by different security paradigms.
The owner of an event can add or delete any property of that event. When an "ATTENDEE" property is created for a calendar user, and a handle has been supplied for that user, the property is created with default values for its parameters. The owner of the event cannot modify the parameters of that property, only the user to whom it corresponds can do that.
When a user is updating their "ATTENDEE" property no error will be returned if there is an attempt to modify other event data, but the modifications will not occur.
It is possible for a user to refuse invitations from another user. In that case an "ATTENDEE" property will not be created for that user and the status for that user's handle will indicate that the invitation was refused. This may also occur when attempting to double book resources.
When fetching events the security model is based on the iCalendar classification of the event. Users grant other users different access levels to different classes of events. The three access levels are: no read access, read the start and end times of the event only, and read all details of the event. When fetching events with CAPI this results in some events for which only the "DTSTART", "DURATION" and "DTEND" properties will be returned. All other events will be invisible or all of their properties will be returned.
CAPI does not allow users to modify the security records which govern this behaviour.
Alarms are considered private to each user, so users cannot read or write alarms for each other. Since users cannot read each others alarms it is not possible for users to do fetches by alarm range on each other's calendars. Any user may set an alarm for an event which they are attending, so the same events can have a different alarm when fetched by a different user.
Alarms will be returned by a fetch by id on the current user's agenda, and in fetches by alarm range. The alarm always applies to the logged in user.
All event recurrences are expanded into separate recurrence dates. This affects events which are stored with "RRULE" properties. Once an event is stored any "RRULE" and "EXRULE" properties will be lost.
When fetching events, iCalendar data is returned with a separate "VEVENT" component for each instance of a recurring event. This may result in a lot of repeated data for events with many instances. This behaviour may change in the future.
Users are identified to CAPI by a userid string, or by using a search string specifying, for example, the user's name. The string format is flexible and allows the caller to specify a number of optional parameters. Depending on the server configuration, some of these options (such as the Node ID) may be required in the identification string. The same user identification string format is used both at logon and when obtaining a handle, however not all options will be applicable in both cases.
Logging into the server as a resource is not supported.
All options are specified using key-value pairs. The entire string is a collection of such pairs. The userid is separated from the extended data by an ASCII '?' character. The character immediately following this one is the delimiter of each subsequent field value pair. The delimiter may be any ASCII character except a digit, a letter, NUL, '*' or '='. The rest of the string consists of field-value pairs separated by the chosen delimiter. The string is terminated by a delimiter followed by a NUL character. Field value pairs consist of a field name, followed by an equal sign ('='), followed by the value. The value is a string which does not contain the delimiter character, the NUL character, and for user identification strings, the slash ('/') (aka solidus) character.
For example, the field name G denotes the given name, and S denotes the surname. The following is a sample legal string for identifying a user. No userid is specified, so the optional parameters would used to search for the user. (Note that if a search results in multiple matches, CAPI will return an error to the caller; a userid is the best method of specifying a user, if it is available.) Even with no userid, we still have the question mark '?' character separating the userid from the extended string. The character immediately following, in this case a slash '/', is used as the delimiter. Note that the string ends with the delimiter character, and is NUL terminated.
?/S=Bunny/G=Bugs/
Any field used for identifying a user may be terminated with a '*', which is used as a wildcard. This is not available for specifying nodes. The following will also match the above user:
?/S=Bu*/G=Bugs/
Remember that if multiple users match a given search string, the CAPI call will return an error.
Resources have a different name structure; they are identified with the single field RS which indicates resource name.
The following grammar (in ABNF form, as described in RFC 2234) describes legal logon strings:
The description below diverges from ABNF in that values in double quotes are case-sensitive, ie. field names must be in uppercase. Also, the delimiter character must be the same in all cases in a single string.
logon-string = userid "?" [ DELIMITER ext-string ] %x00 userid = *( ALPHA / DIGIT / "-") ext-string = 1*( field ) field = ( node / company-domain / surname / given-name / initials / generation / org-unit / organization / country / admin / private / resource-name ) DELIMITER
Specifying a particular field more than once is, while silly, still legal, although only the last field will be used.
node = "ND=" node-number node-number = 1*DIGIT company-domain = "CD=" 1*VALUE-CHAR surname = "S=" 1*VALUE-CHAR ["*"] given-name = "G=" 1*VALUE-CHAR ["*"] initials = "I=" 1*VALUE-CHAR ["*"] generation = "X=" 1*VALUE-CHAR ["*"] org-unit = ( "OU1" / "OU2" / "OU3" / "OU4" ) "=" 1*VALUE-CHAR ["*"] organization = "O=" 1*VALUE-CHAR ["*"] country = "C=" 1*VALUE-CHAR ["*"] DELIMITER admin = "A=" 1*VALUE-CHAR ["*"] DELIMITER private = "P=" 1*VALUE-CHAR ["*"] DELIMITER resource-name = "RS=" 1*VALUE-CHAR ["*"] DELIMITER DELIMITER = %x01-%x29 / %x2B-%x2F / %x3A-%x3C / %x3E-%x40 / %x5B-%x60 / %x7B-%x7F
Note also that the DELIMITER cannot be used as a VALUE-CHAR.
VALUE-CHAR = %x01-29 / %x2B-2E / %x30-7F
CAPI deals with MIME (see RFC 2045) encapsulated iCalendar objects for both input and output. A single request may fetch data from a list of calendars. A reply to such a request will consist of a separate iCalendar object for each calendar in the list, inside separate MIME parts. That is, a request for events from calendarA and calendarB results in a MIME stream of this form:
... MIME envelope--MIMEBOUNDARYasdfasdf Content-type: text/calendar Content-Transfer-Encoding: quoted-printable BEGIN:VCALENDAR... events from calendarAEND:VCALENDAR --MIMEBOUNDARYasdfasdf Content-type: text/calendar Content-Transfer-Encoding: quoted-printable BEGIN:VCALENDAR... events from calendarBEND:VCALENDAR --MIMEBOUNDARYasdfasdf--
The order of the iCalendar objects corresponds to the order of the calendars in the request list. If a request results in an empty solution set, the return stream will be an empty iCalendar object. If there is any sort of error with a calendar the iCalendar reply object corresponding to that calendar will be empty.
For example, in the example above if calendarB was deleted by someone else just prior to an attempt to fetch data, the resulting stream would have the following form:
Content-type: text/calendar
Content-Transfer-Encoding: 7bit
BEGIN:VCALENDAR
... events from calendarA
END:VCALENDAR
Content-type: text/calendar
Content-Transfer-Encoding: 7bit
BEGIN:VCALENDAR
END:VCALENDAR
On a successful fetch the "VCALENDAR" will contain many "VEVENT" components, each containing the requested properties, if available. iCalendar allows these different components to contain information about different instances of the same event. The returned data may use any of the following methods to give instance specific information:
Please note that the "DTSTART" property returned indicates the start time of the first instance identified in the "VEVENT" component in which it resides and not the start time of the first instance of the event in the Calendar Store. Furthermore the number of "VEVENT" components returned in the calendar has no relation to the number of instances of the event. Consequently, when fetching events, if the recurrence identifying properties are not requested, there will be no way to determine how many instances exist, and to which instances each returned property applies.
When storing, data supplied to CAPI must consist of a single "VCALENDAR" component inside a single MIME part. The calendar may contain many "VEVENTS", but these must all be information about a single event. For example, this is a valid input:
Content-type: text/calendar Content-Transfer-Encoding: 7bit BEGIN:VCALENDAR BEGIN:VEVENTevent propertiesEND:VEVENT BEGIN:VEVENTevent propertiesEND:VEVENT END:VCALENDAR
Access to data through CAPI is controlled by the calendar server. It is based on the requester's identity and the data / operation being requested. CAPI provides an interface to request reading any combination of properties. Properties that the requesting user is not authorized to read will not be returned in the CAPI stream and an appropriate status code will be returned by the function call. However, if the user is allowed to read the proprty but it does not exist in the events requested, the property will not be present in the CAPI stream and the return status is not affected. For example, if the VEVENT.GEO property is requested, and it exists, but the requester does not have permission to read it, the resulting CAPI stream will not contain the VEVENT.GEO property in the data stream and an access violation status code will be returned. If the requester has permission to read the VEVENT.GEO property, but the components do not have a GEO property value, the data stream will not contain the VEVENT.GEO property but no error will be returned because of the missing property.
Users will only have access to modify the events to which they are invited, or which they own. If the user is the owner of the event they will have full privileges to modify the event (except for modifying other users' attendance information), otherwise if they are invited to the event they will have restricted privileges to modify information relating to their own attendance, such as acceptance and alarms.
CAPI will silently ignore attempts to modify properties that the user is not permitted to modify. This simplifies the implementation of modification in these cases.
Errors may occur for specific agendas when attempting to modify events or when creating events. These errors will be returned using a supplied array of status values, allowing the rest of the operation to proceed.
|
 Copyright © 1996, 2002 Oracle Corporation. All Rights Reserved. |
|