Creating,Reading,Updating and Deleting calendar entries
Chapter 11-2
Creating,Reading,Updating and Deleting calendar entries
This chapter explains how to use Calendar and Scheduling API functions to create or delete calendar entries.
Creating calendar entries
Calendar entries can be created in a database using the CalCreateEntry routine. CalCreateEntry takes iCalendar input and attempts to create an event in a Notes/Domino database based on that iCalendar.
The iCalendar input must contain data for a single calendar identifier, but that calendar entry may contain a recurrence pattern and may also contain additional VEVENTs that contain information about a specific instance. If the iCalendar specified does not contain a UID, then a UID will be generated for the created entry and optionally returned from the create method (a DHANDLE to char* data will be populated if it was provided).
When iCalendar input lists a value in ORGANIZER that matches the owner of the mailfile the entry is being created it, invitations to that calendar entry will be sent to all PARTICIPANTs listed in the iCalendar (although this can be disabled).
Reading calendar entries
Information about calendar entries in a date range can be returned using the CalReadRange routines. This will return view level information about any existing calendar entries that appear in a Notes/Domino calendar. This is useful to get the identifiers for calendar entries within a date range, as well as to get basic information about the calendar entries that would be needed to display those entries in a calendar view. This does not actually open any notes in the database, so it is performant but it also does not provide full information (such as the Description) in the returned iCalendar data. There are several advanced capabilities that can be used in the ReadRangeExt method to control the data that is returned and to control paging capabilities.
Information about a particular calendar entry can be read using the CalReadEntry routines. This requires that an identifier to a particular calendar entry be passed in. This identifier can be UID(preferred), NOTEID, or UNID. CalReadEntry does require opening the note or notes that represent the calendar data and returns a full iCalendar representation, including things like DESCRIPTION and references to attachment data.
For recurring meetings, CalReadEntry can return data about the entire series (An iCalendar VEVENT representing the recurrence pattern and series data as well as a VEVENT to represent any instances that contain data that is an exception to the base recurrence pattern or series data). Also, the specification of a RECURRENCE-ID allows for data for only a particular occurrence to be returned.
iCalendar data is returned as char* data in a DHANDLE.
Updating calendar entries
Calendar entries can be updated in a database using the CalUpdateEntry routine. CalUpdateEntry takes iCalendar input and attempts to update an event in a Notes/Domino database based on that iCalendar. The iCalendar itself contains the identifiers in the UID and/or RECURRENCE-ID, so these do not need to be specified as arguments.
Currently, only a single instance of a recurring meeting can be updated at a time. This means that the provided iCalendar input of a recurring update must contain a VEVENT that specifies both UID and RECURRENCE-ID. Note: Updates to more than one instance may be allowed in the future.
When iCalendar input lists a value in ORGANIZER that matches the owner of the mailfile the entry is being created it, invitations to that calendar entry will be sent to all PARTICIPANTs listed in the iCalendar (although this can be disabled).
Updates will fail if the iCalendar appears less recent than the existing iCalendar (based on SEQUENCE).
Deleting calendar entries
Calendar entries can be deleted from a database using the CalEntryAction routine and passing in the CAL_PROCESS_DELETE action. Unlike CalUpdateAction, CalEntryAction can act on an entire series, a particular instance, or a range (this and future). Using CAL_PROCESS_DELETE does not send out cancellations or decline notices and removes the calendar forever. If you are using this for meetings and want to send out cancelations or declines when you delete it, use CAL_PROCESS_SMARTDELETE instead and it will choose delete, cancel, or decline based on the calendar entry you are acting on.
Example Using Calendar and Scheduling Functions
- Create
code snippet
note: GetDBHdl is one of helper methods, used here only to show the usage of Calendar and Scheduling api. The code of these
functions can be find in samples.
*/
#define CRLF "\r\n"
#define ICAL_UID "20121120T172345Z-JJU9O5@example.com"
char pszICalendar[] = "BEGIN:VCALENDAR" CRLF
"VERSION:2.0" CRLF
"PRODID:-//hacksw/handcal//NONSGML v1.0//EN" CRLF
"BEGIN:VEVENT" CRLF
"UID:" ICAL_UID CRLF
"DTSTAMP:20121120T172345Z" CRLF
"DTSTART:20121120T100000Z" CRLF
"DTEND:20121120T120000Z" CRLF
"RRULE:FREQ=DAILY;COUNT=10" CRLF
"SUMMARY:Bastille Day Party" CRLF
"ORGANIZER:mailto:jsmith@example.com" CRLF
"ATTENDEE:mailto:jdoe@example.com" CRLF
"END:VEVENT" CRLF
"END:VCALENDAR" CRLF;
//delayed
//start at 20121120T180000Z and end at 20121120T210000Z
char pszICalendarDelayed[] = "BEGIN:VCALENDAR" CRLF
"VERSION:2.0" CRLF
"PRODID:-//hacksw/handcal//NONSGML v1.0//EN" CRLF
"BEGIN:VEVENT" CRLF
"UID:" ICAL_UID CRLF
"DTSTAMP:20121120T172345Z" CRLF
"DTSTART:20121120T180000Z" CRLF
"DTEND:20121120T210000Z" CRLF
"SUMMARY:(Delayed)Bastille Day Party" CRLF
"END:VEVENT" CRLF
"END:VCALENDAR" CRLF;
STATUS error = NOERROR;
char* pInputFile = "mail/Test.nsf";
DHANDLE hDB = NULLHANDLE;
DWORD dwFlags = 0;
MEMHANDLE hRetUID = NULL;
char* pszRetUID = NULL;
//step1:Get database handle;
if (error = GetDBHdl(pInputFile , hDB))
return error;
//step2:Create calendar entry to the database
error = CalCreateEntry(hDB, pszICalender, dwFlags, &hRetUID, NULL);
if (error == NOERROR)
return error;
pszRetUID = OSMemoryLock(hRetUID);
printf("UID Returnd %s \r\n", pszRetUID);
OSMemoryUnlock(hRetUID);
OSMemoryFree(hRetUID);
- Read:
code snippet
*/
STATUS error = NOERROR;
MEMHANDLE hCalData = NULL;
DWORD dwFlags = CAL_READ_INCLUDE_X_LOTUS;
char* pszCalData = NULL;
error = CalReadEntry(hDB, pszICalenderUID, NULL, &hCalData, NULL, dwFlags, NULL);
if(error != NOERROR)
return error;
pszCalData = OSMemoryLock(hCalData);
printf("Calender Data Returnd\r\n%s\r\n", pszCalData);
OSMemoryUnlock(hCalData);
OSMemoryFree(hCalData);
- Update:
code snippet
*/
STATUS error = NOERROR;
DWORD dwFlags = 0;
error = CalUpdateEntry(hDB, pszICalendarDelayed, NULL, NULL, "Delayed for some reason...", dwFlags, NULL);
- Delete
code snippet
*/
STATUS error = NOERROR;
DWORD dwAction = CAL_PROCESS_DELETE;
DWORD dwRange = 0;
PEXT_CALACTION_DATA pExtActionInfo = NULL;
error = CalEntryAction(hDB, pszICalenderUID, NULL, dwAction, dwRange, "Cancled", pExtActionInfo, 0, NULL);
---