chrome.syncFileSystem

Description:	Use the `chrome.syncFileSystem` API 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.
Availability:	Since Chrome 35.
Permissions:	"syncFileSystem"
Learn More:	Manage Data Chrome Office Hours: Synched File System

Summary

Types
ServiceStatus
FileStatus
ConflictResolutionPolicy
Methods
requestFileSystem − `chrome.syncFileSystem.requestFileSystem(function callback)`
setConflictResolutionPolicy − `chrome.syncFileSystem.setConflictResolutionPolicy( ConflictResolutionPolicy policy, function callback)`
getConflictResolutionPolicy − `chrome.syncFileSystem.getConflictResolutionPolicy(function callback)`
getUsageAndQuota − `chrome.syncFileSystem.getUsageAndQuota(DOMFileSystem fileSystem, function callback)`
getFileStatus − `chrome.syncFileSystem.getFileStatus(Entry fileEntry, function callback)`
getFileStatuses − `chrome.syncFileSystem.getFileStatuses(array of object fileEntries, function callback)`
getServiceStatus − `chrome.syncFileSystem.getServiceStatus(function callback)`
Events
onServiceStatusChanged
onFileStatusChanged

Types

ServiceStatus

Enum

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.)

"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.)

FileStatus

Enum

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.

"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.

ConflictResolutionPolicy

Enum
`"last_write_win"`, or `"manual"`

Methods

requestFileSystem


              chrome.syncFileSystem.requestFileSystem(function callback)

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

function

callback

A callback type for requestFileSystem.

The callback parameter should be a function that looks like this:

function(DOMFileSystem fileSystem) {...};

DOMFileSystem

fileSystem

setConflictResolutionPolicy


              chrome.syncFileSystem.setConflictResolutionPolicy(    ConflictResolutionPolicy policy, function callback)

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

ConflictResolutionPolicy policy

function

Parameters
ConflictResolutionPolicy	policy
function	(optional) callback	A generic result callback to indicate success or failure. If you specify the callback parameter, it should be a function that looks like this: `function() {...};`

(optional) callback

A generic result callback to indicate success or failure.

If you specify the callback parameter, it should be a function that looks like this:

function() {...};

getConflictResolutionPolicy


              chrome.syncFileSystem.getConflictResolutionPolicy(function callback)

Gets the current conflict resolution policy.

Parameters

function

callback

A callback type for getConflictResolutionPolicy.

The callback parameter should be a function that looks like this:

function( ConflictResolutionPolicy policy) {...};

ConflictResolutionPolicy

policy

getUsageAndQuota


              chrome.syncFileSystem.getUsageAndQuota(DOMFileSystem fileSystem, function callback)

Returns the current usage and quota in bytes for the 'syncable' file storage for the app.

Parameters

DOMFileSystem fileSystem

function

callback

A callback type for getUsageAndQuota.

The callback parameter should be a function that looks like this:

function(object info) {...};

object

info

integer	usageBytes
integer	quotaBytes

getFileStatus


              chrome.syncFileSystem.getFileStatus(Entry fileEntry, function callback)

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

Entry fileEntry

function

callback

A callback type for getFileStatus.

The callback parameter should be a function that looks like this:

function( FileStatus status) {...};

FileStatus

status

getFileStatuses


              chrome.syncFileSystem.getFileStatuses(array of object fileEntries, function callback)

Returns each FileStatus for the given fileEntry array. Typically called with the result from dirReader.readEntries().

Parameters

array of object

fileEntries

Properties of each object

function

callback

A callback type for getFileStatuses.

The callback parameter should be a function that looks like this:

function(array of object status) {...};

array of object

status

Properties of each object

Entry	fileEntry	One of the Entry's originally given to getFileStatuses.
FileStatus	status	The status value can be `'synced'`, `'pending'` or `'conflicting'`.
string	(optional) error	Optional error that is only returned if there was a problem retrieving the FileStatus for the given file.

getServiceStatus


              chrome.syncFileSystem.getServiceStatus(function callback)

Returns the current sync backend status.

Parameters

function

callback

A callback type for getServiceStatus.

The callback parameter should be a function that looks like this:

function( ServiceStatus status) {...};

ServiceStatus

status

Events

onServiceStatusChanged

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).

addListener


                    chrome.syncFileSystem.onServiceStatusChanged.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(object detail) {...};

object

detail

ServiceStatus	state
string	description

onFileStatusChanged

Fired when a file has been updated by the background sync service.

addListener


                    chrome.syncFileSystem.onFileStatusChanged.addListener(function callback)

Parameters

function

callback

The callback parameter should be a function that looks like this:

function(object detail) {...};

object

detail

Entry	fileEntry	`fileEntry` for the target file whose status has changed. Contains name and path information of synchronized file. On file deletion, `fileEntry` information will still be available but file will no longer exist.
FileStatus	status	Resulting file status after onFileStatusChanged event. The status value can be `'synced'`, `'pending'` or `'conflicting'`.
enum of `"added"`, `"updated"`, or `"deleted"`	(optional) action	Sync action taken to fire onFileStatusChanged event. The action value can be `'added'`, `'updated'` or `'deleted'`. Only applies if status is `'synced'`.
enum of `"local_to_remote"`, or `"remote_to_local"`	(optional) direction	Sync direction for the onFileStatusChanged event. Sync direction value can be `'local_to_remote'` or `'remote_to_local'`. Only applies if status is `'synced'`.