Fetching Events

You can fetch events from a user‚Äôs Calendar database using the EKEventStore class of the Event Kit framework. You can fetch a custom set of events that match a predicate you provide, or you can fetch an individual event by its unique identifier. After you fetch an event, you can access its associated calendar information with the properties of the EKEvent class.

Fetching Events with a Predicate

It‚Äôs common to fetch events that fall within a date range. The event store method eventsMatchingPredicate: fetches all events that fall within the date range specified in the predicate you provide. You must create the predicate for the eventsMatchingPredicate: method with the EKEventStore method predicateForEventsWithStartDate:endDate:calendars:. Listing 1-1 demonstrates fetching all events that occur between 30 days before the current date and 15 days after the current date.

Listing 1-1  Fetching events with a predicate

// Create the predicate's start and end dates.

CFGregorianDate gregorianStartDate, gregorianEndDate;

CFGregorianUnits startUnits = {0, 0, -30, 0, 0, 0};

CFGregorianUnits endUnits = {0, 0, 15, 0, 0, 0};

CFTimeZoneRef timeZone = CFTimeZoneCopySystem();

gregorianStartDate = CFAbsoluteTimeGetGregorianDate(

    CFAbsoluteTimeAddGregorianUnits(CFAbsoluteTimeGetCurrent(), timeZone, startUnits),

    timeZone);

gregorianStartDate.hour = 0;

gregorianStartDate.minute = 0;

gregorianStartDate.second = 0;

gregorianEndDate = CFAbsoluteTimeGetGregorianDate(

    CFAbsoluteTimeAddGregorianUnits(CFAbsoluteTimeGetCurrent(), timeZone, endUnits),

    timeZone);

gregorianEndDate.hour = 0;

gregorianEndDate.minute = 0;

gregorianEndDate.second = 0;

NSDate* startDate =

    [NSDate dateWithTimeIntervalSinceReferenceDate:CFGregorianDateGetAbsoluteTime(gregorianStartDate, timeZone)];

NSDate* endDate =

    [NSDate dateWithTimeIntervalSinceReferenceDate:CFGregorianDateGetAbsoluteTime(gregorianEndDate, timeZone)];

CFRelease(timeZone);

// Create the predicate.

NSPredicate *predicate = [eventStore predicateForEventsWithStartDate:startDate endDate:endDate calendars:nil]; // eventStore is an instance variable.

// Fetch all events that match the predicate.

NSArray *events = [eventStore eventsMatchingPredicate:predicate];

[self setEvents:events];

You can specify a subset of calendars to search by passing an array of EKCalendar objects as the calendars parameter of the predicateForEventsWithStartDate:endDate:calendars: method. You can get the user‚Äôs calendars from the event store‚Äôs calendars property. Passing nil tells the method to fetch from all of the user‚Äôs calendars.

Because the eventsMatchingPredicate: method is synchronous, you may not want to run it on your application‚Äôs main thread. For asynchronous behavior, run the method on another thread with the dispatch_async function or with an NSOperation object.

Fetching Individual Events with an Identifier

If you want to fetch an individual event and you know the event‚Äôs unique identifier from fetching it previously with a predicate, use the EKEventStore method eventWithIdentifier: to fetch the event. You can get an event‚Äôs unique identifier with the eventIdentifier property.

Sorting Events by Start Date

Applications often want to display event data to the user that is sorted by start date. To sort an array of EKEvent objects by date, call sortedArrayUsingSelector: on the array, providing the selector for the compareStartDateWithEvent: method.