Chapter 11-15

Calendar and Scheduling





Introduction

Calendar and scheduling features are available through the C API. This section will focus on how to add an appointment or a meeting invitation to a User's schedule, delete a scheduled event from a User's schedule and query a User's busy/free time information. Please refer to the sample program, misc\schedule for coding details.

Components of Calendar and Scheduling

The following items comprise an appointment note in a User's schedule maintained in the User's mail database.

Item Name
Description
Constant
$Alarm Alarm is on
$AlarmDescriptionShows up when alarm rings
$AlarmOffsetx minutes before or after StartDateTime
$BusyNameFully distinguished username of person that is busyMAIL_APPT_BUSYNAME_ITEM
$BusyPriorityTells scheduler if time is busy or free MAIL_APPT_BUSYNAME_ITEM
$CSVersion This item is used to determine what version a cs document was created in
$NoPurgeEnd date/time (prevents note from being purged)FIELD_NOPURGE
$PublicAccessPrivate or public accessible
_ViewIconScheduled event Icon displayed
AppointmentTypeType of scheduled event
apptUNIDUNID of the scheduled event
BodyDetailed description of the scheduled event
BookFreeTimeCorrespond to the "Pencil in" check box in the Notes UI
CalendarDateTimeCauses appointment to show up in Calendar View
CHAIRFully distinguished name of the mail file owner
EndDateEnd date/time of the scheduled event
EndDateTimeEnd date/time of the scheduled eventMAIL_APPT_ENDTIME_ITEM
EndTimeEnd date/time of the scheduled event
ExcludeFromViewPrevents non sent appts from showing up in drafts view
FromFully distinguished usernameMAIL_FROM_ITEM
FormWhat form to displayFIELD_FORM
ORGTABLESet for the scheduled event
PrincipalFully distinguished name of the mail file owner
SEQUENCENUMKeeps the scheduled event orderedMAIL_APPT_SEQUENCE_ITEM
StartDateStart date/time of the scheduled event
StartDateTimeStart date/time of the scheduled eventMAIL_APPT_STARTTIME_ITEM
StartTimeStart date/time of the scheduled event
SubjectBrief description of the scheduled eventMAIL_SUBJECT_ITEM
Use NSFItemAppend API to add each item to the appointment note.

Item Name
Description
Constant
CopyTo Fully distinguished name(s) of the Optional invitee(s)
SendToFully distinguished name(s) of the Primary invitee(s)
BlindCopyToFully distinguished name(s) of FYI invitee(s)


Invita-
tion
Counter- ing
Re-
schedule
Accept-
ing
(1)
(2)
(1)
(2)
(2)
(1)
(2)
$BusyNamecurrent user--current user----current user--
$BusyPriority1--2----1--
$CSFlags------ww--w
$REF------yesyes--yes
_ViewIcon15813339393315883
_ViewIcon211
CopyToNULLyesyesyesyesyesyes
Delegator--------------
Delegee----yes--------
Formappointmentnoticenoticenoticenoticenoticeappointment
FormToUsenotice
NewEndDate----yesyes------
NewEndTime----yesyes------
NewStartDate----yesyes------
NewStartTime----yesyes------
NoticeType--ITTUAA
Recipientsyes------------
SEQUENCENUM1111313
StatusUpdate----yes--yesyes
(1)
(2)
(1)
(2)
(2)
(1)
(2)
Invita-
tion
Counter- ing
Re-
schedule
Accept-
ing
Declin- ing
Delegat- ing
Cancelled
Confirm- ed
(1)
(2)
(1)
(3)
(4)
(2)
(2)
$BusyNamecurrent user--current user--------
$BusyPriority2--2--------
$CSFlags--w--wwww
$REF--yes--yes--yesyes
_ViewIcon848484841338110
_ViewIcon21111
CopyToyesyesyesyesyesyesyes
Delegator--------yes----
Delegeeyes--yesyes------
Formnoticenoticenoticenoticenotice(ReplyNotice)notice
FormToUse----------noticenotice
NewEndDateyes--yes--------
NewEndTimeyes--yes--------
NewStartDateyes--yes--------
NewStartTimeyes--yes--------
NoticeTypeRRDDLCN
Recipients--------------
SEQUENCENUM1111133
StatusUpdateyes--yes----yesyes
(1)
(2)
(1)
(3)
(4)
(2)
(2)
Declin- ing
Delegat- ing
Cancelled
Confirm-
ed





The following sections describe each of the items alphabetically.

$Alarm
The $Alarm item is of type TYPE_NUMBER and indicates the alarm is on. Set this value to 1.

$AlarmOffset
The $AlarmOffset item is of type TYPE_NUMBER and indicates when the alarm should ring (negative = x minutes before StartDateTime or positive = x minutes after).

$BusyName
The $BusyName item is of type TYPE_TEXT and contains the fully distinguished username of the person that is busy in that timeslot (ex. CN=Jane Doe/OU=CAM/O=Lotus) .

