DriveContents

public interface DriveContents

A reference to a Drive file's contents. There are two types of DriveContents:

Any changes made to the DriveContents through either their ParcelFileDescriptor or OutputStream will not be visible until either commit(GoogleApiClient, MetadataChangeSet) is executed (for existing contents already associated to a DriveFile), or a new file is created using this contents (through createFile(GoogleApiClient, MetadataChangeSet, DriveContents) or CreateFileActivityBuilder, for new contents).

In both cases, the discard(GoogleApiClient) method can be used to discard any changes to any kind of DriveContents, so those changes will never be applied to a DriveFile or persisted in Drive.

Once this DriveContents instance has been committed, used for creation, or discarded, it becomes closed and any subsequent method call will throw an IllegalStateException.

Public Method Summary

abstract PendingResult<Status>
commit(GoogleApiClient apiClient, MetadataChangeSet changeSet, ExecutionOptions executionOptions)
Advanced version of commit which commits this contents and updates the metadata (if provided) of the file associated to this DriveContents instance and allows the client to specify a conflict resolution strategy or request completion notifications via the executionOptions parameter.
abstract PendingResult<Status>
commit(GoogleApiClient apiClient, MetadataChangeSet changeSet)
Commits this contents and updates the metadata (if provided) of the file associated to this DriveContents instance.
abstract void
discard(GoogleApiClient apiClient)
Discards this contents and any changes that were performed.
abstract DriveId
getDriveId()
Gets the DriveId for the file that owns these contents.
abstract InputStream
getInputStream()
Returns an InputStream that allows you to read this file's contents.
abstract int
getMode()
Gets the mode the contents are opened in.
abstract OutputStream
getOutputStream()
Returns an OutputStream that allows you to write new contents.
abstract ParcelFileDescriptor
getParcelFileDescriptor()
Returns a ParcelFileDescriptor that points to the Drive file's contents.
abstract PendingResult<DriveApi.DriveContentsResult>
reopenForWrite(GoogleApiClient apiClient)
Closes this contents and returns a new contents opened in MODE_WRITE_ONLY.

Public Methods

public abstract PendingResult<Status> commit (GoogleApiClient apiClient, MetadataChangeSet changeSet, ExecutionOptions executionOptions)

Advanced version of commit which commits this contents and updates the metadata (if provided) of the file associated to this DriveContents instance and allows the client to specify a conflict resolution strategy or request completion notifications via the executionOptions parameter.

A file conflict happens when the written contents are not applied on top of the file revision that Drive originally provided when the contents were read by the application. A conflict could happen when an application reads contents at revision X, then writes revision X+1 and by the time X+1 is committed (or uploaded to the server), the file version is not X anymore (another app or a remote change already modified the file to revision X').

This method should only be used on DriveContents that are already associated to a particular file. See setConflictStrategy(int) for details on using each conflict strategy.

After this method returns, this instance will be closed and will no longer be usable.

Parameters
apiClient The GoogleApiClient to service the call. The client must be connected before invoking this method.
changeSet The set of changes that will be applied to the Metadata of the file associated to this contents instance. Should only include the specific fields that should be updated. Can be null if no metadata changes should be applied with this commit.
executionOptions Contains any extra settings for this commit action, such as the strategy for handling conflicts or whether the client should be notified of failures when applying this operation on the server. See ExecutionOptions for more info. When null is provided, this method will use default ExecutionOptions, that is CONFLICT_STRATEGY_OVERWRITE_REMOTE strategy, no completion event requested and no operation tag.
Returns
  • A PendingResult which can be used to verify the success of the operation.
Throws
IllegalStateException If one of the following is true:

public abstract PendingResult<Status> commit (GoogleApiClient apiClient, MetadataChangeSet changeSet)

Commits this contents and updates the metadata (if provided) of the file associated to this DriveContents instance. This method should only be used on DriveContents that are already associated to a particular file (obtained through open(GoogleApiClient, int, DriveFile.DownloadProgressListener)).

This method behaves like commit(GoogleApiClient, MetadataChangeSet, ExecutionOptions) with null ExecutionOptions, which means CONFLICT_STRATEGY_OVERWRITE_REMOTE strategy, no completion event requested and no operation tag. Use the advanced version of commit if you'd like to specify different ExecutionOptions.

After this method returns, this instance will be closed and will no longer be usable.

Parameters
apiClient The GoogleApiClient to service the call. The client must be connected before invoking this method.
changeSet The set of changes that will be applied to the Metadata of the file associated to this contents instance. Should only include the specific fields that should be updated. Can be null if no metadata changes should be applied with this commit.
Returns
  • A PendingResult which can be used to verify the success of the operation.
Throws
IllegalStateException If one of the following is true:

public abstract void discard (GoogleApiClient apiClient)

Discards this contents and any changes that were performed. Calling this method will not save any changes performed through this object.

After this method returns, this instance will be closed and will no longer be usable.

Parameters
apiClient The GoogleApiClient to service the call. The client must be connected before invoking this method.

public abstract DriveId getDriveId ()

Gets the DriveId for the file that owns these contents. Will be null if this instance corresponds to new contents (obtained through newDriveContents(GoogleApiClient)}.

public abstract InputStream getInputStream ()

Returns an InputStream that allows you to read this file's contents. This method may only be used with files opened with MODE_READ_ONLY; to read/write from a file opened with MODE_READ_WRITE, use the file descriptor returned by getParcelFileDescriptor(). This method may only be called once per DriveContents instance.

public abstract int getMode ()

Gets the mode the contents are opened in.

public abstract OutputStream getOutputStream ()

Returns an OutputStream that allows you to write new contents. This method may only be used with files opened with MODE_WRITE_ONLY; to read/write from a file opened with MODE_READ_WRITE, use the file descriptor returned by getParcelFileDescriptor(). This method may only be called once per DriveContents instance.

public abstract ParcelFileDescriptor getParcelFileDescriptor ()

Returns a ParcelFileDescriptor that points to the Drive file's contents. If this file was opened with MODE_READ_ONLY or MODE_READ_WRITE, the file referenced by the returned file descriptor will contain the most recent version of the file. Otherwise, the returned file descriptor will point to an empty file.

public abstract PendingResult<DriveApi.DriveContentsResult> reopenForWrite (GoogleApiClient apiClient)

Closes this contents and returns a new contents opened in MODE_WRITE_ONLY. The returned DriveContents are usable for conflict detection.

This method can only be called on MODE_READ_ONLY contents. Calling it on MODE_WRITE_ONLY or MODE_READ_WRITE contents, or on closed contents throws an IllegalStateException.

This method is useful for conflict detection, and often used in conjunction with commit(GoogleApiClient, MetadataChangeSet, ExecutionOptions), however it can also be used to open contents in MODE_WRITE_ONLY from an existing instance of MODE_READ_ONLY contents.

After this method returns, this instance will be closed and will no longer be usable.

Parameters
apiClient The GoogleApiClient to service the call.
Returns