Calendar API: 1 Overview

GEOS SDK TechDocs

Introduction

2 Examples

Functionality

MSG_CALENDAR_ADD_EVENT
MSG_CALENDAR_GET_EVENT_BY_ID
MSG_CALENDAR_MODIFY_EVENT_BY_ID
MSG_CALENDAR_DELETE_EVENT_BY_ID
MSG_CALENDAR_CHECK_IF_EVENT_EXISTS

These five messages correspond to the operations you can perform on the user's calendar database: add an event, get an event you added, modify an event you added, delete an event you added, and search for the existence of any event within a specified time interval.

Because these messages are sent via IACP to the Calendar application, they cannot directly return status values. In each case, you specify a callback message and an object to receive it; status values and requested information (if any) are processed by your callback method.

Callback Prototypes

CALENDAR_ADD_EVENT_CALLBACK_MSG

Prototype of the callback message for MSG_CALENDAR_ADD_EVENT; passes status value and the assigned event ID.

CALENDAR_GET_EVENT_CALLBACK_MSG

Prototype of the callback message for MSG_CALENDAR_GET_EVENT_BY_ID; passes status value and handle to a CalendarReturnedEventStruct.

CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSG

Prototype of the callback message for MSG_CALENDAR_MODIFY_EVENT_BY_ID, MSG_CALENDAR_DELETE_EVENT_BY_ID, and MSG_CALENDAR_CHECK_IF_EVENT_EXISTS; passes status value.

Event Types

Ordinary

Ordinary events have a start date, start time, end date, end time, an optional alarm at or before the start time, and a text description.

Only the start date is mandatory; if no start time (CAL_NO_TIME) is specified, the event is listed as a daily reminder (before the time-ordered list for its day). If only a start date and time are specified (the end date and time are CAL_NO_DATE and CAL_NO_TIME), the event is listed at the start time without an associated interval. If an end time is also specified, the event is shown spanning a time interval on a single day; if both an end date and time are specified, the event is shown spanning the entire interval from the start date and time until the end date and time.

If you specify a start time and an end date, you must also specify an end time; if the end time (or date and time) is specified, it must be later than the start time.

If you specify a start date and no start time (a daily reminder), do not specify an end time; specify an end date if you wish to have a multi-day daily reminder. Do not use the CEPS_reserveWholeDay parameter to create a multi-day daily reminder; if you omit the start and end times, you will instead create a multi-day event (see below) with the default start and end times of 00:00 and 23:59.

Result of Specifying Start and End Parameters

Start Param Specified		End Param Specified		Result
Date	Time	Date	Time
Yes	No	No	No	Daily reminder, listed at beginning of day.
Yes	No	Yes	No	Multi-day daily reminder, listed at the beginning of each day.
Yes	No	*	Yes	Not defined. Typically creates a daily reminder.
Yes	Yes	No	No	Event listed (at the start time) with no interval.
Yes	Yes	No	Yes	Event spanning a time interval on one day.
Yes	Yes	Yes	Yes	Event (possibly) spanning multiple days.
Yes	Yes	Yes	No	Not allowed.
* = Doesn't matter "No" = CAL_NO_DATE or CAL_NO_TIME was specified

Multi-day

Multi-day events are ordinary events that have a start and end time for each day in their date range, as opposed to being one continuous event spanning multiple days. The start and end time is the same for each day. Specify a multi-day event by including a non-zero value (the number of days) for CEPS_reserveWholeDay in CalendarEventParamStruct; also specify the start and end time (which will apply to each day) and the start day. The end day value is ignored when CEPS_reserveWholeDay is non-zero. If you omit the start or end time (using CAL_NO_TIME), it defaults to 00:00 (start time) or 23:59 (end time).

To-do List

To-do list events all appear in one list; they are not tied to any specific day. Each to-do event has a status (high priority, normal, or completed) and a text description. Specify a to-do list event by setting the start date to CAL_NO_DATE and the start time to the event's status.

Repeating

Repeating events automatically recur according to a specified pattern (daily, monthly, etc.). This API currently does not support repeating events; the error CEE_EVENT_NOT_SUPPORTED will be returned if you specify a non-zero CEPS_repeatInfo field when adding or modifying event, or if you attempt to get, modify, or delete a repeating event. Also, MSG_CALENDAR_CHECK_IF_EVENT_EXISTS will not check for repeating events in the specified range.

Alarms

Alarms use the RTCM (Real-Time Clock Manager) library, which allows them to activate when Calendar is not running or when the device is sleeping.

Checking the Calendar Version

[Calendar]
calApi = True

See GEOS .INI Files for more information on INI files; also see this example.

Data Types

structures:

CalendarEventParamStruct
CalendarReturnedEventStruct
CalendarEventRepeatInfo
CalendarEventRepeatDurationData

CalendarAlarmStruct
CalendarEventRepeatLength

CalendarEventDescType
CalendarAlarmIntervalType
CalendarEventRepeatDuration
CalendarEventRepeatLengthUnitType
CalendarEventRepeatWeekday
CalendarEventRepeatIntervalType
CalendarEventRepeatInterval

CalendarEventError
CalendarToDoItemStatus

Internal Messages

MSG_CALENDAR_REQUEST_SEARCH
MSG_CALENDAR_DELETE_EVENTS_BEFORE_DATE
MSG_CALENDAR_GET_NEXT_EVENT_ID
MSG_CALENDAR_SET_NEXT_EVENT_ID

GEOS SDK TechDocs

Introduction

2 Examples