iOS Developer Library

Developer

EventKit Framework Reference EKEventStore Class Reference

Options
Deployment Target:

On This Page
Language:

EKEventStore

An instance of the EKEventStore class represents the Calendar database. It is an application’s point of contact for accessing calendar and reminder data.

On iOS 5 and later, initialize an event store object with the default init method. On iOS 6 and later, you must request access to an entity type after the event store is initialized with requestAccessToEntityType:completion: for data to return.

On OS X, use initWithAccessToEntityTypes: instead of the default init method. Acceptable entity types are EKEntityMaskEvent for events and EKEntityMaskReminder for reminders.

Create a predicate, or a search query for events, with the predicateForEventsWithStartDate:endDate:calendars: method.

Fetch and process events that match a given predicate with the eventsMatchingPredicate: and enumerateEventsMatchingPredicate:usingBlock: methods.

Save and delete events from the event store with the saveEvent:span:commit:error: and removeEvent:span:commit:error: methods.

Use similar methods to access and manipulate reminders. Reminders are not available in Event Kit before iOS 6.

  • Prompts the user to grant or deny access to event or reminder data.

    Declaration

    Swift

    func requestAccessToEntityType(_ entityType: EKEntityType, completion completion: EKEventStoreRequestAccessCompletionHandler)

    Objective-C

    - (void)requestAccessToEntityType:(EKEntityType)entityType completion:(EKEventStoreRequestAccessCompletionHandler)completion

    Parameters

    entityType

    The event or reminder entity type.

    completion

    The block to call when the request completes.

    Discussion

    In iOS 6 and later, requesting access to an event store asynchronously prompts your users for permission to use their data. The user is only prompted the first time your app requests access to an entity type; any subsequent instantiations of EKEventStore uses existing permissions. When the user taps to grant or deny access, the completion handler will be called on an arbitrary queue. Your app is not blocked while the user decides to grant or deny permission.

    After users choose their permission level, the event store either calls the completion handler or broadcasts an EKEventStoreChangedNotification. The completion handler is called on iOS 6 and later, and the notification is broadcasted on iOS 5. Because users may deny access to the event store, your app should handle an empty data case.

    Availability

    Available on iOS 6 and later.

  • Returns the authorization status for the given entity type.

    Declaration

    Swift

    class func authorizationStatusForEntityType(_ entityType: EKEntityType) -> EKAuthorizationStatus

    Objective-C

    + (EKAuthorizationStatus)authorizationStatusForEntityType:(EKEntityType)entityType

    Parameters

    entityType

    The event or reminder entity type.

    Return Value

    The app’s authorization status of the given type.

    Availability

    Available on iOS 6 and later.

  • The unique identifier for the event store. (read-only)

    Declaration

    Swift

    var eventStoreIdentifier: String { get }

    Objective-C

    @property(nonatomic, readonly) NSString *eventStoreIdentifier

    Discussion

    If the store is damaged, it is re-created and given a new identifier. If this value is different from a fetched value, you should take the appropriate action.

    Availability

    Available in iOS 4.0 and later.

  • Returns either the event’s first occurrence or the reminder with the specified identifier.

    Declaration

    Swift

    func calendarItemWithIdentifier(_ identifier: String) -> EKCalendarItem

    Objective-C

    - (EKCalendarItem *)calendarItemWithIdentifier:(NSString *)identifier

    Parameters

    identifier

    The calendar item’s unique identifier.

    Return Value

    The reminder or the first occurrence of an event with the specified identifier.

    Availability

    Available in iOS 6.0 and later.

  • Returns either the event’s first occurrences or the reminders with the specified external identifier.

    Declaration

    Swift

    func calendarItemsWithExternalIdentifier(_ externalIdentifier: String) -> [EKCalendarItem]

    Objective-C

    - (NSArray<EKCalendarItem *> *)calendarItemsWithExternalIdentifier:(NSString *)externalIdentifier

    Parameters

    externalIdentifier

    The calendar item’s external identifier.

    Return Value

    An array of calendar items with the specified identifier.

    Discussion

    The external identifier can be obtained from the calendarItemExternalIdentifier property. There may be more than one matching calendar item due to reasons discussed in calendarItemExternalIdentifier.

    Availability

    Available in iOS 6.0 and later.

  • Returns an unordered array of source objects.

    Declaration

    Swift

    var sources: [EKSource] { get }

    Objective-C

    @property(nonatomic, readonly) NSArray<EKSource *> *sources

    Return Value

    An unordered array of EKSource objects.

    Discussion

    An EKSource object represents an account that contains calendars.

    Availability

    Available in iOS 5.0 and later.

  • Returns a source with the specified identifier.

    Declaration

    Swift

    func sourceWithIdentifier(_ identifier: String) -> EKSource

    Objective-C

    - (EKSource *)sourceWithIdentifier:(NSString *)identifier

    Parameters

    identifier

    The source’s unique identifier.

    Return Value

    The source with the specified identifier.

    Availability

    Available in iOS 5.0 and later.

  • Commits all unsaved changes to the event store.

    Declaration

    Swift

    func commit() throws

    Objective-C

    - (BOOL)commit:(NSError * _Nullable *)error

    Parameters

    error

    A pointer to an NSError object. You do not need to create an NSError object. The commit operation aborts after the first failure if you pass NULL.

    Return Value

    If the commit operation succeeded, YEStrue; otherwise, NOfalse. Returns YEStrue even when there are no changes to commit.

    Discussion

    This method allows you to save batched changes to the event store. For example, if you pass NOfalse as the commit parameter to the saveCalendar:commit:error:, removeCalendar:commit:error:, saveEvent:span:commit:error:, or removeEvent:span:commit:error: methods, the changes are not saved until this method is invoked. Likewise, if you pass YEStrue as the commit parameter to the aforementioned methods, there is no need to call this method.

    Availability

    Available in iOS 5.0 and later.

  • Returns the event store to its saved state.

    Declaration

    Swift

    func reset()

    Objective-C

    - (void)reset

    Discussion

    This method updates all the properties of all the objects with their corresponding values in the event store. Any local changes that were not saved before invoking this method will be lost. All objects that were created or retrieved using this store are disassociated from it and should be considered invalid.

    Availability

    Available in iOS 5.0 and later.

    See Also

    reset

  • Pulls new data from remote sources if necessary.

    Declaration

    Swift

    func refreshSourcesIfNecessary()

    Objective-C

    - (void)refreshSourcesIfNecessary

    Discussion

    Use this method to pull new data from remote sources if the local data is out of date.

    Availability

    Available in iOS 5.0 and later.

