Class: EKEventStore

Inherits:
NSObject show all

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.

Instance Attribute Summary (collapse)

Class Method Summary (collapse)

Instance Method Summary (collapse)

Methods inherited from NSObject

#!, #!=, #!~, #, #==, #===, #=~, #Rational, #__callee__, #__method__, #__send__, #__type__, `, alloc, allocWithZone:, #autoContentAccessingProxy, autoload, autoload?, autorelease_pool, #awakeAfterUsingCoder:, binding, block_given?, caller, cancelPreviousPerformRequestsWithTarget:, cancelPreviousPerformRequestsWithTarget:selector:object:, catch, class, classFallbacksForKeyedArchiver, #classForCoder, #classForKeyedArchiver, classForKeyedUnarchiver, #clone, conformsToProtocol:, #copy, copyWithZone:, #dealloc, #define_singleton_method, description, display, #doesNotRecognizeSelector:, #dup, #enum_for, #eql?, #equal?, #extend, fail, #finalize, format, #forwardInvocation:, #forwardingTargetForSelector:, framework, #freeze, #frozen?, getpass, gets, global_variables, #init, initialize, #initialize_clone, #initialize_copy, #initialize_dup, #inspect, instanceMethodForSelector:, instanceMethodSignatureForSelector:, #instance_eval, #instance_exec, #instance_of?, #instance_variable_defined?, #instance_variable_get, #instance_variable_set, #instance_variables, instancesRespondToSelector:, isSubclassOfClass:, #is_a?, iterator?, #kind_of?, lambda, load, load_bridge_support_file, load_plist, local_variables, loop, #method, #methodForSelector:, #methodSignatureForSelector:, #methods, #mutableCopy, mutableCopyWithZone:, new, #nil?, open, p, #performSelector:onThread:withObject:waitUntilDone:, #performSelector:onThread:withObject:waitUntilDone:modes:, #performSelector:withObject:afterDelay:, #performSelector:withObject:afterDelay:inModes:, #performSelectorInBackground:withObject:, #performSelectorOnMainThread:withObject:waitUntilDone:, #performSelectorOnMainThread:withObject:waitUntilDone:modes:, print, printf, #private_methods, proc, #protected_methods, #public_method, #public_methods, #public_send, putc, puts, raise, rand, readline, readlines, #replacementObjectForCoder:, #replacementObjectForKeyedArchiver:, require, resolveClassMethod:, resolveInstanceMethod:, #respond_to?, #respond_to_missing?, select, #send, setVersion:, #singleton_methods, sprintf, srand, superclass, #taint, #tainted?, #tap, test, throw, #to_plist, #to_s, trace_var, trap, #trust, #untaint, untrace_var, #untrust, #untrusted?, version

Constructor Details

This class inherits a constructor from NSObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class NSObject

Instance Attribute Details

- (EKCalendar) defaultCalendarForNewEvents (readonly)

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

Returns:

- (EKCalendar) defaultCalendarForNewReminders (readonly)

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

Returns:

- (String) eventStoreIdentifier (readonly)

The unique identifier for the event store. (read-only) 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.

Returns:

Class Method Details

+ (EKAuthorizationStatus) authorizationStatusForEntityType(entityType)

Returns the authorization status for the given entity type.

Parameters:

  • entityType (EKEntityType) —

    The event or reminder entity type.

Returns:

Instance Method Details

- (EKCalendarItem) calendarItemsWithExternalIdentifier(externalIdentifier)

Returns either the event’s first occurrences or the reminders with the specified external identifier. 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.

Parameters:

  • externalIdentifier (String) —

    The calendar item’s external identifier.

Returns:

  • (EKCalendarItem) —

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

- (EKCalendarItem) calendarItemWithIdentifier(identifier)

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

Parameters:

  • identifier (String) —

    The calendar item’s unique identifier.

Returns:

  • (EKCalendarItem) —

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

- (Array) calendarsForEntityType(entityType)

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

Parameters:

  • entityType (EKEntityType) —

    The calendar’s entity type.

Returns:

  • (Array) —

    The calendar that supports the specified entity type.

- (EKCalendar) calendarWithIdentifier(identifier)

Returns the calendar with the specified identifier.

Parameters:

  • identifier (String) —

    The calendar’s unique identifier.

Returns:

  • (EKCalendar) —

    The calendar with the specified identifier.

- (Object) cancelFetchRequest(fetchIdentifier)

Cancels the request to fetch reminders. Once called, the completion block specified in fetchRemindersMatchingPredicate:completion: will not be called.

Parameters:

  • fetchIdentifier (Object) —

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

Returns:

- (Boolean) commit(error)

Commits all unsaved changes to the event store. 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.

Parameters:

  • error (Pointer) —

    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.

Returns:

  • (Boolean) —

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

- (Object) enumerateEventsMatchingPredicate(predicate, usingBlock:block)

Finds all events that match a given predicate and calls a given callback for each event found. 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(3) OS X Developer Tools Manual Page or NSOperation.

Parameters:

  • predicate (NSPredicate) —

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

  • block (EKEventSearchCallback) —

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

Returns:

- (Array) eventsMatchingPredicate(predicate)

Returns all events that match a given predicate. 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(3) OS X Developer Tools Manual Page or NSOperation.

Parameters:

  • predicate (NSPredicate) —

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

Returns:

  • (Array) —

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

