1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 // Use the <code>chrome.syncFileSystem</code> API to save and synchronize data
6 // on Google Drive. This API is NOT for accessing arbitrary user docs stored in
7 // Google Drive. It provides app-specific syncable storage for offline and
8 // caching usage so that the same data can be available across different
9 // clients. Read <a href="app_storage.html">Manage Data</a> for more on using
11 namespace syncFileSystem {
13 added, updated, deleted
17 // The sync service is being initialized (e.g. restoring data from the
18 // database, checking connectivity and authenticating to the service etc).
21 // The sync service is up and running.
24 // The sync service is not synchronizing files because the remote service
25 // needs to be authenticated by the user to proceed.
26 authentication_required,
28 // The sync service is not synchronizing files because the remote service
29 // is (temporarily) unavailable due to some recoverable errors, e.g.
30 // network is offline, the remote service is down or not
31 // reachable etc. More details should be given by |description| parameter
32 // in OnServiceInfoUpdated (which could contain service-specific details).
33 temporary_unavailable,
35 // The sync service is disabled and the content will never sync.
36 // (E.g. this could happen when the user has no account on
37 // the remote service or the sync service has had an unrecoverable
43 // Not conflicting and has no pending local changes.
46 // Has one or more pending local changes that haven't been synchronized.
49 // File conflicts with remote version and must be resolved manually.
54 local_to_remote, remote_to_local
57 enum ConflictResolutionPolicy {
58 last_write_win, manual
62 // <code>fileEntry</code> for the target file whose status has changed.
63 // Contains name and path information of synchronized file.
65 // <code>fileEntry</code> information will still be available
66 // but file will no longer exist.
67 [instanceOf=Entry] object fileEntry;
69 // Resulting file status after $ref:onFileStatusChanged event.
70 // The status value can be <code>'synced'</code>,
71 // <code>'pending'</code> or <code>'conflicting'</code>.
74 // Sync action taken to fire $ref:onFileStatusChanged event.
75 // The action value can be
76 // <code>'added'</code>, <code>'updated'</code> or <code>'deleted'</code>.
77 // Only applies if status is <code>'synced'</code>.
80 // Sync direction for the $ref:onFileStatusChanged event.
81 // Sync direction value can be
82 // <code>'local_to_remote'</code> or <code>'remote_to_local'</code>.
83 // Only applies if status is <code>'synced'</code>.
84 SyncDirection? direction;
87 dictionary FileStatusInfo {
88 // One of the Entry's originally given to getFileStatuses.
89 [instanceOf=Entry] object fileEntry;
91 // The status value can be <code>'synced'</code>,
92 // <code>'pending'</code> or <code>'conflicting'</code>.
95 // Optional error that is only returned if there was a problem retrieving
96 // the FileStatus for the given file.
100 dictionary StorageInfo {
105 dictionary ServiceInfo {
107 DOMString description;
110 // A callback type for requestFileSystem.
111 callback GetFileSystemCallback =
112 void ([instanceOf=DOMFileSystem] object fileSystem);
114 // A callback type for getUsageAndQuota.
115 callback QuotaAndUsageCallback = void (StorageInfo info);
117 // Returns true if operation was successful.
118 callback DeleteFileSystemCallback = void (boolean result);
120 // A callback type for getFileStatus.
121 callback GetFileStatusCallback = void (FileStatus status);
123 // A callback type for getFileStatuses.
124 callback GetFileStatusesCallback = void (FileStatusInfo[] status);
126 // A callback type for getServiceStatus.
127 callback GetServiceStatusCallback = void (ServiceStatus status);
129 // A callback type for getConflictResolutionPolicy.
130 callback GetConflictResolutionPolicyCallback =
131 void (ConflictResolutionPolicy policy);
133 // A generic result callback to indicate success or failure.
134 callback ResultCallback = void ();
136 interface Functions {
137 // Returns a syncable filesystem backed by Google Drive.
138 // The returned <code>DOMFileSystem</code> instance can be operated on
139 // in the same way as the Temporary and Persistant file systems (see
140 // <a href="http://www.w3.org/TR/file-system-api/">http://www.w3.org/TR/file-system-api/</a>).
141 // Calling this multiple times from
142 // the same app will return the same handle to the same file system.
143 static void requestFileSystem(GetFileSystemCallback callback);
145 // Sets the default conflict resolution policy
146 // for the <code>'syncable'</code> file storage for the app.
147 // By default it is set to <code>'last_write_win'</code>.
148 // When conflict resolution policy is set to <code>'last_write_win'</code>
149 // conflicts for existing files are automatically resolved next time
150 // the file is updated.
151 // |callback| can be optionally given to know if the request has
153 static void setConflictResolutionPolicy(
154 ConflictResolutionPolicy policy,
155 optional ResultCallback callback);
157 // Gets the current conflict resolution policy.
158 static void getConflictResolutionPolicy(
159 GetConflictResolutionPolicyCallback callback);
161 // Returns the current usage and quota in bytes
162 // for the <code>'syncable'</code> file storage for the app.
163 static void getUsageAndQuota([instanceOf=DOMFileSystem] object fileSystem,
164 QuotaAndUsageCallback callback);
166 // Returns the $ref:FileStatus for the given <code>fileEntry</code>.
167 // The status value can be <code>'synced'</code>,
168 // <code>'pending'</code> or <code>'conflicting'</code>.
169 // Note that <code>'conflicting'</code> state only happens when
170 // the service's conflict resolution policy is set to <code>'manual'</code>.
171 static void getFileStatus([instanceOf=Entry] object fileEntry,
172 GetFileStatusCallback callback);
174 // Returns each $ref:FileStatus for the given <code>fileEntry</code> array.
175 // Typically called with the result from dirReader.readEntries().
176 static void getFileStatuses(object[] fileEntries,
177 GetFileStatusesCallback callback);
179 // Returns the current sync backend status.
180 static void getServiceStatus(GetServiceStatusCallback callback);
184 // Fired when an error or other status change has happened in the
185 // sync backend (for example, when the sync is temporarily disabled due to
186 // network or authentication error).
187 static void onServiceStatusChanged(ServiceInfo detail);
189 // Fired when a file has been updated by the background sync service.
190 static void onFileStatusChanged(FileInfo detail);