Data Types

  • Indicates whether modifications should apply to a single event or all future events of a recurring event.

    Declaration

    Swift

    enum EKSpan : Int { case ThisEvent case FutureEvents }

    Objective-C

    typedef enum { EKSpanThisEvent, EKSpanFutureEvents } EKSpan;

    Constants

    • ThisEvent

      EKSpanThisEvent

      Modifications to this event instance should affect only this instance.

      Available in iOS 4.0 and later.

    • FutureEvents

      EKSpanFutureEvents

      Modifications to this event instance should also affect future instances of this event.

      Available in iOS 4.0 and later.

    Import Statement

    Objective-C

    @import EventKit;

    Swift

    import EventKit

    Availability

    Available in iOS 4.0 and later.

  • Indicates the current authorization status for a specific entity type.

    Declaration

    Swift

    enum EKAuthorizationStatus : Int { case NotDetermined case Restricted case Denied case Authorized }

    Objective-C

    typedef enum { EKAuthorizationStatusNotDetermined = 0, EKAuthorizationStatusRestricted, EKAuthorizationStatusDenied, EKAuthorizationStatusAuthorized } EKAuthorizationStatus;

    Constants

    • NotDetermined

      EKAuthorizationStatusNotDetermined

      The user has not yet made a choice regarding whether the app may access the service.

      Available in iOS 6.0 and later.

    • Restricted

      EKAuthorizationStatusRestricted

      The app is not authorized to access the service. The user cannot change this app’s authorization status, possibly due to active restrictions such as parental controls being in place.

      Available in iOS 6.0 and later.

    • Denied

      EKAuthorizationStatusDenied

      The user explicitly denied access to the service for the app.

      Available in iOS 6.0 and later.

    • Authorized

      EKAuthorizationStatusAuthorized

      The app is authorized to access the service.

      Available in iOS 6.0 and later.

    Import Statement

    Objective-C

    @import EventKit;

    Swift

    import EventKit

    Availability

    Available in iOS 6.0 and later.

  • Posted whenever changes are made to the Calendar database, including adding, removing, and changing events or reminders. Individual changes are not described. When you receive this notification, you should refetch all EKEvent and EKReminder objects you have accessed, as they are considered stale. If you are actively editing an event and do not wish to refetch it unless it is absolutely necessary to do so, you can call the refresh method on it. If the method returns YEStrue, you do not need to refetch the event.

    Declaration

    Swift

    let EKEventStoreChangedNotification: String

    Import Statement

    Objective-C

    @import EventKit;

    Swift

    import EventKit

    Availability

    Available in iOS 4.0 and later.