Security/sec/SOSCircle/SecureObjectSync/SOSDataSource.h

   1 /*
   2  * Copyright (c) 2013-2014 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 SOSDataSource.h
  27  The functions provided in SOSDataSource.h provide the protocol to a
  28  secure object syncing data source.  This is something than can produce
  29  manifests and manifest digests and query objects by digest and merge
  30  objects into the data source.
  31  */
  32
  33 #ifndef _SEC_SOSDATASOURCE_H_
  34 #define _SEC_SOSDATASOURCE_H_
  35
  36 #include <SecureObjectSync/SOSManifest.h>
  37 #include <utilities/SecCFRelease.h>
  38
  39 __BEGIN_DECLS
  40
  41 /* SOSDataSource protocol (non opaque). */
  42 typedef struct SOSDataSourceFactory *SOSDataSourceFactoryRef;
  43 typedef struct SOSDataSource *SOSDataSourceRef;
  44 typedef struct __OpaqueSOSEngine *SOSEngineRef;
  45 typedef struct __OpaqueSOSObject *SOSObjectRef;
  46 typedef struct __OpaqueSOSTransaction *SOSTransactionRef;
  47
  48 //
  49 // MARK: - SOSDataSourceFactory protocol
  50 //
  51 struct SOSDataSourceFactory {
  52     CFArrayRef       (*copy_names)(SOSDataSourceFactoryRef factory);
  53     SOSDataSourceRef (*create_datasource)(SOSDataSourceFactoryRef factory, CFStringRef dataSourceName, CFErrorRef *error);
  54     void             (*release)(SOSDataSourceFactoryRef factory);
  55 };
  56
  57 //
  58 // MARK: - SOSDataSource protocol
  59 //
  60
  61 /* Implement this if you want to create a new type of sync client.
  62    Currently we support keychains, but the engine should scale to
  63    entire filesystems. */
  64 enum SOSMergeResult {
  65     kSOSMergeFailure = 0,   // CFErrorRef returned, no error returned in any other case
  66     kSOSMergeLocalObject,   // We choose the current object in the dataSource the manifest is still valid.
  67     kSOSMergePeersObject,   // We chose the peers object over our own, manifest is now dirty.
  68     kSOSMergeCreatedObject, // *createdObject is returned and should be released
  69 };
  70 typedef CFIndex SOSMergeResult;
  71
  72 //
  73 // MARK: - SOSDataSource struct
  74 //
  75
  76 //
  77 // MARK: SOSDataSourceTransactionType
  78 //
  79 enum SOSDataSourceTransactionType {
  80     kSOSDataSourceNoneTransactionType = 0,
  81     kSOSDataSourceImmediateTransactionType,
  82     kSOSDataSourceExclusiveTransactionType,
  83     kSOSDataSourceNormalTransactionType,
  84     kSOSDataSourceExclusiveRemoteTransactionType,
  85 };
  86 typedef CFOptionFlags SOSDataSourceTransactionType;
  87
  88 enum SOSDataSourceTransactionPhase {
  89     kSOSDataSourceTransactionDidRollback = 0,   // A transaction just got rolled back
  90     kSOSDataSourceTransactionWillCommit,        // A transaction is about to commit.
  91     kSOSDataSourceTransactionDidCommit,         // A transnaction sucessfully committed.
  92 };
  93 typedef CFOptionFlags SOSDataSourceTransactionPhase;
  94
  95 enum SOSDataSourceTransactionSource {
  96     kSOSDataSourceSOSTransaction,        // A remotely initated transaction.
  97     kSOSDataSourceAPITransaction,        // A user initated transaction.
  98 };
  99 typedef CFOptionFlags SOSDataSourceTransactionSource;
 100
 101 typedef void (^SOSDataSourceNotifyBlock)(SOSDataSourceRef ds, SOSTransactionRef txn, SOSDataSourceTransactionPhase phase, SOSDataSourceTransactionSource source, struct SOSDigestVector *removals, struct SOSDigestVector *additions);
 102
 103 struct SOSDataSource {
 104     // SOSEngine - every datasource has an engine that is notified of changes
 105     // to the datasource.
 106     SOSEngineRef engine;
 107
 108     // General SOSDataSource methods
 109     CFStringRef (*dsGetName)(SOSDataSourceRef ds);
 110     void (*dsSetNotifyPhaseBlock)(SOSDataSourceRef ds, SOSDataSourceNotifyBlock notifyBlock);
 111     SOSManifestRef (*dsCopyManifest)(SOSDataSourceRef ds, CFErrorRef *error);
 112     bool (*dsForEachObject)(SOSDataSourceRef ds, SOSManifestRef manifest, CFErrorRef *error, void (^handleObject)(CFDataRef key, SOSObjectRef object, bool *stop));
 113     CFDataRef (*dsCopyStateWithKey)(SOSDataSourceRef ds, CFStringRef key, CFStringRef pdmn, CFErrorRef *error);
 114     bool (*dsWith)(SOSDataSourceRef ds, CFErrorRef *error, SOSDataSourceTransactionSource source, void(^transaction)(SOSTransactionRef txn, bool *commit));
 115     bool (*dsRelease)(SOSDataSourceRef ds, CFErrorRef *error); // Destructor
 116
 117     // SOSTransaction methods, writes to a dataSource require a transaction.
 118     SOSMergeResult (*dsMergeObject)(SOSTransactionRef txn, SOSObjectRef object, SOSObjectRef *createdObject, CFErrorRef *error);
 119     bool (*dsSetStateWithKey)(SOSDataSourceRef ds, SOSTransactionRef txn, CFStringRef pdmn, CFStringRef key, CFDataRef state, CFErrorRef *error);
 120     bool (*dsRestoreObject)(SOSTransactionRef txn, uint64_t handle, CFDictionaryRef item, CFErrorRef *error);
 121
 122     // SOSObject methods
 123     CFDataRef (*objectCopyDigest)(SOSObjectRef object, CFErrorRef *error);
 124     CFDataRef (*objectCopyPrimaryKey)(SOSObjectRef object, CFErrorRef *error);
 125     SOSObjectRef (*objectCreateWithPropertyList)(CFDictionaryRef plist, CFErrorRef *error);
 126     CFDictionaryRef (*objectCopyPropertyList)(SOSObjectRef object, CFErrorRef *error);
 127     CFDictionaryRef (*objectCopyBackup)(SOSObjectRef object, uint64_t handle, CFErrorRef *error);
 128 };
 129
 130 //
 131 // MARK: - SOSDataSource protocol implementation
 132 //
 133 static inline SOSEngineRef SOSDataSourceGetSharedEngine(SOSDataSourceRef ds, CFErrorRef *error) {
 134     return ds->engine;
 135 }
 136
 137 static inline CFStringRef SOSDataSourceGetName(SOSDataSourceRef ds) {
 138     return ds->dsGetName(ds);
 139 }
 140
 141 static inline void SOSDataSourceSetNotifyPhaseBlock(SOSDataSourceRef ds, SOSDataSourceNotifyBlock notifyBlock) {
 142     ds->dsSetNotifyPhaseBlock(ds, notifyBlock);
 143 }
 144
 145 static inline SOSManifestRef SOSDataSourceCopyManifest(SOSDataSourceRef ds, CFErrorRef *error) {
 146     return ds->dsCopyManifest(ds, error);
 147 }
 148
 149 static inline bool SOSDataSourceForEachObject(SOSDataSourceRef ds, SOSManifestRef manifest, CFErrorRef *error, void (^handleObject)(CFDataRef digest, SOSObjectRef object, bool *stop)) {
 150     return ds->dsForEachObject(ds, manifest, error, handleObject);
 151 }
 152
 153 static inline bool SOSDataSourceWith(SOSDataSourceRef ds, CFErrorRef *error,
 154                                      void(^transaction)(SOSTransactionRef txn, bool *commit)) {
 155     return ds->dsWith(ds, error, kSOSDataSourceSOSTransaction, transaction);
 156 }
 157
 158 static inline bool SOSDataSourceWithAPI(SOSDataSourceRef ds, bool isAPI, CFErrorRef *error,
 159                                      void(^transaction)(SOSTransactionRef txn, bool *commit)) {
 160     return ds->dsWith(ds, error, isAPI ? kSOSDataSourceAPITransaction : kSOSDataSourceSOSTransaction, transaction);
 161 }
 162
 163 static inline CFDataRef SOSDataSourceCopyStateWithKey(SOSDataSourceRef ds, CFStringRef key, CFStringRef pdmn, CFErrorRef *error)
 164 {
 165     return ds->dsCopyStateWithKey(ds, key, pdmn, error);
 166 }
 167
 168 static inline bool SOSDataSourceRelease(SOSDataSourceRef ds, CFErrorRef *error) {
 169     return !ds || ds->dsRelease(ds, error);
 170 }
 171
 172 //
 173 // MARK: - SOSTransaction
 174 //
 175 static inline SOSMergeResult SOSDataSourceMergeObject(SOSDataSourceRef ds, SOSTransactionRef txn, SOSObjectRef peersObject, SOSObjectRef *createdObject, CFErrorRef *error) {
 176     return ds->dsMergeObject(txn, peersObject, createdObject, error);
 177 }
 178
 179 static inline bool SOSDataSourceSetStateWithKey(SOSDataSourceRef ds, SOSTransactionRef txn, CFStringRef key, CFStringRef pdmn, CFDataRef state, CFErrorRef *error)
 180 {
 181     return ds->dsSetStateWithKey(ds, txn, key, pdmn, state, error);
 182 }
 183
 184
 185 //
 186 // MARK: - SOSObject methods
 187 //
 188 static inline CFDataRef SOSObjectCopyDigest(SOSDataSourceRef ds, SOSObjectRef object, CFErrorRef *error) {
 189     return ds->objectCopyDigest(object, error);
 190 }
 191
 192 static inline CFDataRef SOSObjectCopyPrimaryKey(SOSDataSourceRef ds, SOSObjectRef object, CFErrorRef *error) {
 193     return ds->objectCopyPrimaryKey(object, error);
 194 }
 195
 196 static inline SOSObjectRef SOSObjectCreateWithPropertyList(SOSDataSourceRef ds, CFDictionaryRef plist, CFErrorRef *error) {
 197     return ds->objectCreateWithPropertyList(plist, error);
 198 }
 199
 200 static inline CFDictionaryRef SOSObjectCopyPropertyList(SOSDataSourceRef ds, SOSObjectRef object, CFErrorRef *error) {
 201     return ds->objectCopyPropertyList(object, error);
 202 }
 203
 204 static inline CFDictionaryRef SOSObjectCopyBackup(SOSDataSourceRef ds, SOSObjectRef object, uint64_t handle, CFErrorRef *error) {
 205     return ds->objectCopyBackup(object, handle, error);
 206 }
 207
 208 static inline bool SOSObjectRestoreObject(SOSDataSourceRef ds, SOSTransactionRef txn, uint64_t handle, CFDictionaryRef item, CFErrorRef *error) {
 209     return ds->dsRestoreObject(txn, handle, item, error);
 210 }
 211
 212
 213 //
 214 // MARK: SOSDataSourceFactory helpers
 215 //
 216
 217 static inline SOSEngineRef SOSDataSourceFactoryGetEngineForDataSourceName(SOSDataSourceFactoryRef factory, CFStringRef dataSourceName, CFErrorRef *error)
 218 {
 219     SOSDataSourceRef ds = factory->create_datasource(factory, dataSourceName, error);
 220     SOSEngineRef engine = ds ? SOSDataSourceGetSharedEngine(ds, error) : (SOSEngineRef) NULL;
 221     SOSDataSourceRelease(ds, NULL); // TODO: Log this error?!
 222
 223     return engine;
 224 }
 225
 226 __END_DECLS
 227
 228 #endif /* !_SEC_SOSDATASOURCE_H_ */