$BusyPriority
The $BusyPriority item is of type TYPE_TEXT and tells the scheduler whether this schedule event should be considered busy or free time:

"1" = Busy Value
"2" = Not Busy

$CSFlags
The $CSFlags item is of type TYPE_TEXT.

"m"= R5 repeat message
"i" = R5 repeat instance

$CSVersion
The $CSVersion item is of type TYPE_TEXT.

Non existent for 4.5/4.6 documents
"2" = R5 documents

$NoPurge
The $NoPurge item is of type TYPE_TIME and contains the ending date/time. This item prevents the note from being purged by replication before the schedule event has occurred. Use ConvertTextToTIMEDATE for the ending time string (ex. "03/16/2000 05:00 pm"). $PublicAccess
The $PublicAccess item is of type TYPE_TEXT and indicates if this scheduled event can be viewed by public:

"1" indicates this scheduled event can be viewed by the public
Skip this item to mark it as Private

_ViewIcon
The _ViewIcon item is of type TYPE_NUMBER and indicates what view icon to use. When creating an appointment, set this value to 160. See the Summary of Invitation Event Note Itemssection for the used value when creating a meeting invitation.

_ViewIcon2
The _ViewIcon2 item is of type TYPE_NUMBER. It is the secondary icon to display in a view column. See the Summary of Invitation Event Note Itemssection for the used value when creating a meeting invitation.

AppointmentType
The AppointmentType item is of type TYPE_TEXT and can be one of the following values:

"0" = Personal Appointment
"1" = Anniversary
"2" = Event
"3" = Meeting Invitation
"4" = Reminder

apptUNID
The apptUNID item is of type TYPE_TEXT and contains the Universal NoteID of the scheduled event.

Body
The Body item is of type TYPE_COMPOSITE and contains the scheduled event's detailed description.

BookFreeTime
The BookFreeTime item is of type TYPE_TEXT. It is the "Pencil in" check box in the Notes UI:

"" = the not checked "Pencil in" check box
"1" = the checked "Pencil in" check box

CalendarDateTime
The CalendarDateTime is of type TYPE_TIME and contains the start date/time of the appointment. Adding this item to the note causes the scheduled time to show up in the calendar view. Use ConvertTextToTIMEDATE for CalendarDateTime string (ex. "03/16/2000 09:00 am"). CHAIR
The CHAIR item is of type TYPE_TEXT and contains the fully distinguished username of the owner of the mail database that created the calendar entry (ex. CN=Jane Doe/OU=CAM/O=Lotus) .

CopyTo
The CopyTo item is of type TYPE_TEXT or TYPE_TEXTLIST and contains the scheduled event's optional invitee(s). Delegator
The Delegator item is of type TYPE_TEXT and contains the fully distinguished username of the person delegating the event.

Delegee
The Delegee item is of type TYPE_TEXT and contains the fully distinguished username of the person the event is delegated to.

EndDate
The EndDate is of type TYPE_TIME and is the end date/time of the scheduled event. Use ConvertTextToTIMEDATE for CalendarDateTime string (ex. "03/16/2000 05:00 pm"). It is mainly used in the UI to display a single instance of a value from a multi-valued EndDateTime item. It is also used in some of the Calendar view display columns.

EndDateTime
The EndDateTime is of type TYPE_TIME or TYPE_TIME_RANGE and contains the end date/time of the scheduled event. Use ConvertTextToTIMEDATE for EndDateTime string (ex. "03/16/2000 05:00 pm").

EndTime
The EndTime is of type TYPE_TIME and contains the end date/time of the scheduled event. Use ConvertTextToTIMEDATE for CalendarDateTime string (ex. "03/16/2000 05:00 pm"). It is mainly used in the UI to display a single instance of a value from a multi-valued EndDateTime item. It is also used in some of the Calendar view display columns.

ExcludeFromView
The ExcludeFromView item is of type TYPE_TEXT and prevents the scheduled events that are not sent from showing up in the drafts view. The value of this item is "D".

Form
The Form item is of type TYPE_TEXT and determines what form to display. Set this value to "Appointment" when creating an appointment. When creating a meeting invitation, see the Summary of Invitation Event Note Itemssectionfor the required value.

FormToUse
The FormToUse item is of type TYPE_TEXT.

From
The From item is of type TYPE_TEXT and contains the fully distinguished username who created or sent it (ex. CN=Jane Doe/OU=CAM/O=Lotus). NewEndDate
The NewEndDate is of type TYPE_TIME and is the new end date/time of the scheduled event.

NewEndTime
The NewEndTime is of type TYPE_TIME and is the new end date/time of the scheduled event.

NewStartDate
The NewStartDate is of type TYPE_TIME and is the new start date/time of the scheduled event.

NewStartTime
The NewStartTime is of type TYPE_TIME and is the new start date/time of the scheduled event.

NoticeType
The NoticeType item is of type TYPE_TEXT and can be one of the following values:

"I" = Invitation
"U" = Rescheduled
"C" = Cancelled
"N" = Confirmed
"A" = Accepted
"R" = Declined
"T" = Countered
"D" = Delegated
"L" = Delegate Invited

