CalendarService Data Types

CalendarService defines and uses several data types.

Calendar

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`

Event

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"}`

Alarm

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

Participant

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”

RecurrenceRule

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.

Note

RecurrenceDayOfWeek

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

RecurrenceEnd

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

CalendarServiceOptions

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”

CalendarServiceFailure

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.