| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/SyncServices.framework |
| Availability | Available in Mac OS X v10.4 and later. |
| Companion guide | |
| Declared in | ISyncRecordSnapshot.h |
| Related sample code |
The ISyncRecordSnapshot class provides a client with access to an immutable copy of the records in the truth database. The truth database is an aggregate of all records of all supported entities and properties of all registered clients. ISyncRecordSnapshot provides a variety of methods for querying the records in the snapshot.
There is no mutable variant of ISyncRecordSnapshot for changing records—only the sync engine updates the truth by clients pushing records during a sync session. If the sync engine modifies records after a snapshot is created, the snapshot does not contain those changes. You must create a new snapshot to get the latest records.
Use the snapshotOfRecordsInTruthWithEntityNames:usingIdentifiersForClient: ISyncManager method to create a snapshot of the truth database. Use the recordsWithIdentifiers: method to get a dictionary representation of all the specified records where the keys in the returned dictionary are the record identifiers. For example, a configuration tool might create a snapshot to query records in the truth database and provide various filtering.
However, if you are syncing and want a snapshot that is consistent with the sync session (for example, another client is pushing changes that you have not pulled yet), then you need to use the snapshotOfRecordsInTruth ISyncSession method to get a snapshot.
Other methods in this class are used to query the snapshot. Use the recordsWithIdentifiers: method to get specific records (it is more efficient to request records in batches, not all at once). Use the recordsWithMatchingAttributes: method to get records that match specific attribute values, and the sourceIdentifiersForRelationshipName:withTargetIdentifier: or targetIdentifiersForRelationshipName:withSourceIdentifier: method to get records that match relationship values. Because all of these query methods can be computationally intensive, use them with care.
You can also use an ISyncRecordReference object to maintain a persistent reference to a record. Use the recordReferenceForRecordWithIdentifier: method to get an ISyncRecordReference object.
– targetIdentifiersForRelationshipName:withSourceIdentifier:
– sourceIdentifiersForRelationshipName:withTargetIdentifier:
Returns the record identifier that corresponds to the given record reference object.
- (NSString *)recordIdentifierForReference:(ISyncRecordReference *)reference isModified:(BOOL *)modifyFlag
Specifies the record reference object corresponding to the returned record identifier. This method may change internal properties of this object. Use the modifyFlag argument to determine if this object changes.
Optional flag used to determine if this method changes any properties of reference. For example, if internal properties change since reference was created or since this method was last invoked, this method updates reference and sets modifyFlag accordingly. If modifyFlag is non-NULL and reference changes then modifyFlag is set to YES . Otherwise, if modifyFlag is non-NULL then it is set to NO.
Returns the record identifier corresponding to the specified ISyncRecordReference reference argument. The returned identifier is in the scope of the receiver. For example, it the receiver is a global snapshot, then the returned record identifier is a global identifier. Returns nil if no record exists that corresponds to reference.
Typically, a client archives record reference objects and unarchives them before syncing. The client uses this method to get the local record identifiers for the archived record references. If the original record is not present in the truth database then this method returns the record identifier for the record that matches the identity properties. If more than one record matches the identity properties, then this method returns the record identifier of the first record found.
If the record reference was unarchived before invoking this method, it may be stale and need to be modified internally. In this case, use the modifyFlag argument in this method and if the record reference changes, save it again. This insures that the most current record reference objects are used in subsequent syncs.
ISyncRecordSnapshot.hReturns a record reference that corresponds to the given record identifier.
- (ISyncRecordReference *)recordReferenceForRecordWithIdentifier:(NSString *)identifier
A record identifier that is in the scope of the receiver. For example, if the receiver was created using the snapshotOfRecordsInTruth ISyncSession method, then identifier must be a global identifier. If the receiver was created using the snapshotOfRecordsInTruthWithEntityNames:usingIdentifiersForClient: ISyncManager method, then identifier must be in the scope of the client.
Returns the record reference associated with identifier. Returns nil if no record can be found for identifier.
ISyncRecordSnapshot.hReturns a dictionary containing the records.
- (NSDictionary *)recordsWithIdentifiers:(NSArray *)recordIdentifiers
Returns a dictionary containing the records specified by recordIdentifiers, an array of record identifiers. The dictionary keys are the record identifiers, and the values are the record dictionaries. The returned dictionary does not contain key-value pairs for deleted records or invalid record identifiers.
ISyncRecordSnapshot.hReturns a dictionary containing all the records that match a query.
- (NSDictionary *)recordsWithMatchingAttributes:(NSDictionary *)attributes
The attributes argument specifies the query and supports key-value pairs for record properties. For example, a key might be firstName and a value might be "Jane" in the attributes dictionary. Optionally, you can use the ISyncRecordEntityNameKey key to limit the search to a particular entity. The keys in the returned dictionary are the record identifiers, and the values are the record dictionaries that match the query.
ISyncRecordSnapshot.hReturns an array of the record identifiers belonging to the source objects of a relationship.
- (NSArray *)sourceIdentifiersForRelationshipName:(NSString *)relationshipName withTargetIdentifier:(NSString *)targetIdentifier
Returns an array of the record identifiers of the source objects belonging to the relationship, specified by relationshipName, whose target object identifier is targetIdentifier. You can use this method to get the inverse of a to-many or to-one relationship when that relationship is not defined in the schema.
ISyncRecordSnapshot.hReturns an array of record identifiers belonging to the target objects of a relationship.
- (NSArray *)targetIdentifiersForRelationshipName:(NSString *)relationshipName withSourceIdentifier:(NSString *)sourceIdentifier
Returns an array of the record identifiers of the target objects belonging to the relationship, specified by relationshipName, whose source object identifier is sourceIdentifier. If relationshipName is a to-one relationship, then the returned array contains no more than one object, otherwise it may contain multiple objects. If the relationship is ordered, the order of the record identifiers matches the order of the records. A record identifier may appear in the array multiple times. Use this method if you want to resolve the destination objects of a relationship.
ISyncRecordSnapshot.hLast updated: 2006-07-07
Mac OS X Reference Library Data Management: Syncing ISyncRecordSnapshot Class Reference