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. 11 namespace 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=FileEntry] 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 FileEntry's originally given to getFileStatuses. 89 [instanceOf=FileEntry] 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 getConflictResolutionPolicy. 127 callback GetConflictResolutionPolicyCallback = 128 void (ConflictResolutionPolicy policy); 129 130 // A generic result callback to indicate success or failure. 131 callback ResultCallback = void (); 132 133 interface Functions { 134 // Returns a syncable filesystem backed by Google Drive. 135 // The returned <code>DOMFileSystem</code> instance can be operated on 136 // in the same way as the Temporary and Persistant file systems (see 137 // <a href="http://www.w3.org/TR/file-system-api/">http://www.w3.org/TR/file-system-api/</a>). 138 // Calling this multiple times from 139 // the same app will return the same handle to the same file system. 140 static void requestFileSystem(GetFileSystemCallback callback); 141 142 // Sets the default conflict resolution policy 143 // for the <code>'syncable'</code> file storage for the app. 144 // By default it is set to <code>'last_write_win'</code>. 145 // When conflict resolution policy is set to <code>'last_write_win'</code> 146 // conflicts for existing files are automatically resolved next time 147 // the file is updated. 148 // |callback| can be optionally given to know if the request has 149 // succeeded or not. 150 static void setConflictResolutionPolicy( 151 ConflictResolutionPolicy policy, 152 optional ResultCallback callback); 153 154 // Gets the current conflict resolution policy. 155 static void getConflictResolutionPolicy( 156 GetConflictResolutionPolicyCallback callback); 157 158 // Returns the current usage and quota in bytes 159 // for the <code>'syncable'</code> file storage for the app. 160 static void getUsageAndQuota([instanceOf=DOMFileSystem] object fileSystem, 161 QuotaAndUsageCallback callback); 162 163 // Returns the $ref:FileStatus for the given <code>fileEntry</code>. 164 // The status value can be <code>'synced'</code>, 165 // <code>'pending'</code> or <code>'conflicting'</code>. 166 // Note that <code>'conflicting'</code> state only happens when 167 // the service's conflict resolution policy is set to <code>'manual'</code>. 168 static void getFileStatus([instanceOf=FileEntry] object fileEntry, 169 GetFileStatusCallback callback); 170 171 // Returns each $ref:FileStatus for the given <code>fileEntry</code> array. 172 // Typically called with the result from dirReader.readEntries(). 173 static void getFileStatuses(object[] fileEntries, 174 GetFileStatusesCallback callback); 175 }; 176 177 interface Events { 178 // Fired when an error or other status change has happened in the 179 // sync backend (for example, when the sync is temporarily disabled due to 180 // network or authentication error). 181 static void onServiceStatusChanged(ServiceInfo detail); 182 183 // Fired when a file has been updated by the background sync service. 184 static void onFileStatusChanged(FileInfo detail); 185 }; 186 187 }; 188