Oracle® Calendar SDK Java API Reference
10g Release 1 (10.1.1)

B14474-01


oracle.calendar.sdk
Class Session

java.lang.Object
  extended byoracle.calendar.sdk.Session


public class Session
extends java.lang.Object

Constructor Summary
Session()
Creates a new session.

Method Summary
void authenticate(int in_flags, java.lang.String in_user, java.lang.String in_password)
Authenticates a calendar user.
void configureACE(int in_flags, java.lang.String in_authenticationMechanism, java.lang.String in_compressionMechanism, java.lang.String in_encryptionMechanism)
Configures the given session to use specific ACE (Authentication, Compression, and Encryption) mechanisms between the SDK client and the Calendar server.
void connect(int in_flags, java.lang.String in_host)
Establishes a connection with a calendar service.
void connectAsSysop(int in_flags, java.lang.String in_host, java.lang.String in_nodeId, java.lang.String in_password)
Logs on as SYSOP; once logged on, SYSOP can assume the identity of any user on the same node by calling CSDK_SetIdentity().
void deauthenticate(int in_flags)
Deauthenticates the current user.
void deleteContacts(int in_flags, java.lang.String[] in_UIDs, RequestResult out_requestResult)
Deletes vCards specified by a set of UIDs.
void deleteEvents(int in_flags, java.lang.String[] in_UIDs, java.lang.String in_RECURRENCEID, int in_modifier, RequestResult out_requestResult)
Deletes specified events; must be acting as the event owner for this to succeed.
void deleteTasks(int in_flags, java.lang.String[] in_UIDs, RequestResult out_requestResult)
Deletes tasks from the current user's agenda.
void disconnect(int in_flags)
Disconnects from the calendar server.
void dispose()
Destroys a session.
java.lang.String fetchContactsByQuery(int in_flags, Query in_query, java.lang.String[] in_vcardProperties, RequestResult out_requestResult)
Fetches contacts which satisfy the conditions specified in the query.
java.lang.String fetchContactsByUID(int in_flags, java.lang.String[] in_UIDs, java.lang.String[] in_vcardProperties, RequestResult out_requestResult)
Fetches vCards from an authenticated connection.
java.lang.String fetchEventsByAlarmRange(int in_flags, Handle[] in_agendas, java.lang.String in_start, java.lang.String in_end, java.lang.String[] in_veventProperties, RequestResult out_requestResult)
Fetches events which have alarms (reminders) that will trigger within the time range specified; the end of the time range is exclusive.
java.lang.String fetchEventsByRange(int in_flags, Handle[] in_agendas, java.lang.String in_start, java.lang.String in_end, java.lang.String[] in_veventProperties, RequestResult out_requestResult)
Fetches events which occur within the time range specified.
java.lang.String fetchEventsByUID(int in_flags, Handle in_agenda, java.lang.String[] in_UIDs, java.lang.String in_RECURRENCEID, int in_modifier, java.lang.String[] in_veventProperties, RequestResult out_requestResult)
Fetches events by their UIDs.
java.lang.String fetchTasksByAlarmRange(int in_flags, Handle[] in_agendas, java.lang.String in_start, java.lang.String in_end, java.lang.String[] in_vtodoProperties, RequestResult out_requestResult)
Fetches tasks that have alarms (reminders) that will trigger within the time range specified (the end of the time range is exclusive).
java.lang.String fetchTasksByRange(int in_flags, Handle[] in_agendas, java.lang.String in_start, java.lang.String in_end, java.lang.String[] in_vtodoProperties, RequestResult out_requestResult)
Fetches tasks which are active within the time range specified (the end of the time range is exclusive).
java.lang.String fetchTasksByUID(int in_flags, Handle in_agenda, java.lang.String[] in_UIDs, java.lang.String[] in_vtodoProperties, RequestResult out_requestResult)
Retrieves tasks with given UIDs on the given agenda.
protected void finalize()
Destroys a session.
java.lang.String getCapabilities(int in_flags, int in_capabilityID)
Returns information on this SDK release and/or the calendar server.
Handle getHandle(int in_flags, java.lang.String in_user)
Returns a handle to a particular user's calendar store.
boolean isValid()
If the Session was previosly destroyed, isValid would return false An invalid session should not be used anymore.
void setIdentity(int in_flags, java.lang.String in_user)
Allows an authenticated user to work on behalf of another calendar user or resource.
void storeContacts(int in_flags, java.lang.String in_contactData, RequestResult out_requestResult)
Stores vCards on a server through an authenticated connection by in_session; The vCards must be passed in via a CAPIStream.
void storeEvents(int in_flags, java.lang.String in_eventData, RequestResult out_requestResult)
This function reads one VCALENDAR object from in_stream and stores each contained VEVENT on the server.
void storeTasks(int in_flags, java.lang.String in_taskData, RequestResult out_requestResult)
Creates/modifies tasks on the current user's agenda depending on the store flag passed in.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Session

public Session()
        throws Api.StatusException
Creates a new session.
Throws:
Api.StatusException

Method Detail

finalize

protected void finalize()
                 throws java.lang.Throwable
Destroys a session.
Throws:
java.lang.Throwable

dispose

public void dispose()
             throws java.lang.Throwable
