1### Importing the JS module
2
3````
4Cu.import("resource://gre/modules/CloudSync.jsm");
5
6let cloudSync = CloudSync();
7console.log(cloudSync); // Module is imported
8````
9
10### cloudSync.local
11
12#### id
13
14Local device ID. Is unique.
15
16````
17let localId = cloudSync.local.id;
18````
19
20#### name
21
22Local device name.
23
24````
25let localName = cloudSync.local.name;
26````
27
28### CloudSync.tabs
29
30#### addEventListener(type, callback)
31
32Add an event handler for Tabs events. Valid type is `change`. The callback receives no arguments.
33
34````
35function handleTabChange() {
36  // Tabs have changed.
37}
38
39cloudSync.tabs.addEventListener("change", handleTabChange);
40````
41
42Change events are emitted when a tab is opened or closed, when a tab is selected, or when the page changes for an open tab.
43
44#### removeEventListener(type, callback)
45
46Remove an event handler. Pass the type and function that were passed to addEventListener.
47
48````
49cloudSync.tabs.removeEventListener("change", handleTabChange);
50````
51
52#### mergeRemoteTabs(client, tabs)
53
54Merge 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.
55
56````
57let remoteClient = {
58  id: "fawe78",
59  name: "My Firefox client",
60};
61
62let remoteTabs = [
63    {title: "Google",
64     url: "https://www.google.com",
65     icon: "https://www.google.com/favicon.ico",
66     lastUsed: 1400799296192},
67    {title: "Reddit",
68     url: "http://www.reddit.com",
69     icon: "http://www.reddit.com/favicon.ico",
70     lastUsed: 1400799296192
71     deleted: true},
72];
73
74cloudSync.tabs.mergeRemoteTabs(client, tabs).then(
75  function() {
76    console.log("merge complete");
77  }
78);
79````
80
81#### getLocalTabs()
82
83Returns a promise. Passes a list of local tabs when complete.
84
85````
86cloudSync.tabs.getLocalTabs().then(
87  function(tabs) {
88    console.log(JSON.stringify(tabs));
89  }
90);
91````
92
93#### clearRemoteTabs(client)
94
95Clears all tabs for a remote client.
96
97````
98let remoteClient = {
99  id: "fawe78",
100  name: "My Firefox client",
101};
102
103cloudSync.tabs.clearRemoteTabs(client);
104````
105
106### cloudSync.bookmarks
107
108#### getRootFolder(name)
109
110Gets 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).
111
112````
113cloudSync.bookmarks.getRootFolder("My Bookmarks").then(
114  function(rootFolder) {
115    console.log(rootFolder);
116  }
117);
118````
119
120### cloudSync.bookmarks.RootFolder
121
122This is a root folder object for bookmarks, created by `cloudSync.bookmarks.getRootFolder`.
123
124#### BOOKMARK
125
126Bookmark type. Used in results objects.
127
128````
129let bookmarkType = rootFolder.BOOKMARK;
130````
131
132#### FOLDER
133
134Folder type. Used in results objects.
135
136````
137let folderType = rootFolder.FOLDER;
138````
139
140#### SEPARATOR
141
142Separator type. Used in results objects.
143
144````
145let separatorType = rootFolder.SEPARATOR;
146````
147
148#### addEventListener(type, callback)
149
150Add an event handler for Tabs events. Valid types are `add, remove, change, move`. The callback receives an ID corresponding to the target item.
151
152````
153function handleBoookmarkEvent(id) {
154  console.log("event for id:", id);
155}
156
157rootFolder.addEventListener("add", handleBookmarkEvent);
158rootFolder.addEventListener("remove", handleBookmarkEvent);
159rootFolder.addEventListener("change", handleBookmarkEvent);
160rootFolder.addEventListener("move", handleBookmarkEvent);
161````
162
163#### removeEventListener(type, callback)
164
165Remove an event handler. Pass the type and function that were passed to addEventListener.
166
167````
168rootFolder.removeEventListener("add", handleBookmarkEvent);
169rootFolder.removeEventListener("remove", handleBookmarkEvent);
170rootFolder.removeEventListener("change", handleBookmarkEvent);
171rootFolder.removeEventListener("move", handleBookmarkEvent);
172````
173
174#### getLocalItems()
175
176Callback receives a list of items on the local client. Results have the following form:
177
178````
179{
180  id: "faw8e7f", // item guid
181  parent: "f7sydf87y", // parent folder guid
182  dateAdded: 1400799296192, // timestamp
183  lastModified: 1400799296192, // timestamp
184  uri: "https://www.google.ca", // null for FOLDER and SEPARATOR
185  title: "Google"
186  type: rootFolder.BOOKMARK, // should be one of rootFolder.{BOOKMARK, FOLDER, SEPARATOR},
187  index: 0 // must be unique among folder items
188}
189````
190
191````
192rootFolder.getLocalItems().then(
193  function(items) {
194    console.log(JSON.stringify(items));
195  }
196);
197````
198
199#### getLocalItemsById([...])
200
201Callback receives a list of items, specified by ID, on the local client. Results have the same form as `getLocalItems()` above.
202
203````
204rootFolder.getLocalItemsById(["213r23f", "f22fy3f3"]).then(
205  function(items) {
206    console.log(JSON.stringify(items));
207  }
208);
209````
210
211#### mergeRemoteItems([...])
212
213Merge 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.
214
215````
216rootFolder.mergeRemoteItems([
217        {
218          id: 'f2398f23',
219          type: rootFolder.FOLDER,
220          title: 'Folder 1',
221          parent: '9f8237f928'
222        },
223        {
224          id: '9f8237f928',
225          type: rootFolder.FOLDER,
226          title: 'Folder 0',
227        }
228      ]).then(
229  function(items) {
230    console.log(items); // any generated IDs are filled in now
231    console.log("merge completed");
232  }
233);
234````