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