Pinning files

Pinning a file causes the latest version of that file's contents and metadata to be downloaded to the local device whenever a new version is available. Once a file is pinned by one application it is locally available to all applications that have permissions to that file.

Important: Because pinned files are downloaded to the device whenever a new version is available, pinning files can significantly increase a user's mobile data and device storage usage. You should avoid pinning files without a user's consent and inform them of the extra storage and bandwidth requirements of pinning files. These requirements increase for larger and frequently updated files.

File pinning uses two metadata attributes:

isPinnable()

Determines if the file can be pinned. All binary file types can be pinned to the local device. Non-binary files such as Docs, Sheets, Slides, and file shortcuts are typically not pinnable.

isPinned()

Indicates if the file is already pinned to the device.

If a file is pinnable, you can toggle the pinning status using the MetadataChangeSet.Builder.setPinned() method.

The typical workflow for pinning and unpinning files is as follows:

1. Request the file metadata
2. When the task completes successfully, retrieve the Metadata object.
3. Check if isPinnable returns true
4. Check the value of isPinned
5. Set the setPinned metadata parameter accordingly
6. Call DriveResourceClient.updateMetadata method, passing in the Metadata object.

The following example illustrates the code necessary to retrieve the metadata, check the pinning status, and then pin the file.

Task<Metadata> pinFileTask = getDriveResourceClient().getMetadata(file).continueWithTask(
        new Continuation<Metadata, Task<Metadata>>() {
            @Override
            public Task<Metadata> then(@NonNull Task<Metadata> task) throws Exception {
                Metadata metadata = task.getResult();
                if (!metadata.isPinnable()) {
                    showMessage(getString(R.string.file_not_pinnable));
                    return Tasks.forResult(metadata);
                }
                if (metadata.isPinned()) {
                    showMessage(getString(R.string.file_already_pinned));
                    return Tasks.forResult(metadata);
                }
                MetadataChangeSet changeSet =
                        new MetadataChangeSet.Builder().setPinned(true).build();
                return getDriveResourceClient().updateMetadata(file, changeSet);
            }
        });
PinFileActivity.java

If your application attempts to change the pinning status with setPinned() you should also handle the success or failure of the task as in this example:

pinFileTask
        .addOnSuccessListener(this,
                new OnSuccessListener<Metadata>() {
                    @Override
                    public void onSuccess(Metadata metadata) {
                        showMessage(getString(R.string.metadata_updated));
                        finish();
                    }
                })
        .addOnFailureListener(this, new OnFailureListener() {
            @Override
            public void onFailure(@NonNull Exception e) {
                Log.e(TAG, "Unable to update metadata", e);
                showMessage(getString(R.string.update_failed));
                finish();
            }
        });
PinFileActivity.java