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.
4
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
10// this API.
11namespace syncFileSystem {
12  enum SyncAction {
13    added, updated, deleted
14  };
15
16  enum ServiceStatus {
17    // The sync service is being initialized (e.g. restoring data from the
18    // database, checking connectivity and authenticating to the service etc).
19    initializing,
20
21    // The sync service is up and running.
22    running,
23
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,
27
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,
34
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
38    // error.)
39    disabled
40  };
41
42  enum FileStatus {
43    // Not conflicting and has no pending local changes.
44    synced,
45
46    // Has one or more pending local changes that haven't been synchronized.
47    pending,
48
49    // File conflicts with remote version and must be resolved manually.
50    conflicting
51  };
52
53  enum SyncDirection {
54    local_to_remote, remote_to_local
55  };
56
57  enum ConflictResolutionPolicy {
58    last_write_win, manual
59  };
60
61  dictionary FileInfo {
62    // <code>fileEntry</code> for the target file whose status has changed.
63    // Contains name and path information of synchronized file.
64    // On file deletion,
65    // <code>fileEntry</code> information will still be available
66    // but file will no longer exist.
67    [instanceOf=Entry] object fileEntry;
68
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>.
72    FileStatus status;
73
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>.
78    SyncAction? action;
79
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;
85  };
86
87  dictionary FileStatusInfo {
88    // One of the Entry's originally given to getFileStatuses.
89    [instanceOf=Entry] object fileEntry;
90
91    // The status value can be <code>'synced'</code>,
92    // <code>'pending'</code> or <code>'conflicting'</code>.
93    FileStatus status;
94
95    // Optional error that is only returned if there was a problem retrieving
96    // the FileStatus for the given file.
97    DOMString? error;
98  };
99
100  dictionary StorageInfo {
101    long usageBytes;
102    long quotaBytes;
103  };
104
105  dictionary ServiceInfo {
106    ServiceStatus state;
107    DOMString description;
108  };
109
110  // A callback type for requestFileSystem.
111  callback GetFileSystemCallback =
112      void ([instanceOf=DOMFileSystem] object fileSystem);
113
114  // A callback type for getUsageAndQuota.
115  callback QuotaAndUsageCallback = void (StorageInfo info);
116
117  // Returns true if operation was successful.
118  callback DeleteFileSystemCallback = void (boolean result);
119
120  // A callback type for getFileStatus.
121  callback GetFileStatusCallback = void (FileStatus status);
122
123  // A callback type for getFileStatuses.
124  callback GetFileStatusesCallback = void (FileStatusInfo[] status);
125
126  // A callback type for getServiceStatus.
127  callback GetServiceStatusCallback = void (ServiceStatus status);
128
129  // A callback type for getConflictResolutionPolicy.
130  callback GetConflictResolutionPolicyCallback =
131      void (ConflictResolutionPolicy policy);
132
133  // A generic result callback to indicate success or failure.
134  callback ResultCallback = void ();
135
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://dev.w3.org/2009/dap/file-system/file-dir-sys.html">
141    // http://dev.w3.org/2009/dap/file-system/file-dir-sys.html</a>).
142    //
143    // Calling this multiple times from
144    // the same app will return the same handle to the same file system.
145    //
146    // Note this call can fail. For example, if the user is not signed in to
147    // Chrome or if there is no network operation. To handle these errors it is
148    // important chrome.runtime.lastError is checked in the callback.
149    static void requestFileSystem(GetFileSystemCallback callback);
150
151    // Sets the default conflict resolution policy
152    // for the <code>'syncable'</code> file storage for the app.
153    // By default it is set to <code>'last_write_win'</code>.
154    // When conflict resolution policy is set to <code>'last_write_win'</code>
155    // conflicts for existing files are automatically resolved next time
156    // the file is updated.
157    // |callback| can be optionally given to know if the request has
158    // succeeded or not.
159    static void setConflictResolutionPolicy(
160        ConflictResolutionPolicy policy,
161        optional ResultCallback callback);
162
163    // Gets the current conflict resolution policy.
164    static void getConflictResolutionPolicy(
165        GetConflictResolutionPolicyCallback callback);
166
167    // Returns the current usage and quota in bytes
168    // for the <code>'syncable'</code> file storage for the app.
169    static void getUsageAndQuota([instanceOf=DOMFileSystem] object fileSystem,
170                                 QuotaAndUsageCallback callback);
171
172    // Returns the $(ref:FileStatus) for the given <code>fileEntry</code>.
173    // The status value can be <code>'synced'</code>,
174    // <code>'pending'</code> or <code>'conflicting'</code>.
175    // Note that <code>'conflicting'</code> state only happens when
176    // the service's conflict resolution policy is set to <code>'manual'</code>.
177    static void getFileStatus([instanceOf=Entry] object fileEntry,
178                              GetFileStatusCallback callback);
179
180    // Returns each $(ref:FileStatus) for the given <code>fileEntry</code> array.
181    // Typically called with the result from dirReader.readEntries().
182    static void getFileStatuses(object[] fileEntries,
183                                GetFileStatusesCallback callback);
184
185    // Returns the current sync backend status.
186    static void getServiceStatus(GetServiceStatusCallback callback);
187  };
188
189  interface Events {
190    // Fired when an error or other status change has happened in the
191    // sync backend (for example, when the sync is temporarily disabled due to
192    // network or authentication error).
193    static void onServiceStatusChanged(ServiceInfo detail);
194
195    // Fired when a file has been updated by the background sync service.
196    static void onFileStatusChanged(FileInfo detail);
197  };
198
199};
200