| Oracle Calendar API Developer's Guide Release 2.5 Part Number B10097-01 |
|
| View PDF |
| Oracle Calendar API Developer's Guide Release 2.5 Part Number B10097-01 |
|
| View PDF |
This chapter contains detailed information on the following functions:
CAPIStatus CAPI_AuthenticateAsSysop ( const char * in_password, const char * in_host, const char * in_nodeName, CAPIFlag in_flags, CAPISession * io_session )
Logon as sysop.
Once logged on, the 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 sysop.
If the host parameter specifies ACE mechanisms, these will be ignored. The admin default ACE settings from the calendar server will be used.
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 sysop logon via CAPI in which case a security error will be returned.
The operations available to 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.
CAPIStatus
The sessions created by calling this routine must be destroyed by calling CAPI_Logoff.
Connect to myNode on the server running on the default port of calserver.acme.com, to authenticate as sysop:
{ CAPIStatus myStatus = CAPI_AuthenticateAsSysop("theSysopPassword", "calserver.acme.com", "myNode", CAPI_FLAG_NONE, &mySession); }
Connect to the default node on the server running on the default port of calserver.acme.com, to authenticate as sysop:
{ CAPIStatus myStatus = CAPI_AuthenticateAsSysop("theSysopPassword", "calserver.acme.com", NULL, CAPI_FLAG_NONE, &mySession); }
CAPIStatus CAPI_Connect ( const char * in_host, CAPIFlag in_flags, CAPISession * out_session )
Establish a connection with a calendar service.
The session obtained in this manner can only be used with CAPI_GetCapabilities, CAPI_Logon or CAPI_Logoff. The session cannot be used to perform any other calendar operations until a user has authenticated using CAPI_Logon.
The format of the in_host parameter is:
host-string = hostname "?" ext-param x00
Nul-terminated string
hostname = *( ALPHA / DIGIT / "." ) [":" port-number]
Identifies a calendar store, or calendar domain server (CDS)
port-number = 1*DIGIT
Identifies the port on which the server is listening (optional). In most cases this should be left out so as to use the default port number
CAPIStatus
{ CAPIStatus myStatus = CAPI_STAT_OK; CAPISession mySession = NULL; myStatus = CAPI_connect("calserver.acme.com", CAPI_FLAG_NONE, &mySession); }
Connect to port 12345 on host calserver.acme.com:
{ CAPIStatus myStatus = CAPI_STAT_OK; CAPISession mySession = NULL;
myStatus = CAPI_connect("calserver.acme.com:12345", CAPI_FLAG_NONE, &mySession);
}
CAPIStatus CAPI_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 CAPI.
C function pointers are given to CAPI for each action (send, receive) which CAPI will call to either read or send data.
During a CAPI_Store...() call, CAPI 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 CAPI_Fetch...() call, CAPI 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:
Send callback:
Receive callback:
When CAPI 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 CAPI_DestroyStreams()
CAPIStatus
CAPI_STAT_API_NULL : both supplied callbacks were NULL
CAPI_CreateMemoryStream() , CAPI_CreateFileStreamFromFilenames()
CAPIStatus CAPI_CreateFileStream ( CAPISession in_session, CAPIStream * out_stream, FILE * in_readFile, FILE * in_writeFile, CAPIFlag in_flags )
Creates file stream to allow CAPI to read from or write to open files.
For compatibility reasons, it is safer to use CAPI_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
Store events from the file "events.ics":
FILE * myFileFullOfMIMEEncapsulatediCal = fopen("events.ics", "rb"); if (myFileFullOfMIMEEncapsulatediCal != NULL) { CAPIStream myInputStream = NULL; CAPIStatus status = CAPI_CreateFileStream(mySession, &myInputStream, myFileFullOfMIMEEncapsulatediCal, NULL, // no output file CAPI_FLAG_NONE); if (status == CAPI_STAT_OK) { status = CAPI_StoreEvent(mySession, myHandles, numHandles, handleStatus, CAPI_STORE_REPLACE, myInputStream); } fclose(myFileFullOfMIMEEncapsulatediCal); CAPI_DestroyStreams(mySession, &myInputStream, 1, CAPI_FLAG_NONE); }
Fetch events and write them to the file "myAgenda.ics":
FILE * outputFile = fopen("myAgenda.ics", "wb"); if (outputFile != NULL) { CAPIStream myOutputStream = NULL; CAPIStatus status = CAPI_CreateFileStream(mySession, &myOutputStream, NULL, // no input file outputFile, CAPI_FLAG_NONE); if (status == CAPI_STAT_OK) { status = CAPI_FetchEventsByRange(mySession, myHandles, numHandles, handleStatus, CAPI_FLAG_NONE, "20020722T000000", "20020722T235900", NULL, 0, myOutputStream); } fclose(outputFile); CAPI_DestroyStreams(mySession, &myOutputStream, 1, CAPI_FLAG_NONE); }
CAPIStatus CAPI_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 CAPI to read from or write to files.
CAPIStatus
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 CAPI_FLAG_NONE); if (status == CAPI_STAT_OK) { status = CAPI_StoreEvent(mySession, myHandles, numHandles, handleStatus, CAPI_STORE_REPLACE, myInputStream); CAPI_DestroyStreams(mySession, &myInputStream, 1, CAPI_FLAG_NONE); }
Fetch events and write them to the file "myAgenda.ics":
CAPIStream myOutputStream = NULL; CAPIStatus status = CAPI_CreateFileStreamFromFilenames(mySession, &myOutputStream, NULL, // no input file NULL, // no input file mode "myAgenda.ics", "wb", CAPI_FLAG_NONE); if (status == CAPI_STAT_OK) { status = CAPI_FetchEventsByRange(mySession, myHandles, numHandles, handleStatus, CAPI_FLAG_NONE, "20020722T000000", "20020722T235900", NULL, 0, myOutputStream); CAPI_DestroyStreams(mySession, &myOutputStream, 1, CAPI_FLAG_NONE); }
CAPIStatus CAPI_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 CAPI.
This is often the simplest type of stream to use.
Read buffers are read by CAPI during CAPI_Store... calls and write buffers are written to by CAPI during CAPI_Fetch... calls. The read buffers are managed by your application, whereas CAPI will allocate and free the write buffers. The write buffer is freed by CAPI when the memory stream is destroyed.
The stream returned by this function must be destroyed by calling CAPI_DestroyStreams.
CAPIStatus
CAPI_STAT_API_NULL : both supplied buffers were NULL
Store events from the buffer "events"
const char events[] = "MIME-Version: 1.0\n" "Content-Type: text/calendar\n" "Content-Transfer-Encoding: quoted-printable\n\n" "BEGIN:VCALENDAR\n" "VERSION:2.0\n" ...etc "END:VCALENDAR\n"; CAPIStream myInputStream = NULL; CAPIStatus status = CAPI_CreateMemoryStream(mySession, &myInputStream, events, NULL, // no write buffer CAPI_FLAG_NONE); if (status == CAPI_STAT_OK) { status = CAPI_StoreEvent(mySession, myHandles, numHandles, handleStatus, CAPI_STORE_REPLACE, myInputStream); CAPI_DestroyStreams(mySession, &myInputStream, 1, CAPI_FLAG_NONE); }
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, CAPI_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:\n%s", todaysEvents); } CAPI_DestroyStreams(mySession, &myOutputStream, 1, CAPI_FLAG_NONE); }
CAPIStatus CAPI_DeleteEvent ( CAPISession in_session, CAPIHandle * in_handles, int in_numHandles, CAPIStatus * io_status, CAPIFlag in_flags, const char * in_UID, const char * in_RECURRENCEID, int in_modifier )
This function deletes the specified event from the specified agendas.
The events to delete are identified by the UID, recurrence ID and modifiers. If the recurrence ID is not specified it is assumed that all recurrences should be deleted. The event is only removed from the agendas specified by the supplied CAPIHandles.
Different agendas may have different events with the same UID, at most one of which the current user may be able to modify. Each element in the array of errors may be set to indicate that there was no such UID, that the current user cannot modify that event, or that the event was found, and deleted from the agenda (OK). If no event could be deleted from any agenda the returned status will be fatal. If any agenda had a security error, the returned status will be a security error. If no agenda had a security error, but at least one had a no such UID error, then the returned status will be no such UID. Otherwise the returned status will be OK, (Unless an error occured in processing).
CAPIStatus
CAPIStatus CAPI_DestroyHandles ( CAPISession in_session, CAPIHandle * io_handles, int in_numHandles, CAPIFlag in_flags )
Destroy handles returned by CAPI_GetHandle().
CAPIStatus
{ CAPIHandle h1, h2; CAPI_GetHandle(mySession, "arthur", CAPI_FLAG_NONE, &h1); CAPI_GetHandle(mySession, "tim...", CAPI_FLAG_NONE, &h2); ... CAPIHandle handles[] = {h1, h2}; CAPI_DestroyHandles(mySession, handles, 2, CAPI_FLAG_NONE); }
CAPIStatus CAPI_DestroyStreams ( CAPISession in_session, CAPIStream * in_streams, int in_numStreams, CAPIFlag in_flags )
This function destroys streams created by the various CAPI_CreateXXXStream functions.
CAPIStatus
CAPIStatus CAPI_FetchEventByID ( CAPISession in_session, CAPIHandle in_handle, CAPIFlag in_flags, const char * in_UID, const char * in_RECURRENCEID, int in_modifier, const char ** in_requestProperties, int in_numProperties, CAPIStream in_stream )
This function fetches an event from the server using its iCalendar UID.
First the event with the specified UID is retrieved from the specified agenda. If the property list is not NULL the event is stripped to include only those specified properties. The event is then encapsulated in a calendar object inside a MIME object and written to the supplied stream.
If the event cannot be found an error is returned and nothing is written to the stream. If a property is requested, but cannot be returned for security reasons a non-fatal error is returned.
CAPIStatus
CAPIStatus CAPI_FetchEventsByAlarmRange ( CAPISession in_session, CAPIHandle * in_handles, int in_numHandles, CAPIStatus * io_status, CAPIFlag in_flags, const char * in_DTSTART, const char * in_DTEND, const char ** in_requestProperties, int in_numProperties, CAPIStream in_stream )
This function downloads events with alarms which fall in the specified time range and returns them as MIME-Encapsulated iCalendar data via the CAPIStream.
For each handle; events are downloaded from that handle's associated agenda, as long as the event has an alarm which falls in the time range between the indicated start and end times. If in_requestProperties is non-NULL the events are stripped to include only the indicated properties. The objects are then sent to the CAPIStream.
A single MIME multipart object is written to the stream. A part is created in the MIME object for each handle which was passed. Each part contains a single Calendar object. The calendar object will contain any events that were found on the indicated agenda. The order of the returned calendar objects corresponds to the order of the received handles.
If any of the indicated properties are not available for security reasons a non-fatal error will be returned.
CAPIStatus
CAPIStatus CAPI_FetchEventsByRange ( CAPISession in_session, CAPIHandle * in_handles, int in_numHandles, CAPIStatus * io_status, CAPIFlag in_flags, const char * in_DTSTART, const char * in_DTEND, const char ** in_requestProperties, int in_numProperties, CAPIStream in_stream )
This function downloads events which fall in the specified time range and returns them as MIME-Encapsulated iCalendar data via the CAPIStream.
For each handle; events are downloaded from that handle's associated agenda, as long as the event overlaps the time range between the indicated start and end times. If in_requestProperties is non-NULL the events are stripped to include only the indicated properties. The objects are then sent to the CAPIStream.
A single MIME multipart object is written to the stream. A part is created in the MIME object for each handle which was passed. Each part contains a single Calendar object. The calendar object will contain any events that were found on the indicated agenda. The order of the returned calendar objects corresponds to the order of the received handles.
If any of the indicated properties are not available for security reasons a non-fatal error will be returned.
Please note that some vendors may not support the complete range of dates that iCalendar supports. If this is the case then the CAPI should behave as if the server supports the full range of iCalendar dates and that there are no events outside the server supported range. However CAPI should indicate if a fetch range overlapped the range not supported by the server by returning a non-fatal error. The server supported date ranges can be obtained through a call to CAPI_GetCapabilities.
CAPIStatus
CAPIStatus CAPI_GetCapabilities ( CAPISession in_session, CAPICapabilityID in_capabilityID, CAPIFlag in_flags, const char ** out_value )
Returns information on this CAPI release and/or the calendar server.
CAPI 2.5: type of in_capabilityID was changed from "long" to "CAPICapabilityID"
CAPIStatus CAPI_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 logon string follows the same format as that of the string used by CAPI_Logon.
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.
CAPIStatus
This function allocates a handle which must be cleaned up with a call to CAPI_DestroyHandles. If an error is returned no handle is allocated and no clean up is required.
Get a handle for a user whose userid is "roger":
{ CAPIHandle shrubber = NULL; stat = CAPI_GetHandle(mySession, "roger", CAPI_FLAG_NONE, &shrubber); }
Get a handle for a user named "Arnold Layne" (Surname Layne, Given name Arnold):
{ CAPIHandle arnold = NULL; stat = CAPI_GetHandle(mySession, "?/S=Layne/G=Arnold/, CAPI_FLAG_NONE, &arnold); }
Get a handle for a resource named "keg" on node "1234":
{ CAPIHandle keg = NULL; stat = CAPI_GetHandle(mySession, "?/RS=keg/ND=1234/", CAPI_FLAG_NONE, &keg); }
Get a handle for the current user:
{ CAPIHandle currUser = NULL; stat = CAPI_GetHandle(mySession, NULL, CAPI_FLAG_NONE, &currUser); }
CAPI 2.5: Resource names must be an exact match. (There used to be an implicit * at the end of the string.)
CAPIStatus CAPI_GetLastStoredUIDs ( CAPISession in_session, char const *const ** out_UIDs, unsigned long * out_count, CAPIFlag in_flags )
This function returns the UID(s) of the last event(s) stored by a successful call to CAPI_StoreEvent, or no UID if the there was no call to CAPI_StoreEvent or the last call was not successful.
The UIDs returned are static read-only strings. The strings are only valid until the next call to CAPI_StoreEvent; hence, it may be desirable to copy (e.g. strcpy()) the UIDs to another variable. These UIDs are appropriate for use in subsequent CAPI calls.
CAPIStatus
CAPI 2.5 : type of "out_count" changed from "long *" to "unsigned long *"
{ const char ** newUIDs = NULL; unisigned long numUIDs = 0; CAPI_StoreEvent(mySession, ...); stat = CAPI_GetLastStoredUIDs(mySession, &newUIDs, &numUIDs, CAPI_FLAG_NONE); for (unisigned long u = 0; u < numUIDs; u++) { cout << "Stored UID:" << newUIDs[u] << endl; } }
void CAPI_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 *"
void CAPI_GetStatusString ( CAPIStatus in_status, const char ** out_string )
This function returns a read-only string representation of a CAPIStatus.
This is generally more useful to a programmer than the numeric representation.
None. The string returned is a const string that cannot be freed
CAPIStatus CAPI_HandleInfo ( 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 static 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 CAPI_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 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.
Print the name of the logged in user:
{ CAPIHandle loginUser = NULL; const char * fullName = NULL; stat = CAPI_GetHandle(mySession, NULL, CAPI_FLAG_NONE, &loginUser); stat = CAPI_HandleInfo(mySession, loginUser, CAPI_HANDLE_NAME, &fullName); cout << "Currently logged in as " << fullName << endl; CAPI_DestroyHandles(mySession, &loginUser, 1, CAPI_FLAG_NONE); }
Print out Doctor Winston's e-mail address:
{ CAPIHandle doctor = NULL; const char * email = NULL; stat = CAPI_GetHandle(mySession, "drwinston", CAPI_FLAG_NONE, &doctor); stat = CAPI_HandleInfo(mySession, doctor, CAPI_HANDLE_MAILTO, &email); cout << "drwinston's email address is " << email << endl; CAPI_DestroyHandles(mySession, &doctor, 1, CAPI_FLAG_NONE); }
CAPIStatus CAPI_Logoff ( CAPISession * io_session, CAPIFlag in_flags )
Use CAPI_Logoff to either de-authenticate, or completely close your CAPISession.
To select which action to perform, use the in_flags parameter with either of these values:
CAPI_MODE_NONE: De-authenticate and disconnect from the calendar server
CAPI_LOGOFF_STAY_CONNECTED: De-authenticate but stay connected. The session can still be used to read capabilities and can be used to re-authenticate (as the same user or a different user) using CAPI_Logon().
CAPIStatus
Since the "stay connected" mode does not destroy the session, a final call to CAPI_Logoff is needed to destroy the sesssion in this case.
Disconnect from a server:
{ ... stat = CAPI_Logoff(&mySession, CAPI_MODE_NONE); // mySession should now be NULL }
Re-authenticate as a different user:
{ ... stat = CAPI_Logoff(&mySession, CAPI_LOGOFF_STAY_CONNECTED); ... stat = CAPI_Logon("manfromscene24", "blue", "", CAPI_FLAG_NONE, &mySession); }
CAPIStatus CAPI_Logon ( const char * in_user, const char * in_password, const char * in_host, CAPIFlag in_flags, CAPISession * io_session )
Establish a session with the Calendar Store.
No session will be returned if an error occurs.
The session parameter can be used in 2 ways:
With calendar servers that support the ACE framework, CAPI_Logon will try to use the default ACE mechanisms set by the server. For authentication mechanisms that don't require user credentials at each logon (e.g. gssapi:kerberos5 or web:CAL), an empty string may be passed for the user and password parameters.
The in_host parameter is the same as documented in CAPI_Connect except it may have extended parameters as shown:
host-string = hostname "?" ext-param x00 ext-param = DELIMITER fields the extended string is used to specify ACE mechanisms fields = [authentication-mech] [compression-mech] [encryption-mech] authentication-mech = "AUTH=" ACE-mechanism DELIMITER compression-mech = "COMP=" ACE-mechanism DELIMITER encryption-mech = "ENCR=" ACE-mechanism DELIMITER To find out which ACE-mechanisms the server support use CAPI_Connect followed by CAPI_GetCapabilities DELIMITER = x01-29 / x2B-2F / x3A-3C / x3E-40 / %5B-60 / %7B-7F Everything except NUL, "*", DIGIT, "=", ALPHA
Please refer to the section on User Identification for the format of the in_user parameter.
CAPIStatus
The sessions created by calling this routine must be destroyed by calling CAPI_Logoff.
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 = NULL; myStatus = CAPI_connect("calserver.acme.com", CAPI_FLAG_NONE, &mySession); if (myStatus == CAPI_STAT_OK) { myStatus = CAPI_Logon("keithm", "abcdefg", "", CAPI_FLAG_NONE, &mySession); } }
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 = NULL; myStatus = CAPI_connect("calserver.acme.com", CAPI_FLAG_NONE, &mySession); if (myStatus == CAPI_STAT_OK) { myStatus = CAPI_Logon("?/S=MacDonald/G=Keith/ND=200/", "abcdefg", "", CAPI_FLAG_NONE, &mySession); } }
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 = NULL; myStatus = CAPI_connect("calserver.acme.com", CAPI_FLAG_NONE, &mySession); if (myStatus == CAPI_STAT_OK) { myStatus = CAPI_Logon("keithm?/ND=200/", "abcdefg", "", CAPI_FLAG_NONE, &mySession); } }
Connect to a server running on calserver.acme.com, using gssapi:kerberos5 authenticatication:
{ CAPISession mySession = NULL; myStatus = CAPI_connect("calserver.acme.com", CAPI_FLAG_NONE, &mySession); if (myStatus == CAPI_STAT_OK) { myStatus = CAPI_Logon("", "", "?/AUTH=gssapi:kerberos5/", CAPI_FLAG_NONE, &mySession); } }
(Note: for web authentication, replace "gssapi:kerberos5" with "web:CAL")
Authenticate as user keithm using the company domain MYDOMAIN hosted by the domain server "mycds.myasp.com"
{ CAPISession mySession = NULL; CAPIStatus myStatus = CAPI_Logon("keithm?/CD=MYDOMAIN/", "abcdefg", "mycds.myasp.com" CAPI_FLAG_NONE, &mySession); }
CAPIStatus CAPI_SetConfigFile ( const char * in_configFileName, const char * in_logFileName )
Calling this function will allow CAPI to read configuration settings which control error logging, and the other configuration parameters listed in the "Configuration" section of this manual.
Note: To use the "web" ACE authentication module, you MUST call this function since the web authentication reads configuration settings from this file.
Note: If called, this function should be the first CAPI function called by your process and should not be called by each thread.
CAPIStatus
CAPI_STAT_API_NULL : one of the input parameters was NULL
The Configuration section.
Create a file "capi.ini" with the contents:
[LOG] log_activity = true log_modulesinclude = { CAPI }
and call CAPI_SetConfigFile:
CAPIStatus stat = CAPI_SetConfigFile("capi.ini", "capi.log");
This will turn on "activity" level logging in CAPI and the output will go into capi.log.
CAPIStatus CAPI_SetIdentity ( CAPISession in_session, const char * in_user, CAPIFlag in_flags )
Allow an authenticated user (CAPI_Logon) to work on behalf of another calendar user or resource.
For this to work, full designate rights must have been set in advance; otherwise a security error will be returned.
The format of the in_user parameter is the same as in the CAPI_Logon function. The authenticated user may revert to her original identity by using NULL as username.
If you've logged in as sysop (CAPI_AuthenticateAsSysop), 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.
CAPIStatus
myStatus = CAPI_SetIdentity(mySession, "keithm", CAPI_FLAG_NONE); myStatus = CAPI_SetIdentity(mySession, "?/S=MacDonald/G=Keith/", CAPI_FLAG_NONE); myStatus = CAPI_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 * at the end of the string.)
CAPIStatus CAPI_StoreEvent ( CAPISession in_session, CAPIHandle * in_handles, int in_numHandles, CAPIStatus * io_status, CAPIFlag in_flags, CAPIStream in_stream )
Store events in the supplied list of calendars.
If an event is already in the Calendar (as identified by its UID and Recurrence-ID) it will be updated. CAPI is not responsible for enforcing iCalendar security or data integrity as defined by the "ORGANIZER", "SEQUENCE" and "DTSTAMP" properties. It is the responsibility of the CAPI user to be familiar with this model and to enforce it. CAPI_StoreEvent is capable of overwriting these properties.
When this function returns, the buffer for CAPIStatus return values, io_status, will contain the status associated with each handle relative to the store operation. That is, io_status[i] holds the status of the store operation for the calendar addressed by in_handles[i]. io_status must be large enough to hold in_numHandles CAPIStatus codes. A failure for one particular handle will not cause a failure for the entire operation.
CAPI_StoreEvent allows data to passed in several VEVENT components. Each VEVENT may or may not refer to the same event. These will be processed as if they had been supplied to many consecutive calls to CAPI_StoreEvent, one per call, in the order in which they appear in the "VCALENDAR". Despite the fact that behaviour is the same, it is preferable to make only one call to CAPI_StoreEvent, as this is likely to be more efficient than many calls. A huge collection of VEVENTs will however require more memory to process.
CAPI_StoreEvent can create new instances, either of a new event or of an event which is already on the server. It can also be used to modify groups of instances, either all, one or a range of instances of an existing event. The appropriate behaviour is chosen through the specification of the properties "UID", "RECURRENCE-ID", "DTSTART", "RDATE", "RRULE", "EXDATE" and "EXRULE".
If "UID" does not match an event that already exists on the server then it is a request to create a new event on the server. In this case a "RECURRENCE-ID" property may not be specified, and a "DTSTART" property must be specified.
If the "UID" property matches an event that already exists on the server, the "RECURRENCE-ID" property is not present, and at least one of "DTSTART", "RDATE", "RRULE", "EXDATE" and "EXRULE" is present then the request is to add new instances to the event. If any instances on the server are identified by these dates they will be overwritten.
If the "UID" property matches an event that already exists on the server, and none of "RECURRENCE-ID", "DTSTART", "RDATE", "RRULE", "EXDATE" or "EXRULE" are present, then this is a request to modify all of the instances of an event. In this case the "DTEND" property may not be present.
If the "UID" property matches an event that already exists on the server, and the "RECURRENCE-ID" property is present, and it has no "range" parameter, then this is a request to modify a single instance. None of the properties "RDATE", "RRULE", "EXDATE" and "EXRULE" can be specified in this case, but the "DTSTART" property can be used to modify the start time of the particular instance.
If the "UID" property matches an event that already exists on the server, and the "RECURRENCE-ID" property is present, and it has a "range" parameter, then this is a request to modify a range of instances. None of the properties "DTSTART", "RDATE", "RRULE", "EXDATE" and "EXRULE" can be specified in this case. Also, "DTEND" may not be specified, although "DURATION" may be.
The iCalendar "RRULE" property is a concise way of specifying many instances of an event, however CAPI expands recurrence rules to specific dates, storing only these dates, and discarding the expanded recurrence rule. In the case of a recurrence rule that goes for ever, the list of created dates will be limited to a server-defined number of instances.
E-mail and wireless notification of newly created and modified events can be sent using the CAPI_NOTIFY_EMAIL and CAPI_NOTIFY_SMS flags.
E-mail, wireless and audio reminders to be triggered in advance of an event are also supported. Specify them using VALARM objects in the following format:
BEGIN:VALARM ACTION:<name> TRIGGER:-PT2H1M END:VALARM
where <name> can take one of the following values:
CAPI_StoreEvent also provides the following mutually exclusive bit flags which govern the interpretation of the rest of the specified properties:
This mode can be used when creating new instances or modifying existing ones. When creating new instances they are created with all the properties as specified in the data. When existing instances are being modified all their properties are replaced with the ones specified in the supplied data.
Event as it currently appears in the calendar store, prior to calling CAPI_StoreEvent (applies to all examples):
BEGIN:VEVENT ORGANIZER:Mailto:A@example.com ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED;CN=BIG A:Mailto:A@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=B:Mailto:B@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=C:Mailto:C@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=Hal:Mailto:D@example.com ATTENDEE;RSVP=FALSE;TYPE=ROOM:conf_Big@example.com ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE:Mailto:E@example.com DTSTAMP:19980611T190000Z DTSTART:19980701T200000Z DTEND:19980701T2100000Z SUMMARY:Conference LOCATION:The Big Conference Room UID:calsrv.example.com-873970198738777@example.com SEQUENCE:0 STATUS:CONFIRMED END:VEVENT
Call CAPI_StoreEvent with the following ICAL stream, which modifies a particular instance:
BEGIN:VCALENDAR PRODID:-//ACME//NONSGML DesktopCalendar//EN VERSION:2.0 BEGIN:VEVENT ORGANIZER:Mailto:A@example.com ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED;CN=BIG A:Mailto:A@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=B:Mailto:B@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=C:Mailto:C@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=Hal:Mailto:D@example.com DTSTAMP:19980611T190000Z RECURRENCE-ID:19980701T200000Z DURATION:PT1H SUMMARY:Conference UID:calsrv.example.com-873970198738777@example.com SEQUENCE:1 STATUS:CONFIRMED END:VEVENT END:VCALENDAR
Upon successful completion of the CAPI_StoreEvent call, the event stored on the server will have its properties replaced the net effect being:
This mode can be used when creating new instances or modifying existing ones. When creating new instances they are created with all the properties as specified in the data. When existing instances are being modified, this mode only affects the specified properties. Any property that is updated must be completely updated. Effectively, all instances of any supplied property are completely deleted from the event on the calendar store and replaced with supplied properties. Thus, even to update a single ATTENDEE property, all ATTENDEE properties must be supplied.
Call CAPI_StoreEvent with the following ICAL stream:
BEGIN:VCALENDAR PRODID:-//ACME//NONSGML DesktopCalendar//EN VERSION:2.0 BEGIN:VEVENT RECURRENCE-ID:19980701T200000Z DTEND:19980701T2200000Z DESCRIPTION:We need to discuss the project schedule. Please come prepared. UID:calsrv.example.com-873970198738777@example.com SEQUENCE:1 END:VEVENT END:VCALENDAR
Call CAPI_StoreEvent with the following ICAL stream:
BEGIN:VCALENDAR PRODID:-//ACME//NONSGML DesktopCalendar//EN VERSION:2.0 BEGIN:VEVENT ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED;CN=BIG A:Mailto:A@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=B:Mailto:B@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=C:Mailto:C@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=Hal:Mailto:D@example.com ATTENDEE;RSVP=FALSE;TYPE=ROOM:conf_Big@example.com ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE:Mailto:E@example.com RECURRENCE-ID:19980701T200000Z DTEND:19980701T2200000Z DESCRIPTION:We need to discuss the project schedule. Please come prepared. UID:calsrv.example.com-873970198738777@example.com SEQUENCE:1 END:VEVENT END:VCALENDAR
When CAPI_StoreEvent is called with either one of the above ICAL streams, the end time of the event recurrence will be moved, a description will be added, and the sequence number will be bumped. The calendar store copy will be as follows:
BEGIN:VEVENT ORGANIZER:Mailto:A@example.com ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED;CN=BIG A:Mailto:A@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=B:Mailto:B@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=C:Mailto:C@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=Hal:Mailto:D@example.com ATTENDEE;RSVP=FALSE;TYPE=ROOM:conf_Big@example.com ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE:Mailto:E@example.com DTSTAMP:19980611T193000Z DTSTART:19980701T200000Z DTEND:19980701T2200000Z SUMMARY:Conference DESCRIPTION:We need to discuss the project schedule. Please come prepared. LOCATION:The Big Conference Room UID:calsrv.example.com-873970198738777@example.com SEQUENCE:1 STATUS:CONFIRMED END:VEVENT
This mode can only be used when modifying existing instances of an event. The non-indexing properties are deleted from the event. Some properties may appear many times. To delete one of these an exact match is required on the property, and its value, but not necessarily its parameters. For properties like "DURATION", which do not have a text value, the string output by CAPI must be matched. To delete all appearances of a particular property the property name only is specified, with no value and no parameters.
Call CAPI_StoreEvent with the following ICAL stream:
BEGIN:VCALENDAR PRODID:-//ACME//NONSGML DesktopCalendar//EN VERSION:2.0 BEGIN:VEVENT LOCATION:The Big Conference Room SUMMARY:Bla Bla Bla UID:calsrv.example.com-873970198738777@example.com END:VEVENT END:VCALENDAR
Upon successful completion of the CAPI_StoreEvent call, the LOCATION property will be deleted. The SUMMARY property will not be touched because it does not match the current summary. The calendar store copy will be as follows:
BEGIN:VEVENT ORGANIZER:Mailto:A@example.com ATTENDEE;ROLE=CHAIR;PARTSTAT=ACCEPTED;CN=BIG A:Mailto:A@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=B:Mailto:B@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=C:Mailto:C@example.com ATTENDEE;RSVP=TRUE;TYPE=INDIVIDUAL;CN=Hal:Mailto:D@example.com ATTENDEE;RSVP=FALSE;TYPE=ROOM:conf_Big@example.com ATTENDEE;ROLE=NON-PARTICIPANT;RSVP=FALSE:Mailto:E@example.com DTSTAMP:19980611T190000Z DTSTART:19980701T200000Z DTEND:19980701T2100000Z SUMMARY:Conference UID:calsrv.example.com-873970198738777@example.com SEQUENCE:0 STATUS:CONFIRMED END:VEVENT
in_stream : stream for CAPI to read data from
CAPIStatus
|
 Copyright © 1996, 2002 Oracle Corporation. All Rights Reserved. |
|
