CalendarService Data Types
CalendarService defines and uses several data types.
An object representing a calendar.
| Property Name | Type | Description | Example |
|---|---|---|---|
id | String | A stringified number unique to each calendar. Generated by the native device at the time of calendar creation. | "6544287" |
title | String | The name of the calendar. | "Awanasa's Calendar" |
allowsContentModifications | Boolean | Indicates whether the calendar is editable (true) or read-only (false). | false |
hexColor | String | Specifies the accent color shown for this calendar’s events on the device UI. Valid entries must contain a number sign (#) followed by a six-character hex color value. | "#009EDB" |
type | String | Metadata about the calendar’s type. | "exchange" |
isPrimary | Boolean | Indicates whether the selected calendar is the default calendar for the device. | true |
An object representing an event.
| Property Name | Type | Description | Example |
|---|---|---|---|
id | String | A stringified number unique to each event. Generated by the native device at the time of event creation. | "7824456" |
isAllDay | Boolean | Indicates whether the event is all-day. Defaults to false. | true |
startDateSecondsUTC | Number | Denotes the starting date and time for a given display range. | 1667692800 |
endDateSecondsUTC | Number | Denotes the ending date and time for a given display range. | 1668211200 |
availability | EventAvailability | Indicates a participant’s availability during an event. Defaults to “Busy”. | "Busy" |
status | EventStatus | This parameter is read-only; any value specified by the user is ignored by the plugin. | "Tentative" |
calendarId | String | Matches the id value from the associated calendar. | "6544287" |
title | String | The name of the event. | "Chan's Birthday Party" |
location | String | The location of the event. | "415 Mission St, San Francisco, CA, 94105" |
notes | String | Miscellaneous notes associated with the event. | "Don't forget to bring the cake!" |
alarms | Alarm[] | Indicates when a reminder is generated before the start of an event. | {relativeOffsetSeconds: 3600} |
attendees | Participant[] | Lists the attendees for an event. | {name: "Alex Driskall", email: "alex_driskall@example.com", role: "Required", status: "Accepted"} |
recurrenceRules | RecurrenceRule[] | Specifies any recurrence rules for an event. | {frequency: "Monthly"} |
An object representing when a notification is generated before an event.
| Property Name | Type | Description | Example |
|---|---|---|---|
relativeOffsetSeconds | Number | The amount of time, in seconds, before an event when a reminder notification is generated. | 1800 |
An object representing an invitee to a particular calendar event.
| Property Name | Type | Description | Example |
|---|---|---|---|
name | String | The name of the participant. | "Chan Ming Lewis" |
email | String | The email address of the participant. | "chan_ming_lewis_fake_email@employer.com" |
role | ParticipantRole | Indicates the level of necessity of an invitee’s attendance. | "Optional" |
status | ParticipantStatus | Indicates whether an invitee will attend an event. | "Attending" |
An object representing the recurrence cadence of a calendar event.
| Property Name | Type | Description | Example |
|---|---|---|---|
frequency | RecurrenceFrequency | Indicates the frequency of the event’s recurrence. | "Weekly" |
interval | Number | Indicates the interval at which the event’s recurrence takes place. Defaults to 1. For example, if the value of the frequencyparameter is "Weekly" and the value of the interval is 3, the event recurs every three weeks. | 3 |
daysOfTheWeek | RecurrenceDayOfWeek[] | Indicates which days of the week the events occurs on. | {dayOfTheWeek: "Thursday"} |
daysOfTheMonth | Number[] | Indicates which days of the month the event occurs on. Acceptable values include positive integers from 1 through 31 (inclusive). | 5 |
monthsOfTheYear | Number[] | Indicates which months of the year the event occurs on. Acceptable values include positive integers from 1 through 12 (inclusive). | 6 |
weeksOfTheYear | Number[] | Indicates which weeks of the year the event occurs on. Acceptable values include positive integers from 1 through 53 (inclusive). | 17 |
daysOfTheYear | Number[] | Indicates which days of the year the event occurs on. Acceptable values include positive integers from 1 through 366 (inclusive). | 200 |
setPositions | Number[] | Specifies a comma-separated list of values that correspond to the nth occurrence within the set of recurrence instance specified by the rule. The example provided shows a possible RecurrenceRule object representation of "the third and fifth weekdays of the month". | { frequency: "Monthly", daysOfTheWeek: {dayOfTheWeek: "Monday", "Tuesday", "Wednesday", "Thursday", "Friday"}, setPositions, 3, 5 } |
end | RecurrenceEnd | Indicates when the event recurrence ends. | {occurrenceCount: 8} |
Recurrence rule properties are defined in accordance with the standardized iCalendar data format. For more information of the specifics of the iCalendar format, see Internet Calendaring and Scheduling Core Object Specification.
An object for specifying the weekly recurrence cadence of a calendar event.
| Property Name | Type | Description | Example |
|---|---|---|---|
dayOfTheWeek | Weekday | Indicates the day of the week. | "Monday" |
weekNumber | Number[] | Indicates the week number within the calendar year. Acceptable values include positive integers from 1 through 53 (inclusive). | 25 |
An object for specifying the end of a recurrence cadence of a calendar event.
| Property Name | Type | Description | Example |
|---|---|---|---|
endDateSecondsUTC | Number | Denotes the ending date and time for a given recurring event. | 1668211200 |
occurrenceCount | Number | Denotes the number of times an event recurs. | 12 |
An object for specifying which instances of a recurring event are affected by an update to or deletion of one instance of an event.
| Property Name | Type | Description | Example |
|---|---|---|---|
span | Span | Indicates whether an update to or deletion of a recurring event applies to the specified event instance only, or the specified event instance and all future recurrences. | "ThisAndFollowingEvents" |
An object representing an error that occurred when accessing CalendarService features.
| Property Name | Type | Description |
|---|---|---|
code | CalendarServiceFailureCode | A value representing the reason for a calendar error. See CalendarServiceFailureCode in CalendarService Constants for the list of possible values. |
message | String | A string value describing the reason for the failure. This value is suitable for use in user error messages. The message is provided in English and isn’t localized. |