chrome/common/extensions/api/sync_file_system.idl

   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=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 };