- (EKEvent) eventWithIdentifier(identifier)

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

Parameters:

  • identifier (String) —

    The identifier of the event.

Returns:

  • (EKEvent) —

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

- (Object) fetchRemindersMatchingPredicate(predicate, completion:completion)

Fetches reminders matching a given predicate. 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.

Parameters:

  • predicate —

    The search predicate.

  • completion —

    An array of the matched reminders passed by reference.

Returns:

  • (Object) —

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

- (NSPredicate) predicateForEventsWithStartDate(startDate, endDate:endDate, calendars:calendars)

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

Parameters:

  • startDate (NSDate) —

    The start date of the range of events fetched.

  • endDate (NSDate) —

    The end date of the range of events fetched.

  • calendars (Array) —

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

Returns:

- (NSPredicate) predicateForIncompleteRemindersWithDueDateStarting(startDate, ending:endDate, calendars:calendars)

Fetches incomplete reminders in a set of calendars within an optional range. 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.

Parameters:

  • startDate (NSDate) —

    The starting bound of the range to search.

  • endDate (NSDate) —

    The ending bound of the range to search.

  • calendars (Array) —

    An array of calendars to search.

Returns:

  • (NSPredicate) —

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

- (NSPredicate) predicateForRemindersInCalendars(calendars)

Fetches all reminders in a set of calendars.

Parameters:

  • calendars (Array) —

    An array of calendars to search.

Returns:

  • (NSPredicate) —

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

- (Object) refreshSourcesIfNecessary

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

Returns:

- (Boolean) removeCalendar(calendar, commit:commit, error:error)

Removes a calendar from the event store by either batching or committing the changes. This method raises an exception if calendar belongs to another event store.

Parameters:

  • calendar (EKCalendar) —

    The calendar to be removed.

  • commit (Boolean) —

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

  • error (Pointer) —

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

Returns:

  • (Boolean) —

    YES if successful; otherwise, NO.

- (Boolean) removeEvent(event, span:span, commit:commit, error:error)

Removes an event or recurring events from the event store by either batching or committing the changes. This method raises an exception if it is passed an event from another event store.

Parameters:

  • event (EKEvent) —

    The event to remove.

  • span (EKSpan) —

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

  • commit (Boolean) —

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

  • error (Pointer) —

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

Returns:

  • (Boolean) —

    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.

- (Boolean) removeEvent(event, span:span, error:error)

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

Parameters:

  • event (EKEvent) —

    The event to be removed.

  • span (EKSpan) —

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

  • error (Pointer) —

    The error if one occurred; otherwise, nil.

Returns:

  • (Boolean) —

    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.

- (Boolean) removeReminder(reminder, commit:commit, error:error)

Removes a reminder from the event store by either committing or batching the changes. This method raises an exception if reminder belongs to another event store.

Parameters:

  • reminder (EKReminder) —

    The reminder to be removed.

  • commit (Boolean) —

    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 (Pointer) —

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

Returns:

  • (Boolean) —

    If successful, YES; otherwise, NO.

- (Object) requestAccessToEntityType(entityType, completion:completion)

Prompts the user to grant or deny access to event or reminder data. 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. 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.Important: If your app has never requested access before, you must request access to events or reminders before attempting to fetch or create them. If you request data before prompting the user for access with this method, you’ll need to reset the event store with the reset method in order to start receiving data once the user grants access.

Parameters:

  • entityType (EKEntityType) —

    The event or reminder entity type.

  • completion (EKEventStoreRequestAccessCompletionHandler) —

    The block to call when the request completes.

Returns:

- (Object) reset

Returns the event store to its saved state. 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.

Returns:

- (Boolean) saveCalendar(calendar, commit:commit, error:error)

Saves a calendar to the event store by either committing or batching the changes. This method raises an exception if calendar belongs to another event store.

Parameters:

  • calendar (EKCalendar) —

    The calendar to be saved.

  • commit (Boolean) —

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

  • error (Pointer) —

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

Returns:

  • (Boolean) —

    YES if successful; otherwise, NO.

- (Boolean) saveEvent(event, span:span, commit:commit, error:error)

Saves an event or recurring events to the event store by either batching or committing the changes. 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.

Parameters:

  • event (EKEvent) —

    The event to be saved.

  • span (EKSpan) —

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

  • commit (Boolean) —

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

  • error (Pointer) —

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

Returns:

  • (Boolean) —

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

- (Boolean) saveEvent(event, span:span, error:error)

Saves changes to an event permanently. 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.

Parameters:

  • event (EKEvent) —

    The event to be saved.

  • span (EKSpan) —

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

  • error (Pointer) —

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

Returns:

  • (Boolean) —

    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.

- (Boolean) saveReminder(reminder, commit:commit, error:error)

Saves changes to a reminder by either committing or batching the changes. This method raises an exception if reminder belongs to another event store.

Parameters:

  • reminder (EKReminder) —

    The reminder to be saved.

  • commit (Boolean) —

    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 (Pointer) —

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

Returns:

  • (Boolean) —

    If successful, YES; otherwise, NO.

- (Array) sources

Returns an unordered array of source objects. An EKSource object represents an account that contains calendars.

Returns:

- (EKSource) sourceWithIdentifier(identifier)

Returns a source with the specified identifier.

Parameters:

  • identifier (String) —

    The source’s unique identifier.

Returns:

  • (EKSource) —

    The source with the specified identifier.