chrome.syncFileSystem
- Description
Use the
chrome.syncFileSystemAPI to save and synchronize data on Google Drive. This API is NOT for accessing arbitrary user docs stored in Google Drive. It provides app-specific syncable storage for offline and caching usage so that the same data can be available across different clients. Read Manage Data for more on using this API. - Permissions
syncFileSystem
Summary
- Types
- Methods
- Events
Types
ConflictResolutionPolicy
Enum
"last_write_win"
"manual"
FileInfo
Properties
- action
SyncAction optional
Sync action taken to fire
onFileStatusChangedevent. The action value can be'added','updated'or'deleted'. Only applies if status is'synced'. - direction
SyncDirection optional
Sync direction for the
onFileStatusChangedevent. Sync direction value can be'local_to_remote'or'remote_to_local'. Only applies if status is'synced'. - fileEntry
Entry
fileEntryfor the target file whose status has changed. Contains name and path information of synchronized file. On file deletion,fileEntryinformation will still be available but file will no longer exist. - status
Resulting file status after
onFileStatusChangedevent. The status value can be'synced','pending'or'conflicting'.
FileStatus
Enum
"synced"
Not conflicting and has no pending local changes.
"pending"
Has one or more pending local changes that haven't been synchronized.
"conflicting"
File conflicts with remote version and must be resolved manually.
FileStatusInfo
Properties
- error
string optional
Optional error that is only returned if there was a problem retrieving the FileStatus for the given file.
- fileEntry
Entry
One of the Entry's originally given to getFileStatuses.
- status
The status value can be
'synced','pending'or'conflicting'.
ServiceInfo
Properties
- description
string
- state
ServiceStatus
Enum
"initializing"
The sync service is being initialized (e.g. restoring data from the database, checking connectivity and authenticating to the service etc).
"running"
The sync service is up and running.
"authentication_required"
The sync service is not synchronizing files because the remote service needs to be authenticated by the user to proceed.
"temporary_unavailable"
The sync service is not synchronizing files because the remote service is (temporarily) unavailable due to some recoverable errors, e.g. network is offline, the remote service is down or not reachable etc. More details should be given by description parameter in OnServiceInfoUpdated (which could contain service-specific details).
"disabled"
The sync service is disabled and the content will never sync. (E.g. this could happen when the user has no account on the remote service or the sync service has had an unrecoverable error.)
StorageInfo
Properties
- quotaBytes
number
- usageBytes
number
SyncAction
Enum
"added"
"updated"
"deleted"
SyncDirection
Enum
"local_to_remote"
"remote_to_local"
Methods
getConflictResolutionPolicy
chrome.syncFileSystem.getConflictResolutionPolicy(
callback?:
function,
)
Gets the current conflict resolution policy.
Parameters
- callback
function optional
The
callbackparameter looks like:(policy: ConflictResolutionPolicy) => void- policy
Returns
Promise<ConflictResolutionPolicy>
Chrome 117+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getFileStatus
chrome.syncFileSystem.getFileStatus(
fileEntry:
Entry,
callback?:
function,
)
Returns the FileStatus for the given fileEntry. The status value can be 'synced', 'pending' or 'conflicting'. Note that 'conflicting' state only happens when the service's conflict resolution policy is set to 'manual'.
Parameters
- fileEntry
Entry
- callback
function optional
The
callbackparameter looks like:(status: FileStatus) => void- status
Returns
Promise<FileStatus>
Chrome 117+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getFileStatuses
chrome.syncFileSystem.getFileStatuses(
fileEntries:
object[],
callback?:
function,
)
Returns each FileStatus for the given fileEntry array. Typically called with the result from dirReader.readEntries().
Parameters
- fileEntries
object[]
- callback
function optional
The
callbackparameter looks like:(status: FileStatusInfo[]) => void- status
Returns
Promise<FileStatusInfo[]>
Chrome 117+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getServiceStatus
chrome.syncFileSystem.getServiceStatus(
callback?:
function,
)
Returns the current sync backend status.
Parameters
- callback
function optional
The
callbackparameter looks like:(status: ServiceStatus) => void- status
Returns
Promise<ServiceStatus>
Chrome 117+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
getUsageAndQuota
chrome.syncFileSystem.getUsageAndQuota(
fileSystem:
DOMFileSystem,
callback?:
function,
)
Returns the current usage and quota in bytes for the 'syncable' file storage for the app.
Parameters
- fileSystem
DOMFileSystem
- callback
function optional
The
callbackparameter looks like:(info: StorageInfo) => void- info
Returns
Promise<StorageInfo>
Chrome 117+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
requestFileSystem
chrome.syncFileSystem.requestFileSystem(
callback?:
function,
)
Returns a syncable filesystem backed by Google Drive. The returned DOMFileSystem instance can be operated on in the same way as the Temporary and Persistant file systems (see http://dev.w3.org/2009/dap/file-system/file-dir-sys.html).
Calling this multiple times from the same app will return the same handle to the same file system.
Note this call can fail. For example, if the user is not signed in to Chrome or if there is no network operation. To handle these errors it is important chrome.runtime.lastError is checked in the callback.
Parameters
- callback
function optional
The
callbackparameter looks like:(fileSystem: DOMFileSystem) => void- fileSystem
DOMFileSystem
Returns
Promise<DOMFileSystem>
Chrome 117+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
setConflictResolutionPolicy
chrome.syncFileSystem.setConflictResolutionPolicy(
policy:
ConflictResolutionPolicy,
callback?:
function,
)
Sets the default conflict resolution policy for the 'syncable' file storage for the app. By default it is set to 'last_write_win'. When conflict resolution policy is set to 'last_write_win' conflicts for existing files are automatically resolved next time the file is updated. callback can be optionally given to know if the request has succeeded or not.
Parameters
- policy
- callback
function optional
The
callbackparameter looks like:() => void
Returns
Promise<void>
Chrome 117+Promises are supported in Manifest V3 and later, but callbacks are provided for backward compatibility. You cannot use both on the same function call. The promise resolves with the same type that is passed to the callback.
Events
onFileStatusChanged
chrome.syncFileSystem.onFileStatusChanged.addListener(
callback:
function,
)
Fired when a file has been updated by the background sync service.
Parameters
- callback
function
The
callbackparameter looks like:(detail: FileInfo) => void- detail
onServiceStatusChanged
chrome.syncFileSystem.onServiceStatusChanged.addListener(
callback:
function,
)
Fired when an error or other status change has happened in the sync backend (for example, when the sync is temporarily disabled due to network or authentication error).
Parameters
- callback
function
The
callbackparameter looks like:(detail: ServiceInfo) => void- detail