| Oracle® Calendar Application Developer's Guide 10g Release 1 (10.1.1) Part Number B14477-01 |
|
|
View PDF |
| Oracle® Calendar Application Developer's Guide 10g Release 1 (10.1.1) Part Number B14477-01 |
|
|
View PDF |
The Oracle Calendar SDK uses the iCalendar format for dealing with Calendar data. However, not all iCalendar data is actively supported by this version of the SDK. In particular, VFREEBUSY and VJOURNAL components are not supported.
Data for these properties will not always be preserved because events are shared entities in Oracle Calendar. Some properties are stored only per event rather than per instance so only one value is preserved. In particular, a calendar event with several attendees will appear in each of the attendee's agendas. However, that calendar event appears only once in the Oracle Calendar store.
For more information regarding data types, syntax, and other characteristics of iCalendar components and properties, see RFC 2445 - Internet Calendaring and Scheduling Core Object Specification (iCalendar).
The Oracle Calendar SDK also uses the vCard format for dealing with contact information. For more information regarding characteristics of vCard components and properties, see RFC 2426 - vCard MIME Directory Profile.
The following tables and sections describe the iCalendar and vCard components and properties that the Oracle Calendar SDK supports. The Oracle Calendar SDK also provides Oracle-specific components and properties whose names begin with "X-ORACLE."
The Oracle Calendar SDK supports the VEVENT and VTODO iCalendar components.
The following tables describe the component properties of VEVENT and VTODO. The following are clarifications of some of these table's headings and abbreviations:
Columns labeled "Minimum Occurrences" indicate the minimum number of each component property (or property parameter) that the client must create or generate in order to add the specified component to the Calendar store.
Columns labeled "Maximum Occurrence" indicate the maximum number of each component property (or property parameter) the specified component may contain.
The symbol "n" indicates no limit of the maximum number of the specified property or parameter
Describes appointments, daily notes, day events, and holidays.
Table 3-1 Component Properties of VEVENT
| Component Property | Minimum Occurrences | Maximum Occurrences | Data Type |
|---|---|---|---|
|
|
0 |
1 |
file location of the attachment |
|
|
0 |
n |
CAL-ADDRESS |
|
|
0 |
n |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
n |
TEXT |
|
|
0 |
n |
TEXT |
|
|
0 |
1 |
DATE-TIME |
|
|
0 |
1 |
TEXT |
|
|
1 (However, must not appear with DURATION) |
1 |
DATE-TIME (default), DATE |
|
|
0 |
1 |
DATE-TIME |
|
|
1 |
1 |
DATE-TIME (default), DATE |
|
|
1 (However, must not appear with DTEND) |
1 |
DURATION |
|
|
0 |
1 |
DATE-TIME (default), DATE |
|
|
0 |
1 |
RECUR |
|
|
0 |
1 |
two semicolon-separated FLOAT values. |
|
|
0 |
1 |
DATE-TIME |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
CAL-ADDRESS |
|
|
0 |
1 |
INTEGER |
|
|
0 |
n |
DATE-TIME (default), DATE, PERIOD |
|
|
0 |
1 |
DATE-TIME |
|
|
0 |
n |
DATE-TIME (default), DATE |
|
|
0 |
n |
TEXT |
|
|
0 |
1 |
RECUR |
|
|
0 |
1 |
INTEGER |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
URI |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
BOOLEAN |
|
|
0 |
1 |
URI |
|
|
0 |
|
TEXT |
|
|
0 |
1 |
BOOLEAN |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
BOOLEAN |
|
|
0 |
1 |
TEXT |
|
X-ORACLE-RTC-SENDEMAILNOTIFICATION |
0 |
1 |
BOOLEAN |
|
|
0 |
1 |
INTEGER |
|
|
0 |
1 |
TEXT |
Describes reminders for Calendar entries. Properties of VALARM include the type of reminder, such as a popup or an email, and the time before which the VALARM should notify the user of the Calendar event.
Table 3-2 Component Properties of VEVENT
| Component Property | Minimum Occurrences | Maximum Occurrences | Data Type |
|---|---|---|---|
|
|
1 |
1 |
TEXT |
|
|
0 (May appear only if ACTION is EMAIL) |
n |
CAL-ADDRESS |
|
|
Required only if ACTION is DESCRIPTION or EMAIL |
1 |
TEXT |
|
|
0 (REPEAT must appear if DURATION appears) |
1 |
DURATION |
|
|
0 (DURATION must appear if REPEAT appears) |
1 |
INTEGER |
|
|
Required only if ACTION is EMAIL |
1 |
TEXT |
|
|
1 |
1 |
TRIGGER |
The VTODO component describes tasks stored in the Oracle Calendar server.
Table 3-3 Component Properties of VTODO
| Component Property | Minimum Occurrences | Maximum Occurrences | Data Type |
|---|---|---|---|
|
|
0 |
n |
CAL-ADDRESS |
|
|
0 |
n |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
n |
TEXT |
|
|
0 |
1 |
DATE-TYPE |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
DATE-TIME |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
DATE-TIME |
|
|
0 |
1 |
DATE-TIME (default), DATE |
|
|
1 (However, must not appear of DURATION appears) |
1 |
DATE-TIME (default), DATE |
|
|
1 (However, must not appear if DUE appears) |
1 |
DURATION |
|
|
0 |
1 |
two semicolon separated FLOAT values |
|
|
0 |
1 |
DATE-TIME |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
CAL-ADDRESS |
|
|
0 |
1 |
INTEGER |
|
|
0 |
1 |
INTEGER |
|
|
0 |
n |
TEXT |
|
|
0 |
n |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
INTEGER |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
URI |
|
|
0 |
1 |
TEXT |
The following describes the iCalendar and Oracle-specific component properties of the VEVENT, VTODO, and VALARM calendar components.
This property defines the action to be invoked when an alarm is triggered. It can have one of the following values:
AUDIO:
DISPLAY:
EMAIL:
PROCEDURE:
X-ORACLE-ALARM-DEFAULT: Specifies that a VEVENT or VTODO calendar component be created or modified to have an alarm based on the user's default alarm settings.
X-ORACLE-ALARM-NONE: Specifies that a VEVENT or VTODO calendar component be created or modified without an alarm.
X-ORACLE-SMS: Indicates that the VALARM should have the server send an out-of-band reminder (such as an SMS or email) according to the user's preferences
The current version of the Calendar SDK doesn't fully support the ATTACH property as stated in RFC 2045. Only file URIs are supported. The SDK must be configured to support the ATTACH property. This involves setting tmpDirectoryPath in the SDK section of the Oracle Calendar SDK configuration file. See Chapter 7, "Oracle Calendar SDK Configuration Settings" for more information about this setting. Temporary file attachments will be saved in the directory specified in tmpDirectoryPath when an event is exported.
When an event is imported or stored, the ATTACH property value is file location of the attachment. The following is an example of the ATTACH property of an event to be stored:
ATTACH:file:/tmp/my_attachment.txt
When an event is exported or fetched, if the configuration setting tmpDirectoryPath points to a valid directory, any attachments will be downloaded in subdirectories of this directory. These subdirectories will be in the following format:
./<UID>-<RECURRENCE_ID>
If tmpDirectoryPath does not point to a valid directory, attachments will not be downloaded.
The following is an example of the ATTACH property of a fetched event:
ATTACH:file:///c:/20050427T160642Z-45c-a90b-27b4a6d7-Oracle-20050427T040000Z/my_attachment.txt
Defines an attendee within a calendar component.
When storing ATTENDEE properties, an attempt will be made to correlate attendee properties with Calendar users. CSDK_StoreEvents performs a look-up on the Oracle Calendar server to find the corresponding calendar user. Non-calendar users will still be invited (as "external attendees") when using CSDK_StoreEvents.
Look-ups are performed first using the X-ORACLE-GUID parameter, if present. If this fails, the user is treated as an external attendee. If the X-ORACLE-GUID parameter is not present, the value of the ATTENDEE property is used to do a look-up by email address of the calendar user.
To add a resource as an attendee, use either the X-ORACLE-GUID parameter, or set the CUTYPE parameter to "RESOURCE" and the CN parameter to the resource's name.
When retrieving data with the Oracle Calendar SDK, a property is generated for each ATTENDEE. The parameters PARTSTAT, ROLE, CUTYPE, and CN are obtained from the attendee and user information.
The following table describes the property parameters of ATTENDEE:
Table 3-4 Property Parameters of ATTENDEE
| Property Parameter | Minimum Occurrences | Maximum Occurrences | Data Type |
|---|---|---|---|
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
URI |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
A BASE64 encoded character string, as defined by [RFC 2045] |
|
X-ORACLE-PERSONAL-COMMENT-ISDIRTY |
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
0 |
1 |
TRUE/FALSE |
Defines the categories for a calendar component.
When using CSDK_StoreEvents, the CATEGORIES value is stored on the server and will be returned by the various CSDK_FetchEvents functions. (The property X-ORACLE-EVENTTYPE is used with CSDK_StoreEvents to specify the event type and the same values are recognized).
Calling one of the CSDK_FetchEventsBy functions will return a user-specified value (which may have been stored using the Oracle Calendar SDK or another client).
Defines the access classification for a calendar component.
This property is mapped to an Oracle Calendar server access level. The mapping between the CLASS value and the Oracle Calendar server access level is as follows:
Table 3-5 Mapping Between CLASS Values and Oracle Calendar Server Access Levels
| iCalendar CLASS Value | Oracle Calendar Server Access Level |
|---|---|
|
CLASS:PUBLIC |
PUBLIC |
|
CLASS:PRIVATE |
PERSONAL |
|
CLASS:CONFIDENTIAL |
CONFIDENTIAL |
|
CLASS:PRIVATE X-ORACLE-CLASS:NORMAL |
NORMAL |
If the CLASS property is not specified, the access level for the calendar component is PUBLIC. This is the behavior as defined in RFC 2445.
This property is stored per event, which implies that all recurrence instances of an event must have the same CLASS value.
Represents contact information or alternately a reference to contact information associated with the calendar component.
Specifies the date and time that the calendar information was created by the calendar user agent in the calendar store. The date and time is a UTC value.
Provides a more complete description of the calendar component than that provided by the SUMMARY property.
This is set to the Event's details. It will be truncated if it is longer than 32 Kb. This property is stored per instance when calling CSDK_StoreEvents.
Indicates the date/time that the instance of the iCalendar object was created. The value must be specified in the UTC time format. This property is different than the CREATED and LAST-MODIFIED properties. These two properties are used to specify when the particular Calendar data in the calendar store was created and last modified. This is different than when the iCalendar object representation of the Calendar service information was created or last modified.
Specifies when the Calendar component begins.
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.
Specifies a positive duration of time.
For example, a duration of 15 days, 5 hours and 20 seconds would be represented as P15DT5H0M20S. A duration of 7 weeks would be represented as P7W
Defines the list of date/time exceptions for a recurring calendar component. The following is an example of this property:
EXDATE:19960402T010000Z,19960403T010000Z,19960404T010000Z
Defines a rule or repeating pattern for an exception to a recurrence set. For example, the following excludes, for a recurrence set, dates that occur every other week on Tuesday and Thursday for 4 occurrences:
EXRULE:FREQ=WEEKLY;COUNT=4;INTERVAL=2;BYDAY=TU,TH
The following excludes dates that occur every day for 10 occurrences:
EXRULE:FREQ=DAILY;COUNT=10
The following excludes dates that occur every year in June and July for 8 occurrences
EXRULE:FREQ=YEARLY;COUNT=8;BYMONTH=6,7
Specifies information related to the global position for the activity specified by a calendar component. The property value specifies latitude and longitude, in that order.
Specifies the date and time that the information associated with the calendar component was last revised in the calendar store. This is analogous to the modification date and time for a file in the file system. The property value must be specified in the UTC time format.
Defines the organizer for a calendar component. Uses the same property parameters as ATTENDEE.
Used by an assignee or delegatee of a VTODO to convey the percent completion of a task to the Organizer. The property value is a positive integer between zero and one hundred.
Defines the relative priority for a calendar component.
This property is mapped to one of the Oracle Calendar server's five priority values. This property is stored per event.
Defines the list of date/times for a recurrence set. The following are examples of this property:
RDATE:19970714T123000Z RDATE;TZID=US-EASTERN:19970714T083000 RDATE;VALUE=DATE:19970101,19970120,19970217,19970421,19970526,19970704, 19970901,19971014,19971128,19971129,19971225
RDATEs of the type VALUE=PERIOD are not supported.
Used in conjunction with the UID property to identify a specific instance of a recurring VEVENT or VTODO calendar component. The property value is the effective value of the DTSTART property of the recurrence instance.
Represent a relationship or reference between one calendar component and another. It consists of the persistent, globally unique identifier of another calendar component. This value would be represented in a calendar component by the UID property.
The Oracle Calendar SDK stores this value as-is, but does not use it; there is no business logic associated with it.
Defines the equipment or resources anticipated for an activity specified by a calendar entity.
Defines the number of time the alarm should be repeated, after the initial trigger.
If the alarm triggers more than once, then this property must be specified along with the "DURATION" property.
Defines the revision sequence number of the calendar component within a sequence of revisions.
Defines the overall status or confirmation for the calendar component.
A tentative event will have a TENTATIVE status. Non-tentative events will be marked as CONFIRMED. No other STATUS values are generated.
Defines whether an event is transparent or not to busy time searches. Time transparency is the characteristic of an event that determines whether it appears to consume time on a calendar.
Events that consume actual time for the individual or resource associated with the calendar are recorded as OPAQUE, allowing them to be detected by free-busy time searches. Other events, which do not take up the individual's (or resource's) time are recorded as TRANSPARENT, making them invisible to free-busy time searches.
The Oracle Calendar SDK keeps track of transparency separately per attendee with the X-ORACLE-SHOWASFREE parameter on the ATTENDEE property, which can have the values FREE, BUSY, OUT, or TENTATIVE.
However, the Oracle Calendar SDK uses the TRANSP property only on output. It is set to OPAQUE for regular events and TRANSPARENT for day events, daily notes, and holidays.
Defines the persistent, globally unique identifier for the calendar component.
If a UID is not specified in stored data the Oracle Calendar server will assign a UID. When using CSDK_StoreEvents, the generated UIDs are returned as part of the results in CSDKRequestResult.
This property defines an Oracle-specific access classification for an iCalendar component.
This property describes the access classification specific to Oracle for the iCalendar component. Currently, this property is only being used for iCalendar components with the "NORMAL" access level. For interoperability and security considerations, "X-ORACLE-CLASS:NORMAL" is always returned with "CLASS:PRIVATE".
Identifies the type of event that the VEVENT represents. The property can be specified once in the VEVENT component. Possible values are "daily note", "holiday", "day event", and "appointment".
The following is an example of this property:
X-ORACLE-EVENTTYPE:DAY EVENT
Indicates that an instance is Web conference-enabled. This property is generated by the Oracle Calendar server and used by Calendar clients. This property can be specified in the VEVENT calendar component.
Specifies the organization associated with the task described by the VTODO. The property may be specified multiple times in a VTODO calendar component.
The following is an example of this property:
X-ORACLE-ORGANIZATION:ACME, Inc.
Specifies dial-in information required by attendees to join a teleconference, such as the phone number and conference ID. This property may be specified once in the VEVENT calendar component.
The following is an example of this property:
X-ORACLE-RTC-DIALININFO:1-999-999-9999 Conference Id: 999999
A boolean value that specifies whether Calendar Web services should include Web conference details (including the Join URL) to allow attendees to join a conference through an email invitation. This property may be specified once in the VEVENT calendar component.
The following is an example of this property:
X-ORACLE-RTC-ENABLEDIRECTJOIN:TRUE
Specifies the URL of the Web page hosting the Web conference associated with this calendar component instance. This value is set by Web conference. This property may be specified once in the VEVENT calendar component.
The following is an example of this property:
X-ORACLE-RTC-HOST-URL:http://www.example.com
Specifies the Web conference ID associated with the VEVENT calendar component instance. The value is strictly generated by the Web conference server. This property may be specified once in the VEVENT calendar component.
The optional key (the password) of a Web conference. The property can be specified in the VEVENT calendar component.
Currently not supported by the Oracle Calendar server and its clients. The Oracle Calendar server will always set this value to TRUE. Oracle Calendar server clients should not expose this property to users. This property may be specified once in the VEVENT calendar component.
Indicates the security type of an Web conference enabled instance. Possible types are "restricted", "regular", and "public". The property may be specified once in the VEVENT calendar component. This property may be specified once in the VEVENT calendar component.
If set to TRUE, specifies that the Calendar client should create the notification email addressed to the attendees of the conference. This property may be specified once in the VEVENT calendar component.
Specifies the site ID associated with the Web conference represented by the VEVENT. The value for this property is generated by the Oracle Calendar server. Clients will not access this value. An administrator will be able to change the designated value in order to track sites integrated with Web conferencing. This property may be specified once in the VEVENT calendar component.
The following describes iCalendar and Oracle-specific property parameters of CAL-ADDRESS (the data type of ATTENDEE and ORGANIZER).
Common or displayable name associated with the component property (in this case, ATTENDEE or ORGANIZER).
Indicates the URI that points to the directory information corresponding to the ATTENDEE or ORGANIZER.
Indicates the participation status of the ATTENDEE or ORGANIZER.
This parameter may have the following values, which have the following responses and replies from Oracle Connector for Outlook and the Oracle Calendar native client:
Table 3-6 PARTSTAT Possible Values
| ATTENDEE Property Parameters | Native Client Reply | OCFO Response |
|---|---|---|
|
PARTSTAT=NEEDS-ACTION |
Decide later |
None |
|
PARTSTAT=ACCEPTED |
Accepted |
Accepted |
|
PARTSTAT=DECLINED |
Declined |
Declined |
|
PARTSTAT=DECLINED X-ORACLE-UNAVAILABLE=TRUE (This is only applicable when connecting to Release 2 (9.0.4) of the Oracle Calendar server) |
Declined; would prefer another time |
Declined |
|
PARTSTAT=TENTATIVE |
Accepted; would prefer another time |
Tentative |
Note that X-ORACLE-UNAVAILABLE is only meaningful when set to TRUE and PARTSTAT is set to DECLINED.
Uniquely identifies Oracle Collaboration Suite users.
The following is an example of this property:
ATTENDEE;X-ORACLE-GUID=D99DBDBAAF8D6D3DE0340003BA18F2E9:mailto: john.doe@example.com
Specifies the personal comment of a Calendar user. This parameter can be specified in the ATTENDEE property.
The value type of this property is a BASE64 encoded character string as defined by RFC 2045.
The following is an example of an attendee component with the X-ORACLE-PERSONAL-COMMENT property defined:
ATTENDEE;X-ORACLE-PERSONAL-COMMENT= RoaXMgaXMgYSBtdWx0aS1saW5lXG4NCiAgcGVyc29uYWwgYW5ub3RhdGlvbi4gV2l0aC BhIGJ1bmNoIG9mIHNwZWNpYWxcbg0KICBjaGFyIHN1Y2ggYXMgY29tbWEgKCwpIHNlbWkt Y29sb24gKDspLCBhbmQgZG91YmxlLQ0KICBxdW90ZSAoXCIpLiI=: MAILTO:john.doe@example.com
If set to TRUE, specifies that the DESCRIPTION property of the VEVENT component was modified after the value of the X-ORACLE-PERSONAL-COMMENT and X-ORACLE-PERSONAL-COMMENT-RTF parameters were last modified. This parameter can be specified on the ATTENDEE property.
Describes business and personal contacts in a Calendar user's address book. The following is a sample of a vCard:
BEGIN:VCARD UID:ORACLE:CALSERV:CONTACT/AAAAAAAABBBBBBBBCCCCCCCCDDDDDDDD REV:20040802T195051Z EMAIL;TYPE=PREF;TYPE=INTERNET:calendar.user@my-company.com ADR;TYPE=X-ORACLE-OTHER:;;;;;; ADR;TYPE=HOME:;;;;;; ADR;TYPE=WORK:;;;;;; N:User;Calendar;;; FN:User\, Calendar VERSION:3.0 END:VCARD
Table 3-7 Component Properties of vCard
| Component Property | Minimum Occurrences | Maximum Occurrences | Data Type |
|---|---|---|---|
|
|
1 |
n |
TEXT values separated by semicolons |
|
|
0 |
1 |
vCard (default), TEXT, URI |
|
|
0 |
1 |
DATE (default), DATE-TIME |
|
|
0 |
n |
TEXT values separated by commas |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
1 |
1 |
TEXT |
|
|
0 |
1 |
two FLOAT values separated by semicolons |
|
|
0 |
1 |
BINARY (default), TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
BINARY (default), URI |
|
|
0 |
1 |
TEXT |
|
|
1 |
1 |
TEXT (can have multiple values) |
|
|
0 |
1 |
TEXT values separated by a commas |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT values separated by semicolons |
|
|
0 |
1 |
BINARY (default), URI |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
DATE-TIME (default), DATE |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
n |
phone-number value |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
UTC-offset value (default), TEXT |
|
|
0 |
1 |
TEXT |
|
|
0 |
1 |
URI |
|
|
1 |
1 |
TEXT |
The following describes the iCalendar and Oracle-specific component properties of vCard.
Specifies information about another person who will act on behalf of the individual or resource associated with the vCard.
Specifies the birth date of the object the vCard represents. The default is a single date value. It can also be reset to a single date-time value.
Specifies a public key or authentication certificate associated with the object that the vCard represents.
Specifies the formatted text corresponding to the delivery address of the object the vCard represents. It can include the type parameter TYPE to specify the delivery label type.
Specifies the type of electronic mail software that is used by the individual associated with the vCard.
Specifies the descriptive name given instead of or in addition to the one that the vCard represents. It can also be used to specify a familiar form of a proper name specified by the FN or N types.
Specifies an image or photograph information that annotates some aspect of the object the vCard represents. The default is a binary value. It can also be reset to uri value.
Specify information concerning the role, occupation, or business category of the object the vCard represents.
Specifies the family name or given name text to be used for national-language-specific sorting of the FN and N types.
