sec/SOSCircle/SecureObjectSync/SOSEngine.h

   1 /*
   2  * Created by Michael Brouwer on 7/17/12.
   3  * Copyright 2012 Apple Inc. All Rights Reserved.
   4  */
   5
   6 /*!
   7  @header SOSEngine.h
   8  The functions provided in SOSEngine.h provide an interface to a
   9  secure object syncing engine
  10  */
  11
  12 #ifndef _SEC_SOSENGINE_H_
  13 #define _SEC_SOSENGINE_H_
  14
  15 #include <SecureObjectSync/SOSTransport.h>
  16 #include <CoreFoundation/CFRuntime.h>
  17
  18 __BEGIN_DECLS
  19
  20 enum {
  21     kSOSEngineInvalidMessageError = 1,
  22     kSOSEngineInternalError = 2,
  23 };
  24
  25 typedef struct __OpaqueSOSEngine *SOSEngineRef;
  26 typedef struct __OpaqueSOSPeer *SOSPeerRef;
  27
  28 /* SOSDataSource protocol (non opaque). */
  29 typedef struct SOSDataSource *SOSDataSourceRef;
  30
  31 typedef struct __OpaqueSOSObject *SOSObjectRef;
  32
  33 /* Implement this if you want to create a new type of sync client.
  34  Currently we support keychains, but the engine should scale to
  35  entire filesystems. */
  36 enum SOSMergeResult {
  37     kSOSMergeFailure = 0,   // CFErrorRef returned, no error returned in any other case
  38     kSOSMergeLocalObject,   // We choose the current object in the dataSource the manifest is still valid.
  39     kSOSMergePeersObject,   // We chose the peers object over our own, manifest is now dirty.
  40     kSOSMergeCreatedObject, // *createdObject is returned and should be released
  41 };
  42 typedef CFIndex SOSMergeResult;
  43
  44 struct SOSDataSource {
  45     bool (*get_manifest_digest)(SOSDataSourceRef ds, uint8_t *out_digest, CFErrorRef *error);
  46     SOSManifestRef (*copy_manifest)(SOSDataSourceRef ds, CFErrorRef *error);
  47     bool (*foreach_object)(SOSDataSourceRef ds, SOSManifestRef manifest, CFErrorRef *error, bool (^handle_object)(SOSObjectRef object, CFErrorRef *error));
  48     SOSMergeResult (*add)(SOSDataSourceRef ds, SOSObjectRef object, CFErrorRef *error);
  49     void (*release)(SOSDataSourceRef ds);
  50
  51     SOSObjectRef (*createWithPropertyList)(SOSDataSourceRef ds, CFDictionaryRef plist, CFErrorRef *error);
  52     CFDataRef (*copyDigest)(SOSObjectRef object, CFErrorRef *error);
  53     CFDataRef (*copyPrimaryKey)(SOSObjectRef object, CFErrorRef *error);
  54     CFDictionaryRef (*copyPropertyList)(SOSObjectRef object, CFErrorRef *error);
  55     SOSObjectRef (*copyMergedObject)(SOSObjectRef object1, SOSObjectRef object2, CFErrorRef *error);
  56     CFDictionaryRef (*backupObject)(SOSObjectRef object, uint64_t handle, CFErrorRef *error);
  57     bool (*restoreObject)(SOSDataSourceRef ds, uint64_t handle, CFDictionaryRef item, CFErrorRef *error);
  58 };
  59
  60 // Create a new engine instance for a given datasource.
  61 SOSEngineRef SOSEngineCreate(SOSDataSourceRef dataSource, CFErrorRef *error);
  62
  63 // Dispose of an engine when it's no longer needed.
  64 void SOSEngineDispose(SOSEngineRef engine);
  65
  66 // Handle incoming message from a remote peer.
  67 bool SOSEngineHandleMessage(SOSEngineRef engine, SOSPeerRef peer,
  68                             CFDataRef message, CFErrorRef *error);
  69
  70 // Initiate a sync with the providied peer by sending it a message.
  71 bool SOSEngineSyncWithPeer(SOSEngineRef engine, SOSPeerRef peer, bool force,
  72                            CFErrorRef *error);
  73
  74 /* Internal functions exposed for testability. */
  75 CFDataRef SOSEngineCreateManifestDigestMessage(SOSEngineRef engine, SOSPeerRef peer, CFErrorRef *error);
  76 CFDataRef SOSEngineCreateManifestMessage(SOSEngineRef engine, SOSPeerRef peer, CFErrorRef *error);
  77 CFDataRef SOSEngineCreateManifestAndObjectsMessage(SOSEngineRef engine, SOSPeerRef peer, CFErrorRef *error);
  78
  79 CFStringRef SOSMessageCopyDescription(CFDataRef message);
  80
  81 __END_DECLS
  82
  83 #endif /* !_SEC_SOSENGINE_H_ */