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