| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/CalendarStore.framework |
| Availability | Available in Mac OS X v10.5 and later. |
| Companion guide | |
| Declared in | CalCalendarStore.h |
| Related sample code |
There is only one CalCalendarStore object and it represents a connection to the iCal database. You retrieve all other types of calendar objects—including calendars, events, and tasks—using this shared CalCalendarStore object.
Use the defaultCalendarStore class method to get the shared CalCalendarStore object. Use the calendars method to fetch all the CalCalendar objects, and the calendarWithUID: method to fetch individual calendars. Use the eventsWithPredicate: and tasksWithPredicate: methods to fetch events and tasks. These methods take an NSPredicate object as the argument. Use the eventPredicate... and taskPredicate... methods to create NSPredicate objects for common queries that you can pass to these methods.
Use specific CalCalendar, CalEvent, and CalTask properties and methods to make changes to these types of objects. If you make local changes to calendars, events, and tasks, invoke the corresponding save... method; otherwise, your changes do not persist. You might also need to track changes.
Calendars, events, and tasks may be added, changed, or deleted after you fetch them. Changes can occur locally or externally where local changes are made by your application and external changes are made by other applications. When these objects change, you might want to take some action, especially if you retain fetched objects—for example, update the display. You can track changes by observing notifications.
The following notifications are posted when your application changes these types of objects: CalCalendarsChangedNotification, CalEventsChangedNotification, and CalTasksChangedNotification.
The following notifications are posted when another application changes these types of objects: CalCalendarsChangedExternallyNotification, CalEventsChangedExternallyNotification, and CalTasksChangedExternallyNotification notifications.
Returns the shared CalCalendarStore object.
+ (CalCalendarStore *)defaultCalendarStore
The shared CalCalendarStore object.
The first time an application invokes this method, Calendar Store might migrate the calendar data from a previous Mac OS X file format to the current one. This method returns nil if the migration fails.
Invoke this method to get the shared instance. Do not create a CalCalendarStore object directly.
CalCalendarStore.hReturns an NSPredicate object that specifies events within a date range that belong to the specified calendars.
+ (NSPredicate *)eventPredicateWithStartDate:(NSDate *)startDate endDate:(NSDate *)endDate calendars:(NSArray *)calendars
The start date of the date range.
The end date of the date range.
An array of CalCalendar objects that the events must belong to.
An NSPredicate object that specifies events within a date range that belong to the specified calendars.
If an event is greater than or equal to startDate and less than or equal to endDate, and belongs to a calendar in calendars, then it is included in the predicate’s result.
CalCalendarStore.hReturns an NSPredicate object that specifies events with a UID and within a date range that belong to the specified calendars.
+ (NSPredicate *)eventPredicateWithStartDate:(NSDate *)startDate endDate:(NSDate *)endDate UID:(NSString *)UID calendars:(NSArray *)calendars
The start date of the date range.
The end date of the date range.
The UID for the returned events.
An array of CalCalendar objects that the events must belong to.
An NSPredicate object that specifies events with a UID and within a date range that belong to the specified calendars.
Recurring events have the same UID. Therefore, use this method, instead of the eventPredicateWithStartDate:endDate:calendars: method, if you want to fetch all events belonging to the same master recurring event.
CalCalendarStore.hReturns an NSPredicate object that specifies tasks that belong to the specified calendars.
+ (NSPredicate *)taskPredicateWithCalendars:(NSArray *)calendars
An array of CalCalendar objects that the tasks must belong to.
An NSPredicate object that specifies tasks that belong to the specified calendars.
CalCalendarStore.hReturns an NSPredicate object that specifies completed tasks since the specified date and that belong to the specified calendars.
+ (NSPredicate *)taskPredicateWithTasksCompletedSince:(NSDate *)completedSince calendars:(NSArray *)calendars
Specifies the completion date.
An array of CalCalendar objects that the tasks must belong to.
If a task is completed after completedSince and belongs to a calendar in calendars, then it is included in the returned predicate’s result.
CalCalendarStore.hReturns an NSPredicate object that specifies tasks that are incomplete and belong to the specified calendars.
+ (NSPredicate *)taskPredicateWithUncompletedTasks:(NSArray *)calendars
An array of CalCalendar objects that the tasks must belong to.
An NSPredicate object that specifies tasks that are incomplete and belong to the specified calendars.
CalCalendarStore.hReturns an NSPredicate object that specifies incomplete tasks due before the specified date and that belong to the specified calendars.
+ (NSPredicate *)taskPredicateWithUncompletedTasksDueBefore:(NSDate *)dueDate calendars:(NSArray *)calendars
Specifies the due date of the tasks.
An array of CalCalendar objects that the tasks must belong to.
If an incomplete task’s due date is before dueDate and belongs to a calendar in calendars, then it is included in the returned predicate’s result.
CalCalendarStore.hReturns an array of CalCalendar objects representing the user’s calendars in the order they appear in iCal.
- (NSArray *)calendars
An array of CalCalendar objects. Returns an empty array if the user hasn’t launched iCal and created any calendars.
This method returns an empty array if the user has calendar data from a previous version of Mac OS X but has not launched iCal in Mac OS X v10.5 yet. iCal needs to be launched at least once on Mac OS X v10.5 to migrate the user's calendar data from a previous version. If no calendar data from a previous version exists, then this method creates and returns the default calendars.
CalCalendarStore.hReturns a CalCalendar object that corresponds to the given UID.
- (CalCalendar *)calendarWithUID:(NSString *)UID
A string that uniquely identifies a calendar.
The calendar that corresponds to the UID. Returns nil if no calendar with the specified UID exists.
CalCalendarStore.hReturns an array of CalEvent objects that match the specified predicate.
- (NSArray *)eventsWithPredicate:(NSPredicate *)predicate
Describes the set of records that should be returned. If nil, an exception is raised.
An array of CalEvent objects that match the specified predicate. Returns nil if the predicate is invalid.
The predicate passed to this method must be valid—it must be created using one of the class methods defined in this class to create predicates, the eventPredicateWith... or taskPredicateWith... methods.
For performance reasons, this method only returns events that fall within a specific four year timespan. If the date range between the predicate’s start date and end date is greater than four years, then the timespan containing events is always the first four years of the date range
If you observe the CalEventsChangedNotification notification, you can retain the predicate and send it evaluateWithObject:, passing the changed event to determine whether the notification affects the event objects you previously fetched.
CalCalendarStore.hReturns an event that matches the specified unique identifier.
- (CalEvent *)eventWithUID:(NSString *)uid occurrence:(NSDate *)date
The unique identifier of an event.
The date of a recurring event. Pass nil if the event is not recurring.
A CalEvent object that matches the specified unique identifier and date. Returns nil if the event is not found, or the event is recurring and date is not specified.
CalCalendarStore.hRemoves the specified calendar from the iCal database.
- (BOOL)removeCalendar:(CalCalendar *)calendar error:(NSError **)error
The calendar object to remove. Must be a local calendar not a subscribed, birthday, or CalDAV calendar.
If this method returns NO, an NSError object describing the error. See Calendar Store Constants Reference for description of error codes.
If successful, returns YES; otherwise, returns NO and sets the error argument to an NSError object describing the error.
CalCalendarStore.hRemoves the specified event from the calendar store.
- (BOOL)removeEvent:(CalEvent *)event span:(CalSpan)span error:(NSError **)error
The event to remove.
Specifies the span of a recurring event—whether the change should be applied to future occurrences, all occurrences, or just this instance. Applying changes to future occurrences or all occurrences may cause the UID or occurrence date of the event to change.
If this method returns NO, an NSError object describing the error. See Calendar Store Constants Reference for description of error codes.
If successful, returns YES; otherwise, returns NO and sets the error argument to an NSError object describing the error.
CalCalendarStore.hRemoves the specified task from the calendar store.
- (BOOL)removeTask:(CalTask *)task error:(NSError **)error
The task to remove.
If this method returns NO, an NSError object describing the error. See InstantMessage Constants Reference for description of error codes.
If successful, returns YES; otherwise, returns NO and sets the error argument to an NSError object describing the error.
CalCalendarStore.hSaves local changes to the specified calendar object to the iCal database.
- (BOOL)saveCalendar:(CalCalendar *)calendar error:(NSError **)error
The calendar object to save. Must be a local calendar not a subscribed, birthday, or CalDAV calendar.
If this method returns NO, an NSError object describing the error. See InstantMessage Constants Reference for description of error codes.
If successful, returns YES; otherwise, returns NO and sets the error argument to an NSError object describing the error.
Use this method to both create a new calendar and save changes to an existing calendar. Changes you make to calendars do not persist unless you invoke this method.
CalCalendarStore.hSaves the specified event to the calendar store.
- (BOOL)saveEvent:(CalEvent *)event span:(CalSpan)span error:(NSError **)error
The event to save.
Specifies the span of a recurring event—if the change should be applied to future occurrences, all occurrences, or just this instance. Applying changes to future occurrences or all occurrences may cause the UID or occurrence date of the event to change.
If this method returns NO, an NSError object describing the error. See InstantMessage Constants Reference for description of error codes.
If successful, returns YES; otherwise, returns NO and sets the error argument to an NSError object describing the error.
Use this method to save new event objects and modifications to existing event objects. Changes to event objects are not persistent until this method is invoked. The calendar property needs to be set before attempting to save an event.
CalCalendarStore.hSaves the specified task to the calendar store.
- (BOOL)saveTask:(CalTask *)task error:(NSError **)error
The task to save.
If this method returns NO, an NSError object describing the error. See Calendar Store Constants Reference for description of error codes.
If successful, returns YES; otherwise, returns NO and sets the error argument to an NSError object describing the error.
Use this method to save new task objects and modifications to existing task objects. Changes to task objects are not persistent until this method is invoked. The calendar property needs to be set before attempting to save a task.
CalCalendarStore.hReturns an array of CalTask objects that match the specified predicate.
- (NSArray *)tasksWithPredicate:(NSPredicate *)predicate
Describes the set of records that should be returned.
An array of CalTask objects. Returns nil if the predicate is invalid.
The predicate passed to this method must be valid. You create valid predicates using the predicate methods described in this class. The predicate must specify an array of calendars to query and can filter the tasks by due date and completion date. All subpredicates must be joined with an AND, and all dates and calendars must be arrays and added via variable substitution. Calendars are specified using the IN operator.
Date ranges may be specified using the BETWEEN, greater than, less than, greater than or equal, and less than or equal operators. Use a subpredicate that tests equality to null to return tasks that do not have a completion or due date.
For example, the following code fragment creates a predicate that returns all incomplete tasks due before March 1, 2006.
dueDatePredicate = [NSPredicate predicateWithFormat:@"dueDate < %@" |
argumentArray:[NSArray arrayWithObject:[NSDate dateWithNaturalLanguageString:@"12am March 1, 2006"]]]; |
completionDatePredicate = [NSPredicate predicateWithFormat:@"completedDate = <null>"]; |
calendarPredicate = [NSPredicate predicateWithFormat:@"calendar IN %@))" |
argumentArray:[NSArray arrayWithObject:[CalCalendarStore calendars]]]; |
finalPredicate = [NSPredicate andPredicateWithSubpredicates: |
[NSArray arrayWithObjects:dueDatePredicate, completionDatePredicate, calendarPredicate, nil]]; |
NSArray *tasks = [[CalCalendarStore defaultCalendarStore] tasksWithPredicate:finalPredicate]; |
If you observe the CalTasksChangedNotification notification, you can retain the predicate and send it evaluateWithObject:, passing the changed task to determine whether the notification affects the task objects you previously fetched.
CalCalendarStore.hReturns a task that matches the specified unique identifier.
- (CalTask *)taskWithUID:(NSString *)uid
A unique identifier for a task.
A task that matches the specified unique identifier.
CalCalendarStore.hThe range of events to apply changes to for a recurring event.
typedef enum {
CalSpanThisEvent,
CalSpanFutureEvents,
CalSpanAllEvents
} CalSpan;
CalSpanThisEventApply changes to just this instance of a recurring event.
Available in Mac OS X v10.5 and later.
Declared in CalCalendarStore.h.
CalSpanFutureEventsApply changes to all future events of a recurring event.
Available in Mac OS X v10.5 and later.
Declared in CalCalendarStore.h.
CalSpanAllEventsApply changes to all events of a recurring event.
Available in Mac OS X v10.5 and later.
Declared in CalCalendarStore.h.
Use these constants when invoking the saveEvent:span:error: and removeEvent:span:error: methods.
CalendarStore/CalCalendarStore.hSpecifies the records that changed.
extern NSString * const CalInsertedRecordsKey; extern NSString * const CalUpdatedRecordsKey; extern NSString * const CalDeletedRecordsKey;
CalInsertedRecordsKeyAn array of record UIDs that were inserted.
Available in Mac OS X v10.5 and later.
Declared in CalCalendarStore.h.
CalUpdatedRecordsKeyAn array of record UIDs whose properties were changed.
Available in Mac OS X v10.5 and later.
Declared in CalCalendarStore.h.
CalDeletedRecordsKeyAn array of record UIDs that were deleted.
Available in Mac OS X v10.5 and later.
Declared in CalCalendarStore.h.
These keys are used in the user information dictionary of CalCalendarStore change notifications.
CalendarStore/CalNotificationCenter.hKeys in the user information dictionary of a notification sent by an instance of this class.
extern NSString * const CalSenderProcessIDKey; extern NSString * const CalUserUIDKey;
CalSenderProcessIDKeyThe key for a process ID that identifies the application that changed either a calendar, event, or task object.
This key is used in the user information dictionary for these notifications:
CalCalendarsChangedNotification
CalEventsChangedNotification
CalTasksChangedNotification
CalCalendarsChangedExternallyNotification
CalEventsChangedExternallyNotification
CalTasksChangedExternallyNotification
Available in Mac OS X v10.5 and later.
Declared in CalCalendarStore.h.
CalUserUIDKeyThe key for a user UID that identifies the user that changed either a calendar, event, or task object.
This key is used in the user information dictionary for these notifications:
CalCalendarsChangedNotification
CalEventsChangedNotification
CalTasksChangedNotification
CalCalendarsChangedExternallyNotification
CalEventsChangedExternallyNotification
CalTasksChangedExternallyNotification
Available in Mac OS X v10.5 and later.
Declared in CalCalendarStore.h.
CalCalendarStore.hPosted by the shared NSNotificationCenter object when this application process changes calendar objects. The notification object is the shared CalCalendarStore object. The user information dictionary contains the CalSenderProcessIDKey and CalUserUIDKey keys which identify the process and user that made the change to the calendars. In addition, the user information dictionary may contain one or more of the following keys which indicate the type of change: CalInsertedRecordsKey, CalUpdatedRecordsKey, and CalDeletedRecordsKey. The value for these keys is an array containing the UIDs for the events that were inserted, updated, or deleted. Use the calendarWithUID: method to get the changed calendar object.
CalCalendarStore.hPosted by the shared NSNotificationCenter object when this application process changes event objects. The notification object is the shared CalCalendarStore object. The user information dictionary contains the CalSenderProcessIDKey and CalUserUIDKey keys which identify the process and user that made the change to the calendars. In addition, the user information dictionary may contain one or more of the following keys which indicate the type of change: CalInsertedRecordsKey, CalUpdatedRecordsKey, and CalDeletedRecordsKey. The value for these keys is an array containing the UIDs for the events that were inserted, updated, or deleted. Use the eventsWithPredicate: or the eventWithUID:occurrence: method to get the changed event object. If the event is recurring, read Fetching Objects in Calendar Store Programming Guide for how to fetch recurring events within a date range.
CalCalendarStore.hPosted by the shared NSNotificationCenter object when this application process changes task objects. The notification object is the shared CalCalendarStore object. The user information dictionary contains the CalSenderProcessIDKey and CalUserUIDKey keys which identify the process and user that made the change to the calendars. In addition, the user information dictionary may contain one or more of the following keys which indicate the type of change: CalInsertedRecordsKey, CalUpdatedRecordsKey, and CalDeletedRecordsKey. The value for these keys is an array containing the UIDS for the tasks that were inserted, updated, or deleted. Use the tasksWithPredicate: or the taskWithUID: method to get the changed task object.
CalCalendarStore.hPosted by the shared NSNotificationCenter object when another application process changes calendar objects. The notification object is the shared CalCalendarStore object. The user information dictionary contains the CalSenderProcessIDKey and CalUserUIDKey keys which identify the process and user that made the change to the calendars. In addition, the user information dictionary may contain one or more of the following keys which indicate the type of change: CalInsertedRecordsKey, CalUpdatedRecordsKey, and CalDeletedRecordsKey. The value for these keys is an array containing the UIDs for the calendars that were inserted, updated, or deleted. Use the calendarWithUID: method to get the changed calendar object.
CalCalendarStore.hPosted by the shared NSNotificationCenter object when another application process changes event objects. This notification is identical to the CalEventsChangedNotification notification except that it is triggered by an external process.
CalCalendarStore.hPosted by the shared NSNotificationCenter object when another application process changes task objects. This notification is identical to the CalTasksChangedNotification notification except that it is triggered by an external process.
CalCalendarStore.hLast updated: 2009-06-23
Mac OS X Reference Library Data Management: Calendar Data CalCalendarStore Class Reference