MSG_CALENDAR_ADD_EVENT

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:

*params

Pointer to a CalendarEventParamStruct structure holding the event you are adding.

completionOptr

Optr to the object in your application to receive the callback reply message; specify zero (0) for no callback.

completionMsg

Name of your callback-handling message.

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.

MSG_CALENDAR_GET_EVENT_BY_ID

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:

eventID

Unique event ID specifying the event you are requesting. This ID was returned when you added the event with MSG_CALENDAR_ADD_EVENT.

owner

Owner assigned to the created memory block holding the event data. It should correspond to the thread that will lock and read the block.

completionOptr

Optr to the object in your application to receive the callback reply message.

completionMsg

Name of your callback-handling message.

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.

MSG_CALENDAR_MODIFY_EVENT_BY_ID

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:

*params

Pointer to a CalendarEventParamStruct structure holding the modified event, which will completely replace the existing event.

eventID

Unique event ID specifying the event you are modifying. This ID was returned when you added the event with MSG_CALENDAR_ADD_EVENT.

completionOptr

Optr to the object in your application to receive the callback reply message; specify zero (0) for no callback.

completionMsg

Name of your callback-handling message.

Return: Nothing. Error status is passed to your callback method, if specified.

Include: calendar.goh

See Also: CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSG prototype.

MSG_CALENDAR_DELETE_EVENT_BY_ID

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:

eventID

Unique event ID specifying the event you are deleting. This ID was returned when you added the event with MSG_CALENDAR_ADD_EVENT.

completionOptr

Optr to the object in your application to receive the callback reply message; specify zero (0) for no callback.

completionMsg

Name of your callback-handling message.

Return: Nothing. Error status is passed to your callback method, if specified.

Include: calendar.goh

See Also: CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSG prototype.

MSG_CALENDAR_CHECK_IF_EVENT_EXISTS

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:

startDateTime

Start date and time of search interval.

endDateTime

End date and time of search interval.

completionOptr

Optr to the object in your application to receive the callback reply message.

completionMsg

Name of your callback-handling message.

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.

CALENDAR_ADD_EVENT_CALLBACK_MSG

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:

error

The error code of your "add event" request; CEE_NORMAL if successful.

eventID

The unique identifier of this event, if it was successfully added.

Return: Nothing.

Include: calendar.goh

See Also: MSG_CALENDAR_ADD_EVENT

CALENDAR_GET_EVENT_CALLBACK_MSG

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:

error

The error code of your "get event" request; CEE_NORMAL if successful.

eventBlock

Unlocked global memory block containing the returned CalendarReturnedEventStruct .

Return: Nothing.

Include: calendar.goh

See Also: MSG_CALENDAR_GET_EVENT_BY_ID

CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSG

void        CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSG(
        CalendarEventError
                         error); 

Template for your

• MSG_CALENDAR_MODIFY_EVENT_BY_ID,
• MSG_CALENDAR_DELETE_EVENT_BY_ID, and
  
• MSG_CALENDAR_CHECK_IF_EVENT_EXISTS

@message (CALENDAR_ACCESS_EVENT_COMMON_CALLBACK_MSG) 
                 MSG_MYAPP_PROCESS_EVENT_EXISTS_CALLBACK;

Pass:

error

The error code of your request. 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.

CalendarEventParamStruct

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.

CalendarAlarmStruct

typedef WordFlags CalendarAlarmStruct;

/* CalendarAlarmIntervalType */
#define CAS_TYPE            (0x8000 | 0x4000)
#define CAS_TYPE_OFFSET     (14)

typedef ByteEnum CalendarAlarmIntervalType;
#define CAIT_MINUTES	(0x0)    /* Must use CAIT_MINUTES on the Communicator */
#define CAIT_HOURS	(0x1)
#define CAIT_DAYS	(0x2)

/*  set if there is alarm */
#define CAS_HAS_ALARM       (0x2000)

/*  data according to CAS_TYPE */
#define CAS_INTERVAL        (0x1fff)
#define CAS_INTERVAL_OFFSET (0)

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.

CalendarEventDescType

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.

CalendarReturnedEventStruct

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.

CalendarEventError

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.

CalendarEventRepeatInfo

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.

CalendarEventRepeatInterval

typedef WordFlags CalendarEventRepeatInterval;

