summaryrefslogtreecommitdiffstats
path: root/services/cloudsync/docs
diff options
context:
space:
mode:
Diffstat (limited to 'services/cloudsync/docs')
-rw-r--r--services/cloudsync/docs/api.md234
-rw-r--r--services/cloudsync/docs/architecture.rst54
-rw-r--r--services/cloudsync/docs/dataformat.rst77
-rw-r--r--services/cloudsync/docs/example.rst132
-rw-r--r--services/cloudsync/docs/index.rst19
5 files changed, 516 insertions, 0 deletions
diff --git a/services/cloudsync/docs/api.md b/services/cloudsync/docs/api.md
new file mode 100644
index 000000000..bca3193a4
--- /dev/null
+++ b/services/cloudsync/docs/api.md
@@ -0,0 +1,234 @@
+### Importing the JS module
+
+````
+Cu.import("resource://gre/modules/CloudSync.jsm");
+
+let cloudSync = CloudSync();
+console.log(cloudSync); // Module is imported
+````
+
+### cloudSync.local
+
+#### id
+
+Local device ID. Is unique.
+
+````
+let localId = cloudSync.local.id;
+````
+
+#### name
+
+Local device name.
+
+````
+let localName = cloudSync.local.name;
+````
+
+### CloudSync.tabs
+
+#### addEventListener(type, callback)
+
+Add an event handler for Tabs events. Valid type is `change`. The callback receives no arguments.
+
+````
+function handleTabChange() {
+ // Tabs have changed.
+}
+
+cloudSync.tabs.addEventListener("change", handleTabChange);
+````
+
+Change events are emitted when a tab is opened or closed, when a tab is selected, or when the page changes for an open tab.
+
+#### removeEventListener(type, callback)
+
+Remove an event handler. Pass the type and function that were passed to addEventListener.
+
+````
+cloudSync.tabs.removeEventListener("change", handleTabChange);
+````
+
+#### mergeRemoteTabs(client, tabs)
+
+Merge remote tabs from upstream by updating existing items, adding new tabs, and deleting existing tabs. Accepts a client and a list of tabs. Returns a promise.
+
+````
+let remoteClient = {
+ id: "fawe78",
+ name: "My Firefox client",
+};
+
+let remoteTabs = [
+ {title: "Google",
+ url: "https://www.google.com",
+ icon: "https://www.google.com/favicon.ico",
+ lastUsed: 1400799296192},
+ {title: "Reddit",
+ url: "http://www.reddit.com",
+ icon: "http://www.reddit.com/favicon.ico",
+ lastUsed: 1400799296192
+ deleted: true},
+];
+
+cloudSync.tabs.mergeRemoteTabs(client, tabs).then(
+ function() {
+ console.log("merge complete");
+ }
+);
+````
+
+#### getLocalTabs()
+
+Returns a promise. Passes a list of local tabs when complete.
+
+````
+cloudSync.tabs.getLocalTabs().then(
+ function(tabs) {
+ console.log(JSON.stringify(tabs));
+ }
+);
+````
+
+#### clearRemoteTabs(client)
+
+Clears all tabs for a remote client.
+
+````
+let remoteClient = {
+ id: "fawe78",
+ name: "My Firefox client",
+};
+
+cloudSync.tabs.clearRemoteTabs(client);
+````
+
+### cloudSync.bookmarks
+
+#### getRootFolder(name)
+
+Gets the named root folder, creating it if it doesn't exist. The root folder object has a number of methods (see the next section for details).
+
+````
+cloudSync.bookmarks.getRootFolder("My Bookmarks").then(
+ function(rootFolder) {
+ console.log(rootFolder);
+ }
+);
+````
+
+### cloudSync.bookmarks.RootFolder
+
+This is a root folder object for bookmarks, created by `cloudSync.bookmarks.getRootFolder`.
+
+#### BOOKMARK
+
+Bookmark type. Used in results objects.
+
+````
+let bookmarkType = rootFolder.BOOKMARK;
+````
+
+#### FOLDER
+
+Folder type. Used in results objects.
+
+````
+let folderType = rootFolder.FOLDER;
+````
+
+#### SEPARATOR
+
+Separator type. Used in results objects.
+
+````
+let separatorType = rootFolder.SEPARATOR;
+````
+
+#### addEventListener(type, callback)
+
+Add an event handler for Tabs events. Valid types are `add, remove, change, move`. The callback receives an ID corresponding to the target item.
+
+````
+function handleBoookmarkEvent(id) {
+ console.log("event for id:", id);
+}
+
+rootFolder.addEventListener("add", handleBookmarkEvent);
+rootFolder.addEventListener("remove", handleBookmarkEvent);
+rootFolder.addEventListener("change", handleBookmarkEvent);
+rootFolder.addEventListener("move", handleBookmarkEvent);
+````
+
+#### removeEventListener(type, callback)
+
+Remove an event handler. Pass the type and function that were passed to addEventListener.
+
+````
+rootFolder.removeEventListener("add", handleBookmarkEvent);
+rootFolder.removeEventListener("remove", handleBookmarkEvent);
+rootFolder.removeEventListener("change", handleBookmarkEvent);
+rootFolder.removeEventListener("move", handleBookmarkEvent);
+````
+
+#### getLocalItems()
+
+Callback receives a list of items on the local client. Results have the following form:
+
+````
+{
+ id: "faw8e7f", // item guid
+ parent: "f7sydf87y", // parent folder guid
+ dateAdded: 1400799296192, // timestamp
+ lastModified: 1400799296192, // timestamp
+ uri: "https://www.google.ca", // null for FOLDER and SEPARATOR
+ title: "Google"
+ type: rootFolder.BOOKMARK, // should be one of rootFolder.{BOOKMARK, FOLDER, SEPARATOR},
+ index: 0 // must be unique among folder items
+}
+````
+
+````
+rootFolder.getLocalItems().then(
+ function(items) {
+ console.log(JSON.stringify(items));
+ }
+);
+````
+
+#### getLocalItemsById([...])
+
+Callback receives a list of items, specified by ID, on the local client. Results have the same form as `getLocalItems()` above.
+
+````
+rootFolder.getLocalItemsById(["213r23f", "f22fy3f3"]).then(
+ function(items) {
+ console.log(JSON.stringify(items));
+ }
+);
+````
+
+#### mergeRemoteItems([...])
+
+Merge remote items from upstream by updating existing items, adding new items, and deleting existing items. Folders are created first so that subsequent operations will succeed. Items have the same form as `getLocalItems()` above. Items that do not have an ID will have an ID generated for them. The results structure will contain this generated ID.
+
+````
+rootFolder.mergeRemoteItems([
+ {
+ id: 'f2398f23',
+ type: rootFolder.FOLDER,
+ title: 'Folder 1',
+ parent: '9f8237f928'
+ },
+ {
+ id: '9f8237f928',
+ type: rootFolder.FOLDER,
+ title: 'Folder 0',
+ }
+ ]).then(
+ function(items) {
+ console.log(items); // any generated IDs are filled in now
+ console.log("merge completed");
+ }
+);
+```` \ No newline at end of file
diff --git a/services/cloudsync/docs/architecture.rst b/services/cloudsync/docs/architecture.rst
new file mode 100644
index 000000000..a7a8aa7ba
--- /dev/null
+++ b/services/cloudsync/docs/architecture.rst
@@ -0,0 +1,54 @@
+.. _cloudsync_architecture:
+
+============
+Architecture
+============
+
+CloudSync offers functionality similar to Firefox Sync for data sources. Third-party addons
+(sync adapters) consume local data, send and receive updates from the cloud, and merge remote data.
+
+
+Files
+=====
+
+CloudSync.jsm
+ Main module; Includes other modules and exposes them.
+
+CloudSyncAdapters.jsm
+ Provides an API for addons to register themselves. Will be used to
+ list available adapters and to notify adapters when sync operations
+ are requested manually by the user.
+
+CloudSyncBookmarks.jsm
+ Provides operations for interacting with bookmarks.
+
+CloudSyncBookmarksFolderCache.jsm
+ Implements a cache used to store folder hierarchy for filtering bookmark events.
+
+CloudSyncEventSource.jsm
+ Implements an event emitter. Used to provide addEventListener and removeEventListener
+ for tabs and bookmarks.
+
+CloudSyncLocal.jsm
+ Provides information about the local device, such as name and a unique id.
+
+CloudSyncPlacesWrapper.jsm
+ Wraps parts of the Places API in promises. Some methods are implemented to be asynchronous
+ where they are not in the places API.
+
+CloudSyncTabs.jsm
+ Provides operations for fetching local tabs and for populating the about:sync-tabs page.
+
+
+Data Sources
+============
+
+CloudSync provides data for tabs and bookmarks. For tabs, local open pages can be enumerated and
+remote tabs can be merged for displaying in about:sync-tabs. For bookmarks, updates are tracked
+for a named folder (given by each adapter) and handled by callbacks registered using addEventListener,
+and remote changes can be merged into the local database.
+
+Versioning
+==========
+
+The API carries an integer version number (clouySync.version). Data records are versioned separately and individually.
diff --git a/services/cloudsync/docs/dataformat.rst b/services/cloudsync/docs/dataformat.rst
new file mode 100644
index 000000000..916581459
--- /dev/null
+++ b/services/cloudsync/docs/dataformat.rst
@@ -0,0 +1,77 @@
+.. _cloudsync_dataformat:
+
+===========
+Data Format
+===========
+
+All fields are required unless noted otherwise.
+
+Bookmarks
+=========
+
+Record
+------
+
+type:
+ record type; one of CloudSync.bookmarks.{BOOKMARK, FOLDER, SEPARATOR, QUERY, LIVEMARK}
+
+id:
+ GUID for this bookmark item
+
+parent:
+ id of parent folder
+
+index:
+ item index in parent folder; should be unique and contiguous, or they will be adjusted internally
+
+title:
+ bookmark or folder title; not meaningful for separators
+
+dateAdded:
+ timestamp (in milliseconds) for item added
+
+lastModified:
+ timestamp (in milliseconds) for last modification
+
+uri:
+ bookmark URI; not meaningful for folders or separators
+
+version:
+ data layout version
+
+Tabs
+====
+
+ClientRecord
+------------
+
+id:
+ GUID for this client
+
+name:
+ name for this client; not guaranteed to be unique
+
+tabs:
+ list of tabs open on this client; see TabRecord
+
+version:
+ data layout version
+
+
+TabRecord
+---------
+
+title:
+ name for this tab
+
+url:
+ URL for this tab; only one tab for each URL is stored
+
+icon:
+ favicon URL for this tab; optional
+
+lastUsed:
+ timetamp (in milliseconds) for last use
+
+version:
+ data layout version
diff --git a/services/cloudsync/docs/example.rst b/services/cloudsync/docs/example.rst
new file mode 100644
index 000000000..33d0f0531
--- /dev/null
+++ b/services/cloudsync/docs/example.rst
@@ -0,0 +1,132 @@
+.. _cloudsync_example:
+
+=======
+Example
+=======
+
+.. code-block:: javascript
+
+ Cu.import("resource://gre/modules/CloudSync.jsm");
+
+ let HelloWorld = {
+ onLoad: function() {
+ let cloudSync = CloudSync();
+ console.log("CLOUDSYNC -- hello world", cloudSync.local.id, cloudSync.local.name, cloudSync.adapters);
+ cloudSync.adapters.register('helloworld', {});
+ console.log("CLOUDSYNC -- " + JSON.stringify(cloudSync.adapters.getAdapterNames()));
+
+
+ cloudSync.tabs.addEventListener("change", function() {
+ console.log("tab change");
+ cloudSync.tabs.getLocalTabs().then(
+ function(records) {
+ console.log(JSON.stringify(records));
+ }
+ );
+ });
+
+ cloudSync.tabs.getLocalTabs().then(
+ function(records) {
+ console.log(JSON.stringify(records));
+ }
+ );
+
+ let remoteClient = {
+ id: "001",
+ name: "FakeClient",
+ };
+ let remoteTabs1 = [
+ {url:"https://www.google.ca",title:"Google",icon:"https://www.google.ca/favicon.ico",lastUsed:Date.now()},
+ ];
+ let remoteTabs2 = [
+ {url:"https://www.google.ca",title:"Google Canada",icon:"https://www.google.ca/favicon.ico",lastUsed:Date.now()},
+ {url:"http://www.reddit.com",title:"Reddit",icon:"http://www.reddit.com/favicon.ico",lastUsed:Date.now()},
+ ];
+ cloudSync.tabs.mergeRemoteTabs(remoteClient, remoteTabs1).then(
+ function() {
+ return cloudSync.tabs.mergeRemoteTabs(remoteClient, remoteTabs2);
+ }
+ ).then(
+ function() {
+ return cloudSync.tabs.getRemoteTabs();
+ }
+ ).then(
+ function(tabs) {
+ console.log("remote tabs:", tabs);
+ }
+ );
+
+ cloudSync.bookmarks.getRootFolder("Hello World").then(
+ function(rootFolder) {
+ console.log(rootFolder.name, rootFolder.id);
+ rootFolder.addEventListener("add", function(guid) {
+ console.log("CLOUDSYNC -- bookmark item added: " + guid);
+ rootFolder.getLocalItemsById([guid]).then(
+ function(items) {
+ console.log("CLOUDSYNC -- items: " + JSON.stringify(items));
+ }
+ );
+ });
+ rootFolder.addEventListener("remove", function(guid) {
+ console.log("CLOUDSYNC -- bookmark item removed: " + guid);
+ rootFolder.getLocalItemsById([guid]).then(
+ function(items) {
+ console.log("CLOUDSYNC -- items: " + JSON.stringify(items));
+ }
+ );
+ });
+ rootFolder.addEventListener("change", function(guid) {
+ console.log("CLOUDSYNC -- bookmark item changed: " + guid);
+ rootFolder.getLocalItemsById([guid]).then(
+ function(items) {
+ console.log("CLOUDSYNC -- items: " + JSON.stringify(items));
+ }
+ );
+ });
+ rootFolder.addEventListener("move", function(guid) {
+ console.log("CLOUDSYNC -- bookmark item moved: " + guid);
+ rootFolder.getLocalItemsById([guid]).then(
+ function(items) {
+ console.log("CLOUDSYNC -- items: " + JSON.stringify(items));
+ }
+ );
+ });
+
+ function logLocalItems() {
+ return rootFolder.getLocalItems().then(
+ function(items) {
+ console.log("CLOUDSYNC -- local items: " + JSON.stringify(items));
+ }
+ );
+ }
+
+ let items = [
+ {"id":"9fdoci2KOME6","type":rootFolder.FOLDER,"parent":rootFolder.id,"title":"My Bookmarks 1"},
+ {"id":"1fdoci2KOME5","type":rootFolder.FOLDER,"parent":rootFolder.id,"title":"My Bookmarks 2"},
+ {"id":"G_UL4ZhOyX8m","type":rootFolder.BOOKMARK,"parent":"1fdoci2KOME5","title":"reddit: the front page of the internet","uri":"http://www.reddit.com/"},
+ ];
+ function mergeSomeItems() {
+ return rootFolder.mergeRemoteItems(items);
+ }
+
+ logLocalItems().then(
+ mergeSomeItems
+ ).then(
+ function(processedItems) {
+ console.log("!!!", processedItems);
+ console.log("merge complete");
+ },
+ function(error) {
+ console.log("merge failed:", error);
+ }
+ ).then(
+ logLocalItems
+ );
+ }
+ );
+
+
+ },
+ };
+
+ window.addEventListener("load", function(e) { HelloWorld.onLoad(e); }, false);
diff --git a/services/cloudsync/docs/index.rst b/services/cloudsync/docs/index.rst
new file mode 100644
index 000000000..d7951776d
--- /dev/null
+++ b/services/cloudsync/docs/index.rst
@@ -0,0 +1,19 @@
+.. _cloudsync:
+
+=====================
+CloudSync
+=====================
+
+CloudSync is a service that provides access to tabs and bookmarks data
+for third-party sync addons. Addons can read local bookmarks and tabs.
+Bookmarks and tab data can be merged from remote devices.
+
+Addons are responsible for maintaining an upstream representation, as
+well as sending and receiving data over the network.
+
+.. toctree::
+ :maxdepth: 1
+
+ architecture
+ dataformat
+ example
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-14 07:49:48 +0000