Destroys a session.
Throws:
java.lang.Throwable

connectAsSysop

public void connectAsSysop(int in_flags,
                           java.lang.String in_host,
                           java.lang.String in_nodeId,
                           java.lang.String in_password)
                    throws Api.StatusException
Logs on as SYSOP; once logged on, SYSOP can assume the identity of any user on the same node by calling CSDK_SetIdentity().

A node must always be specified since masternode and Calendar domain functionality is not available during logon as SYSOP.

If ACE mechanisms have been configured on the session, these will be ignored. The admin default ACE settings from the calendar server will be used for all SYSOP connections.

SYSOP authentication is only available with version 5.3 and newer servers. An error will be returned if the specified host does not support this feature. A Calendar server may be configured to refuse SYSOP logon via the SDK in which case a security error will be returned.

The operations available to SYSOPs are limited to the following:

Once the identity has been set to a user, all operations will be performed as if that user had logged in.

See CSDK_Connect() for the format of the in_host parameter.

Parameters:
in_flags - Bit flags modifying behavior. This must be CSDK_FLAG_NONE currently.
in_host - Calendar server host name (with optional port number)
in_nodeId - Node ID to connect to as SYSOP. Node aliases are not currently supported.
in_password - Node ID to connect to as SYSOP. Node aliases are not currently supported.
Throws:
Api.StatusException

connect

public void connect(int in_flags,
                    java.lang.String in_host)
             throws Api.StatusException
Establishes a connection with a calendar service.
Parameters:
in_flags - Bit flags (pass CSDK_FLAG_NONE)
in_host - Calendar server host (with optional port number, for example "calserver.acme.com" or "calserver.acme.com:12345"). The host[:port] may optionally be followed by ?/CD=<calendar domain>/
Throws:
Api.StatusException

configureACE

public void configureACE(int in_flags,
                         java.lang.String in_authenticationMechanism,
                         java.lang.String in_compressionMechanism,
                         java.lang.String in_encryptionMechanism)
                  throws Api.StatusException
Configures the given session to use specific ACE (Authentication, Compression, and Encryption) mechanisms between the SDK client and the Calendar server.

If this function is not called, the default mechanisms as set on the calendar server will be used.

The server needs proper configuration for some ACE mechanisms

NULL values can be specified to select the server's default mechanism for any of the three types of mechanisms.

Parameters:
in_flags - SDK_FLAG_NONE
in_authenticationMechanism - * @param in_compressionMechanism * @param in_encryptionMechanism * @throws Api.StatusException
Throws:
Api.StatusException

authenticate

public void authenticate(int in_flags,
                         java.lang.String in_user,
                         java.lang.String in_password)
                  throws Api.StatusException
Authenticates a calendar user.

This must be done prior to making any calls to store or fetch data.

Refer to the section on User Identification for the format of the in_user parameter.

Parameters:
in_flags - Bit flags modifying behavior. This must be CSDK_FLAG_NONE currently.
in_user - Must be a null-terminated string. Refer to the "User Identification" section for syntax.
in_password - User's password. May be NULL.
Throws:
Api.StatusException

deauthenticate

public void deauthenticate(int in_flags)
                    throws Api.StatusException
Deauthenticates the current user.

An unauthenticated server connection is kept open and can be used to re-authenticate again. The server connection is kept open until either a call to CSDK_Disconnect() or the session is destroyed.

Parameters:
in_flags - Bit flags modifying behavior. This must be CSDK_FLAG_NONE currently.
Throws:
Api.StatusException

disconnect

public void disconnect(int in_flags)
                throws Api.StatusException
Disconnects from the calendar server.
Parameters:
in_flags - Bit flags modifying behavior. This must be CSDK_FLAG_NONE currently.
Throws:
Api.StatusException

getHandle

public Handle getHandle(int in_flags,
                        java.lang.String in_user)
                 throws Api.StatusException
Returns a handle to a particular user's calendar store.

With this handle, subsequent calls can access items in this agenda. If an error is returned no CAPIHandle will be allocated and no cleanup is required.

The in_user string follows the same format as that of the string used by CSDK_Authenticate.

A handle to the current user is returned if in_user is NULL.

This function is blocked for sysop that has not assumed the identity of a user.

Parameters:
in_flags - Bit flags (none at this time, set to CSDK_FLAG_NONE)
in_user - User as defined for CSDK_Authenticate. May be NULL in which case a handle to the current user is returned.
Throws:
Api.StatusException

setIdentity

public void setIdentity(int in_flags,
                        java.lang.String in_user)
                 throws Api.StatusException
Allows an authenticated user to work on behalf of another calendar user or resource.

For subsequent calls to this function to work, designate rights must have been granted to the authenticated user.

The format of the in_user parameter is the same as in the CSDK_Authenticate function. The authenticated user may revert to his or her original identity by using NULL as username.

If you've logged in as Calendar SYSOP (CSDK_ConnectAsSysop), then designate rights are ignored and you will be able to work as any Calendar user or resource. All Calendar operations will appear to have been done by the user, rather than on behalf of the user by a designate.

Parameters:
in_flags - Bit flags (CSDK_FLAG_NONE at this time)
in_user - Person (or resource) to work as, an X400 or UID
Throws:
Api.StatusException

getCapabilities

public java.lang.String getCapabilities(int in_flags,
                                        int in_capabilityID)
                                 throws Api.StatusException
Returns information on this SDK release and/or the calendar server.
Parameters:
in_flags - : CSDK_FLAG_NONE at this time
in_capabilityID - : ID for a capability (see CAPI_CAPAB_* in ctapi.h)
Returns:
String The value of the requested capability
Throws:
Api.StatusException

storeEvents

public void storeEvents(int in_flags,
                        java.lang.String in_eventData,
                        RequestResult out_requestResult)
                 throws Api.StatusException
This function reads one VCALENDAR object from in_stream and stores each contained VEVENT on the server.

Attendees

Unlike CAPI_StoreEvent, the only attendees of the event will be those specified using ATTENDEE properties in the iCalendar (with the exception of the case where CSDK_FLAG_STORE_INVITE_SELF is used, in which case the logged-in user will always be invited regardless of whether an ATTENDEE property is supplied for that user).

The address specified in the ATTENDEE properties is used to identify calendar users. If no calendar user exists with the address specified in the ATTENDEE property value, then the attendee is considered "external" and will be invited using an Internet standard protocol such as iMIP if the calendar server is capable of doing so.

The ATTENDEE PARTSTAT parameter is ignored except for the following:

Resources

The Oracle Calendar Server stores a PARTSTAT value for each resource, but resources do not have e-mail addresses. To permit the usage of the ATTENDEE property for inviting resources, the following syntax is supported:

ATTENDEE;CUTYPE=RESOURCE;CN=projecter:MAILTO:ignored@foobar.com

Groups

Oracle Calendar Groups can be invited using a non-standard (but legal) ATTENDEE property of the following form:

ATTENDEE;CUTYPE=GROUP;CN=developers:MAILTO:ignored@foobar.com

As suggested by the example, the property value (MAILTO:ignored@foobar.com) is NOT used. In this example, the group "developers" will be expanded and the members will be invited as calendar users. When fetching this event, the members of the group (at the time of the call to CSDK_StoreEvents) will be returned as individual ATTENDEE properties.

The server does not enforce uniqueness of group names - if multiple matches are found, an error will be returned.

Errors

Detailed error information is returned through the out_requestResult parameter. Unless a parse error result is returned, there will be at least one result per VEVENT stored, containing a CAPI_STATUS value for storing that VEVENT. Passing in a NULL (zero) value for out_requestResult will prevent the request results from being returned, but is not considered an error.

Recurrence Rules

Recurrence rules (RRULE) are supported by this function and require that the event's DTSTART be specified in local (using a TZID=... and a VTIMEZONE component) or floating time (as per RFC 2445). A limitation of the calendar server requires that no more that one RRULE can be specified for a given VEVENT, nor can the RRULE be changed when modifying an event (the only way to change the occurrences is to use RDATEs and/or EXDATEs).

UIDs

The calendar server prevents any user/resource from owning more than one event with a given UID. However, UIDs are not necessarily unique on the calendar server, so a user/resource may be invited to more than one event with a given UID. Users of the SDK should attempt to provide globally unique UIDs when adding events to the calendar server.

Storing an event without a UID will result in a new UID being generated by the calendar server and there will be a small performance penalty. The generated UIDs are returned as part of the results in out_requestResult.

Per-Instance Properties (DESCRIPTION and ATTACH)

Currently there are only two such properties, DESCRIPTION and ATTACH. These properties are in one of the following states for a given instance:

If an event has only one instance, by default, that instance property becomes the event's property.

To replace or modify these properties, use the flags CSDK_FLAG_STORE_MODIFY and CSDK_FLAG_STORE_REPLACE.

To modify, replace, or remove a property defined in an instance, the RECURRENCE-ID of the instance must be specified in the VEVENT passed as input.

To modify, replace, or remove a property defined in an event, do not specify a RECURRENCE-ID in the VEVENT passed in input.

Example 1: You have a meeting with three instances and all instances use the ATTACH property defined in the event. This property refers to the file attach1.txt. You want to modify the attachment of that event (for each of the 3 instances) so that the property refers to the file attach2.txt instead. You therefore need to use the flag CSDK_FLAG_STORE_MODIFY and a VEVENT without a RECURRENCE-ID that contains an ATTACH property that refers to attach2.txt. The ATTACH property will be modified at the event level, so all three instances will now refer to attach2.txt.

Example 2: You have a meeting with three instances and all the instances use the event's ATTACH property. This property refers to attach1.txt. You want to modify the ATTACH property of the third instance so that it refers to attach2.txt. You therefore need to use the flag CSDK_FLAG_STORE_MODIFY and a VEVENT with the RECURRENCE-ID of the third instance that contains an ATTACH property that refers to the new attachment. The ATTACH property will be modified for the third instance, which will now refer to attach2.txt. The first two instances will still refer to attach1.txt.

How Can I...

Parameters:
in_flags - Bit flags modifying behavior. It may be one of the following:
  • CSDK_FLAG_STORE_CREATE: Create if no event with the given UID exists, otherwise return an error
  • CSDK_FLAG_STORE_REPLACE: Completely replace event on server with this copy, error if object doesn't exist
  • CSDK_FLAG_STORE_IMPORT: If event exists, CSDK_FLAG_STORE_REPLACE, else CSDK_FLAG_STORE_CREATE
  • CSDK_FLAG_STORE_MODIFY: Modify only the supplied properties of an existing event
  • CSDK_FLAG_STORE_REPLY: Any attendee of an event can use this mode to update their own attendance status and alarms
and optionally, a combination of:
  • CSDK_FLAG_STORE_INVITE_SELF: Add current user as an attendee, even if no ATTENDEE is in the iCal
  • CSDK_FLAG_STREAM_NOT_MIME: Incoming stream is not inside a MIME wrapper
  • CAPI_NOTIFY_EMAIL: Send e-mail notification (default is to NOT send)
  • CAPI_NOTIFY_SMS: Send SMS notification (default is to NOT send)
out_requestResult - If non-NULL, will be filled in with detailed results of the transaction. This may include error messages from reading the iCalendar data or any other errors encountered while processing the request.
in_eventData - String containing the iCalendar data to be stored
Throws:
Api.StatusException

deleteEvents

public void deleteEvents(int in_flags,
                         java.lang.String[] in_UIDs,
                         java.lang.String in_RECURRENCEID,
                         int in_modifier,
                         RequestResult out_requestResult)
                  throws Api.StatusException
Deletes specified events; must be acting as the event owner for this to succeed.

This does not "uninvite" attendees; it deletes the event. Individual (or a range) of instances can be deleted using {in_RECURRENCEID, in_modifier}, but only a single UID can be used in this case.

Parameters:
in_flags - Bit Flags:
  • CSDK_FLAG_NONE: Default behavior
  • CSDK_FLAG_CONTINUE_ON_ERROR: if the delete fails on one UID we still delete the other valid UIDs. out_requestResult will contain information on every UID we tried to fetch.
in_UIDs - An array of strings containing the UID(s) of the event(s) to delete. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string.
in_RECURRENCEID - To delete ALL occurrences of an event, pass in NULL or an empty string. To delete individual (or a range of) occurrences, specify an iCalendar recurrence-id in either DATE or DATE-TIME format that identifies one occurrence of the event.
in_modifier - When a recurrence-id is specified using in_RECURRENCEID, this modifier determines whether the specified occurrences, or a range of occurrences will be deleted. The following are the possible values:
  • CAPI_THISINSTANCE
  • CAPI_THISANDPRIOR
  • CAPI_THISANDFUTURE
out_requestResult - If non-NULL, will be filled in with detailed results of the transaction
Throws:
Api.StatusException

fetchEventsByUID

public java.lang.String fetchEventsByUID(int in_flags,
                                         Handle in_agenda,
                                         java.lang.String[] in_UIDs,
                                         java.lang.String in_RECURRENCEID,
                                         int in_modifier,
                                         java.lang.String[] in_veventProperties,
                                         RequestResult out_requestResult)
                                  throws Api.StatusException
Fetches events by their UIDs.

Specific instances of one event may be fetched using the in_RECURRENCEID and in_modifier parameters.

Specific properties can be requested using the in_requestProperties parameter. This parameter is a NULL(zero)-terminated or "empty string"-terminated array of C strings containing the property names to be returned.

For maximum performance, limit the properties you request (particularly the ATTENDEE property) to only what you need.

Parameters:
in_flags - Bit flags:
  • CSDK_FLAG_NONE: Default behavior
  • CSDK_FLAG_FETCH_AGENDA_ATTENDEE_ONLY: Only get/return ATTENDEE for the agenda being viewed
  • CSDK_FLAG_FETCH_LOCALTIMES: Return all dates & times in the user's time zone (the user's time zone preference stored on the calendar server)
  • CSDK_FLAG_FETCH_EXPAND_RRULE: Expand recurrence rules and return a set of VEVENTs one per instance generated by the recurrence rule
  • CSDK_FLAG_CONTINUE_ON_ERROR: if the fetch fails on one uid we still fetch the other valid UIDs and return the stream with these *valid* events. out_requestResult will contain information on every UID we tried to fetch.
  • CSDK_FLAG_STREAM_NOT_MIME: Do not wrap the iCalendar in a MIME container
in_agenda - The agenda on which to search for event(s) with the given UID(s). A NULL value will search on the current user's agenda.
in_UIDs - An array of strings containing the UID(s) of the events to fetch. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string.
in_RECURRENCEID - To fetch ALL occurrences of an event, pass in NULL or an empty string. To fetch individual (or a range of) occurrences, specify an iCalendar recurrence-id in either DATE or DATE-TIME format which identifies one occurrence of the event.
in_modifier - When a recurrence-id is specified using in_RECURRENCEID, this modifier determines whether the specified occurrences, or a range of occurrences will be fetched. Values are:
  • CAPI_THISINSTANCE
  • CAPI_THISANDPRIOR
  • CAPI_THISANDFUTURE
in_veventProperties - To fetch only specific iCalendar properties of the events, pass in an array of property names. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string. An empty array (such as NULL or an empty string), will cause all available properties to be returned.
out_requestResult - If non-NULL, will be filled in with detailed results of the transaction.
Throws:
Api.StatusException

fetchEventsByAlarmRange

public java.lang.String fetchEventsByAlarmRange(int in_flags,
                                                Handle[] in_agendas,
                                                java.lang.String in_start,
                                                java.lang.String in_end,
                                                java.lang.String[] in_veventProperties,
                                                RequestResult out_requestResult)
                                         throws Api.StatusException
Fetches events which have alarms (reminders) that will trigger within the time range specified; the end of the time range is exclusive.
Parameters:
in_flags - Bit flags:
  • CSDK_FLAG_NONE: Default behavior
  • CSDK_FLAG_FETCH_AGENDA_ATTENDEE_ONLY: Only get/return ATTENDEE for the agenda being viewed
  • CSDK_FLAG_FETCH_COMBINED: Return all events in one VCALENDAR rather than one VCALENDAR per agenda. This is faster.
  • CSDK_FLAG_FETCH_EXCLUDE_HOLIDAYS: Do not fetch holidays
  • CSDK_FLAG_FETCH_EXCLUDE_DAILYNOTES: Do not fetch daily notes
  • CSDK_FLAG_FETCH_EXCLUDE_DAYEVENTS: Do not fetch day events
  • CSDK_FLAG_FETCH_EXCLUDE_APPOINTMENTS: Do not appointments
  • CSDK_FLAG_FETCH_EXCLUDE_ACCEPTED: Do not fetch accepted events
  • CSDK_FLAG_FETCH_EXCLUDE_DECLINED: Do not fetch declined events
  • CSDK_FLAG_FETCH_EXCLUDE_UNCONFIRMED: Do not fetch unconfirmed events
  • CSDK_FLAG_FETCH_LOCALTIMES: Return all dates and times in the user's time zone (the user's time zone preference stored on the calendar server)
  • CSDK_FLAG_FETCH_DO_NOT_EXPAND_RRULE: Do not expand recurrence rules. This will cause the entire event to be returned instead of only the instances which have alarms scheduled to trigger during the range.
  • CSDK_FLAG_STREAM_NOT_MIME: Do not wrap the iCalendar in a MIME container
in_agendas - The agenda(s) in which to search for events. This parameter is an array of CAPIHandles, and MUST be terminated with a zero value (CSDK_HANDLE_INITIALIZER). A NULL value, or an empty array will search on the current user's agenda.
in_start - Beginning of date/time range. May be of any of the following forms:
  • DATE: For example, 20020928
  • DATE-TIME: Must be in either floating (for example, 20020929T120000) or UTC time (e.g. 20020929T170000Z). Floating time uses the user's time zone (the user's time zone preference stored on the Calendar server).
  • DURATION: A relative date or date-time expressed using the duration notation (for example, +PT5DT3H represents 5 days 3 hours in the future, -PT1W 1 week in the past). in_start is relative to the current time at the moment of the fetch.
in_end - End of date/time range. May be in any of the formats shown for in_start.
  • NOTE for DURATION: duration specified as the in_end is relative to the in_start. ex: in_end = +P2D, means in_end = in_start + 2 Days
in_veventProperties - To fetch only specific iCalendar properties of the events, pass in an array of property names. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string. An empty array (such as NULL or an empty string) will cause all available properties to be returned.
out_requestResult - If non-NULL, will be filled in with detailed results of the transaction.
Throws:
Api.StatusException

fetchEventsByRange

public java.lang.String fetchEventsByRange(int in_flags,
                                           Handle[] in_agendas,
                                           java.lang.String in_start,
                                           java.lang.String in_end,
                                           java.lang.String[] in_veventProperties,
                                           RequestResult out_requestResult)
                                    throws Api.StatusException
Fetches events which occur within the time range specified. The end of the time range is exclusive.
Parameters:
in_flags - Bit flags:
  • CSDK_FLAG_NONE: Default behavior
  • CSDK_FLAG_FETCH_AGENDA_ATTENDEE_ONLY: Only get/return ATTENDEE for the agenda being viewed
  • CSDK_FLAG_FETCH_COMBINED: Return all events in one VCALENDAR rather than one VCALENDAR per agenda. This is faster.
  • CSDK_FLAG_FETCH_EXCLUDE_HOLIDAYS: Do not fetch holidays
  • CSDK_FLAG_FETCH_EXCLUDE_DAILYNOTES: Do not fetch daily notes
  • CSDK_FLAG_FETCH_EXCLUDE_DAYEVENTS: Do not fetch day events
  • CSDK_FLAG_FETCH_EXCLUDE_APPOINTMENTS: Do not appointments
  • CSDK_FLAG_FETCH_EXCLUDE_ACCEPTED: Do not fetch accepted events
  • CSDK_FLAG_FETCH_EXCLUDE_DECLINED: Do not fetch declined events
  • CSDK_FLAG_FETCH_EXCLUDE_UNCONFIRMED: Do not fetch unconfirmed events
  • CSDK_FLAG_FETCH_LOCALTIMES: Return all dates & times in the user's time zone (the user's time zone preference stored on the calendar server)
  • CSDK_FLAG_FETCH_DO_NOT_EXPAND_RRULE: Do not expand recurrence rules. This will cause the entire event to be returned instead of only the instances which fall during the range.
  • CSDK_FLAG_STREAM_NOT_MIME: Do not wrap the iCalendar in a MIME container