/* which week */
#define CERI_WEEK         (0x8000 | 0x4000 | 0x2000)
#define CERI_WEEK_OFFSET  (13)

/*  number of units between events. */
#define CERI_COUNT        (0x1000 | 0x0800 | 0x0400 | 0x0200 | 0x0100 | 0x0080 | 0x0040)
#define CERI_COUNT_OFFSET (6)

/*  CalendarEventRepeatWeekday  */
#define CERI_DAY          (0x0020 | 0x0010 | 0x0008)
#define CERI_DAY_OFFSET   (3)

/*  How frequently the event should be repeated */
/* CalendarEventRepeatIntervalType */
#define CERI_TYPE         (0x0004 | 0x0002 | 0x0001)
#define CERI_TYPE_OFFSET  (0)

typedef ByteEnum CalendarEventRepeatWeekday;
#define CERW_SUNDAY     (0x0)
#define CERW_MONDAY     (0x1)
#define CERW_TUESDAY    (0x2)
#define CERW_WEDNESDAY  (0x3)
#define CERW_THURSDAY   (0x4)
#define CERW_FRIDAY     (0x5)
#define CERW_SATURDAY   (0x6)

typedef ByteEnum CalendarEventRepeatIntervalType;
#define CERIT_DAILY           (0x0)
#define CERIT_WEEKLY          (0x1)
#define CERIT_MONTHLY_WEEKDAY (0x2)
#define CERIT_MONTHLY_DATE    (0x3)
#define CERIT_YEARLY_WEEKDAY  (0x4)
#define CERIT_YEARLY_DATE     (0x5)

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:

DAILY:

CERI_WEEK = unused
CERI_DAY = unused
CERI_COUNT = number of days between repeats (usually 1)

WEEKLY:

CERI_WEEK = unused
CERI_DAY = which day of week to repeat
CERI_COUNT = number of weeks between repeats (usually 1)

BI-WEEKLY:

CERI_WEEK = unused
CERI_DAY = which day of week to repeat
CERI_COUNT = number of weeks between repeats (2 in this case)

MONTHLY_WEEKDAY (e.g., the first Thursday of each month):

CERI_WEEK = which week in month
CERI_DAY = which day of week
CERI_COUNT = number of months between repeats (usually 1)

MONTH_DATE (e.g., the 15th of each month):

CERI_WEEK = unused
CERI_DAY = unused
CERI_COUNT = number of months between repeats (the date is taken from the appointment info itself, not the repeat info)

YEARLY_WEEKDAY (e.g., the first Thursday of November):

CERI_WEEK = which week in month
CERI_DAY = which day of week
CERI_COUNT = number of years between repeats (month is taken from the appointment info itself, not the repeat info)

YEARLY_DATE (e.g., birthdays):

CERI_WEEK = unused
CERI_DAY = unused
CERI_COUNT = number of years between repeats (month and day are taken from the appointment info itself, not the repeat info)

CalendarEventRepeatDuration

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.

CalendarEventRepeatDurationData

typedef union {
    FileDate                  CERDD_until;   /* Repeat until when */
    CalendarEventRepeatLength CERDD_length;  /* Repeat for how long */
} CalendarEventRepeatDurationData;

typedef WordFlags CalendarEventRepeatLength;
#define CERL_COUNT        (0xfffc)
#define CERL_COUNT_OFFSET (2)

/* CalendarEventRepeatLengthUnitType */
#define CERL_UNIT         (0x0002 | 0x0001)
#define CERL_UNIT_OFFSET  (0)

typedef ByteEnum CalendarEventRepeatLengthUnitType;
#define CERLUT_DAY      (0x0)
#define CERLUT_WEEK     (0x1)
#define CERLUT_MONTH    (0x2)
#define CERLUT_YEAR     (0x3)

typedef WordFlags FileDate;
#define FD_YEAR		        0xfe00  /* :7 year since FDAT_BASE_YEAR */
#define FD_MONTH		0x01e0  /* :4 month (1-12) */
#define FD_DAY                  0x001f  /* :5 day of the month (1-31) */
#define FD_YEAR_OFFSET	        9
#define FD_MONTH_OFFSET	        5
#define FD_DAY_OFFSET		0

#define FDAT_BASE_YEAR		1980 

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.