keychain/SecureObjectSync/SOSChangeTracker.h

   1 /*
   2  * Copyright (c) 2015 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24
  25 /*!
  26  @header SOSChangeTracker.h - Manifest caching and change propagation.
  27  */
  28
  29 #ifndef _SEC_SOSCHANGETRACKER_H_
  30 #define _SEC_SOSCHANGETRACKER_H_
  31
  32 #include "keychain/SecureObjectSync/SOSDataSource.h"
  33
  34 #include "utilities/simulatecrash_assert.h"
  35
  36 __BEGIN_DECLS
  37
  38 enum {
  39     kSOSErrorNotConcreteError = 1042,
  40 };
  41
  42
  43 //
  44 // Interface to encoding and decoding changes
  45 //
  46
  47 typedef CFTypeRef SOSChangeRef;
  48
  49 static inline void SOSChangesAppendDelete(CFMutableArrayRef changes, CFTypeRef object) {
  50     const void *values[] = { object };
  51     SOSChangeRef change = CFArrayCreate(kCFAllocatorDefault, values, array_size(values), &kCFTypeArrayCallBacks);
  52     CFArrayAppendValue(changes, change);
  53     CFReleaseSafe(change);
  54 }
  55
  56 static inline void SOSChangesAppendAdd(CFMutableArrayRef changes, CFTypeRef object) {
  57     CFArrayAppendValue(changes, object);
  58 }
  59
  60 // Return the object and return true if it's an add and false if it's a delete.
  61 static inline bool SOSChangeGetObject(SOSChangeRef change, CFTypeRef *object) {
  62     if (CFGetTypeID(change) == CFArrayGetTypeID()) {
  63         assert(CFArrayGetCount(change) == 1);
  64         *object = CFArrayGetValueAtIndex(change, 0);
  65         return false;
  66     } else {
  67         *object = change;
  68         return true;
  69     }
  70 }
  71
  72 CFDataRef SOSChangeCopyDigest(SOSDataSourceRef dataSource, SOSChangeRef change, bool *isDel, SOSObjectRef *object, CFErrorRef *error);
  73
  74 CFStringRef SOSChangeCopyDescription(SOSChangeRef change);
  75
  76 CFStringRef SOSChangesCopyDescription(CFArrayRef changes);
  77
  78 //
  79 // ChangeTracker
  80 //
  81
  82 typedef struct __OpaqueSOSChangeTracker *SOSChangeTrackerRef;
  83
  84 SOSChangeTrackerRef SOSChangeTrackerCreate(CFAllocatorRef allocator, bool isConcrete, CFArrayRef children, CFErrorRef *error);
  85
  86 // Change the concreteness of the current ct (a non concrete ct does not support SOSChangeTrackerCopyManifest().
  87 void SOSChangeTrackerSetConcrete(SOSChangeTrackerRef ct, bool isConcrete);
  88
  89 typedef bool(^SOSChangeTrackerUpdatesChanges)(SOSChangeTrackerRef ct, SOSEngineRef engine, SOSTransactionRef txn, SOSDataSourceTransactionSource source, SOSDataSourceTransactionPhase phase, CFArrayRef changes, CFErrorRef *error);
  90
  91 void SOSChangeTrackerRegisterChangeUpdate(SOSChangeTrackerRef ct, SOSChangeTrackerUpdatesChanges child);
  92
  93 typedef bool(^SOSChangeTrackerUpdatesManifests)(SOSChangeTrackerRef ct, SOSEngineRef engine, SOSTransactionRef txn, SOSDataSourceTransactionSource source, SOSDataSourceTransactionPhase phase, SOSManifestRef removals, SOSManifestRef additions, CFErrorRef *error);
  94
  95 void SOSChangeTrackerRegisterManifestUpdate(SOSChangeTrackerRef ct, SOSChangeTrackerUpdatesManifests child);
  96
  97 // Remove any blocks registered though either SOSChangeTrackerRegisterChangeUpdate or SOSChangeTrackerRegisterManifestUpdate
  98 void SOSChangeTrackerResetRegistration(SOSChangeTrackerRef ct);
  99
 100 // Set the manifest for this changeTracker, causing it to be updated whenever changes pass by.
 101 // Set the manifest to NULL to stop tracking changes (but not forwarding to children).
 102 void SOSChangeTrackerSetManifest(SOSChangeTrackerRef ct, SOSManifestRef manifest);
 103
 104 // Return a snapshot of the current manifest of this ct.
 105 SOSManifestRef SOSChangeTrackerCopyManifest(SOSChangeTrackerRef ct, CFErrorRef *error);
 106
 107 // Apply changes to the (cached) manifest, and notify all children accordingly
 108 bool SOSChangeTrackerTrackChanges(SOSChangeTrackerRef ct, SOSEngineRef engine, SOSTransactionRef txn, SOSDataSourceTransactionSource source, SOSDataSourceTransactionPhase phase, CFArrayRef changes, CFErrorRef *error);
 109
 110 __END_DECLS
 111
 112 #endif /* !_SEC_SOSCHANGETRACKER_H_ */