in_agendas - The agenda(s) in which to search for events. This parameter is an array of CAPIHandles, and MUST be terminated with a zero value (CSDK_HANDLE_INITIALIZER). A NULL value, or an empty array will search on the current user's agenda.
in_start - Beginning of date/time range. May be of any of the following forms:
  • DATE: For example, 20020928
  • DATE-TIME: Must be in either floating (for example, 20020929T120000) or UTC time (e.g. 20020929T170000Z). Floating time uses the user's time zone (the user's time zone preference stored on the Calendar server).
  • DURATION: A relative date or date-time expressed using the duration notation (for example, +PT5DT3H represents 5 days 3 hours in the future, -PT1W 1 week in the past). in_start is relative to the current time at the moment of the fetch.
in_end - End of date/time range. May be in any of the formats shown for in_start.
  • NOTE for DURATION: duration specified as the in_end is relative to the in_start. ex: in_end = +P2D, means in_end = in_start + 2 Days
in_veventProperties - To fetch only specific iCalendar properties of the events, pass in an array of property names. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string. An empty array (such as NULL or an empty string), will cause all available properties to be returned.
out_requestResult - If non-NULL, will be filled in with detailed results of the transaction.
Throws:
Api.StatusException

storeTasks

public void storeTasks(int in_flags,
                       java.lang.String in_taskData,
                       RequestResult out_requestResult)
                throws Api.StatusException
Creates/modifies tasks on the current user's agenda depending on the store flag passed in.

Only one store flag should be used. If multiple flags are passed the error CAPI_STAT_API_FLAGS will be returned. The following flags may be used:

Other flags may be specified along with one of the above store flags:

This function is blocked for SYSOP that has not assumed the identity of a user.

Parameters:
in_flags - Store flag
in_taskData - String containing a VCALENDAR with one or more VTODOs
out_requestResult - Returned request result object (may be NULL)
Throws:
Api.StatusException

isValid

public boolean isValid()
If the Session was previosly destroyed, isValid would return false An invalid session should not be used anymore. The reason this function is not synchronized is that it will be called inside blocks that already synchronized the session (that would be a deadlock). That means that by the time this function returned true, the state of the Session might have change and the Session became invalid.
Returns:
true if session is valid, false otherwise

fetchTasksByRange

public java.lang.String fetchTasksByRange(int in_flags,
                                          Handle[] in_agendas,
                                          java.lang.String in_start,
                                          java.lang.String in_end,
                                          java.lang.String[] in_vtodoProperties,
                                          RequestResult out_requestResult)
                                   throws Api.StatusException
Fetches tasks which are active within the time range specified (the end of the time range is exclusive).
Parameters:
in_flags - Bit flags:
  • CSDK_FLAG_NONE
  • CSDK_FLAG_STREAM_NOT_MIME: Do not wrap the iCalendar in a MIME container
in_agendas - The agenda(s) on which to search for tasks. This parameter is an array of CAPIHandles, and MUST be terminated with a zero value (CSDK_HANDLE_INITIALIZER). A NULL value, or an empty array will search on the current user's agenda.
in_start - Beginning of date/time range. May be of any of the following forms:
  • DATE: For example, 20020928
  • DATE-TIME: Must be in either floating (for example, 20020929T120000) or UTC time (for example, 20020929T170000Z)
  • DURATION: A relative date or date-time expressed using the duration notation (for example, +PT5DT3H represents 5 days 3 hours in the future, -PT1W 1 week in the past). in_start is relative to the current time at the moment of the fetch.
in_end - End of date/time range. May be in any of the formats shown for in_start.
  • NOTE for DURATION: duration specified as the in_end is relative to the in_start. ex: in_end = +P2D, means in_end = in_start + 2 Days
in_vtodoProperties - To fetch only specific iCalendar properties of the tasks, pass in an array of property names. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string. An empty array (i.e. NULL or an empty string), will cause all available properties to be returned.
out_requestResult - If non-NULL, will be filled in with detailed results of the transaction.
Throws:
Api.StatusException

fetchTasksByUID

public java.lang.String fetchTasksByUID(int in_flags,
                                        Handle in_agenda,
                                        java.lang.String[] in_UIDs,
                                        java.lang.String[] in_vtodoProperties,
                                        RequestResult out_requestResult)
                                 throws Api.StatusException
Retrieves tasks with given UIDs on the given agenda.
Parameters:
in_flags - Bit flags:
  • CSDK_FLAG_NONE
  • CSDK_FLAG_CONTINUE_ON_ERROR: if the fetch fails on one uid we still fetch the other valid UIDs and return the stream with these *valid* events. out_requestResult will contain information on every UID we tried to fetch.
  • CSDK_FLAG_STREAM_NOT_MIME: Do not wrap the iCalendar in a MIME container
in_agenda - The agenda on which to search for tasks with the given UIDs. A NULL value will search on the current user's agenda.
in_UIDs - An array of strings containing the UID(s) of the tasks to fetch. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string.
in_vtodoProperties - To fetch only specific iCalendar properties of the tasks, pass in an array of property names. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string. An empty array (i.e. NULL or an empty string), will cause all available properties to be returned.
out_requestResult - If non-NULL, will be filled in with detailed results of the transaction.
Throws:
Api.StatusException

