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:
- Request the file metadata
- When the task completes successfully, retrieve the
Metadata
object. - Check if
isPinnable
returnstrue
- Check the value of
isPinned
- Set the
setPinned
metadata parameter accordingly - Call
DriveResourceClient.updateMetadata
method, passing in theMetadata
object.
The following example illustrates the code necessary to retrieve the metadata, check the pinning status, and then pin the file.
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: