public interface

# DriveContents

com.google.android.gms.drive.DriveContents

## Class Overview

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

- Contents already associated to an existing `DriveFile`. This type is obtained through `open(GoogleApiClient, int, DriveFile.DownloadProgressListener)`.
- Contents not associated to any file and used only when creating a new file. This type is obtained through `newDriveContents(GoogleApiClient)`.

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

## Summary

Public Methods
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: This DriveContents was opened in `MODE_READ_ONLY`. This DriveContents is not associated to a file (obtained through `newDriveContents(GoogleApiClient)`)). The specified `ExecutionOptions` is incompatible with this DriveContents.

#### 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: This DriveContents was opened in `MODE_READ_ONLY`. This DriveContents is not associated to a file (obtained through `newDriveContents(GoogleApiClient)`)).

#### 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

- A `PendingResult` which can be used to verify the success of the operation and retrieve the `MODE_WRITE_ONLY` Contents when they are ready.