| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/SyncServices.framework |
| Availability | Available in Mac OS X v10.4 and later. |
| Companion guide | |
| Declared in | ISyncChange.h |
| Related sample code |
An ISyncChange object encapsulates a set of changes to a single record such as adding, deleting, and modifying a record. You use ISyncChange objects to push your changes to the sync engine. Similarly, you pull ISyncChange objects from the sync engine when applying sync engine changes.
You use the changeWithType:recordIdentifier:changes: method to create an ISyncChange object specifying the type of change (an add, delete, or modify), the identifier for the record that changed, and the new property values if any. Use the pushChange: ISyncSession method to push the change to the sync engine. You can also use the deleteRecordWithIdentifier: ISyncSession method to delete a record without needing to create an ISyncChange object.
Use the changeEnumeratorForEntityNames: ISyncSession method to pull changes from the sync engine. Use the returned object enumerator to process each ISyncChange object. Use the type method to each ISyncChange object to get the type of change (add, modify or delete), the recordIdentifier method to get the record identifier, and the changes method get descriptions of the change.
Creates an ISyncChange object.
+ (id)changeWithType:(ISyncChangeType)type recordIdentifier:(NSString *)recordIdentifier changes:(NSArray)changes
Creates and returns an ISyncChange object of the type specified by type, for the record identified by recordIdentifier, and with the changes specified by changes. The type argument should be one of the ISyncChangeTypeAdd, ISyncChangeTypeModify or ISyncChangeTypeDelete constants. The changes array encapsulates multiple property changes to a single record—it is expected to contain dictionaries that use the keys described in “ISyncChange Property Keys.” Each dictionary in the array encapsulates the change to a single property and specifies the property name, action, and new value if applicable. Use this method to create changes for pushing to the sync engine. Use the pushChange: ISyncSession method to push the change to the sync engine.
ISyncChange.hReturns an array of changes made to the record.
- (NSArray*)changes
Returns an array of the changes made to the record returned by record with the identifier returned by recordIdentifier . The changes array encapsulates multiple property changes to a single record. The returned array contains dictionaries with keys specifying the type of change to a property and its new value. See “ISyncChange Property Keys” for a description of the keys used in these dictionaries. See ISyncChangePropertyValueKey for a description of the value of relationship properties. Returns nil if the change type is ISyncChangeTypeDelete.
ISyncChange.hInitializes an ISyncChange object.
- (id)initWithChangeType:(ISyncChangeType)type recordIdentifier:(NSString *)recordIdentifier changes:(NSArray)changes
Initializes an ISyncChange object of the type specified by type, for the record identified by recordIdentifier, and with the changes specified by changes. The type argument should be one of the ISyncChangeTypeAdd, ISyncChangeTypeModify or ISyncChangeTypeDelete constants. The changes array encapsulates multiple property changes to a single record—it is expected to contain dictionaries that use the keys described in “ISyncChange Property Keys.” Each dictionary encapsulates the change to a single property and specifies the property name, action, and new value if applicable. Use this method to create changes for pushing to the sync engine. Use the pushChange: ISyncSession method to push the change to the sync engine. This is the designated initializer for this class.
ISyncChange.hReturns a dictionary representation of the record that changed.
- (NSDictionary *)record
The dictionary contains a key-value pair for each property unless the value of a property is unspecified. Only changes created by the sync engine have an associated record. Returns nil if the client created the receiver to push changes, or this is a delete change.
When pulling changes, this method returns a copy of the record as it appears in the truth database. Only those properties supported by the client are included in this record. Use the changes method to get the changes made to this record, and use the recordIdentifier method to get the record’s unique identifier.
ISyncChange.hReturns the unique record identifier for the record that changed.
- (NSString *)recordIdentifier
Returns the unique identifier for the record returned by record , or the record identifier you specified when creating the receiver. Use the changes method to get the changes that were made to this record.
ISyncChange.hReturns the type of change the receiver represents.
- (ISyncChangeType)type
Returns whether or not this change was an add, delete or modify. See “ISyncChangeType” for a description of the possible return values.
ISyncChange.hThe type of change.
typedef int ISyncChangeType; enum __ISyncChangeType { ISyncChangeTypeNone = 0, ISyncChangeTypeAdd = 1, ISyncChangeTypeModify, ISyncChangeTypeDelete };
ISyncChangeTypeAddIndicates a record was added.
Available in Mac OS X v10.4 and later.
Declared in ISyncChange.h.
ISyncChangeTypeDeleteIndicates a record was deleted.
Available in Mac OS X v10.4 and later.
Declared in ISyncChange.h.
ISyncChangeTypeModifyIndicates a record was modified.
Available in Mac OS X v10.4 and later.
Declared in ISyncChange.h.
ISyncChangeTypeNoneIndicates a record was modified.
Available in Mac OS X v10.6 and later.
Declared in ISyncChange.h.
Use one of these values to set the type argument when creating an ISyncChange object using either the changeWithType:recordIdentifier:changes: class method or the initWithChangeType:recordIdentifier:changes: instance method. The type method also returns one of these values.
The following constants are used as keys for individual property changes encapsulated in an ISyncChange object.
extern NSString * const ISyncChangePropertyActionKey; extern NSString * const ISyncChangePropertyNameKey; extern NSString * const ISyncChangePropertyValueKey; extern NSString * const ISyncChangePropertyValueIsDefaultKey;
ISyncChangePropertyActionKeySpecifies whether or not the property is being set or deleted. The value for this key should be either ISyncChangePropertySet or ISyncChangePropertyClear described below.
Available in Mac OS X v10.4 and later.
Declared in ISyncChange.h.
ISyncChangePropertyNameKeyKey for the name of the property.
Available in Mac OS X v10.4 and later.
Declared in ISyncChange.h.
ISyncChangePropertyValueKeyKey for the new value of the property. Not used if the action is ISyncChangePropertyClear. However, the absence of this key does not imply the property is being deleted. This key-value pair may be omitted if the value is unspecified. You can also set the value to nil. If the property is a relationship, then the value is an array of record identifiers belonging to the destination objects. If the relationship is to-one, this array contains a single record identifier.
Declared in ISyncChange.h.
Available in Mac OS X v10.4 and later.
ISyncChangePropertyValueIsDefaultKeyKey for the default value of the property.
Declared in ISyncChange.h.
Available in Mac OS X v10.6 and later.
When pushing changes, use these keys to set key-value pairs for dictionaries you add to the changes argument passed to either the changeWithType:recordIdentifier:changes: class method or the initWithChangeType:recordIdentifier:changes: instance method. When pulling changes, you also use these keys to get the attributes of each change. Use the object enumerator returned by the changes method to iterate through the changes array.
The following constants are possible values for the ISyncChangePropertyActionKey key used to describe the type of change to a single property.
extern NSString * const ISyncChangePropertySet; extern NSString * const ISyncChangePropertyClear;
Last updated: 2009-02-04
