| OLD | NEW |
| (Empty) |
| 1 This file defines the "sync API", an interface to the syncer | |
| 2 backend that exposes (1) the core functionality of maintaining a consistent | |
| 3 local snapshot of a hierarchical object set; (2) a means to transactionally | |
| 4 access and modify those objects; (3) a means to control client/server | |
| 5 synchronization tasks, namely: pushing local object modifications to a | |
| 6 server, pulling nonlocal object modifications from a server to this client, | |
| 7 and resolving conflicts that may arise between the two; and (4) an | |
| 8 abstraction of some external functionality that is to be provided by the | |
| 9 host environment. | |
| 10 | |
| 11 This interface is used as the entry point into the syncer backend | |
| 12 when the backend is compiled as a library and embedded in another | |
| 13 application. A goal for this interface layer is to depend on very few | |
| 14 external types, so that an application can use the sync backend | |
| 15 without introducing a dependency on specific types. A non-goal is to | |
| 16 have binary compatibility across versions or compilers; this allows the | |
| 17 interface to use C++ classes. An application wishing to use the sync API | |
| 18 should ideally compile the syncer backend and this API as part of the | |
| 19 application's own build, to avoid e.g. mismatches in calling convention, | |
| 20 structure padding, or name mangling that could arise if there were a | |
| 21 compiler mismatch. | |
| 22 | |
| 23 The schema of the objects in the sync domain is based on the model, which | |
| 24 is essentially a hierarchy of items and folders similar to a filesystem, | |
| 25 but with a few important differences. The sync API contains fields | |
| 26 such as URL to easily allow the embedding application to store web | |
| 27 browser bookmarks. Also, the sync API allows duplicate titles in a parent. | |
| 28 Consequently, it does not support looking up an object by title | |
| 29 and parent, since such a lookup is not uniquely determined. Lastly, | |
| 30 unlike a filesystem model, objects in the Sync API model have a strict | |
| 31 ordering within a parent; the position is manipulable by callers, and | |
| 32 children of a node can be enumerated in the order of their position. | |
| OLD | NEW |