| Oracle Calendar Application Developer's Guide Release 2 (9.0.4) Part Number B10893-01 |
|
|
View PDF |
| Oracle Calendar Application Developer's Guide Release 2 (9.0.4) Part Number B10893-01 |
|
|
View PDF |
This chapter contains detailed information on useful functions included with the Oracle Calendar SDK.
This section provides details on the following functions:
CAPIStatus CSDK_SetConfigFile ( const char * in_configFileName, const char * in_logFileName )
Calling this function will allow the SDK to read configuration settings which control error logging, and the other configuration parameters listed in the "Configuration" section of this manual.
If called, this function should be the first SDK function called by your process and should not be called by each thread.
Console.log in the "current" directory.CAPIStatus
Return values:
CAPI_STAT_API_NULL: one of the input parameters was NULL
CAPI_STAT_CONFIG_CANNOT_OPEN : Failed to open in_configFileName
oracle.calendar.sdk.Api.init()
Create a file "capi.ini" with the contents:
[LOG] log_activity = true log_modulesinclude = { CAPI }
and call CSDK_SetConfigFile:
CAPIStatus stat = CSDK_SetConfigFile("capi.ini", "capi.log");
This will turn on "activity" level logging in the SDK and the output will go into capi.log.
CAPIStatus CSDK_CreateSession ( CAPIFlag in_flags, CAPISession * out_session )
Create a new session.
The session must be destroyed using CSDK_DestroySession().
CAPIStatus
oracle.calendar.sdk.Session constructor
CAPIStatus CSDK_DestroySession ( CAPISession * io_session )
Destroy a session.
io_session: pointer to session to destroy. Will point to CAPI_SESSION_INITIALIZER on output.
CAPIStatus
oracle.calendar.sdk.Session finalizer
CAPIStatus CSDK_GetCapabilities ( CAPISession in_session, CAPICapabilityID in_capabilityID, CAPIFlag in_flags, const char ** out_value )
Returns information on this SDK release and/or the calendar server.
CAPI 2.5: type of in_capabilityID was changed from "long" to "CAPICapabilityID"
oracle.calendar.sdk.Session.getCapabilities
CAPIStatus CSDK_Authenticate ( CAPISession in_session, CAPIFlag in_flags, const char * in_user, const char * in_password )
Authenticates a calendar user.
This must be done prior to making any calls to store or fetch data.
CAPIStatus
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; CAPIStatus myStatus = 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"); } }
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; CAPIStatus myStatus = 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"); } }
Connect to a server running on the default port of calserver.acme.com, to authenticate as userID ernesth on node 200 using default ACE settings:
{ CAPISession mySession = CSDK_SESSION_INITIALIZER; CAPIStatus myStatus = 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, "ernesth?/ND=200/", "abcdefg"); } }
Connect to a server running on port 12345 of calserver.acme.com, use gssapi:kerberos5 authentication:
{ CAPISession mySession = CSDK_SESSION_INITIALIZER; CAPIStatus myStatus = 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 } }
A call to CSDK_Deauthenticate must be made between calls to CSDK_Authenticate.
oracle.calendar.sdk.Session.authenticate()
CAPIStatus CSDK_ConfigureACE ( CAPISession in_session, CAPIFlag in_flags, const char * in_authMechanism, const char * in_compMechanism, const char * in_encrMechanism )
This function will configure the given session to use specific ACE (Authentication, Compression, 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.
NULL values can be specified to select the server's default mechanism for any of the three types of mechanisms.
CAPIStatus
oracle.calendar.sdk.Session.configureACE()
CAPIStatus CSDK_Connect ( CAPISession in_session, CAPIFlag in_flags, const char * in_host )
Establish a connection with a calendar service.
CAPIStatus
Normal usage: Connect to the 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 = CAPI_SESSION_INITIALIZER; myStatus = CSDK_CreateSession(CAPI_FLAG_NONE, &mySession); if (myStatus == CAPI_STAT_OK) { myStatus = CSDK_connect(mySession, CAPI_FLAG_NONE, "calserver.acme.com"); } }
The server connection should be released by calling CSDK_Disconnect
oracle.calendar.sdk.Session.connect()
CAPIStatus CSDK_ConnectAsSysop ( CAPISession in_session, CAPIFlag in_flags, const char * in_host, const char * in_nodeId, const char * in_password )
Log on as Calendar SYSOP.
Once logged on, the Calendar 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 Calendar 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 Calendar SYSOP connections.
Calendar SYSOP authentication is only available with version 5.3 and newer servers. An error will be returned if the provided host does not support this feature. A calendar server may be configured to refuse Calendar SYSOP logon via the SDK in which case a security error will be returned.
The operations available to Calendar SYSOPs are limited to:
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.
CAPIStatus
oracle.calendar.sdk.Session.connectAsSysop()
CAPIStatus CSDK_Deauthenticate ( CAPISession in_session, CAPIFlag in_flags )
Deauthenticate 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.
CAPIStatus
oracle.calendar.sdk.Session.deauthenticate()
CAPIStatus CSDK_Disconnect ( CAPISession in_session, CAPIFlag in_flags )
Disconnects from the calendar server.
CAPIStatus
oracle.calendar.sdk.Session.disconnect()
CAPIStatus CSDK_SetIdentity ( CAPISession in_session, const char * in_user, CAPIFlag in_flags )
Allow an authenticated user to work on behalf of another calendar user or resource.
For subsequent calls 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 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.
in_session: session
in_user: person (or resource) to work as - an X400 or uid
in_flags: CSDK_FLAG_NONE at this time
CAPIStatus
myStatus = CSDK_SetIdentity(mySession, "dantea", CAPI_FLAG_NONE); myStatus = CSDK_SetIdentity(mySession, "?/S=Alighieri/G=Dante/", CAPI_FLAG_NONE); myStatus = CSDK_SetIdentity(mySession, "?/RS=Conference Room/ND=1234/", CAPI_FLAG_NONE);
CAPI 2.5: Resource names must be an exact match. (There used to be an implicit wildcard at the end of the string.)
SDK 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().
oracle.calendar.sdk.Session.setIdentity()
CAPIStatus CSDK_DestroyHandle ( CAPISession in_session, CAPIHandle * io_handle )
Destroys one handle returned by CSDK_GetHandle().
CAPIStatus
{ CAPIHandle h1 = CSDK_HANDLE_INITIALIZER; CSDK_GetHandle(mySession, "arthur", CSDK_FLAG_NONE, &h1); ... CSDK_DestroyHandle(mySession, &h1); }
None. oracle.calendar.sdk.Handle finalizer will destroy handles.
CAPIStatus CSDK_DestroyMultipleHandles ( CAPISession in_session, CAPIHandle * io_handles, int in_numHandles, CAPIFlag in_flags )
Destroy multiple handles returned by calls to CSDK_GetHandle().
CAPIStatus
{ 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); }
None. oracle.calendar.sdk.Handle finalizer will destroy handles.
CAPIStatus CSDK_GetHandle ( CAPISession in_session, const char * in_user, CAPIFlag in_flags, CAPIHandle * out_handle )
This function 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 a Calendar SYSOP that has not assumed the identity of a user.
CAPIStatus
Return values:
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.
Get a handle for a user whose userID is "ivoa":
{ CAPIHandle shrubber = CSDK_HANDLE_INITIALIZER; stat = CSDK_GetHandle(mySession, "ivoa", CAPI_FLAG_NONE, &shrubber); }
Get a handle for a user named "Arnold Layne" (Surname Layne, Given name Arnold):
{ CAPIHandle arnold = CSDK_HANDLE_INITIALIZER; stat = CSDK_GetHandle(mySession, "?/S=Layne/G=Arnold/, CAPI_FLAG_NONE, &arnold); }
Get a handle for a resource named "keg" on node "1234":
{ CAPIHandle keg = CSDK_HANDLE_INITIALIZER; stat = CSDK_GetHandle(mySession, "?/RS=keg/ND=1234/", CAPI_FLAG_NONE, &keg); }
Get a handle for the current user:
{ CAPIHandle currUser = CSDK_HANDLE_INITIALIZER; stat = CSDK_GetHandle(mySession, NULL, CAPI_FLAG_NONE, &currUser); }
CAPI 2.5: Resource names must be an exact match. (There used to be an implicit wildcard at the end of the string.)
oracle.calendar.sdk.Session.getHandle()
CAPIStatus CSDK_GetHandleInfo ( CAPISession in_session, CAPIHandle in_handle, CAPIFlag in_flags, const char ** out_info )
This function returns information about the agenda of the supplied handle.
Three pieces of information can be returned, chosen by the value of in_flags. The information is returned as a pointer to a read-only string.
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 e-mail address of who the agenda belongs to. Since not all users will have e-mail addresses set on the calendar server, an error (CAPI_STAT_DATA_EMAIL_NOTSET) will be returned when no e-mail address is set.
CAPIStatus
CAPI 2.5: now returns CAPI_STAT_DATA_EMAIL_NOTSET if no e-mail address is set on the server.
{ 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); }
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); }
CAPIStatus CSDK_CreateCallbackStream ( CAPISession in_session, CAPIStream * out_stream, CAPICallback in_sendCallback, void * in_sendUserData, CAPICallback in_recvCallback, void * in_recvUserData, CAPIFlag in_flags )
A callback stream can be used to either supply data to, or receive data from the SDK.
C function pointers are given to the SDK 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_datSize); // the number of characters read or written
The return values from the callbacks must be:
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.
The stream returned by this function must be destroyed by calling CSDK_DestroyStreams()
CAPIStatus
Return values:
CAPI_STAT_API_NULL: both supplied callbacks were NULL
CSDK_CreateMemoryStream, CSDK_CreateFileStreamFromFilenames
None. The Java APIs only use String and StringBuffer objects to send and receive data.
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 file stream to allow the SDK to read from or write to files.
The stream returned by this function must be destroyed by calling CSDK_DestroyStreams.
CAPIStatus
Return values:
CAPIStream myInputStream = NULL; CAPIStatus status = CSDK_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); CSDK_DestroyStreams(mySession, &myInputStream, 1, CSDK_FLAG_NONE); }
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, CAPI_FLAG_NONE, "20020722T000000", "20020722T235900", NULL, 0, myOutputStream); CSDK_DestroyStreams(mySession, &myOutputStream, 1, CSDK_FLAG_NONE); }
None. The Java APIs only use String and StringBuffer objects to send and receive data.
CAPIStatus CSDK_CreateMemoryStream ( CAPISession in_session, CAPIStream * out_stream, const char * in_readBuffer, const char ** out_writeBufferPtr, CAPIFlag in_flags )
A memory stream uses data buffers to pass data between your application and the SDK.
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 the write buffers. The write buffer is freed by the SDK when the memory stream is destroyed.
The stream returned by this function must be destroyed by calling CSDK_DestroyStream.
CAPIStatus
Return values:
CAPI_STAT_API_NULL: both supplied buffers were NULL
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 = CSDK_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); CSDK_DestroyStreams(mySession, &myInputStream, 1, CSDK_FLAG_NONE); }
const char * todaysEvents = NULL; CAPIStream myOutputStream = NULL; CAPIStatus status = CSDK_CreateMemoryStream(mySession, &myOutputStream, NULL, // no read buffer &todaysEvents, CSDK_FLAG_NONE); if (status == CAPI_STAT_OK) { status = CAPI_FetchEventsByRange(mySession, myHandles, numHandles, handleStatus, CAPI_FLAG_NONE, "20020722T000000", "20020722T235900", NULL, 0, myOutputStream); if (status == CAPI_STAT_OK) { printf("Today's events:%s", todaysEvents); } CSDK_DestroyStreams(mySession, &myOutputStream, 1, CAPI_FLAG_NONE); }
CAPIStatus CSDK_DestroyMultipleStreams ( CAPISession in_session, CAPIStream * in_streams, int in_numStreams, CAPIFlag in_flags )
This function destroys streams created by the various CSDK_Create*Stream functions.
CAPIStatus
None. The Java APIs only use String and StringBuffer objects to send and receive data.
CAPIStatus CSDK_DestroyStream ( CAPISession in_session, CAPIStream * io_stream )
This function destroys a stream created by any of the various CSDK_Create*Stream functions.
CAPIStatus
None. The Java APIs only use String and StringBuffer objects to send and receive data.
CAPIStatus CSDK_DeleteContacts ( CAPISession in_session, CAPIFlag in_flags, CAPIUIDSet in_UIDs, CSDKRequestResult * out_requestResult )
Deletes vCards specified by a set of UIDs.
This function is blocked for a Calendar SYSOP that has not assumed the identity of a user.
CAPIStatus
Return values:
oracle.calendar.sdk.Session.deleteContacts()
CAPIStatus CSDK_FetchContactsByQuery ( CAPISession in_session, CAPIFlag in_flags, CSDKQuery in_query, const char ** in_requestProperties, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
This function 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 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.
The request result must be destroyed using CSDK_DestroyRequestResult
CAPIStatus
oracle.calendar.sdk.Session.fetchContactsByQuery()
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 through in_session.
The fetched vCards are returned via in_sendStream, and 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.
This function is blocked for a Calendar SYSOP that has not assumed the identity of a user.
The result must be destroyed using CSDK_DestroyRequestResult
CAPIStatus
Return values:
oracle.calendar.sdk.Session.fetchContactsByUID()
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.
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; 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.
There are several modes that can be used:
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. The CSDKRequestResult contains the server-assigned 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 a Calendar SYSOP that has not assumed the identity of a user.
CAPIStatus
Return values:
stat = CSDK_StoreContacts(mySession, myStream, CSDK_FLAG_STORE_IMPORT, &myRequestResult);
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:oracle;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 = CSDK_CreateMemoryStream(mySession, &myStream, outVCard, NULL, CAPI_FLAG_NONE); // stat = CSDK_StoreContacts(mySession, myStream, CSDK_FLAG_STORE_IMPORT, &myRequestResult);
The request result must be destroyed using CSDK_DestroyRequestResult
oracle.calendar.sdk.Session.storeContacts()
CAPIStatus CSDK_DeleteEvents ( CAPISession in_session, CAPIFlag in_flags, CAPIUIDSet in_UIDs, const char * in_RECURRENCEID, int in_modifier, CSDKRequestResult * out_requestResult )
This function deletes specified events.
Must be acting as the event owner for this to succeed. Unlike CAPI_DeleteEvent(), 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.
The request result must be destroyed using CSDK_DestroyRequestResult
CAPIStatus
oracle.calendar.sdk.Session.deleteEvents()
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 )
This function fetches events which have alarms (reminders) which will trigger within the time range specified.
The end of the time range is exclusive.
The request result must be destroyed using CSDK_DestroyRequestResult
CAPIStatus
oracle.calendar.sdk.Session.fetchEventsByAlarmRange()
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 )
This function fetches events which occur within the time range specified.
The result must be destroyed using CSDK_DestroyRequestResult
CAPIStatus
oracle.calendar.sdk.Session.fetchEventsByRange()
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 )
This function 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.
The result must be destroyed using CSDK_DestroyRequestResult
CAPIStatus
oracle.calendar.sdk.Session.fetchEventsByUID()
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.
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 when the calendar server is capable of doing so.
The ATTENDEE.PARTSTAT parameter is ignored except:
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
Oracle Calendar Groups can be invited using a non-standard (but legal) ATTENDEE property of the 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.
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 CAPIStatus 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 (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).
The calendar server prevents any user/resource from owning more than one event with a given UID. However, UIDs are not neccessarly 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.
And optionally, a combination of:
CAPIStatus
The request result must be destroyed using CSDK_DestroyRequestResult
{ 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); } }
{ // invite these 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:Whoville 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); } }
oracle.calendar.sdk.Session.storeEvents
CAPIStatus CSDK_DeleteTasks ( CAPISession in_session, CAPIFlag in_flags, CAPIUIDSet in_UIDs, CSDKRequestResult * out_requestResult )
This function deletes tasks on the current user's agenda.
This function is blocked for a Calendar SYSOP that has not assumed the identity of a user.
Return values:
oracle.calendar.sdk.Session.deleteTasks()
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 )
This function fetches tasks which have alarms (reminders) which will trigger within the time range specified.
The end of the time range is exclusive.
The request result must be destroyed using CSDK_DestroyRequestResult
CAPIStatus
oracle.calendar.sdk.Session.fetchTasksByAlarmRange()
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 )
This function fetches tasks which are active within the time range specified.
The end of the time range is exclusive.
The request result must be destroyed using CSDK_DestroyRequestResult
CAPIStatus
oracle.calendar.sdk.Session.fetchTasksByRange()
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 )
This function retrieves tasks with given UIDs on the given agenda.
The result must be destroyed using CSDK_DestroyRequestResult
CAPIStatus
oracle.calendar.sdk.Session.fetchTasksByUID()
CAPIStatus CSDK_StoreTasks ( CAPISession in_session, CAPIFlag in_flags, CAPIStream in_stream, CSDKRequestResult * out_requestResult )
This function creates/modifies tasks on the current user's agenda depending on the SDK store flag passed.
Only one flag should be used. If multiple flags are passed the error CAPI_STAT_API_BADPARAM will be returned. There are five possible flags that can be used:
Other flags may be specifed along with one of the above store flags:
This function is blocked for a Calendar SYSOP that has not assumed the identity of a user.
CAPIStatus
Return values:
The request result must be destroyed using CSDK_DestroyRequestResult
oracle.calendar.sdk.Session.storeTasks
CAPIStatus CSDK_AddConditionToQuery ( CSDKQuery in_query, CSDKCondition * in_condition, CSDKOperator in_operator )
Adds a condition to a query object. 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
CAPIStatus
oracle.calendar.sdk.Query.addCondition()
CAPIStatus CSDK_CreateQuery ( CSDKCondition * in_condition, CSDKQuery * out_query )
Creates a query object to be used with CSDK_FetchContactsByQuery. An initial condition is specified (e.g. "Name begins with A") and more conditions may be added using CSDK_AddConditionToQuery.
The query object MUST be destroyed by calling CSDK_DestroyQuery
CAPIStatus
// CSDKCondition cond; // cond.prop = "N"; cond.op = CSDK_OP_STARTSWITH; cond.value = "A"; // CSDKQuery myQuery = CSDK_QUERY_INITIALIZER; stat = CSDK_CreateQuery(&cond, &myQuery); // stat = CSDK_FetchContactsByQuery(mySession, CSDK_FLAG_STREAM_NOT_MIME, myQuery, NULL, // get all properties myStream, &requestResult); // CSDK_DestroyQuery(&myQuery);
oracle.calendar.sdk.Query constructor.
CAPIStatus CSDK_DestroyQuery ( CSDKQuery * io_query )
Destroys a query object created by CSDK_CreateQuery
io_query: a pointer to a query object to destroy. Will point to CSDK_QUERY_INITIALIZER on exit.
CAPIStatus
None. oracle.calendar.sdk.Query finalizer destroys object.
CAPIStatus CSDK_DestroyResult ( CSDKRequestResult * io_requestResult )
This function disposes of all the results in in_requestResult.
io_requestResult : the RequestResult to destroy
CAPIStatus
Return values:
oracle.calendar.sdk.Result finalizer
CAPIStatus CSDK_GetFirstFailure ( CSDKRequestResult in_requestResult, CAPIHandle * out_user, const char ** out_uid, CAPIStatus * out_status )
This function returns the first failure obtained from the API function from which in_requestResult was returned.
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. |
CAPIStatus
Return values:
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);
oracle.calendar.sdk.Result.getFirstFailure()
CAPIStatus CSDK_GetFirstParseError ( CSDKRequestResult in_requestResult, CAPIStatus * out_status, const char ** out_errorBuffer, const char ** out_errorLocation, const char ** out_message )
This function returns the first parsing error obtained from a request result.
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.
CAPIStatus
Return values:
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);
oracle.calendar.sdk.Result.getFirstParseError()
CAPIStatus CSDK_GetFirstResult ( CSDKRequestResult in_requestResult, CAPIHandle * out_user, const char ** out_uid, CAPIStatus * out_status )
This function returns the first result obtained from the API function from which in_requestResult was returned.
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 the result from a given request result at a time. |
CAPIStatus
Return values:
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 << " succeeded." << 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);
oracle.calendar.sdk.Result.getFirstResult()
CAPIStatus CSDK_GetNextFailure ( CSDKRequestResult in_requestResult, CAPIHandle * out_user, const char ** out_uid, CAPIStatus * out_status )
This function returns the next failure contained in a CSDKRequestResult.
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. |
CAPIStatus:
Return values:
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);
oracle.calendar.sdk.Result.getNextFailure()
CAPIStatus CSDK_GetNextParseError ( CSDKRequestResult in_requestResult, CAPIStatus * out_status, const char ** out_errorBuffer, const char ** out_errorLocation, const char ** out_message )
This function returns the next parsing error obtained from a request result.
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.
CAPIStatus
Return values:
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);
oracle.calendar.sdk.Result.getNextParseError()
CAPIStatus CSDK_GetNextResult ( CSDKRequestResult in_requestResult, CAPIHandle * out_user, const char ** out_uid, CAPIStatus * out_status )
This function returns the next result contained in a CSDKRequestResult.
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 the result from a given request result at a time. |
CAPIStatus
Return values:
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);
oracle.calendar.sdk.Result.getNextResult()
void CSDK_GetStatusLevels ( CAPIStatus in_status, unsigned long * out_level1, unsigned long * out_level2, unsigned long * out_level3, unsigned long * out_level4, unsigned long * out_level5 )
This function decomposes a CAPIStatus into its sub-parts.
Each part of the status code specifies more precisely the actual error.
CAPI 2.5: types of "out_level[12345]" changed from "int *" to "unsigned long *"
oracle.calendar.sdk.Api.getStatusLevels()
void CSDK_GetStatusString ( CAPIStatus in_status, const char ** out_string )
This function returns a read-only string representation of a CAPIStatus.
This is generally more useful than the numeric representation.
None. The string returned is a const string cannot be freed
oracle.calendar.sdk.Api.getStatusString()
The following functions have been superceded by their newer, renamed equivalents. While it is best to use the new functions, you can use the older functions provided you define CSDK_USE_OLD_NAMES.
The following functions were included with previous versions of the SDK and are still supported for this release:
Included here is documentation for the functions CAPI_CreateFileStream and CAPI_AuthenticateAsSysop. For more information about these and other legacy functions, see the SDK source files or the documentation included with a previous release.
CSDKStatus CAPI_CreateFileStream ( CAPISession in_session, CAPIStream * out_stream, FILE * in_readFile, FILE * in_writeFile, CAPIFlag in_flags )
Creates file stream to allow the SDK to read from or write to open files.
For compatibility reasons, it is safer to use CSDK_CreateFileStreamFromFilenames which will prevent the need for passing FILE * variables between your application and CAPI.
Files must have been opened using fopen() with an appropriate mode.
CAPIStatus
The stream returned by this function must be destroyed by calling CSDK_DestroyStreams()
FILE * myFileFullOfMIMEEncapsulatediCal = fopen("events.ics", "rb"); if (myFileFullOfMIMEEncapsulatediCal != NULL) { CAPIStream myInputStream = NULL; CAPIStatus status = CAPI_CreateFileStream(mySession, &myInputStream, myFileFullOfMIMEEncapsulatediCal, NULL, // no output file CSDK_FLAG_NONE); if (status == CAPI_STAT_OK) { status = CAPI_StoreEvent(mySession, myHandles, numHandles, handleStatus, CAPI_STORE_REPLACE, myInputStream); } fclose(myFileFullOfMIMEEncapsulatediCal); CSDK_DestroyStreams(mySession, &myInputStream, 1, CSDK_FLAG_NONE); }
FILE * outputFile = fopen("myAgenda.ics", "wb"); if (outputFile != NULL) { CAPIStream myOutputStream = NULL; CAPIStatus status = CAPI_CreateFileStream(mySession, &myOutputStream, NULL, // no input file outputFile, CSDK_FLAG_NONE); if (status == CAPI_STAT_OK) { status = CAPI_FetchEventsByRange(mySession, myHandles, numHandles, handleStatus, CSDK_FLAG_NONE, "20020722T000000", "20020722T235900", NULL, 0, myOutputStream); } fclose(outputFile); CSDK_DestroyStreams(mySession, &myOutputStream, 1, CSDK_FLAG_NONE); }
None. The Java APIs only use String and StringBuffer objects to send and receive data.
CAPIStatus CAPI_AuthenticateAsSysop ( const char * in_password, const char * in_host, const char * in_node, CAPIFlag in_flags, CAPISession * io_session )
Log on as Calendar SYSOP.
Once logged on, the Calendar SYSOP can assume the identity of any user by calling CAPI_SetIdentity().
A node should always be specified since masternode and calendar-domain functionality is not available during logon as Calendar SYSOP.
If the host parameter specifies ACE mechanisms, these will be ignored. The admin default ACE settings from the calendar server will be used.
Calendar SYSOP authentication is only available with version 5.3 and newer servers. An error will be returned if the provided host does not support this feature. A calendar server may be configured to refuse Calendar SYSOP logon via CAPI in which case a security error will be returned.
The operations available to Calendar SYSOPs are limited to:
Once the identity has been set to a user, all operations will be performed as if that user had logged in.
See CAPI_Connect() for the format of the in_host parameter.
in_password: Calendar SYSOP's password. May be NULL.
in_host: Calendar server host name (optional port no.)
in_node: node ID to connect to as Calendar SYSOP.
in_flags: Bit flags modifying behaviour. This must be CAPI_FLAG_NONE currently.
io_session: Session opened by CAPI_Connect
CAPIStatus
Example: // Connect to myNode on the server running on the default port of calserver.acme.com, to authenticate as Calendar SYSOP: { CAPIStatus myStatus = CAPI_AuthenticateAsSysop("theSysopPassword", "calserver.acme.com", "1", CAPI_FLAG_NONE, &mySession); }
The sessions created by calling this routine must be destroyed by calling CAPI_Logoff.
SDK 9.0.4: in_node must now be specified as a number (e.g. "100"). Node aliases are no longer supported, and NULL can no longer be passed in.
