The Nokia 9000i Communicator comes with a calendar application for scheduling appointments and keeping a to-do list. You can add appointments and to-do items with the API defined in calendar.goh; you can also retrieve, modify, and delete events that you have added.
You can search for the existence of any event within a particular time period (including events you did not add yourself); however, Calendar API is not intended for use in retrieving, modifying, or deleting pre-existing events in the user's calendar database.
Calendar API uses IACP (Inter-Application Communication Protocol); your application sends a message to the Calendar application object, which services your request and then returns a status code (and other requested information) with a callback message. Before reading this section, you may wish to review the material on IACP or look at code in the CalApi.goc sample application.
On the Nokia 9000i Communicator, only devices manufactured after February 1997 support this API; your application should check the Calendar application version. Also, only one-time events may be manipulated; this API does not support repeating events.
1 Overview
2 Examples
3 Reference
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.
CALENDAR_ADD_EVENT_CALLBACK_MSGMSG_CALENDAR_ADD_EVENT;
passes status value and the assigned event ID.
CALENDAR_GET_EVENT_CALLBACK_MSGMSG_CALENDAR_GET_EVENT_BY_ID; passes status value and handle to
a CalendarReturnedEventStruct.
CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSGMSG_CALENDAR_MODIFY_EVENT_BY_ID,
MSG_CALENDAR_DELETE_EVENT_BY_ID, and
MSG_CALENDAR_CHECK_IF_EVENT_EXISTS; passes status value.
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.
| 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 | ||||
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).
CAL_NO_DATE and the start time to the event's status.
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.
CalendarAlarmStruct
field in the event's parameter structure, CalendarEventParamStruct.
CalendarAlarmStruct is actually a WordFlag that
encodes whether an alarm is set and how long before the event's start
time it should sound. On the Nokia 9000i Communicator, this time must be
specified in minutes.
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.
[Calendar] calApi = True
See GEOS .INI Files for more information on INI files; also see this example.
structures:
CalendarEventParamStruct CalendarReturnedEventStruct CalendarEventRepeatInfo CalendarEventRepeatDurationDataWordFlags:
CalendarAlarmStruct CalendarEventRepeatLengthByteEnums:
CalendarEventDescType CalendarAlarmIntervalType CalendarEventRepeatDuration CalendarEventRepeatLengthUnitType CalendarEventRepeatWeekday CalendarEventRepeatIntervalType CalendarEventRepeatIntervalenums:
CalendarEventError CalendarToDoItemStatus
MSG_CALENDAR_REQUEST_SEARCH MSG_CALENDAR_DELETE_EVENTS_BEFORE_DATE MSG_CALENDAR_GET_NEXT_EVENT_ID MSG_CALENDAR_SET_NEXT_EVENT_ID
[Calendar] calApi = TrueThis setting can be checked as follows:
#include <initfile.h>
Boolean calapi;
if ( InitFileReadBoolean( "Calendar", "calApi", &calapi ) ) {
/* entry was not found */
FoamDisplayWarning( @CantRunCalApi );
@send application::MSG_META_QUIT();
}
else {
if ( calapi == FALSE ) {
/* entry has wrong value */
FoamDisplayWarning( @NoCalApiSupport );
@send application::MSG_META_QUIT();
}
}
|
CalendarEventParamStruct with parameters to specify an event
with a start date, start time, optional end date, optional end time, and an
alarm.
@include <calendar.goh>
#include <timedate.h> /* definition of TimerDateAndTime */
/* Declare event_g as a Calendar event param structure */
CalendarEventParamStruct event_g;
/* Other variables in this example */
TimerDateAndTime date, time;
Boolean boolEndDate, boolEndTime;
word alarmMinutes;
TCHAR *eventText_g;
/* Fill the start date and time. (Assume the variables "date" and "time"
* have already been filled.) Variables are cast as dwords to prevent
* bit-shifting off the left of a too-small word.
*/
event_g.CEPS_startDateTime =
( (dword)date.TDAT_year << FDAT_YEAR_OFFSET ) |
( (dword)date.TDAT_month << FDAT_MONTH_OFFSET ) |
( (dword)date.TDAT_day << FDAT_DAY_OFFSET ) |
( (dword)time.TDAT_hours << FDAT_HOUR_OFFSET ) |
( (dword)time.TDAT_minutes << FDAT_MINUTE_OFFSET );
/* Fill the end date and time. (Assume the variables "date", "time", and
* "boolEndXxxx" have already been filled.) Variables are cast as dwords to
* prevent bit-shifting off the left of a too-small word. Use CAL_NO_XXXX
* if a value is not specified.
*/
if (boolEndDate) {
event_g.CEPS_endDateTime =
( (dword)date.TDAT_year << FDAT_YEAR_OFFSET ) |
( (dword)date.TDAT_month << FDAT_MONTH_OFFSET ) |
( (dword)date.TDAT_day << FDAT_DAY_OFFSET );
}
else {
event_g.CEPS_endDateTime = (dword)CAL_NO_DATE << FDAT_DAY_OFFSET;
}
if (boolEndTime) {
event_g.CEPS_endDateTime |=
( (dword)time.TDAT_hours << FDAT_HOUR_OFFSET ) |
( (dword)time.TDAT_minutes << FDAT_MINUTE_OFFSET );
}
else {
event_g.CEPS_endDateTime |= (dword)CAL_NO_TIME << FDAT_2SECOND_OFFSET;
}
/* The event will not be a multi-day event */
event_g.CEPS_reserveWholeDay = 0;
/*
* The alarm will go off "alarmMinutes" minutes before event time.
* Mask with CAS_INTERVAL to ensure alarmMinutes is in range.
*/
event_g.CEPS_alarm =
CAS_HAS_ALARM |
( CAIT_MINUTES << CAS_TYPE_OFFSET ) |
( CAS_INTERVAL & ( alarmMinutes << CAS_INTERVAL_OFFSET ));
/* Event has a text description */
event_g.CEPS_eventType = CEDT_GEOS_TEXT;
/* Event is not repeating */
event_g.CEPS_repeatInfo = 0;
/* Assume event text is already pointed to by eventText_g */
event_g.CEPS_dataLength = LocalStringSize( eventText_g );
event_g.CEPS_data = eventText_g;
|
CAL_NO_DATE and the to-do priority is set in the start time
field.
@include <calendar.goh>
/* Declare event_g as a Calendar event param structure */
CalendarEventParamStruct event_g;
/* Other variables in this example */
word myPriority;
TCHAR *eventText_g;
/* "myPriority" can be in the range [0-2] here, corresponding to
* CTDIS_HIGH_PRIORITY, CTDIS_NORMAL_PRIORITY, and CTDIS_COMPLETED.
*/
event_g.CEPS_startDateTime =
((dword)CAL_NO_DATE << FDAT_DAY_OFFSET) |
((dword)(myPriority + CTDIS_HIGH_PRIORITY) << FDAT_2SECOND_OFFSET);
/* Assume the to-do text is already pointed to by eventText_g */
event_g.CEPS_dataLength = LocalStringSize( eventText_g );
event_g.CEPS_data = eventText_g;
/* This parameter must be zero, otherwise the error CEE_EVENT_NOT_SUPPORTED
* will be generated.
*/
event_g.CEPS_repeatInfo = 0;
|
Other parameters in CalendarEventParamStruct will be ignored.
MSG_CALENDAR_ADD_EVENT to the Calendar
application's process object via IACP. The error code and assigned event ID
can be checked in your callback method
(MSG_CALAPI_PROCESS_ADD_EVENT_CALLBACK here); see examples
of callbacks below.
/*
* serverGeodeToken - token of the calendar app
* connectionFlags - optional flags for connection
* iacpConnectionToken - token for this IACP connection
* serverCount - the number of running servers
* hMsgToSend - handle of the recorded message
* hLaunchBlock - handle of launch block
* pLaunchBlock - pointer to launch block
*/
GeodeToken serverGeodeToken = CALENDAR_TOKEN;
IACPConnectFlags connectionFlags = 0;
IACPConnection iacpConnectionToken;
word serverCount;
EventHandle hMsgToSend;
MemHandle hLaunchBlock;
AppLaunchBlock * pLaunchBlock;
/*
* Make a launch block so that server (calendar app) is
* launched if not running already.
*/
hLaunchBlock = IACPCreateDefaultLaunchBlock(
MSG_GEN_PROCESS_OPEN_APPLICATION );
/*
* Make sure it does not bring up the calendar on top of us.
* Otherwise, the user can interact with it and produce
* unwanted side-effects.
*/
pLaunchBlock = MemLock( hLaunchBlock );
pLaunchBlock->ALB_launchFlags |=
( ALF_OPEN_IN_BACK | ALF_DO_NOT_OPEN_ON_TOP );
MemUnlock( hLaunchBlock );
/*
* Connect to the Calendar IACP server.
*/
iacpConnectionToken = IACPConnect( &serverGeodeToken,
connectionFlags,
hLaunchBlock,
NullOptr,
&serverCount );
if ( iacpConnectionToken != IACP_NO_CONNECTION ) {
/*
* Record the ADD_EVENT message for transmittal via IACP.
*/
hMsgToSend = @record null::MSG_CALENDAR_ADD_EVENT(
&event_g;
ConstructOptr( GeodeGetProcessHandle(), NullChunk ),
MSG_CALAPI_PROCESS_ADD_EVENT_CALLBACK );
/*
* Send the recorded message to the Calendar process obj
* using IACPSendMessage.
*/
IACPSendMessage( iacpConnectionToken,
hMsgToSend,
TO_PROCESS,
NULL,
IACPS_CLIENT );
/*
* Shut down the IACP connection and return the error value.
*/
IACPShutdown( iacpConnectionToken, NullOptr );
return( CAE_NO_ERROR );
}
else {
/*
* Return an error as something went wrong
* trying to connect to the calendar app.
*/
return( CAE_CANNOT_CONNECT_CALENDAR );
}
|
MSG_CALENDAR_GET_EVENT_BY_ID via IACP and inspect the returned
memory block in your callback method. Send the IACP message as above,
replacing the ADD_EVENT request with a GET_EVENT one; the
eventID is the one returned to your ADD_EVENT callback.
hMsgToSend = @record MSG_CALENDAR_GET_EVENT_BY_ID(
eventID,
GeodeGetProcessHandle(),
ConstructOptr( GeodeGetProcessHandle(), NullChunk ),
MSG_CALAPI_PROCESS_GET_EVENT_CALLBACK );
|
In your callback method (the last parameter above), extract the information you are interested in. See the sample application CalApi for the complete method; excerpts are shown below.
/* In your class declaration: */
@message (CALENDAR_GET_EVENT_CALLBACK_MSG)
MSG_CALAPI_PROCESS_GET_EVENT_CALLBACK;;
/********************************************************************
* MSG_CALAPI_PROCESS_GET_EVENT_CALLBACK
********************************************************************
* SYNOPSIS: Callback from Calendar IACP server on result of
* MSG_CALENDAR_GET_EVENT_BY_ID.
* PARAMETERS: CalendarEventError error
* MemHandle eventBlock
* RETURN: void
*
* STRATEGY: Check status value; successful if CEE_NORMAL
* If successful,
* Lock and dereference returned global block
* Calculate pointer to event text (it follows
* the returned event structure)
* Extract information from structure
* Free the global memory block!
*
*******************************************************************/
@method CalApiProcessClass, MSG_CALAPI_PROCESS_GET_EVENT_CALLBACK
{
/*
* eventData - pointer to the returned event data
* eventTextData - pointer to the event description
* dateTime - dateTime structure used to display event info
* tempStr - used to convert event info into strings
* alarmType - used to convert alarm info into alarm setting
*/
CalendarReturnedEventStruct * eventData;
TCHAR * eventTextData;
TimerDateAndTime dateTime;
TCHAR tempStr[MAX_EVENT_TEXT_LENGTH];
CalApiAlarmType alarmType;
/*
* If there are no errors in getting the event,
* we lock down the returned structure and dereference
* the event text description.
*/
if ( CEE_NORMAL == error ) {
eventData = MemLock( eventBlock );
eventTextData = (TCHAR*)((TCHAR*)eventData +
sizeof( CalendarReturnedEventStruct ) );
/*
* Convert the start date/time into strings.
* First turn the FileDateAndTime into a TimerDateAndTime.
* Then use LocalFormatDateTime to turn that into a string.
* Don't forget to handle the case where the date or
* time isn't specified (i.e. equals -1).
*/
dateTime.TDAT_year = FDATExtractYear( eventData->CRES_startDateTime ) +
FDAT_BASE_YEAR;
dateTime.TDAT_month = FDATExtractMonth( eventData->CRES_startDateTime );
dateTime.TDAT_day = FDATExtractDay( eventData->CRES_startDateTime );
dateTime.TDAT_hours = FDATExtractHour( eventData->CRES_startDateTime );
dateTime.TDAT_minutes = FDATExtractMinute(
eventData->CRES_startDateTime );
if ( ( eventData->CRES_startDateTime & 0x0000ffff ) == CAL_NO_DATE ) {
strcpy( tempStr, "NO_DATE" );
}
else {
LocalFormatDateTime( tempStr, DTF_SHORT, &dateTime );
}
if ( ( eventData->CRES_startDateTime & 0xffff0000 ) ==
(dword)CAL_NO_TIME << 16 ) {
strcpy( tempStr, "NO_TIME" );
}
else {
LocalFormatDateTime( tempStr, DTF_HM_24HOUR, &dateTime );
}
/* Perform any other processing; display information... */
/*
* Free the event data block.
*/
MemFree( eventBlock );
}
else {
/* Error handling for error != CEE_NORMAL ... */
}
} /* MSG_CALAPI_PROCESS_GET_EVENT_CALLBACK */
|
MSG_CALENDAR_CHECK_IF_EVENT_EXISTS via IACP (as in the example
above). Use your callback to interpret the returned status code.
/* Check for events overlapping the range 12:15 PM June 9, 1997 until
9:15 AM June 10, 1997 */
/* Note that constants are specified as Long literals. */
FileDateAndTime startDateTime_g =
( ( ( 1997L - FDAT_BASE_YEAR ) << FDAT_YEAR_OFFSET ) |
( 6L << FDAT_MONTH_OFFSET ) |
( 9L << FDAT_DAY_OFFSET ) |
( 12L << FDAT_HOUR_OFFSET ) |
( 15L << FDAT_MINUTE_OFFSET ) );
FileDateAndTime endDateTime_g =
( ( ( 1997L - FDAT_BASE_YEAR ) << FDAT_YEAR_OFFSET ) |
( 6L << FDAT_MONTH_OFFSET ) |
( 10L << FDAT_DAY_OFFSET ) |
( 9L << FDAT_HOUR_OFFSET ) |
( 15L << FDAT_MINUTE_OFFSET ) );
hMsgToSend = @record null::MSG_CALENDAR_CHECK_IF_EVENT_EXISTS(
startDateTime_g,
endDateTime_g,
ConstructOptr( GeodeGetProcessHandle(), NullChunk ),
MSG_CALAPI_PROCESS_CHECK_IF_EVENT_EXISTS_CALLBACK );
|
/* In CalApiProcessClass, declare the method: */
@message (CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSG)
MSG_CALAPI_PROCESS_CHECK_IF_EVENT_EXISTS_CALLBACK;
/********************************************************************
* MSG_CALAPI_PROCESS_CHECK_IF_EVENT_EXISTS_CALLBACK
********************************************************************
* SYNOPSIS: Callback from Calendar IACP server on result of
* MSG_CALENDAR_CHECK_IF_EVENT_EXISTS.
* PARAMETERS: CalendarEventError error
* RETURN: void
* STRATEGY: If an event existed, CEE_NORMAL is returned;
* otherwise, we get CEE_EVENT_NOT_FOUND.
*******************************************************************/
@method CalApiProcessClass, MSG_CALAPI_PROCESS_CHECK_IF_EVENT_EXISTS_CALLBACK
{
if (error == CEE_NORMAL) {
/* At least one event in search range... */
} else if (error == CEE_EVENT_NOT_FOUND) {
/* No events overlap search range...*/
} else {
/* A processing error occurred... */
}
} /* MSG_CALAPI_PROCESS_CHECK_IF_EVENT_EXISTS_CALLBACK */
|
void MSG_CALENDAR_ADD_EVENT(
CalendarEventParamStruct
*params,
optr completionOptr,
Message completionMsg);
Adds an event to the calendar database. Only ordinary, multi-day, and to-do list events are supported; repeating events are not.
Pass:
CalendarEventParamStruct structure holding the
event you are adding.Return: Nothing. Error status and event ID (if successful) are passed to your callback method, if specified.
Include: calendar.goh
See Also: CALENDAR_ADD_EVENT_CALLBACK_MSG prototype.
void MSG_CALENDAR_GET_EVENT_BY_ID(
dword eventID,
GeodeHandle owner,
optr completionOptr,
Message completionMsg);
Gets an event in the calendar database. Only ordinary, multi-day, and to-do list events are supported; repeating events are not.
Pass:
Return: Nothing. Error status and data block handle are passed to your callback method.
Include: calendar.goh
See Also: CALENDAR_GET_EVENT_CALLBACK_MSG prototype.
void MSG_CALENDAR_MODIFY_EVENT_BY_ID(
CalendarEventParamStruct
*params,
dword eventID,
optr completionOptr,
Message completionMsg);
Modifies an event in the calendar database. Only ordinary, multi-day, and to-do list events are supported; repeating events are not.
Pass:
CalendarEventParamStruct structure holding the
modified event, which will completely replace the existing event.Return: Nothing. Error status is passed to your callback method, if specified.
Include: calendar.goh
See Also: CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSG prototype.
void MSG_CALENDAR_DELETE_EVENT_BY_ID(
dword eventID,
optr completionOptr,
Message completionMsg);
Deletes an event in the calendar database. Only ordinary, multi-day, and to-do list events are supported; repeating events are not.
Pass:
Return: Nothing. Error status is passed to your callback method, if specified.
Include: calendar.goh
See Also: CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSG prototype.
void MSG_CALENDAR_CHECK_IF_EVENT_EXISTS(
FileDateAndTime startDateTime,
FileDateAndTime endDateTime,
optr completionOptr,
Message completionMsg);
Searches the calendar database to see whether any events occur during a specified interval. Only ordinary, multi-day, and to-do list events are checked; repeating events are not.
Pass:
Return: Nothing; the search result is passed to your callback method. The successful results are:
CEE_NORMAL indicates at least one event in the database overlaps your
search range. CEE_EVENT_NOT_FOUND indicates that no events in the database overlap
your search range. Include: calendar.goh
See Also: CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSG prototype.
void CALENDAR_ADD_EVENT_CALLBACK_MSG(
CalendarEventError
error,
dword eventID);
Template for your MSG_CALENDAR_ADD_EVENT callback. Use this prototype to declare, in the appropriate class definition, the method that will handle the callback from adding an event to the calendar database. For example:
@message (CALENDAR_ADD_EVENT_CALLBACK_MSG) MSG_MYAPP_PROCESS_ADD_EVENT_CALLBACK;
Pass:
CEE_NORMAL
if successful.Return: Nothing.
Include: calendar.goh
See Also: MSG_CALENDAR_ADD_EVENT
void CALENDAR_GET_EVENT_CALLBACK_MSG(
CalendarEventError
error,
MemHandle eventBlock);
Template for your MSG_CALENDAR_GET_EVENT_BY_ID callback. Use this prototype to declare, in the appropriate class definition, the method that will handle the callback from getting an event in the calendar database. For example:
@message (CALENDAR_GET_EVENT_CALLBACK_MSG) MSG_MYAPP_PROCESS_GET_EVENT_CALLBACK;
Pass:
CEE_NORMAL if
successful.CalendarReturnedEventStruct
.Return: Nothing.
Include: calendar.goh
See Also: MSG_CALENDAR_GET_EVENT_BY_ID
void CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSG(
CalendarEventError
error);
Template for your
@message (CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSG)
MSG_MYAPP_PROCESS_EVENT_EXISTS_CALLBACK;
Pass:
CEE_NORMAL
indicates successful deletion
or modification; for the
MSG_CALENDAR_CHECK_IF_EVENT_EXISTS
callback,
CEE_NORMAL is returned if any event overlaps with the specified range,
CEE_EVENT_NOT_FOUND otherwise.Return: Nothing.
Include: calendar.goh
See Also: MSG_CALENDAR_MODIFY_EVENT_BY_ID, MSG_CALENDAR_DELETE_EVENT_BY_ID, MSG_CALENDAR_CHECK_IF_EVENT_EXISTS.
typedef struct {
FileDateAndTime CEPS_startDateTime;
/* Event start date and time */
FileDateAndTime CEPS_endDateTime;
/* Event end date and time */
word CEPS_reserveWholeDay;
/* Number of whole day to reserve the event. The max is
* CALENDAR_MAX_RESERVE_WHOLE_DAYS. 0 if not applicable.
*
* If this field is non-zero, the end date specified in
* CEPS_endDateTime is ignored.
*
* If CEPS_startDateTime does not have time specified, it is assumed
* the start time is 00:00.
*
* If CEPS_endDateTime does not have time specified, it is assumed
* the end time is 23:59
*/
CalendarAlarmStruct CEPS_alarm;
/* Alarm associated with the event */
CalendarEventDescType CEPS_eventType;
/* Type of data of the event */
CalendarEventRepeatInfo *CEPS_repeatInfo;
/* Repeat event info. 0 if the event is not repeating */
word CEPS_dataLength;
/* The number of bytes of the data in CEPS_data. If
* CEPS_eventType is CEDT_GEOS_TEXT, CEPS_dataLength does not include
* NULL.
*/
char* CEPS_data;
/* The event data. If the CEPS_eventType is CEDT_GEOS_TEXT, the
* text passed in from this field must be null-terminated.
*/
} CalendarEventParamStruct; |
typedef enum { CTDIS_HIGH_PRIORITY = 0x101, CTDIS_NORMAL_PRIORITY, CTDIS_COMPLETED, } CalendarToDoItemStatus; |
This structure fully specifies a calendar event.
Most of the fields are self-explanatory. If you wish to add a to-do list
item, specify CAL_NO_DATE for the start date and a
CalendarToDoItemStatus enum in place of the start time.
To-do items do not have start or end times, nor do they repeat or have alarms.
CEPS_reserveWholeDay is used to specify a single event that
spans multiple days. This is a special case of ordinary events;
instead of creating one long event,
the start and end time you specify will apply to each day the event lasts.
For example, you could use this to record a conference that runs
from 10:00 to 15:00 for three consecutive days.
When specifying FileDateAndTime values, cast words and
constants to type (dword) and specify literal long values (such
as "19L") before shifting their bits.
True repeating events are not yet supported.
This structure indicates whether an alarm is set, and how long before the event it should activate itself.
The CAS_HAS_ALARM bit indicates whether the alarm is set for
the associated event. If so, the number masked by CAS_INTERVAL
indicates when the alarm should sound. If the interval is zero, the alarm
activates at the start time of the event; otherwise, it activates
CAS_INTERVAL time units before the event. In the latter case,
the time units are specified by CAS_TYPE, although on the
Nokia 9000i Communicator only CAS_TYPE = CAIT_MINUTES is valid. If
another CAS_TYPE is specified, the alarm will default to the
maximum number of minutes.
For example, an alarm can be set to go off five minutes before the start of
an event by specifying CAS_TYPE = CAIT_MINUTES and
CAS_INTERVAL = 5.
typedef ByteEnum CalendarEventDescType;
#define CEDT_GEOS_TEXT (0x0) /* Description is a null-terminated,
* single-byte text string in the
* GEOS character set */
#define CEDT_UNICODE (0x1) /* Description is a null-terminated,
* double-byte text string in the
* Unicode character set. */
#define CEDT_INK (0x2) /* Description is digital ink. Number
* of points can be determined from
* the dataLength field. *
|
This enum indicates the format of the event description. Only CEDT_GEOS_TEXT is currently supported.
typedef struct {
dword CRES_eventID;
/* Unique event ID */
FileDateAndTime CRES_startDateTime;
/* Event start date and time */
FileDateAndTime CRES_endDateTime;
/* Event end date and time */
word CRES_reserveWholeDay;
/* Number of whole day to reserve the event. The max is
* CALENDAR_MAX_RESERVE_WHOLE_DAYS. 0 if not applicable.
*
* If this field is non-zero, the end date specified in
* CRES_reserveWholeDay is ignored.
*
* If CRES_startDateTime does not have time specified, it is assumed
* the start time is 00:00.
*
* If CRES_endDateTime does not have time specified, it is assumed
* the end time is 23:59
*/
CalendarAlarmStruct CRES_alarm;
/* Alarm associated with the event */
CalendarEventDescType CRES_eventType;
/* Type of data of the event */
word CRES_repeatInfo;
/* Offset in this block that points to CalendarEventRepeatInfo repeat
* event info. 0 if the event is not repeating. */
word CRES_dataLength;
/* The number of bytes of the data in CRES_data. If
* CRES_eventType is CEDT_GEOS_TEXT, CRES_dataLength does not include
* NULL.
*/
/* label char CRES_data;*/
/* The event data. If the CRES_eventType is CEDT_GEOS_TEXT, the
* text passed in from this field must be null-terminated.
*/
} CalendarReturnedEventStruct;
|
The event data (CRES_data) immediately follow this structure
in the returned block. If CRES_eventType = CEDT_GEOS_TEXT,
the text must be null-terminated.
CRES_repeatInfo is not currently supported.
typedef enum {
CEE_NORMAL = 0x0,
CEE_GENERAL_ERROR,
CEE_INTERNAL_ERROR,
CEE_NOT_ENOUGH_MEMORY,
CEE_NOT_ENOUGH_DISKSPACE,
CEE_EVENT_NOT_FOUND,
CEE_EVENT_TEXT_TOO_LONG,
CEE_INVALID_DATE,
CEE_INVALID_TIME,
CEE_INVALID_TODO_ITEM_STATUS,
CEE_INVALID_RESERVE_WHOLE_DAY,
CEE_INVALID_ALARM,
CEE_INVALID_EVENT_TYPE,
CEE_START_DATE_LATER_THAN_END_DATE,
CEE_START_TIME_LATER_THAN_END_TIME,
CEE_MISSING_END_TIME_WHEN_START_TIME_AND_END_DATE_ARE_SET,
CEE_EVENT_NOT_SUPPORTED,
CEE_INVALID_TIME_RANGE, /* The time range specified
* is invalid: end date/time
* is earlier than start date/time.*/
CEE_ACCESS_DENIED /* The requested event is in use and
* your access is denied. */
} CalendarEventError;
|
Error codes returned by Calendar API.
typedef struct {
CalendarEventRepeatInterval CERI_interval;
/* how long between events? */
CalendarEventRepeatDuration CERI_duration;
/* how long shall we keep this up? */
CalendarEventRepeatDurationData CERI_durationData;
/* more details of duration */
word CERI_numExceptions;
/* number of exception dates */
/* label FileDate CERI_exceptions;*/
/* array of dates on which event is *not* to take place */
} CalendarEventRepeatInfo;
|
Included for completeness; repeating events are not supported in calendar.goh API.
This structure specifies the repeat information in a repeating event. An array of exception dates, if any, follows at the end of this structure.
Included for completeness; repeating events are not supported in calendar.goh API.
This member specifies the interval between occurrences of the event.
The meaning of CERI_WEEK, CERI_DAY, and CERI_COUNT
depends on the type of interval for the repeating event:
typedef ByteEnum CalendarEventRepeatDuration; #define CERD_FOREVER (0x0) /* no additional data */ #define CERD_UNTIL (0x1) /* Repeat end date */ #define CERD_LENGTH (0x2) /* CalendarEventRepeatLength */ |
Included for completeness; repeating events are not supported in calendar.goh API.
This member specifies how long before occurrences of the event terminate.
Either the event is repeated indefinitely (CERD_FOREVER), or for
a finite time; CERD_UNTIL and CERD_LENGTH indicate the meaning
of the duration-length parameter.
Included for completeness; repeating events are not supported in calendar.goh API.
This member specifies the duration of a repeating event that terminates. The repeat interval can be specified by its termination date or by its length.
FileDate is an absolute date in a format defined in
file.h.
CalendarEventRepeatLength is a word specifying a time unit
(days, weeks, months, or years) and a count.
The count includes the initial event day; for example,
an event repeating every day for 3 days set for 12/15 would have events on
12/15, 12/16, and 12/17.