| Oracle Calendar Application Developer's Guide Release 2 (9.0.4) Part Number B10893-01 |
|
|
View PDF |
| Oracle Calendar Application Developer's Guide Release 2 (9.0.4) Part Number B10893-01 |
|
|
View PDF |
This chapter discusses a variety of factors to be taken into consideration in your Oracle Calendar SDK implementations:
All SDK functions operate only on UTF-8 encoded text. All strings given to the SDK functions must be in UTF-8 and all strings returned by the SDK will be in UTF-8. For more information on UTF-8, refer to RFC 2279.
The Oracle Calendar SDK uses the iCalendar format (as specified in RFC 2445) for dealing with calendar data. iCalendar information saved via the SDK can be retrieved later. However, not all iCalendar data is actively supported by this revision of the SDK. In particular, VFREEBUSY and VJOURNAL components are not supported.
The 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. This section describes the mappings used for the most common properties.
This property is currently ignored.
When storing "ATTENDEE" properties, an attempt will be made to correlate attendee properties with calendar users. The legacy function CAPI_StoreEvents will compare the attendee address with the addresses of each supplied handle to identify the calendar user. CSDK_StoreEvents performs a look-up on the calendar server to find the corresponding calendar user. Non-calendar users will still be invited (as "external attendees") when using CSDK_StoreEvents.
When using CAPI_StoreEvents, the CATEGORIES property is used to specify the event type. Recognized values are "APPOINTMENT", "DAILY NOTE", "DAY EVENT" and "HOLIDAY". When using CSDK_StoreEvents, the CATEGORIES value is stored on the server and will be returned by the various CSK_FetchEvents functions. (The property X-ORACLE-EVENTTYPE is used with CSDK_StoreEvents to specify the event type and the same values are recognized).
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:
This property is stored per event.
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 when calling CAPI_StoreEvents, and per instance when calling CSDK_StoreEvents.
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 is stored in the location field. When using CorporateTime Server 5.0 or earlier, this value will be truncated to 32 bytes.
This property is mapped to one of the calendar server's 5 priority values. This property is stored per event.
When using CSDK_StoreEvents, recurrence-rules and exceptions to the rules are stored on the calendar server. When using the legacy CAPI_StoreEvents function, recurrence rules are expanded upon event creation and the recurrence-rule itself is not stored on the calendar server.
A value of TENTATIVE indicates a tentative event. Any other value (even CANCELLED) will indicate a non-tentative event.
This property is mapped to the event title. When using CorporateTime Server 5.0 or earlier, this value will be truncated to 64 bytes.
If a UID is not specified in stored data the calendar server will assign a UID. When using CAPI_StoreEvents, the server-assigned UIDs can be read by calling CAPI_GetLastStoredUIDs. When using CSDK_StoreEvents, the UIDs are returned via the CSDKRequestResult.
The current user is able to fetch and store her own reminders. It is not possible to access another user's alarms.
When data created with the SDK or other Oracle Calendar clients is fetched, the following properties are available. Other properties including Oracle-specific extensions (X-ORACLE-...) may also be returned. It is possible to limit the list of properties returned when fetching data. In some cases, there are performance gains to be made by doing so.
A property is generated for each ATTENDEE. The parameters PARTSTAT, ROLE, CUTYPE, and CN are obtained from the attendee and user information.
When calling CAPI_FetchEventsBy..., the event type is returned in this property. CSDK_FetchEventsBy... will return a user-specified value (which may have been stored using the SDK or another client).
The event access level. The access levels are mapped as:
When calling CAPI_FetchEventsBy..., the event details (as seen by the native clients) are returned. CSDK_FetchEventsBy... will return instance-specific details if they exist, or the event details.
The duration of the event, or the end-time of the event.
The start time of the event.
The event location.
The event owner.
The event priority.
When calling CAPI_FetchEventsBy..., this property will contain the names of all attendees which are resources. CSDK_FetchEventsBy... will return a string which may have been stored using CSDK_StoreEvents or by another Oracle Calendar client.
The recurrence-rule stored on the server. This is not available when calling CAPI_FetchEventsBy...
A tentative event will have a TENTATIVE status. Non-tentative events will be marked as CONFIRMED. No other STATUS values are generated.
The event or instance title.
The user-specified UID (as set on event creation) if available, otherwise a server-generated UID.
Converted from native reminders (for the current user only).
The Oracle Calendar SDK uses the vCard format for dealing with contact data. vCard information saved via the SDK can be retrieved later. Versions 2.1 and 3.0 are both supported.
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 properties 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 the SDK this results in some events for which only the "UID," "DTSTART," "DURATION" and "DTEND" properties will be returned. All other events will be invisible or all of their properties will be returned.
The Oracle Calendar SDK 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 other's 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.
Users are identified to the Oracle Calendar SDK 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, but it is possible to work as a designate for a resource.
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 be used to search for the user. (Note that if a search results in multiple matches, the SDK 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 preceding user:
?/S=Bu*/G=Bugs/
Remember that if multiple users match a given search string, the the SDK 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 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 redundant, 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
By default, the SDK deals with MIME (see RFC 2045) encapsulated iCalendar and vCard 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 calendarA END:VCALENDAR --MIMEBOUNDARYasdfasdf Content-type: text/calendar Content-Transfer-Encoding: quoted-printable BEGIN:VCALENDAR ... events from calendarB END: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.
On a successful fetch the "VCALENDAR" may 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 the SDK must consist of a single "VCALENDAR" component inside a single MIME part. The calendar may contain many "VEVENT" objects, 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 VERSION:2.0 BEGIN:VEVENT event properties END:VEVENT BEGIN:VEVENT event properties END:VEVENT END:VCALENDAR
Access to data through the SDK is controlled by the calendar server. It is based on the requester's identity and the data / operation being requested. the SDK provides an interface to request reading any combination of properties. Properties that the requesting user is not authorized to read will not be returned.
Users will only have privileges 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.
The SDK will silently ignore attempts to modify properties that the user is not permitted to modify.
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.