fetchTasksByAlarmRange

public java.lang.String fetchTasksByAlarmRange(int in_flags,
                                               Handle[] in_agendas,
                                               java.lang.String in_start,
                                               java.lang.String in_end,
                                               java.lang.String[] in_vtodoProperties,
                                               RequestResult out_requestResult)
                                        throws Api.StatusException
Fetches tasks that have alarms (reminders) that will trigger within the time range specified (the end of the time range is exclusive).
Parameters:
in_flags - Bit flags:
  • CSDK_FLAG_NONE
  • CSDK_FLAG_STREAM_NOT_MIME: Do NOT wrap the iCalendar in a MIME container
  • in_agendas - The agenda(s) on which to search for tasks. This parameter is an array of CAPIHandles, and MUST be terminated with a zero value (CSDK_HANDLE_INITIALIZER). A NULL value, or an empty array will search on the current user's agenda.
    in_start - Beginning of date/time range. May be in any of the following forms:
    • DATE: For example, 20020928
    • DATE-TIME: Must be in either floating (for example, 20020929T120000) or UTC time (for example, 20020929T170000Z)
    • DURATION: A relative date or date-time expressed using the duration notation (for example, +PT5DT3H represents 5 days 3 hours in the future, -PT1W 1 week in the past). in_start is relative to the current time at the moment of the fetch.
    in_end - End of date/time range. May be in any of the formats shown for in_start.
    • NOTE for DURATION: duration specified as the in_end is relative to the in_start. ex: in_end = +P2D, means in_end = in_start + 2 Days
    in_vtodoProperties - To fetch only specific iCalendar properties of the tasks, pass in an array of property names. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string. An empty array (such as NULL or an empty string), will cause all available properties to be returned.
    out_requestResult - If non-NULL, will be filled in with detailed results of the transaction.
    Throws:
    Api.StatusException

deleteTasks

public void deleteTasks(int in_flags,
                        java.lang.String[] in_UIDs,
                        RequestResult out_requestResult)
                 throws Api.StatusException
Deletes tasks from the current user's agenda.

This function is blocked for SYSOP that has not assumed the identity of a user.

Parameters:
in_flags - Bit Flags:
  • CSDK_FLAG_NONE: Default behavior
  • CSDK_FLAG_CONTINUE_ON_ERROR: if the delete fails on one uid we still delete the other valid UIDs. out_requestResult will contain information on every UID we tried to fetch.
in_UIDs - NULL terminated array of task UIDs
out_requestResult - Returned request result object
Throws:
Api.StatusException

storeContacts

public void storeContacts(int in_flags,
                          java.lang.String in_contactData,
                          RequestResult out_requestResult)
                   throws Api.StatusException
Stores vCards on a server through an authenticated connection by in_session; The vCards must be passed in via a CAPIStream.

By default, the incoming stread is assumed to be MIME-encapsulated vCard. When storing a stream that is not MIME-encapsulated, specify the flag CSDK_FLAG_STREAM_NOT_MIME.

Versions 2.1 and 3.0 of vCard are supported.

When storing multiple vCards, every vCard must be in a seperate MIME part and any MIME part containing a vCard to be stored must contain the "Content-Type: text/x-vcard" header. The only supported character sets for the MIME parts are UTF-8 and US-ASCII.

The following are the store modes that can be used:

  • CAPI_FLAG_NONE: A regular store of one or more vCards. If the vCard contains a UID property, that property is read and a verification is made to ensure that the contact does not already exist on the server. If it does, CAPI_STAT_DATA_VCARD_DUPERROR is returned and the contact is not stored on the server.
  • CSDK_FLAG_STORE_REPLACE: This completely replaces a vCard that already exists on the the server. It reads the UID contained within the UID property of the given vCard, removes that contact from the server, and stores the new one. An error is returned if no contact with the given UID exists on the server.
  • CSDK_FLAG_STORE_MODIFY: Updates a contact already on the server with the new vCard. The UID is extracted in the same way as in _MODIFY and _NONE. The vCard with that UID is then updated: all properties contained in the vCard on the server that are present in the passed-in vCard are modified to contain the property values of the passed-in vCard. Also, All properties that exist in the passed-in vCard that don't exist on the server vCard are added to the server vCard. All other properties not present in the passed-in vCard that exist on the server are ignored.
  • CSDK_FLAG_STORE_REMOVE: The contact on the server is fetched, the properties contained within the passed-in vCard are deleted from the fetched vCard, and then the fetched vCard is stored onto the server.
  • CSDK_FLAG_STORE_IMPORT: This mode checks if the contact already exists on the server via the UID. If it does, then it acts exactly as if CSDK_FLAG_STORE_REPLACE was passed in. Otherwise, it acts exactly like as if CSDK_FLAG_STORE_CREATE was passed in.

The flags supplied are used for each vCard supplied. Results are written to the CSDKRequestResult.

This version of the SDK cannot preserve the supplied UIDs when adding contacts to the server. This ability is planned for the next major release of the SDK with the next major server release.

