Reading and Writing Reminders

Reminders are tasks that may be tied to a specific time or location. They are similar to calendar events, but can be marked complete and may not necessarily span an exact period of time.

Because EKReminder inherits from EKCalendarItem, you can perform the same methods on a reminder as you would on an event, such as adding an alarm with addAlarm: or setting a recurrence rule with addRecurrenceRule:.

Retrieving Reminders

As with events, you must first establish a connection to the event store to access existing reminders. See “Connecting to the Event Store” if you have not already done so.

To initialize a connection with access to reminders on OS X, pass EKEntityMaskReminder instead of EKEntityMaskEvent.

EKEventStore *store = [[EKEventStore alloc] initWithAccessToEntityTypes:EKEntityMaskReminder];

On iOS 6 and later, you must request access to use the user’s Calendar database with the requestAccessToEntityType:completion: method after the event store is initialized. Requesting access to an entity type asynchronously prompts the user to allow or deny your app from using their calendar information. You should handle cases for when the user grants and denies access to your app:

[store requestAccessToEntityType:EKEntityTypeReminder completion:^(BOOL granted, NSError *error) {
    // handle access here
}];

You do not need to request access for the user’s reminders on OS X, because access is automatically granted.

Just like searching for events, there are two ways to retrieve reminders.

Using Predicates

You can call fetchRemindersMatchingPredicate:completion: to access multiple reminders that match a predicate. Pass a predicate returned by one of the following methods:

You can iterate across matched reminders by passing a block to the completion argument, as shown in Listing 2-1.

Listing 2-1  Fetching reminders with a predicate

NSPredicate *predicate = [store predicateForRemindersInCalendars:nil];
 
[store fetchRemindersMatchingPredicate:predicate completion:^(NSArray *reminders) {
    for (EKReminder *reminder in reminders) {
        // do something for each reminder
    }
}];

Using Unique Identifiers

If you know a specific reminder’s unique identifier from previously fetching it with a predicate, you can call the calendarItemWithIdentifier: instance method. calendarItemWithIdentifier: can fetch any calendar item (reminders and events), whereas eventWithIdentifier: fetches only events.

Creating and Editing Reminders

You can create reminders using the reminderWithEventStore: class method. The title and calendar properties are required. The calendar for a reminder is the list with which it is grouped.

Like events, reminders can trigger time-based or location-based alarms to alert the user of a certain task. Read “Configuring Alarms” for more information on how to attach alarms to calendar items.

To associate a start date or due date with a reminder, use the startDateComponents and dueDateComponents properties. To complete a reminder, set the completed property to YES, which automatically sets completionDate to the current date.

Saving and Removing Reminders

Reminders are saved in a similar fashion to events. To save a reminder to the Calendar database, call the saveReminder:commit:error: method. To remove an event, call the removeReminder:commit:error: method.

Remember, the title and calendar properties must explicitly be set before you save your reminder.