OptionalAttendees
The OptionalAttendees item is of type TYPE_TEXT and contains the fully distinguished username of the Optional invitees (ex. CN=Jane Doe/OU=CAM/O=Lotus).

ORGTABLE
The ORGTABLE item is of type TYPE_TEXT. It is set to "C0" for Calendar. Principal
The Principal item is of type TYPE_TEXT and contains the fully distinguished username of the owner of the mail database (ex. CN=Jane Doe/OU=CAM/O=Lotus). Recipients
The Recipients item is of type TYPE_TEXT or TYPE_TEXTLIST and contains the fully distinguished username(s) of all the invitees (ex. CN=Jane Doe/OU=CAM/O=Lotus).

RequiredAttendees
The RequiredAttendees item is of type TYPE_TEXT and contains the fully distinguished username of the Primary invitees (ex. CN=Jane Doe/OU=CAM/O=Lotus).

SendTo
The SendTo item is of type TYPE_TEXT or TYPE_TEXTLIST and contains the scheduled event's primary invitee(s). SEQUENCENUM
The SEQUENCENUM item is of type TYPE_NUMBER and keeps the scheduled events ordered. Set this value to 1 initially.

StartDate
The StartDate is of type TYPE_TIME and is the start date/time of the scheduled event. Use ConvertTextToTIMEDATE for CalendarDateTime string (ex. "03/16/2000 09:00 am"). It is mainly used in the UI to display a single instance of a value from a multi-valued StartDateTime item. It is also used in some of the Calendar view display columns.

StartDateTime
The StartDateTime is of type TYPE_TIME or TYPE_TIME_RANGE and contains the start date/time of the scheduled event. Use ConvertTextToTIMEDATE for StartDateTime string (ex. "03/16/2000 09:00 am"). StartTime
The StartTime is of type TYPE_TIME and is the start date/time of the scheduled event. Use ConvertTextToTIMEDATE for CalendarDateTime string (ex. "03/16/2000 09:00 am"). It is mainly used in the UI to display a single instance of a value from a multi-valued StartDateTime item. It is also used in some of the Calendar view display columns.

StatusUpdate
The StatusUpdate item is of type TYPE_COMPOSITE and contains the scheduled event's status description.

Subject
The Subject item is of type TYPE_TEXT and contains the scheduled event's brief description.



Adding a Scheduled Event to a User's Schedule

This section describes how to use the C API to add an appointment or a meeting invitation to a User's schedule. Following are the basic steps and the corresponding API functions to perform this task. For details, refer to the AddSchedule() routine in the SCHEDULE sample program in the misc\schedule directory.

Note: The specified scheduled event time must be within a day's boundary.

1. Open the mail database (as specified on the command line) for a specified User. (NSFDbOpen)

2. Create a Note in the database (NSFNoteCreate).

3. Set the NOTE CLASS to NOTE_CLASS_DOCUMENT (NSFNoteSetInfo).

4. Allocate a buffer for data to copy each item's value to (OSMemAlloc).

5. Add each of the appropriate Items mentioned in the Components of Calendar and Scheduling section to the Note (NSFItemAppend).

6. Update the Note (NSFNoteUpdate).

7. Free the data buffer (OSMemFree).

8. Close the Note and the Database.


Deleting a Scheduled Event from a User's Schedule

This section describes how to use the C API to delete a scheduled event from a User's schedule. Following are the basic steps and the corresponding API functions to perform this task. For details, refer to the ScheduleTask() routine in the SCHEDULE sample program in the misc\schedule directory.

1. Create an empty text list data structure. (ListAllocate).

2. Add the current user to the list (ListAddEntry).

3. Retrieve the user's schedule container (SchRetrieve).

4. Get the first schedule in the container (SchContainer_GetFirstSchedule).

5. Get the busy time information from the schedule (Schedule_ExtractBusyTimeRange).

6. Attempt to find the "scheduled event to delete" time in the data returned.

7. If the time is found get the schedule list of the user (Schedule_ExtractSchedList).

8. Attempt to find the scheduled event time in the schedule list returned.

9. If the entry is found delete the note.


Query a User's Busy/Free Time Information

This section describes how to use the C API to query a user's busy/free time information. Following are the basic steps and the corresponding API functions to perform this task. For details, refer to the ScheduleTask() routine in the SCHEDULE sample program in the misc\schedule directory.

Note: The specified time range may extend past a day's boundary.

1. Create an empty text list data structur (ListAllocate).

2. Add the current user to the list (ListAddEntry).

3. Retrieve the user's schedule container (SchRetrieve).

4. Get the first schedule in the container (SchContainer_GetFirstSchedule).

5. Get the free time information from the schedule (Schedule_ExtractFreeTimeRange).

6. Get the busy time information from the schedule (Schedule_ExtractBusyTimeRange).

----------------------------------------------------------------------------------------------------------
Click here to comment to IBM on this documentation