The CSDKRequestResult contains the UIDs which can be used to refer to the stored vCards.

The CSDKRequestResult may contain information about errors parsing the vCard streams.

This function is blocked for SYSOP that has not assumed the identity of a user.

Parameters:
in_flags - Flags modifying behavior. One of the following:
  • CSDK_FLAG_STORE_CREATE: Create if no task with the given UID exists, otherwise return an error
  • CSDK_FLAG_STORE_REPLACE: Completely replace task on server with this copy - error if object doesn't exist
  • CSDK_FLAG_STORE_IMPORT: If task exists, CSDK_FLAG_STORE_REPLACE, else CSDK_FLAG_STORE_CREATE
  • CSDK_FLAG_STORE_MODIFY: Modify only the supplied properties of an existing task
  • CSDK_FLAG_STORE_REMOVE: Remove specified properties
and optionally:
  • CSDK_FLAG_STREAM_NOT_MIME: Incoming stream is not inside a MIME wrapper
in_contactData - String containing one or more vCards
out_requestResult - Pointer to a RequestResult that will get filled (pass NULL if you don't want this information returned).
Throws:
Api.StatusException

fetchContactsByUID

public java.lang.String fetchContactsByUID(int in_flags,
                                           java.lang.String[] in_UIDs,
                                           java.lang.String[] in_vcardProperties,
                                           RequestResult out_requestResult)
                                    throws Api.StatusException
Fetches vCards from an authenticated connection.

The fetched vCards are by default in MIME format. Each vCard fetched vCard will be in a separate MIME part. The character set will be UTF-8.

To avoid having the stream MIME-encapsulated, pass in the flag CSDK_FLAG_STREAM_NOT_MIME.

This function is blocked for SYSOP that has not assumed the identity of a user.

Parameters:
in_flags - Bit flags:
  • CSDK_FLAG_NONE
  • CSDK_FLAG_STREAM_NOT_MIME: Do not wrap the output in a MIME container
  • CSDK_FLAG_CONTINUE_ON_ERROR: if the fetch fails on one uid we still fetch the other valid uid's and return the stream with these *valid* events. out_requestResult will contain information on every uid's we tried to fetch.
in_UIDs - NULL terminated array of strings containing UIDs of vCards to fetch
in_vcardProperties - To fetch only specific vCard properties of the contacts, pass in an array of property names. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string. An empty array (i.e. NULL or an empty string), will cause all available properties to be returned.
out_requestResult - To fetch only specific vCard properties of the contacts, pass in an array of property names. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string. An empty array (i.e. NULL or an empty string), will cause all available properties to be returned.
Throws:
Api.StatusException

fetchContactsByQuery

public java.lang.String fetchContactsByQuery(int in_flags,
                                             Query in_query,
                                             java.lang.String[] in_vcardProperties,
                                             RequestResult out_requestResult)
                                      throws Api.StatusException
Fetches contacts which satisfy the conditions specified in the query.

The returned vCards are returned via in_sendStream, and by default will be in MIME format. Each vCard fetched vCard will be in a separate MIME part. The character set will be UTF-8.

To avoid having the stream MIME-encapsulated, pass in the flag CSDK_FLAG_STREAM_NOT_MIME.

Currently the supported types for the queries are N, FN, BDAY, TITLE, ROLE, NOTE, CATEGORIES, NICKNAME, X-ORACLE-SPOUSE, X-ORACLE-ANNIVERSARY, X-ORACLE-OFFICE, and X-ORACLE-ASSISTANTNAME.

Parameters:
in_query - A query object containing the search criteria
in_flags - Bit flags
  • CSDK_FLAG_NONE
  • CSDK_FLAG_STREAM_NOT_MIME: Do NOT wrap the output in a MIME container
in_vcardProperties - To fetch only specific vCard properties of the contacts, pass in an array of property names. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string. An empty array (i.e. NULL or an empty string), will cause all available properties to be returned.
out_requestResult - To fetch only specific vCard properties of the contacts, pass in an array of property names. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string. An empty array (i.e. NULL or an empty string), will cause all available properties to be returned.
Throws:
Api.StatusException

deleteContacts

public void deleteContacts(int in_flags,
                           java.lang.String[] in_UIDs,
                           RequestResult out_requestResult)
                    throws Api.StatusException
Deletes vCards specified by a set of UIDs.

This function is blocked for SYSOP that has not assumed the identity of a user.

Parameters:
in_flags - Bit flags:
  • CSDK_FLAG_NONE
  • CSDK_FLAG_CONTINUE_ON_ERROR: if the fetch fails on one uid we still fetch the other valid uid's and return the stream with these *valid* events. out_requestResult will contain information on every uid's we tried to fetch.
in_UIDs - NULL terminated array of strings containing UIDs of vCards to delete
out_requestResult - To fetch only specific vCard properties of the contacts, pass in an array of property names. The array MUST be terminated with either a NULL (zero) pointer, or an empty (length zero) string. An empty array (i.e. NULL or an empty string), will cause all available properties to be returned.
Throws:
Api.StatusException

Oracle® Calendar SDK Java API Reference
10g Release 1 (10.1.1)

B14474-01

Copyright © 1998, 2005, Oracle. All rights reserved.