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.

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);
            }
        });

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();
            }
        });

Send feedback about...

Drive API for Android
Drive API for Android