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's setPinned() method.

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

1. Request the file metadata
2. Handle the MetadataResult callback
3. Check if isPinnable returns true
4. Check the value of isPinned
5. Set the setPinned metadata parameter accordingly
6. Handle the pinning request MetadataResult callback if a request to setPinned() is made

The following example illustrates the code necessary to handle the MedataResult callback, check the pinning status, and then pin the file.

/**
 * Handles the metadata response. If file is pinnable and not
 * already pinned, makes a request to pin the file.
 */
final ResultCallback<MetadataResult> metadataCallback = new ResultCallback<MetadataResult>() {
    @Override
    public void onResult(MetadataResult result) {
        if (!result.getStatus().isSuccess()) {
            showMessage("Problem while trying to retrieve the file metadata");
            return;
        }
        if (result.getMetadata().isPinnable()) {
            showMessage("File is not pinnable");
            return;
        }
        if (result.getMetadata().isPinned()) {
            showMessage("File is already pinned");
            return;
        }
        DriveFile file = Drive.DriveApi.getFile(getGoogleApiClient(), mFileId);
        MetadataChangeSet changeSet = new MetadataChangeSet.Builder()
                .setPinned(true)
                .build();
        file.updateMetadata(getGoogleApiClient(), changeSet)
                .setResultCallback(pinningCallback);
    }
};

If your application attempts to change the pinning status with setPinned() you must also handle the MetadataResult callback as in this example:

/**
 * Handles the pinning request's response.
 */
final ResultCallback<MetadataResult> pinningCallback = new ResultCallback<MetadataResult>() {
    @Override
    public void onResult(MetadataResult result) {
        if (!result.getStatus().isSuccess()) {
            showMessage("Problem while trying to pin the file");
            return;
        }
        showMessage("File successfully pinned to the device");
    }
};

For a full working example, see the PinFileActivity sample in the Google Drive Android API Demos app.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.