Storage Access Framework

Android API Guide

Android 4.4 引入了存储访问框架Storage Access Framework(SAF)，云或本地存储服务可以实现DocumentProvider来分装他们的服务以便加入到该生态系统中。

SAF包含了
Document Provider, Android 包含几个内置的DocumentsProvider，注入下载Downloads, Images, Videos.
Client App: 一个自定义的App，可发送ACTION_OPEN_DOCUMENT或者ACTION_CREATE_DOCUMENT，接收返回的文件。
Picker: 一个系统UI, 允许用户访问所有document providers 满足client app的搜索条件的。

Overview

架构图

• 以Root开始，指向单一节点，然后改单一节点再扇形展开。每个Root都有一个独一无二的COLUMN_ROOT_ID， 并且指向一个document或者directory， 代表了该Root下的内容。
• 在每个root下是一个single document, 该document指向1 to N个documents， 这下面的每个再指向1 to N个documents。
• 每个文件或者目录 都有COLUMN_DOCUMENT_ID， 该ID必须是独一无二的，且在issue后不可修改的。
• documents 可以是可打开的文件，也可是目录。
• 每个document 可以具有不同的能力，由COLUMN_FLAGS指定。例如：FLAG_SUPPORTS_WRITE, FLAG_SUPPORTS_DELETE, and FLAG_SUPPORTS_THUMBNAIL. 此外，COLUMN_DOCUMENT_ID可以出现在多个目录下。

Control Flow

document provider 的数据模型是基于传统的文件架构。但是，物理上，你可以随意存储，只要可以被DocumentProvider API访问。

下图显示了一个Photo App如何使用SAF访问图片

注意到：
1. Client and Provider 不直接交互。
2. 当客户端发起一个Intent(ACTION_OPEN_DOCUMENT or ACTION_CREATE_DOCUMENT), 可能包括一些filters
3. 一旦Intent发出, the system picker 就会到每个注册的provider，并显示匹配结果。
4. Picker提供一个标准的接口访问文件。

Writing a Client App

在Android 4.3之前，使用ACTION_PICK或者ACTION_GET_CONTENT 获得文件，对于后者是仅copy一份文件。
在Android 4.4及更高版本，将可使用ACTION_OPEN_DOCUMENT来获取文件，是直接使用源文件。

Search for documents

发起搜索图片请求

private static final int READ_REQUEST_CODE = 42;
...
/**
 * Fires an intent to spin up the "file chooser" UI and select an image.
 */
public void performFileSearch() {

    // ACTION_OPEN_DOCUMENT is the intent to choose a file via the system's file
    // browser.
    Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);

    // Filter to only show results that can be "opened", such as a
    // file (as opposed to a list of contacts or timezones)
    intent.addCategory(Intent.CATEGORY_OPENABLE);

    // Filter to show only images, using the image MIME data type.