Calendar and Scheduling
Chapter 12-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
- Appointment:
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 | | | |
| $AlarmDescription | | Shows up when alarm rings | | | |
| $AlarmOffset | | x minutes before or after StartDateTime | | | |
| $BusyName | | Fully distinguished username of person that is busy | | MAIL_APPT_BUSYNAME_ITEM | |
| $BusyPriority | | Tells 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 | | | |
| $NoPurge | | End date/time (prevents note from being purged) | | FIELD_NOPURGE | |
| $PublicAccess | | Private or public accessible | | | |
| _ViewIcon | | Scheduled event Icon displayed | | | |
| AppointmentType | | Type of scheduled event | | | |
| apptUNID | | UNID of the scheduled event | | | |
| Body | | Detailed description of the scheduled event | | | |
| BookFreeTime | | Correspond to the "Pencil in" check box in the Notes UI | | | |
| CalendarDateTime | | Causes appointment to show up in Calendar View | | | |
| CHAIR | | Fully distinguished name of the mail file owner | | | |
| EndDate | | End date/time of the scheduled event | | | |
| EndDateTime | | End date/time of the scheduled event | | MAIL_APPT_ENDTIME_ITEM | |
| EndTime | | End date/time of the scheduled event | | | |
| ExcludeFromView | | Prevents non sent appts from showing up in drafts view | | | |
| From | | Fully distinguished username | | MAIL_FROM_ITEM | |
| Form | | What form to display | | FIELD_FORM | |
| ORGTABLE | | Set for the scheduled event | | | |
| Principal | | Fully distinguished name of the mail file owner | | | |
| SEQUENCENUM | | Keeps the scheduled event ordered | | MAIL_APPT_SEQUENCE_ITEM | |
| StartDate | | Start date/time of the scheduled event | | | |
| StartDateTime | | Start date/time of the scheduled event | | MAIL_APPT_STARTTIME_ITEM | |
| StartTime | | Start date/time of the scheduled event | | | |
| Subject | | Brief description of the scheduled event | | MAIL_SUBJECT_ITEM | |
| | | | | | |
Use NSFItemAppend API to add each item to the appointment note.
- Meeting Invitation:
- Established meeting invitation note:
- The items described above for creating an Appointment note, and
- The following items.
- To create an invitation without sending the invitation notice, use:
| | | | | | |
| Item Name | | Description | | Constant | |
| | | | | | |
| CopyTo | | Fully distinguished name(s) of the Optional invitee(s) | | | |
| SendTo | | Fully distinguished name(s) of the Primary invitee(s) | | | |
| BlindCopyTo | | Fully distinguished name(s) of FYI invitee(s) | | | |
- Use NSFItemAppend API to add each item to the meeting invitation note.
- Meeting invitation event note:
- Meeting invitation originator sends the meeting invitation to invitees
- Invitee counters the meeting time
- Meeting invitation originator re-schedules the meeting
- Invitee accepts the meeting invitation
- Invitee declines the meeting invitation
- Invitee delegate the meeting invitation
- Meeting invitation originator confirms the meeting
- Meeting invitation originator cancels the meeting
- Once the meeting invitation is initiated, one or more of the following events will take place:
The items described above for creating an Appointment note, The items described above for creating an established meeting invitation note, and The following items.
See the Summary of Invitation Event Note Itemssection for summarized information.
| | | | | | |
| Item Name | | Description | | Constant | |
| | | | | | |
| $CSFlags | | Mainly used for repeating entries; Determines what type of repeating entry a document is. | | | |
| _ViewIcon2 | | Secondary icon to display in a view column | | | |
| Delegator | | Fully distinguished name of the delegator | | | |
| Delegee | | Fully distinguished name of the person being delegated to | | | |
| FormToUse | | Only used by UI when sending a notice with additional comments | | | |
| NewEndDate | | New End date/time of the scheduled event | | | |
| NewEndTime | | New End date/time of the scheduled event | | | |
| NewStartDate | | New Start date/time of the scheduled event | | | |
| NewStartTime | | New Start date/time of the scheduled event | | | |
| NoticeType | | Type of the notice | | | |
| OptionalAttendees | | Fully distinguished name(s) of the Optional invitee(s) | | | |
| Recipients | | Complete list of invitees | | | |
| Requiredattendees | | Fully distinguished name(s) of thePrimary invitee(s) | | | |
| StatusUpdate | | Details of the event status | | | |
| | | | | | |
| Legend:
(1) denotes a note to be modified or created for the current "event owner" when the given event occurs. (2) denotes a message note to be sent out when the given event occurs. (3) denotes a message note to be sent to meeting invitation originator when the delegating event occurs. (4) denotes a message note to be sent to delegee when the delegating event occurs. -- - indicates the item is not required for the given event. italic font - indicates the description of the item value. NULL - indicates a NULL value. helv font - indicates the text string of the item value. |
| Invita- tion | | Counter- ing | | Re- schedule | Accept- ing | |
| (1) | (2) | (1) | (2) | (2) | (1) | (2) |
| $BusyName | current user | -- | current user | -- | -- | current user | -- |
| $BusyPriority | 1 | -- | 2 | -- | -- | 1 | -- |
| $CSFlags | -- | -- | -- | w | w | -- | w |
| $REF | -- | -- | -- | yes | yes | -- | yes |
| _ViewIcon | 158 | 133 | 39 | 39 | 33 | 158 | 83 |
| _ViewIcon2 | | | | | | | 11 |
| CopyTo | NULL | yes | yes | yes | yes | yes | yes |
| Delegator | -- | -- | -- | -- | -- | -- | -- |
| Delegee | -- | -- | yes | -- | -- | -- | -- |
| Form | appointment | notice | notice | notice | notice | notice | appointment |
| FormToUse | | | | | | | notice |
| NewEndDate | -- | -- | yes | yes | -- | -- | -- |
| NewEndTime | -- | -- | yes | yes | -- | -- | -- |
| NewStartDate | -- | -- | yes | yes | -- | -- | -- |
| NewStartTime | -- | -- | yes | yes | -- | -- | -- |
| NoticeType | -- | I | T | T | U | A | A |
| Recipients | yes | -- | -- | -- | -- | -- | -- |
| SEQUENCENUM | 1 | 1 | 1 | 1 | 3 | 1 | 3 |
| StatusUpdate | -- | -- | yes | - | - | yes | yes |
| (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) |
| $BusyName | current user | -- | current user | -- | -- | -- | -- |
| $BusyPriority | 2 | -- | 2 | -- | -- | -- | -- |
| $CSFlags | -- | w | -- | w | w | w | w |
| $REF | -- | yes | -- | yes | -- | yes | yes |
| _ViewIcon | 84 | 84 | 84 | 84 | 133 | 81 | 10 |
| _ViewIcon2 | | | | | | 11 | 11 |
| CopyTo | yes | yes | yes | yes | yes | yes | yes |
| Delegator | -- | -- | -- | -- | yes | -- | -- |
| Delegee | yes | -- | yes | yes | -- | -- | -- |
| Form | notice | notice | notice | notice | notice | (ReplyNotice) | notice |
| FormToUse | -- | -- | -- | -- | -- | notice | notice |
| NewEndDate | yes | -- | yes | -- | -- | -- | -- |
| NewEndTime | yes | -- | yes | -- | -- | -- | -- |
| NewStartDate | yes | -- | yes | -- | -- | -- | -- |
| NewStartTime | yes | -- | yes | -- | -- | -- | -- |
| NoticeType | R | R | D | D | L | C | N |
| Recipients | -- | -- | -- | -- | -- | -- | -- |
| SEQUENCENUM | 1 | 1 | 1 | 1 | 1 | 3 | 3 |
| StatusUpdate | yes | -- | yes | -- | -- | yes | yes |
| (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).