EKEventStore Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/EventKit.framework
Availability
Available in iOS 4.0 and later.
Companion guide
Calendar and Reminders Programming Guide
Declared in
EKEventStore.h
Related sample code

Overview

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.

Tasks

Accessing the Event Store

Accessing Calendars

Saving and Removing Calendars

Accessing Events

Saving and Removing Events

Accessing Reminders

Saving and Removing Reminders

Accessing Events or Reminders

Accessing Sources

Saving and Restoring State

Properties

defaultCalendarForNewEvents

The calendar that events are added to by default, as specified by user settings. (read-only)

@property(nonatomic, readonly) EKCalendar *defaultCalendarForNewEvents
Availability
  • Available in iOS 4.0 and later.
Declared In
EKEventStore.h

defaultCalendarForNewReminders

The calendar that events are added to by default, as specified by user settings. (read-only)

@property(nonatomic, readonly) EKCalendar *defaultCalendarForNewReminders

eventStoreIdentifier

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

@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.
Declared In
EKEventStore.h

Class Methods

authorizationStatusForEntityType:

Returns the authorization status for the given entity type.

+ (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.
Declared In
EKEventStore.h

Instance Methods

calendarItemsWithExternalIdentifier:

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

- (NSArray *)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.
Declared In
EKEventStore.h

calendarItemWithIdentifier:

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

- (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.
Declared In
EKEventStore.h

calendarsForEntityType:

Returns calendars that support a given entity type, such as reminders or events.

- (NSArray *)calendarsForEntityType:(EKEntityType)entityType
Parameters
entityType

The calendar’s entity type.

Return Value

The calendar that supports the specified entity type.

Availability
  • Available in iOS 6.0 and later.
See Also
Declared In
EKEventStore.h

calendarWithIdentifier:

Returns the calendar with the specified identifier.

- (EKCalendar *)calendarWithIdentifier:(NSString *)identifier
Parameters
identifier

The calendar’s unique identifier.

Return Value

The calendar with the specified identifier.

Availability
  • Available in iOS 5.0 and later.
Declared In
EKEventStore.h

cancelFetchRequest:

Cancels the request to fetch reminders.

- (void)cancelFetchRequest:(id)fetchIdentifier
Parameters
fetchIdentifier

The identifier of the request as returned by fetchRemindersMatchingPredicate:completion:.

Discussion

Once called, the completion block specified in fetchRemindersMatchingPredicate:completion: will not be called.

Availability
  • Available in iOS 6.0 and later.
Declared In
EKEventStore.h

commit:

Commits all unsaved changes to the event store.

- (BOOL)commit:(NSError **)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, YES; otherwise, NO. Returns YES 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 NO 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 YES as the commit parameter to the aforementioned methods, there is no need to call this method.

Availability
  • Available in iOS 5.0 and later.
Declared In
EKEventStore.h

enumerateEventsMatchingPredicate:usingBlock:

Finds all events that match a given predicate and calls a given callback for each event found.

- (void)enumerateEventsMatchingPredicate:(NSPredicate *)predicate usingBlock:(EKEventSearchCallback)block
Parameters
predicate

The search predicate. Must be created with the predicateForEventsWithStartDate:endDate:calendars: method.

block

The block callback to call for each event. The callback must match the signature defined by EKEventSearchCallback.

Discussion

Only events that have been committed are included in enumeration. Events saved using saveEvent:span:commit:error: with the commit parameter set to NO must call commit: beforehand to be included.

This method is synchronous. For asynchronous behavior, run the method on another thread with dispatch_async or NSOperation.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
EKEventStore.h

eventsMatchingPredicate:

Returns all events that match a given predicate.

- (NSArray *)eventsMatchingPredicate:(NSPredicate *)predicate
Parameters
predicate

The search predicate. Must be created with the predicateForEventsWithStartDate:endDate:calendars: method.

Return Value

All events that match predicate, as an array of EKEvent objects.

Discussion

Only events that have been committed are included in the results. Events saved using saveEvent:span:commit:error: with the commit parameter set to NO must call commit: beforehand to be included.

This method is synchronous. For asynchronous behavior, run the method on another thread with dispatch_async or NSOperation.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
EKEventStore.h

eventWithIdentifier:

Returns the first occurrence of an event with a given identifier.

- (EKEvent *)eventWithIdentifier:(NSString *)identifier
Parameters
identifier

The identifier of the event.

Return Value

The event corresponding to identifier, or nil if no event is found.

Availability
  • Available in iOS 4.0 and later.
Declared In
EKEventStore.h

fetchRemindersMatchingPredicate:completion:

Fetches reminders matching a given predicate.

- (id)fetchRemindersMatchingPredicate:(NSPredicate *)predicate completion:(void (^)(NSArray *))completion
Parameters
predicate

The search predicate.

completion

An array of the matched reminders passed by reference.

Return Value

A value to be used in cancelFetchRequest: to cancel the request later if desired.

Discussion

Only reminders that have been committed are included in the results. Reminders saved using saveReminder:commit:error: with the commit parameter set to NO must call commit: beforehand to be included.

This method fetches reminders asynchronously.

Availability
  • Available in iOS 6.0 and later.
See Also
Declared In
EKEventStore.h

predicateForCompletedRemindersWithCompletionDateStarting:ending:calendars:

Fetches completed reminders in a set of calendars within an optional range.

- (NSPredicate *)predicateForIncompleteRemindersWithDueDateStarting:(NSDate *)startDate ending:(NSDate *)endDate calendars:(NSArray *)calendars
Parameters
startDate

The starting bound of the range to search.

endDate

The ending bound of the range to search.

calendars

An array of calendars to search.

Return Value

The created predicate to be used for fetchRemindersMatchingPredicate:completion:.

Discussion

Pass nil for startDate to find all reminders completed before endDate. Similarly, pass nil for both startDate and endDate to get all complete reminders in the specified calendars.

Availability
  • Available in iOS 6.0 and later.
Declared In
EKEventStore.h

predicateForEventsWithStartDate:endDate:calendars:

Creates and returns a predicate for finding events in the event store that fall within a given date range.

- (NSPredicate *)predicateForEventsWithStartDate:(NSDate *)startDate endDate:(NSDate *)endDate calendars:(NSArray *)calendars
Parameters
startDate

The start date of the range of events fetched.

endDate

The end date of the range of events fetched.

calendars

The calendars to search, as an array of EKCalendar objects. Passing nil indicates to search all calendars.

Return Value

The created predicate.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
EKEventStore.h

predicateForIncompleteRemindersWithDueDateStarting:ending:calendars:

Fetches incomplete reminders in a set of calendars within an optional range.

- (NSPredicate *)predicateForIncompleteRemindersWithDueDateStarting:(NSDate *)startDate ending:(NSDate *)endDate calendars:(NSArray *)calendars
Parameters
startDate

The starting bound of the range to search.

endDate

The ending bound of the range to search.

calendars

An array of calendars to search.

Return Value

The created predicate to be used for fetchRemindersMatchingPredicate:completion:.

Discussion

Pass nil for startDate to find all reminders due before endDate. Similarly, pass nil for both startDate and endDate to get all incomplete reminders in the specified calendars.

Availability
  • Available in iOS 6.0 and later.
Declared In
EKEventStore.h

predicateForRemindersInCalendars:

Fetches all reminders in a set of calendars.

- (NSPredicate *)predicateForRemindersInCalendars:(NSArray *)calendars
Parameters
calendars

An array of calendars to search.

Return Value

The created predicate to be used for fetchRemindersMatchingPredicate:completion:.

Availability
  • Available in iOS 6.0 and later.
Declared In
EKEventStore.h

refreshSourcesIfNecessary

Pulls new data from remote sources if necessary.

- (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.
Declared In
EKEventStore.h

removeCalendar:commit:error:

Removes a calendar from the event store by either batching or committing the changes.

- (BOOL)removeCalendar:(EKCalendar *)calendar commit:(BOOL)commit error:(NSError **)error
Parameters
calendar

The calendar to be removed.

commit

YES to remove the calendar immediately; otherwise, the change is batched until the commit: method is invoked.

error

The error that occurred, if any; otherwise, nil.

Return Value

YES if successful; otherwise, NO.

Discussion

This method raises an exception if calendar belongs to another event store.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
EKEventStore.h

removeEvent:span:commit:error:

Removes an event or recurring events from the event store by either batching or committing the changes.

- (BOOL)removeEvent:(EKEvent *)event span:(EKSpan)span commit:(BOOL)commit error:(NSError **)error
Parameters
event

The event to remove.

span

The span to use. Indicates whether the remove affects future instances of the event in the case of a recurring event.

commit

YES to remove the event immediately; otherwise, the change is batched until the commit: method is invoked.

error

The error that occurred, if any did. Otherwise, nil.

Return Value

If the event has successfully removed, YES; otherwise, NO. Also returns NO if event cannot be removed because it is not in the event store.

Discussion

This method raises an exception if it is passed an event from another event store.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
EKEventStore.h

removeEvent:span:error:

Removes an event from the event store.

- (BOOL)removeEvent:(EKEvent *)event span:(EKSpan)span error:(NSError **)error
Parameters
event

The event to be removed.

span

The span to use. Indicates whether to remove future instances of the event in the case of a recurring event.

error

The error if one occurred; otherwise, nil.

Return Value

If the event has successfully removed, YES; otherwise, NO. Also returns NO if event cannot be removed because it is not in the event store.

Discussion

This method raises an exception if it is passed an event from another event store.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
EKEventStore.h

removeReminder:commit:error:

Removes a reminder from the event store by either committing or batching the changes.

- (BOOL)removeReminder:(EKReminder *)reminder commit:(BOOL)commit error:(NSError **)error
Parameters
reminder

The reminder to be removed.

commit

A Boolean value indicating whether to remove the reminder immediately or to batch the removals; passing NO will not commit the removal from the event store until the commit: method is invoked.

error

The error that occurred, if any; otherwise, nil.

Return Value

If successful, YES; otherwise, NO.

Discussion

This method raises an exception if reminder belongs to another event store.

Availability
  • Available in iOS 6.0 and later.
See Also
Declared In
EKEventStore.h

requestAccessToEntityType:completion:

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

- (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.
Declared In
EKEventStore.h

reset

Returns the event store to its saved state.

- (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
Declared In
EKEventStore.h

saveCalendar:commit:error:

Saves a calendar to the event store by either committing or batching the changes.

- (BOOL)saveCalendar:(EKCalendar *)calendar commit:(BOOL)commit error:(NSError **)error
Parameters
calendar

The calendar to be saved.

commit

YES to save the calendar immediately; otherwise, the change is batched until the commit: method is invoked.

error

The error that occurred, if any; otherwise, nil.

Return Value

YES if successful; otherwise, NO.

Discussion

This method raises an exception if calendar belongs to another event store.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
EKEventStore.h

saveEvent:span:commit:error:

Saves an event or recurring events to the event store by either batching or committing the changes.

- (BOOL)saveEvent:(EKEvent *)event span:(EKSpan)span commit:(BOOL)commit error:(NSError **)error
Parameters
event

The event to be saved.

span

The span to use. Indicates whether the save affects future instances of the event in the case of a recurring event.

commit

To save the event immediately, pass YES; otherwise, the change is batched until the commit: method is invoked.

error

The error that occurred, if any; otherwise, nil.

Return Value

If successful, YES; otherwise, NO. Also returns NO if event does not need to be saved because it has not been modified.

Discussion

This method raises an exception if it is passed an event from another event store.

When an event is saved, it is updated in the Calendar database. Any fields you did not modify are updated to reflect the most recent value in the database. If the event has been deleted from the database, it is re-created as a new event.

Availability
  • Available in iOS 5.0 and later.
See Also
Declared In
EKEventStore.h

saveEvent:span:error:

Saves changes to an event permanently.

- (BOOL)saveEvent:(EKEvent *)event span:(EKSpan)span error:(NSError **)error
Parameters
event

The event to be saved.

span

The span to use. Indicates whether the save affects future instances of the event in the case of a recurring event.

error

The error that occurred, if any; otherwise, nil.

Return Value

If the event has successfully saved, YES; otherwise, NO. Also returns NO if event does not need to be saved because it was not modified.

Discussion

This method raises an exception if it is passed an event from another event store.

When an event is saved, it is updated in the Calendar database. Any fields you did not modify are updated to reflect the most recent value in the database. If the event has been deleted from the database, it is re-created as a new event.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
EKEventStore.h

saveReminder:commit:error:

Saves changes to a reminder by either committing or batching the changes.

- (BOOL)saveReminder:(EKReminder *)reminder commit:(BOOL)commit error:(NSError **)error
Parameters
reminder

The reminder to be saved.

commit

A Boolean value indicating whether to save the reminder immediately or to batch the changes; passing NO will not commit changes to the event store until the commit: method is invoked.

error

The error that occurred, if any; otherwise, nil.

Return Value

If successful, YES; otherwise, NO.

Discussion

This method raises an exception if reminder belongs to another event store.

Availability
  • Available in iOS 6.0 and later.
See Also
Declared In
EKEventStore.h

sources

Returns an unordered array of source objects.

- (NSArray *)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.
Declared In
EKEventStore.h

sourceWithIdentifier:

Returns a source with the specified identifier.

- (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.
Declared In
EKEventStore.h

Constants

EKSpan

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

typedef enum {
   EKSpanThisEvent,
   EKSpanFutureEvents
} EKSpan;
Constants
EKSpanThisEvent

Modifications to this event instance should affect only this instance.

Available in iOS 4.0 and later.

Declared in EKEventStore.h.

EKSpanFutureEvents

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

Available in iOS 4.0 and later.

Declared in EKEventStore.h.

EKAuthorizationStatus

Indicates the current authorization status for a specific entity type.

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

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

Available in iOS 6.0 and later.

Declared in EKEventStore.h.

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.

Declared in EKEventStore.h.

EKAuthorizationStatusDenied

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

Available in iOS 6.0 and later.

Declared in EKEventStore.h.

EKAuthorizationStatusAuthorized

The app is authorized to access the service.

Available in iOS 6.0 and later.

Declared in EKEventStore.h.

EKEventStoreRequestAccessCompletionHandler

The signature for a block object used for operating on events with the requestAccessToEntityType:completion: method.

typedef void (^EKEventStoreRequestAccessCompletionHandler)(BOOL granted, NSError *error);
Availability
  • Available in iOS 6.0 and later.
Declared In
EKEventStore.h

EKEventSearchCallback

The signature for a block object used for operating on events with the enumerateEventsMatchingPredicate:usingBlock: method.

typedef void (^EKEventSearchCallback)(EKEvent *event, BOOL *stop);
Discussion

The event argument is the event to operate on. You can set the value of the stop argument to YES to tell the enumerateEventsMatchingPredicate:usingBlock: method to stop processing events when this block returns.

Availability
  • Available in iOS 4.0 and later.
Declared In
EKEventStore.h

Notifications

EKEventStoreChangedNotification

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 YES, you do not need to refetch the event.
Availability
Declared In
EKEventStore.h


© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-07-17)

Did this document help you? Yes It's good, but... Not helpful...