| Oracle® Calendar Application Developer's Guide 10g Release 1 (10.1.2) Part Number B25489-01 |
|
|
View PDF |
| Oracle® Calendar Application Developer's Guide 10g Release 1 (10.1.2) Part Number B25489-01 |
|
|
View PDF |
This chapter contains detailed information on functions included with the Oracle Calendar SDK.
This section provides details on the following functions:
Table 4-1 Functions
| Function Declaration | Description |
|---|---|
|
CAPIStatus CSDK_AddConditionToQuery (CSDKQuery in_query, CSDKCondition *in_condition, CSDKOperator in_operator) |
Adds a condition to a query object. |
|
CAPIStatus CSDK_Authenticate (CAPISession in_session, CAPIFlag in_flags, const char *in_user, const char *in_password) |
Authenticates a calendar user. |
|
CAPIStatus CSDK_ConfigureACE (CAPISession in_session, CAPIFlag in_flags, const char *in_authenticationMechanism, const char *in_compressionMechanism, const char *in_encryptionMechanism) |
Configures the given session to use specific ACE (Authentication, Compression, and Encryption) mechanisms between the SDK client and the Calendar server. |
|
CAPIStatus CSDK_Connect (CAPISession in_session, CAPIFlag in_flags, const char *in_host) |
Establishes a connection with a calendar service. |
|
CAPIStatus CSDK_ConnectAsSysop (CAPISession in_session, CAPIFlag in_flags, const char *in_host, const char *in_nodeId, const char *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(). |
|
CAPIStatus CSDK_CreateCallbackStream (CAPISession in_session, CAPIStream *out_stream, CAPICallback in_sendCallback, void *in_sendUserData, CAPICallback in_recvCallback, void *in_recvUserData, CAPIFlag in_flags) |
Creates a callback stream that can be used to either supply data to, or receive data from, the SDK. |
|
CAPIStatus CSDK_CreateFileStreamFromFilenames (CAPISession in_session, CAPIStream *out_stream, const char *in_readFileName, const char *in_readMode, const char *in_writeFileName, const char *in_writeMode, CAPIFlag in_flags) |
Creates a file stream to allow the SDK to read from or write to files. |
|
CAPIStatus CSDK_CreateMemoryStream (CAPISession in_session, CAPIStream *out_stream, const char *in_readBuffer, const char **out_writeBufferPtr, CAPIFlag in_flags) |
Creates a memory stream, which uses data buffers to pass data between your application and the SDK. |
|
CAPIStatus CSDK_CreateQuery (CSDKCondition *in_condition, CSDKQuery *out_query) |
Creates a query object to be used with CSDK_FetchEventsByQuery or CSDK_FetchContactsByQuery. |
|
CAPIStatus CSDK_CreateSession (CAPIFlag in_flags, CAPISession *out_session) |
Creates a new session. |
|
CAPIStatus CSDK_Deauthenticate (CAPISession in_session, CAPIFlag in_flags) |
Deauthenticates the current user. |
|
CAPIStatus CSDK_DeleteContacts (CAPISession in_session, CAPIFlag in_flags, CAPIUIDSet in_UIDs, CSDKRequestResult *out_requestResult) |
Deletes vCards specified by a set of UIDs. |
|
CAPIStatus CSDK_DeleteEvents (CAPISession in_session, CAPIFlag in_flags, CAPIUIDSet in_UIDs, const char *in_RECURRENCEID, int in_modifier, CSDKRequestResult *out_requestResult) |
Deletes specified events; must be acting as the event owner for this to succeed. |
|
CAPIStatus CSDK_DeleteTasks (CAPISession in_session, CAPIFlag in_flags, CAPIUIDSet in_UIDs, CSDKRequestResult *out_requestResult) |
Deletes tasks from the current user's agenda. |
|
CAPIStatus CSDK_DestroyHandle (CAPISession in_session, CAPIHandle *in_handle) |
Destroys one handle. |
|
CAPIStatus CSDK_DestroyMultipleHandles (CAPISession in_session, CAPIHandle *in_handles, int in_numHandles, CAPIFlag in_flags) |
Destroys multiple handles returned by calls to CSDK_GetHandle(). |
|
CAPIStatus CSDK_DestroyMultipleStreams (CAPISession in_session, CAPIStream *in_streams, int in_numStreams, CAPIFlag in_flags) |
Destroys streams created by the various CSDK_Create...Stream functions. |
|
CAPIStatus CSDK_DestroyQuery (CSDKQuery *io_query) |
Destroys a query object created by CSDK_CreateQuery. |
|
CAPIStatus CSDK_DestroyResult (CSDKRequestResult *io_requestResult) |
Disposes of all the results in in_requestResult. |
|
CAPIStatus CSDK_DestroySession (CAPISession *io_session) |
Destroys a session. |
|
CAPIStatus CSDK_DestroyStream (CAPISession in_session, CAPIStream *io_stream) |
Destroys a stream created by any of the various CSDK_Create...Stream functions. |
|
CAPIStatus CSDK_Disconnect (CAPISession in_session, CAPIFlag in_flags) |
Disconnects from the Oracle Calendar server. |
|
CAPIStatus CSDK_FetchContactsByQuery (CAPISession in_session, CAPIFlag in_flags, CSDKQuery in_query, const char **in_requestProperties, CAPIStream in_stream, CSDKRequestResult *out_requestResult) |
Fetches contacts which satisfy the conditions specified in the query. |
|
CAPIStatus CSDK_FetchContactsByUID (CAPISession in_session, CAPIFlag in_flags, CAPIUIDSet in_UIDs, const char **in_requestProperties, CAPIStream in_stream, CSDKRequestResult *out_requestResult) |
Fetches vCards from an authenticated connection. |
|
CAPIStatus CSDK_FetchEventsByAlarmRange (CAPISession in_session, CAPIFlag in_flags, CAPIHandle *in_agendas, const char *in_start, const char *in_end, const char **in_requestProperties, CAPIStream in_stream, CSDKRequestResult *out_requestResult) |
Fetches events which have alarms (reminders) that will trigger within the time range specified; the end of the time range is exclusive. |
|
CAPIStatus CSDK_FetchEventsByRange (CAPISession in_session, CAPIFlag in_flags, CAPIHandle *in_agendas, const char *in_start, const char *in_end, const char **in_requestProperties, CAPIStream in_stream, CSDKRequestResult *out_requestResult) |
Fetches events which occur within the time range specified. |
|
CAPIStatus CSDK_FetchEventsByUID (CAPISession in_session, CAPIFlag in_flags, CAPIHandle in_agenda, CAPIUIDSet in_UIDs, const char *in_RECURRENCEID, int in_modifier, const char **in_requestProperties, CAPIStream in_stream, CSDKRequestResult *out_requestResult) |
Fetches events by their UIDs. |
|
CAPIStatus CSDK_FetchTasksByAlarmRange (CAPISession in_session, CAPIFlag in_flags, CAPIHandle *in_handles, const char *in_start, const char *in_end, const char **in_requestProperties, CAPIStream in_stream, CSDKRequestResult *out_requestResult) |
Fetches tasks that have alarms (reminders) that will trigger within the time range specified (the end of the time range is exclusive). |
|
CAPIStatus CSDK_FetchTasksByRange (CAPISession in_session, CAPIFlag in_flags, CAPIHandle *in_handles, const char *in_start, const char *in_end, const char **in_requestProperties, CAPIStream in_stream, CSDKRequestResult *out_requestResult) |
Fetches tasks which are active within the time range specified (the end of the time range is exclusive). |
|
CAPIStatus CSDK_FetchTasksByUID (CAPISession in_session, CAPIHandle in_handle, CAPIFlag in_flags, CAPIUIDSet in_UIDs, const char **in_requestProperties, CAPIStream in_stream, CSDKRequestResult *out_requestResult) |
Retrieves tasks with given UIDs on the given agenda. |
|
CAPIStatus CSDK_GetCapabilities (CAPISession in_session, CAPICapabilityID in_capabilityID, CAPIFlag in_flags, const char **out_value) |
Returns information about this SDK release and/or the Oracle Calendar server. |
|
CAPIStatus CSDK_GetFirstFailure (CSDKRequestResult in_requestResult, CAPIHandle *out_user, const char **out_uid, CAPIStatus *out_status) |
Returns the first failure obtained from the function from which in_requestResult was returned. |
|
CAPIStatus CSDK_GetFirstParseError (CSDKRequestResult in_requestResult, CAPIStatus *out_status, const char **out_errorBuffer, const char **out_errorLocation, const char **out_message) |
Returns the first parsing error obtained from a request result. |
|
CAPIStatus CSDK_GetFirstResult (CSDKRequestResult in_requestResult, CAPIHandle *out_user, const char **out_uid, CAPIStatus *out_status) |
Returns the first result obtained from the function from which in_requestResult was returned. |
|
CAPIStatus CSDK_GetHandle (CAPISession in_session, const char *in_user, CAPIFlag in_flags, CAPIHandle *out_handle) |
Returns a handle to a particular user's calendar store. |
|
CAPIStatus CSDK_GetHandleInfo (CAPISession in_session, CAPIHandle in_handle, CAPIFlag in_flags, const char **out_info) |
Returns information about the agenda of the supplied handle. |
|
CAPIStatus CSDK_GetNextFailure (CSDKRequestResult in_requestResult, CAPIHandle *out_user, const char **out_uid, CAPIStatus *out_status) |
Returns the next failure contained in a CSDKRequestResult. |
|
CAPIStatus CSDK_GetNextParseError (CSDKRequestResult in_requestResult, CAPIStatus *out_status, const char **out_errorBuffer, const char **out_errorLocation, const char **out_message) |
Returns the next parsing error obtained from a request result. |
|
CAPIStatus CSDK_GetNextResult (CSDKRequestResult in_requestResult, CAPIHandle *out_user, const char **out_uid, CAPIStatus *out_status) |
Returns the next result contained in a CSDKRequestResult. |
|
CSDK_GetStatusCode (CAPIStatus in_status, int *out_statusCode) |
A status returned by the CALENDAR_SDK is composed of a status code and some extra bits giving extra context to the error that occurred. |
|
CSDK_GetStatusLevels (CAPIStatus in_status, unsigned long *out_field1, unsigned long *out_field2, unsigned long *out_field3, unsigned long *out_field4, unsigned long *out_field5) |
Decomposes a CAPIStatus into its subparts; each part of the status code specifies more precisely the actual error. |
|
CSDK_GetStatusString (CAPIStatus in_status, const char **out_errorString) |
Returns a read-only string representation of a CAPIStatus (this is generally more useful than the numeric representation). |
|
CAPIStatus CSDK_SetConfigFile (const char *in_configFileName, const char *in_logFileName) |
Allows the SDK to read configuration settings that control error logging and the other configuration parameters listed in the "Configuration" section of this manual. |
|
CAPIStatus CSDK_SetIdentity (CAPISession in_session, const char *in_user, CAPIFlag in_flags) |
Allows an authenticated user to work on behalf of another calendar user or resource. |
|
CAPIStatus CSDK_StoreContacts (CAPISession in_session, CAPIFlag in_flags, CAPIStream in_stream, CSDKRequestResult *out_requestResult) |
Stores vCards on a server through an authenticated connection by in_session; The vCards must be passed in via a CAPIStream. |
|
CAPIStatus CSDK_StoreEvents (CAPISession in_session, CAPIFlag in_flags, CAPIStream in_stream, CSDKRequestResult *out_requestResult) |
This function reads one VCALENDAR object from in_stream and stores each contained VEVENT on the server. |
|
CAPIStatus CSDK_StoreTasks (CAPISession in_session, CAPIFlag in_flags, CAPIStream in_stream, CSDKRequestResult *out_requestResult) |
Creates/modifies tasks on the current user's agenda depending on the store flag passed in. |
Adds a condition to a query object.
CAPIStatus CSDK_AddConditionToQuery ( CSDKQuery in_query, CSDKCondition * in_condition, CSDKOperator in_operator )
Each query may have multiple conditions, each AND'ed or OR'ed with the previous condition(s). There is no way to group conditions, and the OR operator (CSDK_LOP_OR) has a higher priority than the AND operator (CSDK_LOP_AND). Thus, C1 OR C2 AND C3 evaluates as (C1 OR C2) AND C3.
Parameters
A query object created by CSDK_CreateQuery
Condition to add to query
Specifies the operator to use between existing conditions and this one (for example, "OR", "AND")
Returns
CAPIStatus
Equivalent Java Method
oracle.calendar.sdk.Query.addCondition()
Authenticates a calendar user.
CAPIStatus CSDK_Authenticate ( CAPISession in_session, CAPIFlag in_flags, const char * in_user, const char * in_password )
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
Login session handle
Bit flags modifying behavior. This must be CSDK_FLAG_NONE currently.
Must be a null-terminated string. Refer to the "User Identification" section for syntax.
User's password. May be NULL.
Returns
CAPIStatus
Sample
Connect to a server running on the default port of calserver.acme.com to authenticate as userid "keithm" using default ACE settings When no node is specified, either a master node or default node must be configured on the specified host):
{
CAPISession mySession = CSDK_SESSION_INITIALIZER;
status = CSDK_CreateSession(&mySession);
if (myStatus == CAPI_STAT_OK)
{
myStatus = CSDK_Connect(mySession, CAPI_FLAG_NONE, "calserver.acme.com");
}
if (myStatus == CAPI_STAT_OK)
{
myStatus = CSDK_Authenticate(mySession,
CAPI_FLAG_NONE,
"keithm",
"abcdefg");
}
}
Sample
Connect to a server running on the default port of calserver.acme.com to authenticate as user "Keith MacDonald" using default ACE settings:
{
CAPISession mySession = CSDK_SESSION_INITIALIZER;
status = CSDK_CreateSession(&mySession);
if (myStatus == CAPI_STAT_OK)
{
myStatus = CSDK_Connect(mySession, CAPI_FLAG_NONE, "calserver.acme.com");
}
if (myStatus == CAPI_STAT_OK)
{
myStatus = CSDK_Authenticate(mySession,
CAPI_FLAG_NONE,
"?/S=MacDonald/G=Keith/ND=200/",
"abcdefg");
}
}
Sample
Connect to a server running on the default port of calserver.acme.com to authenticate as userid keithm on node 200 using default ACE settings:
{
CAPISession mySession = CSDK_SESSION_INITIALIZER;
status = CSDK_CreateSession(&mySession);
if (myStatus == CAPI_STAT_OK)
{
myStatus = CSDK_Connect(mySession, CAPI_FLAG_NONE, "calserver.acme.com");
}
if (myStatus == CAPI_STAT_OK)
{
myStatus = CSDK_Authenticate(mySession,
CAPI_FLAG_NONE,
"keithm?/ND=200/",
"abcdefg");
}
}
Sample
Connect to a server running on port 12345 of calserver.acme.com and use gssapi:kerberos5 authentication:
{
CAPISession mySession = CSDK_SESSION_INITIALIZER;
status = CSDK_CreateSession(&mySession);
if (myStatus == CAPI_STAT_OK)
{
myStatus = CSDK_Connect(mySession, CAPI_FLAG_NONE, "calserver.acme.com:12345");
}
if (myStatus == CAPI_STAT_OK)
{
myStatus = CSDK_ConfigureACE(mySession,
CAPI_FLAG_NONE,
"gssapi:kerberos5",
NULL,
NULL);
}
if (myStatus == CAPI_STAT_OK)
{
myStatus = CSDK_Authenticate(mySession,
CAPI_FLAG_NONE,
"", // don't pass in user string
""); // don't pass in password
}
}
Cleanup
A call to CSDK_Deauthenticate must be made between calls to CSDK_Authenticate
Equivalent Java Method
oracle.calendar.sdk.Session.authenticate()
Configures the given session to use specific ACE (Authentication, Compression, and Encryption) mechanisms between the SDK client and the Calendar server.
CAPIStatus CSDK_ConfigureACE ( CAPISession in_session, CAPIFlag in_flags, const char * in_authenticationMechanism, const char * in_compressionMechanism, const char * in_encryptionMechanism )
If this function is not called, the default mechanisms as set on the Oracle 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
Login session handle
SDK_FLAG_NONE
Name of authentication mechanism (for example, "cs-standard", "gssapi:kerberos5", NULL)
Name of compression mechanism (for example, "cs-simple", "NONE", NULL)
Name of encryption mechanism (for example, "cs-acipher1", "NONE", NULL)
Returns
CAPIStatus
Equivalent Java Method
oracle.calendar.sdk.Session.configureACE()
Establishes a connection with a calendar service.
CAPIStatus CSDK_Connect ( CAPISession in_session, CAPIFlag in_flags, const char * in_host )
Parameters
Login session handle
Bit flags (pass CSDK_FLAG_NONE)
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>/
Returns
CAPIStatus
Sample
Connect to the Oracle Calendar server calserver.acme.com. This connection can be used to authenticate as any user known to the masternode:
{
CAPIStatus myStatus = CAPI_STAT_OK;
CAPISession mySession = CSDK_SESSION_INITIALIZER;
myStatus = CSDK_CreateSession(CSDK_FLAG_NONE, &mySession);
if (myStatus == CAPI_STAT_OK)
{
myStatus = CSDK_connect(mySession, CSDK_FLAG_NONE, "calserver.acme.com");
}
}
Cleanup
The server connection should be released by calling CSDK_Disconnect
Equivalent Java Method
oracle.calendar.sdk.Session.connect()
Logs on as SYSOP; once logged on, SYSOP can assume the identity of any user on the same node by calling CSDK_SetIdentity().
CAPIStatus CSDK_ConnectAsSysop ( CAPISession in_session, CAPIFlag in_flags, const char * in_host, const char * in_nodeId, const char * in_password )
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 Oracle 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:
Disconnecting by calling CSDK_Disconnect()
Switching identity to a user by calling CSDK_SetIdentity()
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
Login session handle
Bit flags modifying behavior. This must be CSDK_FLAG_NONE currently.
Calendar server host name (with optional port number)
Node ID to connect to as SYSOP. Node aliases are not currently supported.
SYSOP's password
Returns
CAPIStatus
See
CSDK_SetIdentity
Equivalent Java Method
oracle.calendar.sdk.Session.connectAsSysop()
Creates a callback stream that can be used to either supply data to, or receive data from, the SDK.
CAPIStatus CSDK_CreateCallbackStream ( CAPISession in_session, CAPIStream * out_stream, CAPICallback in_sendCallback, void * in_sendUserData, CAPICallback in_recvCallback, void * in_recvUserData, CAPIFlag in_flags )
C function pointers are supplied for each action (send, receive) that the SDK will call to either read or send data.
During a CSDK_Store...() call, the SDK will call the function in_sendCallback, passing in the value in_sendUserData (which is typically used to store some context to be used by the callback function).
During a CSDK_Fetch...() call, the SDK will call the function in_recvCallback, passing in the value in_recvUserData (which is typically used to store some context to be used by the callback function).
Both types of callback functions use the same function signature:
typedef int (*CAPICallback)(
void * in_userData, // user-defined data (the value supplied in CAPI_CreateCallbackStream)
char * io_data, // buffer to read or write
size_t in_dataSize, // the number of characters to read or write
size_t * out_dataSize); // the number of characters read or written
The return values from the callbacks must be one of the following:
Send callback:
CAPI_CALLBACK_CONTINUE: There is more data to be read from the stream
CAPI_CALLBACK_DONE: There is no more data to be read from the stream
A positive integer: An error has occurred. This positive integer will be returned as part of the CAPIStatus returned in bit 5 with the value CAPI_STAT_API_CALLBACK_ERROR
Receive callback:
CAPI_CALLBACK_CONTINUE: No error
A positive integer: An error has occurred (e.g. the stream cannot receive any more data). This positive integer will be returned as part of the CAPIStatus returned in bit 5 with the value CAPI_STAT_API_CALLBACK_ERROR
When the SDK has finished writing data to the receive callback, the callback will be called with in_dataSize == 0.
In many applications, it is easier to use either a memory stream or file stream than a callback stream.
Parameters
Login session handle
On output, will point to new stream.
Send data callback
A value that will be passed to in_sendCallback
Receive data callback
A value that will be passed to in_recvCallback
Bit flags (must be CSDK_FLAG_NONE at this time)
Returns
CAPIStatus
Cleanup
The stream returned by this function must be destroyed by calling CSDK_DestroyStreams()
Return values
Both supplied callbacks were NULL
See
CSDK_CreateMemoryStream()
See
CSDK_CreateFileStreamFromFilenames()
Equivalent Java Method
None. The Java APIs only use String and StringBuffer objects to send and receive data.
Creates a file stream to allow the SDK to read from or write to files.
CAPIStatus CSDK_CreateFileStreamFromFilenames ( CAPISession in_session, CAPIStream * out_stream, const char * in_readFileName, const char * in_readMode, const char * in_writeFileName, const char * in_writeMode, CAPIFlag in_flags )
Parameters
Login session handle
On output, will point to new stream
Name of file from which to read
Mode to pass while opening in_readFileName
Name of file to which to write
Mode to pass while opening in_writeFileName
Bit flags (must be CSDK_FLAG_NONE at this time)
Returns
CAPIStatus
Cleanup
The stream returned by this function must be destroyed by calling CSDK_DestroyStreams.
Return values
An invalid mode was passed in
Failed to open a file
Sample
Store events from the file "events.ics":
CAPIStream myInputStream = NULL;
CAPIStatus status = CAPI_CreateFileStreamFromFilenames(mySession,
&myInputStream,
"events.ics",
"rb",
NULL, // no output file
NULL, // no output file mode
CSDK_FLAG_NONE);
if (status == CAPI_STAT_OK)
{
status = CAPI_StoreEvent(mySession,
myHandles,
numHandles,
handleStatus,
CAPI_STORE_REPLACE,
myInputStream);
CAPI_DestroyStreams(mySession,
&myInputStream,
1,
CSDK_FLAG_NONE);
}
Sample
Fetch events and write them to the file "myAgenda.ics":
CAPIStream myOutputStream = NULL;
CAPIStatus status = CSDK_CreateFileStreamFromFilenames(mySession,
&myOutputStream,
NULL, // no input file
NULL, // no input file mode
"myAgenda.ics",
"wb",
CSDK_FLAG_NONE);
if (status == CAPI_STAT_OK)
{
status = CAPI_FetchEventsByRange(mySession,
myHandles,
numHandles,
handleStatus,
CSDK_FLAG_NONE,
"20020722T000000",
"20020722T235900",
NULL,
0,
myOutputStream);
CAPI_DestroyStreams(mySession,
&myOutputStream,
1,
CSDK_FLAG_NONE);
}
Equivalent Java Method
None. The Java APIs only use String and StringBuffer objects to send and receive data.
Creates a memory stream, which uses data buffers to pass data between your application and the SDK.
CAPIStatus CSDK_CreateMemoryStream ( CAPISession in_session, CAPIStream * out_stream, const char * in_readBuffer, const char ** out_writeBufferPtr, CAPIFlag in_flags )
This is often the simplest type of stream to use.
Read buffers are read by the SDK during CSDK_Store...() calls and write buffers are written to by the SDK during CSDK_Fetch...() calls. The read buffers are managed by your application, whereas the SDK will allocate and free memory for the write buffers. The write buffer is freed by the SDK when the memory stream is destroyed.
Parameters
Login session handle
On output, will point to new stream.
Buffer for the SDK to read from
This address will point to the buffer CAPI is writing into.
Bit flags (must be CSDK_FLAG_NONE at this time)
Returns
CAPIStatus
Cleanup
The stream returned by this function must be destroyed by calling CSDK_DestroyStreams.
Return values
: both supplied buffers were NULL
Sample
Store events from the buffer "events":
const char events[] = "MIME-Version: 1.0\\r\\n"
"Content-Type: text/calendar\\r\\n"
"Content-Transfer-Encoding: quoted-printable\\r\\n\\r\\n"
"BEGIN:VCALENDAR\\r\\n"
"VERSION:2.0\\r\\n"
...etc
"END:VCALENDAR\\r\\n";
CAPIStream myInputStream = NULL;
CAPIStatus status = CAPI_CreateMemoryStream(mySession,
&myInputStream,
events,
NULL, // no write buffer
CSDK_FLAG_NONE);
if (status == CAPI_STAT_OK)
{
status = CAPI_StoreEvent(mySession,
myHandles,
numHandles,
handleStatus,
CAPI_STORE_REPLACE,
myInputStream);
CAPI_DestroyStreams(mySession,
&myInputStream,
1,
CSDK_FLAG_NONE);
}
Sample
Fetch events and write them to a buffer:
const char * todaysEvents = NULL;
CAPIStream myOutputStream = NULL;
CAPIStatus status = CAPI_CreateMemoryStream(mySession,
&myOutputStream,
NULL, // no read buffer
&todaysEvents,
CSDK_FLAG_NONE);
if (status == CAPI_STAT_OK)
{
status = CAPI_FetchEventsByRange(mySession,
myHandles,
numHandles,
handleStatus,
CSDK_FLAG_NONE,
"20020722T000000",
"20020722T235900",
NULL,
0,
myOutputStream);
if (status == CAPI_STAT_OK)
{
printf("Today's events:\\n%s", todaysEvents);
}
CAPI_DestroyStreams(mySession,
&myOutputStream,
1,
CSDK_FLAG_NONE);
}
Equivalent Java Method
None. The Java APIs only use String and StringBuffer objects to send and receive data.
Creates a query object to be used with CSDK_FetchContactsByQuery.
CAPIStatus CSDK_CreateQuery ( CSDKCondition * in_condition, CSDKQuery * out_query )
An initial condition is specified (for example, "CATEGORIES" equals "shareholders") and more conditions may be added using CSDK_AddConditionToQuery.
Parameters
Initial condition for query
On output, will contain new query object
Returns
CAPIStatus
Cleanup
The query object MUST be destroyed by calling CSDK_DestroyQuery
Sample
Create a query that specifies CATEGORIES properties whose values contain "shareholders". Add a condition that specifies ROLE properties whose values contain "chairman". Retrieve contacts that satisfy these two conditions:
//
CSDKCondition cond;
//
cond.prop = "CATEGORIES";
cond.op = CSDK_OP_CONTAINS;
cond.value = "shareholders";
//
CSDKQuery myQuery = CSDK_QUERY_INITIALIZER;
stat = CSDK_CreateQuery(&cond,
&myQuery);
//
cond.prop = "ROLE";
cond.op = CSDK_OP_CONTAINS;
cond.value = "chairman";
//
stat = CSDK_AddConditionToQuery(myQuery,
&cond,
CSDK_LOP_OR);
//
stat = CSDK_FetchContactsByQuery(mySession,
CSDK_FLAG_FETCH_MATCH_CASE,
myQuery,
NULL, // get all properties
myStream,
&requestResult);
//
CSDK_DestroyQuery(&myQuery);
Equivalent Java Method
oracle.calendar.sdk.Query constructor
Creates a new session.
CAPIStatus CSDK_CreateSession ( CAPIFlag in_flags, CAPISession * out_session )
Parameters
Bit flags (currently, set this to CSDK_FLAG_NONE)
Pointer to new session
Cleanup
The session must be destroyed using CSDK_DestroySession()
Equivalent Java Method
oracle.calendar.sdk.Session constructor
Returns
CAPIStatus
Deauthenticates the current user.
CAPIStatus CSDK_Deauthenticate ( CAPISession in_session, CAPIFlag in_flags )
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
Login session handle
Bit flags modifying behavior. This must be CSDK_FLAG_NONE currently.
Returns
CAPIStatus
Equivalent Java Method
oracle.calendar.sdk.Session.deauthenticate()
Deletes vCards specified by a set of UIDs.
CAPIStatus CSDK_DeleteContacts ( CAPISession in_session, CAPIFlag in_flags, CAPIUIDSet in_UIDs, CSDKRequestResult * out_requestResult )
This function is blocked for SYSOP that has not assumed the identity of a user.
Parameters
Login session handle
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.
NULL terminated array of strings containing UIDs of vCards to delete
Pointer to a RequestResult that will get filled
Returns
CAPIStatus
Return values
The session was NULL
in_UIDs was NULL
Equivalent Java Method
oracle.calendar.sdk.Session.deleteContacts()
Deletes specified events; must be acting as the event owner for this to succeed.
CAPIStatus CSDK_DeleteEvents ( CAPISession in_session, CAPIFlag in_flags, CAPIUIDSet in_UIDs, const char * in_RECURRENCEID, int in_modifier, CSDKRequestResult * out_requestResult )
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
Login session handle
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.
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.
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.
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
If non-NULL, will be filled in with detailed results of the transaction
Returns
CAPIStatus
Cleanup
The request result must be destroyed using CSDK_DestroyRequestResult
Equivalent Java Method
oracle.calendar.sdk.Session.deleteEvents()
Deletes tasks from the current user's agenda.
CAPIStatus CSDK_DeleteTasks ( CAPISession in_session, CAPIFlag in_flags, CAPIUIDSet in_UIDs, CSDKRequestResult * out_requestResult )
This function is blocked for SYSOP that has not assumed the identity of a user.
Parameters
Login handle session
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.
NULL terminated array of task UIDs
Returned request result object
Returns
CAPIStatus
Return values
in_session is NULL
in_UIDSet is NULL
Equivalent Java Method
oracle.calendar.sdk.Session.deleteTasks()
Destroys one handle.
CAPIStatus CSDK_DestroyHandle ( CAPISession in_session, CAPIHandle * in_handle )
Parameters
Login session handle
Handle (returned by CSDK_GetHandle) to destroy
Returns
CAPIStatus
Sample
Destroy one handle:
{
CAPIHandle h1 = CSDK_HANDLE_INITIALIZER;
CSDK_GetHandle(mySession, "arthur", CSDK_FLAG_NONE, &h1);
...
OCAP_DestroyHandle(mySession, &h1);
}
Equivalent Java Method
None. oracle.calendar.sdk.Handle finalizer will destroy handles.
Destroys multiple handles returned by calls to CSDK_GetHandle().
CAPIStatus CSDK_DestroyMultipleHandles ( CAPISession in_session, CAPIHandle * in_handles, int in_numHandles, CAPIFlag in_flags )
Parameters
Login session handle
Array of handles (returned by CSDK_GetHandle) to destroy
The size of the handle array
Bit flags (none at this time, set to CSDK_FLAG_NONE)
Returns
CAPIStatus
Sample
Destroy two handles:
{
CAPIHandle h1 = CSDK_HANDLE_INITIALIZER;
CAPIHandle h2 = CSDK_HANDLE_INITIALIZER;
CSDK_GetHandle(mySession, "arthur", CSDK_FLAG_NONE, &h1);
CSDK_GetHandle(mySession, "tim...", CSDK_FLAG_NONE, &h2);
...
CAPIHandle handles[] = {h1, h2};
CSDK_DestroyMultipleHandles(mySession, handles, 2, CSDK_FLAG_NONE);
}
Equivalent Java Method
None. oracle.calendar.sdk.Handle finalizer will destroy handles.
Destroys streams created by the various CSDK_Create...Stream functions.
CAPIStatus CSDK_DestroyMultipleStreams ( CAPISession in_session, CAPIStream * in_streams, int in_numStreams, CAPIFlag in_flags )
Parameters
The session with which streams are associated
Array of streams to destroy
The number of streams in in_streams to destroy
Bit flags modifying behavior. Must be CSDK_FLAG_NONE at this time.
Returns
CAPIStatus
Equivalent Java Method
None. The Java APIs only use String and StringBuffer objects to send and receive data.
Destroys a query object created by CSDK_CreateQuery.
CAPIStatus CSDK_DestroyQuery ( CSDKQuery * io_query )
Parameters
A pointer to a query object to destroy. Will point to CSDK_QUERY_INITIALIZER on exit.
Returns
CAPIStatus
Equivalent Java Method
None. oracle.calendar.sdk.Query finalizer destroys object.
Disposes of all the results in in_requestResult.
CAPIStatus CSDK_DestroyResult ( CSDKRequestResult * io_requestResult )
Parameters
The RequestResult to destroy
Returns
CAPIStatus
Return values
The result io_requestResult has a NULL value
Equivalent Java Method
oracle.calendar.sdk.Result finalizer
Destroys a session.
CAPIStatus CSDK_DestroySession ( CAPISession * io_session )
Parameters
Pointer to session to destroy. Will point to CAPI_SESSION_INITIALIZER on output.
Returns
CAPIStatus
Equivalent Java Method
oracle.calendar.sdk.Session finalizer
Destroys a stream created by any of the various CSDK_Create...Stream functions.
CAPIStatus CSDK_DestroyStream ( CAPISession in_session, CAPIStream * io_stream )
Parameters
The session with which the stream is associated
Stream to destroy
Returns
CAPIStatus
Equivalent Java Method
None. The Java APIs only use String and StringBuffer objects to send and receive data.
Disconnects from the Oracle Calendar server.
CAPIStatus CSDK_Disconnect ( CAPISession in_session, CAPIFlag in_flags )
Parameters
Login session handle
Bit flags modifying behavior. This must be CSDK_FLAG_NONE currently.
Returns
CAPIStatus
Equivalent Java Method
oracle.calendar.sdk.Session.disconnect()
Fetches contacts which satisfy the conditions specified in the query.
CAPIStatus CSDK_FetchContactsByQuery ( CAPISession in_session, CAPIFlag in_flags, CSDKQuery in_query, const char ** in_requestProperties, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
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
Login session handle
Bit flags
CSDK_FLAG_NONE
CSDK_FLAG_STREAM_NOT_MIME: Do NOT wrap the output in a MIME container
A query object containing the search criteria
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.
Stream for the SDK to write into
If non-NULL, will be filled in with detailed results of the transaction.
Returns
CAPIStatus
Cleanup
The request result must be destroyed using CSDK_DestroyRequestResult
Equivalent Java Method
oracle.calendar.sdk.Session.fetchContactsByQuery()
See
CSDK_CreateQuery
Fetches vCards from an authenticated connection.
CAPIStatus CSDK_FetchContactsByUID ( CAPISession in_session, CAPIFlag in_flags, CAPIUIDSet in_UIDs, const char ** in_requestProperties, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
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
Login session handle
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.
NULL terminated array of strings containing UIDs of vCards to fetch
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.
Stream for the SDK to write into
If non-NULL, will be filled in with detailed results of the transaction.
Returns
CAPIStatus
Cleanup
The request result must be destroyed using CSDK_DestroyRequestResult
Return values
The session was NULL
The stream was NULL
in_UIDSet was NULL
in_UIDCount was 0
Equivalent Java Method
oracle.calendar.sdk.Session.fetchContactsByUID()
Fetches events which have alarms (reminders) that will trigger within the time range specified; the end of the time range is exclusive.
CAPIStatus CSDK_FetchEventsByAlarmRange ( CAPISession in_session, CAPIFlag in_flags, CAPIHandle * in_agendas, const char * in_start, const char * in_end, const char ** in_requestProperties, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
Parameters
Login session handle
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 Oracle 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
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.
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.
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
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.
Stream for CAPI to write into
If non-NULL, will be filled in with detailed results of the transaction.
Returns
CAPIStatus
Cleanup
The request result must be destroyed using CSDK_DestroyRequestResult
Equivalent Java Method
oracle.calendar.sdk.Session.fetchEventsByAlarmRange()
Fetches events which occur within the time range specified.
CAPIStatus CSDK_FetchEventsByRange ( CAPISession in_session, CAPIFlag in_flags, CAPIHandle * in_agendas, const char * in_start, const char * in_end, const char ** in_requestProperties, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
The end of the time range is exclusive.
Parameters
Login session handle
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 Oracle 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
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.
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.
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
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.
Stream for CAPI to write into
If non-NULL, will be filled in with detailed results of the transaction.
Returns
CAPIStatus
Cleanup
The request result must be destroyed using CSDK_DestroyRequestResult
Equivalent Java Method
oracle.calendar.sdk.Session.fetchEventsByRange()
Fetches events by their UIDs.
CAPIStatus CSDK_FetchEventsByUID ( CAPISession in_session, CAPIFlag in_flags, CAPIHandle in_agenda, CAPIUIDSet in_UIDs, const char * in_RECURRENCEID, int in_modifier, const char ** in_requestProperties, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
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
Login session handle
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 Oracle 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
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.
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.
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.
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
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.
Stream for CAPI to write into
If non-NULL, will be filled in with detailed results of the transaction.
Returns
CAPIStatus
Cleanup
The request result must be destroyed using CSDK_DestroyRequestResult
Equivalent Java Method
oracle.calendar.sdk.Session.fetchEventsByUID()
Fetches tasks that have alarms (reminders) that will trigger within the time range specified (the end of the time range is exclusive).
CAPIStatus CSDK_FetchTasksByAlarmRange ( CAPISession in_session, CAPIFlag in_flags, CAPIHandle * in_handles, const char * in_start, const char * in_end, const char ** in_requestProperties, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
Parameters
Login session handle
Bit flags:
CSDK_FLAG_NONE
CSDK_FLAG_STREAM_NOT_MIME: Do NOT wrap the iCalendar in a MIME container
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.
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.
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
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.
Stream for CAPI to write into
If non-NULL, will be filled in with detailed results of the transaction.
Returns
CAPIStatus
Cleanup
The request result must be destroyed using CSDK_DestroyRequestResult
Equivalent Java Method
oracle.calendar.sdk.Session.fetchTasksByAlarmRange()
Fetches tasks which are active within the time range specified (the end of the time range is exclusive).
CAPIStatus CSDK_FetchTasksByRange ( CAPISession in_session, CAPIFlag in_flags, CAPIHandle * in_handles, const char * in_start, const char * in_end, const char ** in_requestProperties, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
Parameters
Login session handle
Bit flags:
CSDK_FLAG_NONE
CSDK_FLAG_STREAM_NOT_MIME: Do not wrap the iCalendar in a MIME container
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.
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.
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
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.
Stream for CAPI to write into
If non-NULL, will be filled in with detailed results of the transaction.
Returns
CAPIStatus
Cleanup
The request result must be destroyed using CSDK_DestroyRequestResult
Equivalent Java Method
oracle.calendar.sdk.Session.fetchTasksByRange()
Retrieves tasks with given UIDs on the given agenda.
CAPIStatus CSDK_FetchTasksByUID ( CAPISession in_session, CAPIHandle in_handle, CAPIFlag in_flags, CAPIUIDSet in_UIDs, const char ** in_requestProperties, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
Parameters
Login session handle
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
The agenda on which to search for tasks with the given UIDs. A NULL value will search on the current user's agenda.
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.
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.
Stream for CAPI to write into
If non-NULL, will be filled in with detailed results of the transaction.
Returns
CAPIStatus
Cleanup
The request result must be destroyed using CSDK_DestroyRequestResult
Equivalent Java Method
oracle.calendar.sdk.Session.fetchTasksByUID()
Returns information about this SDK release and/or the Oracle Calendar server.
CAPIStatus CSDK_GetCapabilities ( CAPISession in_session, CAPICapabilityID in_capabilityID, CAPIFlag in_flags, const char ** out_value )
Parameters
Login session handle. If NULL, then no server capabilities can be requested.
ID for a capability (see CAPI_CAPAB_* in ctapi.h)
CSDK_FLAG_NONE at this time
Information is returned in this parameter. The values are returned as read-only strings and are only valid until the next SDK function call that uses the same session.
Changes
CAPI 2.5: type of in_capabilityID was changed from "long" to "CAPICapabilityID"
Equivalent Java Method
oracle.calendar.sdk.Session.getCapabilities
Returns the first failure obtained from the function from which in_requestResult was returned.
CAPIStatus CSDK_GetFirstFailure ( CSDKRequestResult in_requestResult, CAPIHandle * out_user, const char ** out_uid, CAPIStatus * out_status )
A failure is a result which has a status other than CAPI_STAT_OK.
Note: A request result contains the reference to the "current" failure, so only one thread should extract failures from a given request result at a time.
Parameters
The RequestResult from which to extract information
The user whose agenda was being read or written
The uid of the calendar object being read or written, if applicable
The status code for the portion of the operation involving the user and uid specified
Returns
CAPIStatus
Return values
One of the required parameters has a NULL value
No failures in the RequestResult
Sample
Output first failure returned from call to CSDK_StoreContacts, if any
const char * vcardUID = 0;
CAPIStatus vcardStatus = CAPI_STAT_OK;
CSDKRequestResult * myRequestResult = 0;
//
stat = CSDK_StoreContacts(mySession,
myStream,
CSDK_FLAG_STORE_IMPORT,
&myRequestResult);
//
CAPIStatus failStat = CSDK_GetFirstFalure(myRequestResult,
NULL,
&vcardUID,
&vcardStatus);
//
if (failStat == CAPI_STAT_DATA_RRESULT_EOR)
{
cout << "Store of VCARD with UID " << vcardUID << " suceeded." << endl;
}
else
{
const char * statusName = 0;
CSDK_GetStatusString(vcardStatus, &statusName);
cout << "Store of VCARD with UID " << vcardUID << " failed with CAPIStatus " << statusName << "." << endl;
}
//
CSDK_DestroyResult(&myRequestResult);
Equivalent Java Method
oracle.calendar.sdk.Result.getFirstFailure()
Returns the first parsing error obtained from a request result.
CAPIStatus CSDK_GetFirstParseError ( CSDKRequestResult in_requestResult, CAPIStatus * out_status, const char ** out_errorBuffer, const char ** out_errorLocation, const char ** out_message )
A parse error can be generated by any of the CSDK_Store* functions as they attempt to interpret incoming iCalendar or vCard.
Note: A request result contains the reference to the "current" parse error, so only one thread should extract parse errors from a given request result at a time.
A pointer to a copy of the data stream is returned through out_errorBuffer, and a pointer to the parse error location in the buffer is returned via out_errorLocation. Both pointers are valid only until the request result is destroyed.
Parameters
The RequestResult to extract information from
The result's status
The beginning of the buffer with the error
The location in *out_errorBuffer where the error occurred
May contain additional information (NULL may be returned if no message is available)
Returns
CAPIStatus
Return values
One of the required parameters has a NULL value
No parse errors in in_requestResult
Sample
Get the first parsing error from a call to CSDK_StoreContacts:
CAPIStatus stat = CAPI_STAT_OK;
CSDKRequestResult * myRequestResult = 0;
//
stat = CSDK_StoreContacts(mySession,
myStream,
CSDK_FLAG_STORE_IMPORT,
&myRequestResult);
//
const char * buffer = 0;
const char * errorLocation = 0;
const char * message = 0;
//
CAPIStatus parseStat = CSDK_GetFirstParseError(myRequestResult,
NULL,
&buffer,
&errorLocation,
&message);
//
if (parseStat != CAPI_STAT_DATA_RRESULT_EOR)
{
cout << "Error (" << message << ") parsing vCard. Buffer:'" << vcardUID << "' Error starting at:'" << errorLocation << "'" << endl;
}
//
CSDK_DestroyResult(&myRequestResult);
Equivalent Java Method
oracle.calendar.sdk.Result.getFirstParseError()
Returns the first result obtained from the function from which in_requestResult was returned.
CAPIStatus CSDK_GetFirstResult ( CSDKRequestResult in_requestResult, CAPIHandle * out_user, const char ** out_uid, CAPIStatus * out_status )
A result is either a failure or a success. A failure is a result which has a status other than CAPI_STAT_OK.
Note: A request result contains the reference to the "current" result, so only one thread should extract result from a given request result at a time.
Parameters
The RequestResult from which to extract information
The user whose agenda was being read or written
The uid of the calendar object being read or written, if applicable
The status code for the portion of the operation involving the user and uid specified
Returns
CAPIStatus
Return values
One of the required parameters has a NULL value
No results in the RequestResult
Sample
Output first result from call to CSDK_StoreContacts:
const char * vcardUID = 0;
CAPIStatus vcardStatus = CAPI_STAT_OK;
CSDKRequestResult * myRequestResult = 0;
//
stat = CSDK_StoreContacts(mySession,
myStream,
CSDK_FLAG_STORE_IMPORT,
&myRequestResult);
//
CSDK_GetFirstResult(myRequestResult,
NULL,
&vcardUID,
&vcardStatus);
//
if (vcardStatus == CAPI_STAT_OK)
{
cout << "Store of VCARD with UID " << vcardUID << " suceeded." << endl;
}
else
{
const char * statusName = 0;
CSDK_GetStatusString(vcardStatus, &statusName);
cout << "Store of VCARD with UID " << vcardUID << " failed with CAPIStatus " << statusName << "." << endl;
}
//
CSDK_DestroyResult(&myRequestResult);
Equivalent Java Method
oracle.calendar.sdk.Result.getFirstResult()
Returns a handle to a particular user's calendar store.
CAPIStatus CSDK_GetHandle ( CAPISession in_session, const char * in_user, CAPIFlag in_flags, CAPIHandle * out_handle )
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
Login session handle
User as defined for CSDK_Authenticate. May be NULL in which case a handle to the current user is returned.
Bit flags (none at this time, set to CSDK_FLAG_NONE)
Handle for in_user. Must point to NULL on entry.
Returns
CAPIStatus
Return values
Cleanup
This function allocates a handle which must be cleaned up with a call to CSDK_DestroyHandle. If an error is returned no handle is allocated and no clean up is required.
Sample
Get a handle for a user whose userid is "roger":
{
CAPIHandle shrubber = CSDK_HANDLE_INITIALIZER;
stat = CSDK_GetHandle(mySession, "roger", CSDK_FLAG_NONE, &shrubber);
}
Sample
Get a handle for a user named "Arnold Layne" (S urname Layne, G iven name Arnold):
{
CAPIHandle arnold = CSDK_HANDLE_INITIALIZER;
stat = CSDK_GetHandle(mySession, "?/S=Layne/G=Arnold/, CSDK_FLAG_NONE, &arnold);
}
Sample
Get a handle for a resource named "keg" on node "1234":
{
CAPIHandle keg = CSDK_HANDLE_INITIALIZER;
stat = CSDK_GetHandle(mySession, "?/RS=keg/ND=1234/", CSDK_FLAG_NONE, &keg);
}
Sample
Get a handle for the current user:
{
CAPIHandle currUser = CSDK_HANDLE_INITIALIZER;
stat = CSDK_GetHandle(mySession, NULL, CSDK_FLAG_NONE, &currUser);
}
Changes
CAPI 2.5: Resource names must be an exact match. (There used to be an implicit wildcard at the end of the string.)
Equivalent Java Method
oracle.calendar.sdk.Session.getHandle()
Returns information about the agenda of the supplied handle.
CAPIStatus CSDK_GetHandleInfo ( CAPISession in_session, CAPIHandle in_handle, CAPIFlag in_flags, const char ** out_info )
Three pieces of information can be returned, chosen by the value of in_flags. The information is returned as a pointer to a static read-only string.
The following are the types of information that can be returned:
CAPI_HANDLE_TYPE indicates the type of the handle. This can be "user" or "resource" and indicates what type of agenda this is.
CAPI_HANDLE_NAME returns the name of the agenda owner, or resource, in the form of a sequence of field-value pairs, separated by "/". This string, when prepended with a '?' is of an appropriate format to be passed to CSDK_GetHandle. A description of this format is given in "User identification" section of this manual.
CAPI_HANDLE_MAILTO returns the email address of who the agenda belongs to. Since not all users (and no resources) will have e-mail addresses set on the Oracle Calendar server, an error (CAPI_STAT_DATA_EMAIL_NOTSET) will be returned when no e-mail address is set.
Parameters
Login session handle
Handle to get info for
CAPI_HANDLE_TYPE, CAPI_HANDLE_NAME or CAPI_HANDLE_MAILTO
Read-only handle information
Returns
CAPIStatus
Changes
CAPI 2.5: now returns CAPI_STAT_DATA_EMAIL_NOTSET if no e-mail address is set on the server.
Sample
Print the name of the logged in user:
{
CAPIHandle loginUser = CSDK_HANDLE_INITIALIZER;
const char * fullName = NULL;
stat = CSDK_GetHandle(mySession, NULL, CSDK_FLAG_NONE, &loginUser);
stat = CSDK_HandleInfo(mySession, loginUser, CAPI_HANDLE_NAME, &fullName);
cout << "Currently logged in as " << fullName << endl;
CSDK_DestroyHandle(mySession,
&loginUser);
}
Sample
Print out Doctor Winston's e-mail address:
{
CAPIHandle doctor = CSDK_HANDLE_INITIALIZER;
const char * email = NULL;
stat = CAPI_GetHandle(mySession, "drwinston", CSDK_FLAG_NONE, &doctor);
stat = CAPI_HandleInfo(mySession, doctor, CAPI_HANDLE_MAILTO, &email);
cout << "drwinston's email address is " << email << endl;
CSDK_DestroyHandle(mySession,
&doctor);
}
Returns the next failure contained in a CSDKRequestResult.
CAPIStatus CSDK_GetNextFailure ( CSDKRequestResult in_requestResult, CAPIHandle * out_user, const char ** out_uid, CAPIStatus * out_status )
A call to CSDK_GetFirstFailure must precede this call.
Note: A request result contains the reference to the "current" failure, so only one thread should extract failures from a given request result at a time.
Parameters
The RequestResult from which to extract information
The user whose agenda was being read or written
The uid of the calendar object being read or written, if applicable
The status code for the portion of the operation involving the user and uid specified
Returns
CAPIStatus
Return values
One of the required parameters has a NULL value
No more failure in the RequestResult
Sample
Get all failures from a call to CSDK_StoreContacts by calling CSDK_GetNextFailure in a while loop
const char * vcardUID = 0;
CAPIStatus stat = CAPI_STAT_OK;
CSDKRequestResult * myRequestResult = 0;
//
stat = CSDK_StoreContacts(mySession,
myStream,
CSDK_FLAG_STORE_IMPORT,
&myRequestResult);
//
stat = CSDK_GetFirstFailure(myRequestResult,
NULL,
&vcardUID,
&vcardStatus);
//
while (stat != CAPI_STAT_DATA_RRESULT_EOR)
{
const char * statusName = 0;
CSDK_GetStatusString(vcardStatus, &statusName);
cout << "Store of VCARD with UID " << vcardUID << " failed with status " << statusName << endl;
//
stat = CSDK_GetNextFailure(myRequestResult,
NULL,
&vcardUID,
&vcardStatus);
}
//
CSDK_DestroyResult(&myRequestResult);
Equivalent Java Method
oracle.calendar.sdk.Result.getNextFailure()
Returns the next parsing error obtained from a request result.
CAPIStatus CSDK_GetNextParseError ( CSDKRequestResult in_requestResult, CAPIStatus * out_status, const char ** out_errorBuffer, const char ** out_errorLocation, const char ** out_message )
A call to CSDK_GetFirstParseError must precede this call.
Note: A request result contains the reference to the "current" parse error, so only one thread should extract parse errors from a given request result at a time.
A pointer to a copy of the data stream is returned through out_errorBuffer, and a pointer to the parse error location in the buffer is returned via out_errorLocation. Both pointers are valid only until the request result is destroyed.
Parameters
The RequestResult to extract information from
The result's status
The beginning of the buffer with the error
The location in *out_errorBuffer where the error occurred
May contain additional information (NULL may be returned if no message is available)
Returns
CAPIStatus
Return values
One of the required parameters has a NULL value
No parse errors in in_requestResult
Sample
Get all the parsing errors from a call to CSDK_StoreContacts by calling CSDK_GetNextParseError in a while loop
CAPIStatus stat = CAPI_STAT_OK;
CSDKRequestResult * myRequestResult = 0;
//
stat = CSDK_StoreContacts(mySession,
myStream,
CSDK_FLAG_STORE_IMPORT,
&myRequestResult);
//
const char * buffer = 0;
const char * errorLocation = 0;
const char * message = 0;
//
CAPIStatus parseStat = CSDK_GetFirstParseError(myRequestResult,
NULL,
&buffer,
&errorLocation,
&message);
//
while (parseStat != CAPI_STAT_DATA_RRESULT_EOR)
{
cout << "Error (" << message << ") parsing vCard. Buffer:'" << vcardUID << "' Error starting at:'" << errorLocation << "'" << endl;
parseStat = CSDK_GetNextParseError(myRequestResult,
NULL,
&buffer,
&errorLocation,
&message);
}
//
CSDK_DestroyResult(&myRequestResult);
Equivalent Java Method
oracle.calendar.sdk.Result.getNextParseError()
Returns the next result contained in a CSDKRequestResult.
CAPIStatus CSDK_GetNextResult ( CSDKRequestResult in_requestResult, CAPIHandle * out_user, const char ** out_uid, CAPIStatus * out_status )
A call to CSDK_GetFirstResult must precede this call.
Note: A request result contains the reference to the "current" result, so only one thread should extract result from a given request result at a time.
Parameters
The RequestResult from which to extract information
The user whose agenda was being read or written
The uid of the calendar object being read or written, if applicable
The status code for the portion of the operation involving the user and uid specified
Returns
CAPIStatus
Return values
One of the required parameters has a NULL value
No more results in the RequestResult
Sample
Get all results from a call to CSDK_StoreContacts by calling CSDK_GetNextResult in a while loop:
const char * vcardUID = 0;
CAPIStatus stat = CAPI_STAT_OK;
CSDKRequestResult * myRequestResult = 0;
//
stat = CSDK_StoreContacts(mySession,
myStream,
CSDK_FLAG_STORE_IMPORT,
&myRequestResult);
//
stat = CSDK_GetFirstResult(myRequestResult,
NULL,
&vcardUID,
&vcardStatus);
//
while (stat != CAPI_STAT_DATA_RRESULT_EOR)
{
const char * statusName = 0;
CSDK_GetStatusString(vcardStatus, &statusName);
cout << "Store of VCARD with UID " << vcardUID << " returned status " << statusName << endl;
//
stat = CSDK_GetNextResult(myRequestResult,
NULL,
&vcardUID,
&vcardStatus);
}
//
CSDK_DestroyResult(&myRequestResult);
Equivalent Java Method
oracle.calendar.sdk.Result.getNextResult()
A status returned by the CALENDAR_SDK is composed of a status code and some extra bits giving extra context to the error that occurred.
CSDK_GetStatusCode ( CAPIStatus in_status, int * out_statusCode )
This can cause the API user to have to mask these extra bits to compare the status codes. So this helper returns the status without these extra bits s.t. it is comparable with other status codes.
Parameters
CAPI status
contains a statusCode with extra level bits removed
Equivalent Java Method
oracle.calendar.sdk.Api.getStatusCode()
Decomposes a CAPIStatus into its subparts; each part of the status code specifies more precisely the actual error.
CSDK_GetStatusLevels ( CAPIStatus in_status, unsigned long * out_field1, unsigned long * out_field2, unsigned long * out_field3, unsigned long * out_field4, unsigned long * out_field5 )
Parameters
CAPI status
Contains the int result for level1
Contains the int result for level2
Contains the int result for level3
Contains the int result for level4
Contains the int result for level5
Equivalent Java Method
oracle.calendar.sdk.Api.getStatusLevels()
Changes
CAPI 2.5: types of "out_level[12345]" changed from "int *" to "unsigned long *"
Returns a read-only string representation of a CAPIStatus (this is generally more useful than the numeric representation).
CSDK_GetStatusString ( CAPIStatus in_status, const char ** out_errorString )
Parameters
CAPI status
Contains const pointer to the result string
Cleanup
None. The string returned is a const string that cannot be freed.
Equivalent Java Method
oracle.calendar.sdk.Api.getStatusString()
Allows the SDK to read configuration settings that control error logging and the other configuration parameters listed in the "Configuration" section of this manual.
CAPIStatus CSDK_SetConfigFile ( const char * in_configFileName, const char * in_logFileName )
If called, this function should be the first SDK function called by your process and should not be called by each thread.
If you require assistance from Oracle Support for your development with the SDK, you should expect to be asked to call this function in order to generate logs.
Parameters
A null-terminated string containing the filename of the config file.
The name of a file to write log messages to. If this file cannot be created or written to, output will be sent to a file named Console.log in the current directory.
Returns
CAPIStatus
Return values
One of the input parameters was NULL
Failed to open in_configFileName
Equivalent Java Method
oracle.calendar.sdk.Api.init()
See
The Configuration section.
Sample
Create a file "capi.ini" with the contents:
[LOG]
log_activity = true
log_modulesinclude = { CAPI }
Sample
Call CSDK_SetConfigFile (after creating capi.ini). This will turn on "activity" level logging in CAPI and the output will go into capi.log:
CAPIStatus status = CSDK_SetConfigFile("capi.ini", "capi.log");
Sample
Using absolute and relative paths:
CAPIStatus status = CSDK_SetConfigFile("../config/csdk.ini", "/var/log/csdk.log");
Allows an authenticated user to work on behalf of another calendar user or resource.
CAPIStatus CSDK_SetIdentity ( CAPISession in_session, const char * in_user, CAPIFlag in_flags )
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
Login session handle
Person (or resource) to work as, an X400 or UID
Bit flags (CSDK_FLAG_NONE at this time)
Returns
CAPIStatus
Sample
Work on behalf of another user:
myStatus = CSDK_SetIdentity(mySession, "keithm", CSDK_FLAG_NONE); myStatus = CSDK_SetIdentity(mySession, "?/S=MacDonald/G=Keith/", CSDK_FLAG_NONE); myStatus = CSDK_SetIdentity(mySession, "?/RS=Conference Room/ND=1234/", CSDK_FLAG_NONE);
Changes
CAPI 2.5: Resource names must be an exact match. (There used to be an implicit wildcard at the end of the string.)
Changes
9.0.4: SetIdentity can be used to work on behalf of a user on another node using designate rights. This does NOT apply to connections opened via CSDK_ConnectAsSysop().
Equivalent Java Method
oracle.calendar.sdk.Session.setIdentity()
Stores vCards on a server through an authenticated connection by in_session; The vCards must be passed in via a CAPIStream.
CAPIStatus CSDK_StoreContacts ( CAPISession in_session, CAPIFlag in_flags, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
By default, the incoming stream 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 separate 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 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
Login session handle
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
The stream containing vCards
Pointer to a RequestResult that will get filled (pass NULL if you don't want this information returned).
Returns
CAPIStatus
Return values
The session was NULL
The stream was NULL
Tried to store vCard in CSDK_FLAG_STORE_CREATE mode that already exists on the server.
Tried to update, replace, or delete properties but no UID was found in the passed-in vCard.
Invalid flag, or multiple store flags were set
Cleanup
The request result must be destroyed using CSDK_DestroyRequestResult
Sample
Store a non-MIME formatted contact:
stat = CSDK_StoreContacts(mySession,
myStream,
CSDK_FLAG_STORE_IMPORT | CSDK_FLAG_STREAM_NOT_MIME,
&myRequestResult);
Sample
Store a contact with vCard:
strcpy(outVCard,
"MIME-Version: 1.0\015\012\
Content-Type: multipart/mixed;\015\012\
boundary=\"------------CA94974D4D8713DE5B12E6CD\"\015\012\
\015\012\
This is a multi-part message in MIME format.\015\012\
--------------CA94974D4D8713DE5B12E6CD\015\012\
Content-Type: text/x-vcard; charset=UTF-8;\015\012\
name=\"example.vcf\"\015\012\
Content-Disposition: attachment;\015\012\
filename=\"example.vcf\"\015\012\
Content-Transfer-Encoding: quoted-printable\015\012\
\015\012\
BEGIN:VCARD\015\012\
URL:http://www.somewebsite.com\015\012\
ORG:steltor;windows;\015\012\
TITLE:worker\015\012\
EMAIL;TYPE=INTERNET:someone@somewhere.com\015\012\
ADR;TYPE=WORK:;;who knows;snodown;qc;h1l 2H1;Canada\015\012\
NOTE;ENCODING=QUOTED-PRINTABLE;:This is a note\015\012\
N;ENCODING=QUOTED-PRINTABLE:Last;First;Middle\015\012\
FN;ENCODING=QUOTED-PRINTABLE:First Middle Last\015\012\
REV:20011105T145136Z\015\012\
VERSION:2.1\015\012\
END:VCARD\015\012\
\015\012\
--------------CA94974D4D8713DE5B12E6CD--\015\012\015\012");
//
CAPIStatus stat;
//
stat = CAPI_CreateMemoryStream(mySession,
&myStream,
outVCard,
NULL,
CAPI_FLAG_NONE);
//
stat = CSDK_StoreContacts(mySession,
myStream,
CSDK_FLAG_STORE_IMPORT,
&myRequestResult);
Equivalent Java Method
oracle.calendar.sdk.Session.storeContacts()
This function reads one VCALENDAR object from in_stream and stores each contained VEVENT on the server.
CAPIStatus CSDK_StoreEvents ( CAPISession in_session, CAPIFlag in_flags, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
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 Oracle Calendar server is capable of doing so.
The ATTENDEE PARTSTAT parameter is ignored except for the following:
The logged in user
External (non-calendar) attendees
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 Oracle 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 Oracle Calendar server prevents any user/resource from owning more than one event with a given UID. However, UIDs are not necessarily unique on the Oracle 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 Oracle Calendar server.
Storing an event without a UID will result in a new UID being generated by the Oracle 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:
The property is not defined in the instance
The property is defined in the instance
The property is defined in the event (the instance uses the event's property)
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...
add instances to an event?
For recurring events (which use RRULEs), simply store a VEVENT with the event's UID and one or more RDATE properties using the flag CSDK_FLAG_STORE_MODIFY.
For repeating events (not using RRULEs), store a VEVENT with the event's UID and the flag CSDK_FLAG_STORE_MODIFY.
add attendees to an event?
Store VEVENT(s) with ATTENDEE properties for new attendees using flag CSDK_FLAG_STORE_MODIFY. RECURRENCE-ID property can be specified in the VEVENT to invite the attendee to only the specified instance.
remove attendees from an event?
Fetch event, remove the ATTENDEE property for the user to uninvite, then store using the mode CSDK_FLAG_STORE_REPLACE
Parameters
Login session handle
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)
Stream for CAPI to read data from
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.
Returns
CAPIStatus
Cleanup
The request result must be destroyed using CSDK_DestroyRequestResult
Sample
Simple case of adding an event into the current user's calendar:
{
static const char * ical = {"BEGIN:VCALENDAR\\r\\n"
"VERSION:2.0\\r\\n"
"BEGIN:VEVENT\\r\\n"
"DTSTART:20021225T100000Z\\r\\n"
"DTEND:20021225T233000Z\\r\\n"
"SUMMARY:work\\r\\n"
"LOCATION:office\\r\\n"
"END:VEVENT\\r\\n"
"END:VCALENDAR\\r\\n"};
//
CAPIStream memoryStream = CSDK_STREAM_INITIALIZER;
status = CSDK_CreateMemoryStream(mySession,
&memoryStream,
ical,
NULL,
CSDK_FLAG_NONE);
if (!status)
{
status = CSDK_StoreEvents(mySession,
CSDK_FLAG_STORE_CREATE | CSDK_FLAG_STORE_INVITE_SELF | CSDK_FLAG_STREAM_NOT_MIME,
memoryStream,
NULL);
//
CSDK_DestroyStream(mySession,
&memoryStream);
}
}
Sample
Invite several people to a meeting
{
const char * attendees[] = {"?/S=Who/G=Cindy Lou/",
"?/S=Who/G=Lou Lou/",
"?/S=Who/G=Betty Lou/"
"grinch");
//
const int numAttendees = (sizeof(attendees) / sizeof(attendees[0]));
const char ** emailAddresses = (const char **)malloc((numAttendees + 1) * sizeof(const char *));
CAPHandle * handles = (CAPHandle *)malloc(numAttendees * sizeof(CAPHandle *));
//
// get handles:
for (int i = 0; !status && (i < numAttendees); i++)
{
status = CSDK_GetHandle(mySession, attendees[i], CSDK_FLAG_NONE, &handles[i]);
}
//
// terminate the array:
handles[numAttendees] = CSDK_HANDLE_INITIALIZER;
//
if (!status)
{
// get e-mail addresses for each handle using CSDK_GetHandleInfo()
...
}
//
if (!status)
{
static const char * iCalEvent1 = {"BEGIN:VCALENDAR\\r\\n"
"VERSION:2.0\\r\\n"
"BEGIN:VEVENT\\r\\n"
"DTSTART:20021225T100000Z\\r\\n"
"DTEND:20021225T103000Z\\r\\n"
"SUMMARY:SING\\r\\n"
"LOCATION:Town square\\r\\n"};
//
static const char * iCalEvent2 = {"END:VEVENT\\r\\n"
"END:VCALENDAR\\r\\n"};
//
string iCalEvent = iCalEvent1;
for (int attendee = 0; attendee < numAttendees; attendee++)
{
if (emailAddresses[attendee])
{
iCalEvent += "ATTENDEE:mailto:";
iCalEvent += emailAddresses[attendee];
iCalEvent += "\\r\\n";
}
}
iCalEvent += iCalEvent2;
}
//
if (emailAddresses)
{
free(emailAddresses);
}
//
CSDK_DestroyMultipleHandles(mySession,
handles,
numAttendees,
CSDK_FLAG_NONE);
if (handles)
{
free(handles);
}
//
if (!status)
{
CAPIStream memoryStream = CSDK_STREAM_INITIALIZER;
status = CSDK_CreateMemoryStream(mySession,
&memoryStream,
iCalEvent.c_str(),
NULL,
CSDK_FLAG_NONE);
if (!status)
{
status = CSDK_StoreEvents(mySession,
CSDK_FLAG_STORE_CREATE | CSDK_FLAG_STREAM_NOT_MIME,
memoryStream,
NULL);
}
//
CSDK_DestroyStream(mySession,
&memoryStream);
}
}
Equivalent Java Method
oracle.calendar.sdk.Session.storeEvents
Creates/modifies tasks on the current user's agenda depending on the store flag passed in.
CAPIStatus CSDK_StoreTasks ( CAPISession in_session, CAPIFlag in_flags, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
Only one store flag should be used. If multiple flags are passed the error CAPI_STAT_API_FLAGS will be returned. There are five possible flags that can be used:
CSDK_FLAG_STORE_IMPORT: Stores the task if it does not exist and replaces the task if it exists.
CSDK_FLAG_STORE_CREATE: Stores the task. If the task exists the error will be returned.
CSDK_FLAG_STORE_REPLACE: Replaces the existing task. If the task does not exist the error is returned.
CSDK_FLAG_STORE_MODIFY: Modifies specified properties
CSDK_FLAG_STORE_REMOVE: Deletes specified properties
Other flags may be specified along with one of the above store flags:
CSDK_FLAG_STREAM_NOT_MIME: Incoming stream is not inside a MIME wrapper
This function is blocked for SYSOP that has not assumed the identity of a user.
Parameters
Login session handle
Store bit flags
Input stream
Returned request result object (may be NULL)
Returns
CAPIStatus
Cleanup
The request result must be destroyed using CSDK_DestroyRequestResult
Return values
in_session is NULL
in_inputStream is NULL
in_flags is invalid
Equivalent Java Method
oracle.calendar.sdk.Session.storeTasks
