topics/providers/document-provider.jd

page.title=    (Storage Access Framework)
@jd:body
<div id="qv-wrapper">
<div id="qv">

<h2>
<a href="#" onclick="hideNestedItems('#toc44',this);return false;" class="header-toggle">
        <span class="more"> </span>
        <span class="less" style="display:none"> </span></a></h2>
<ol id="toc44" class="hide-nested">
    <li>
        <a href="#overview"></a>
    </li>
    <li>
        <a href="#flow"> </a>
    </li>
    <li>
        <a href="#client">  </a>
        <ol>
        <li><a href="#search"> </a></li>
        <li><a href="#process"> </a></li>
        <li><a href="#metadata">  </a></li>
        <li><a href="#open"> </a></li>
        <li><a href="#create">  </a></li>
        <li><a href="#delete"> </a></li>
        <li><a href="#edit"> </a></li>
        <li><a href="#permissions">  </a></li>
        </ol>
    </li>
    <li><a href="#custom">   </a>
        <ol>
        <li><a href="#manifest"></a></li>
        <li><a href="#contract"></a></li>
        <li><a href="#subclass">   DocumentsProvider</a></li>
        <li><a href="#security"></a></li>
        </ol>
    </li>

</ol>
<h2> </h2>
<ol>
    <li>{@link android.provider.DocumentsProvider}</li>
    <li>{@link android.provider.DocumentsContract}</li>
</ol>

<h2></h2>

<ol>
    <li><a href="http://www.youtube.com/watch?v=zxHVeXbK1P4">
DevBytes: Android 4.4 Storage Access Framework: </a></li>
     <li><a href="http://www.youtube.com/watch?v=UFj9AEz0DHQ">
DevBytes: Android 4.4 Storage Access Framework: </a></li>
</ol>


<h2> </h2>

<ol>
    <li><a href="{@docRoot}samples/StorageProvider/index.html">
 StorageProvider</a></li>
     <li><a href="{@docRoot}samples/StorageClient/index.html">
 StorageClient</a></li>
</ol>

<h2>. :</h2>
<ol>
    <li>
        <a href="{@docRoot}guide/topics/providers/content-provider-basics.html">

</a>
    </li>
</ol>

</div>
</div>


<p>    (Storage Access Framework, SAF)    Android  4.4 (API  19).  SAF
      ,
   ,    .
                 .</p>

<p>         ,
 {@link android.provider.DocumentsProvider},   .
,      ,    SAF
 .</p>

<p> SAF     :</p>

<ul>
<li><strong> </strong>&mdash; ,
  (,  Google)  ,   .
   {@link android.provider.DocumentsProvider}.
      ,
           .
  Android       ,
,   .</li>

<li><strong> </strong>&mdash; ,
{@link android.content.Intent#ACTION_OPEN_DOCUMENT} /
{@link android.content.Intent#ACTION_CREATE_DOCUMENT}
,   .</li>

<li><strong> </strong>&mdash;  ,
 ,    ,    .</li>
</ul>

<p> SAF      :</p>
<ul>
<li>       ,      ;</li>
<li>   ,
 ,   .      , ,
    ,   ;</li>
<li>       , ,
 USB-,  ,      . </li>
</ul>

<h2 id ="overview"></h2>

<p>   SAF   ,
  {@link android.provider.DocumentsProvider}.  <em> </em>
   :</p>
<p><img src="{@docRoot}images/providers/storage_datamodel.png" alt="data model" /></p>
<p class="img-caption"><strong> 1.</strong>    .   Root ( )     Document (),
     .</p>

<p>   .</p>
<ul>

<li>
 ,       .
      {@link android.provider.DocumentsContract.Root#COLUMN_ROOT_ID}
    (),
     .
     ,      ,    ,
   USB-           .</li>

<li>      .       <em>N</em>
  ,   ,      <em>N</em> . </li>

<li>
   ,
 {@link android.provider.DocumentsContract.Document#COLUMN_DOCUMENT_ID}.
         ,
URI,     .</li>


<li>     (  MIME-),
,    (
MIME- {@link android.provider.DocumentsContract.Document#MIME_TYPE_DIR}).</li>

<li>     ,
{@link android.provider.DocumentsContract.Document#COLUMN_FLAGS COLUMN_FLAGS},
 {@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_WRITE},
{@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_DELETE}
{@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_THUMBNAIL}.
       {@link android.provider.DocumentsContract.Document#COLUMN_DOCUMENT_ID}
  .</li>
</ul>

<h2 id="flow"> </h2>
<p>   ,
 .         ,
,       API- {@link android.provider.DocumentsProvider}. ,
       .</p>

<p> 2   ,        SAF
    :</p>
<p><img src="{@docRoot}images/providers/storage_dataflow.png" alt="app" /></p>

<p class="img-caption"><strong> 2.</strong>   Storage Access Framework</p>

<p>   .</p>
<ul>

<li>  SAF
.
  ( ,  , ,    ).</li>

<li> ,   (    )
{@link android.content.Intent#ACTION_OPEN_DOCUMENT}  {@link android.content.Intent#ACTION_CREATE_DOCUMENT}.
  , ,
 MIME- image.</li>

<li>  ,
      ,  .</li>

<li>     ,
    .     2
  Google,   USB-   .</li>
</ul>

<p> 3   ,
 Google:</p>

<p><img src="{@docRoot}images/providers/storage_picker.png" width="340" alt="picker" style="border:2px solid #ddd" /></p>

<p class="img-caption"><strong> 3.</strong>  </p>

<p>    Google,  ,
4.          ,
      .

<p><img src="{@docRoot}images/providers/storage_photos.png" width="340" alt="picker" style="border:2px solid #ddd" /></p>

<p class="img-caption"><strong>4.</strong> </p>

<h2 id="client">  </h2>

<p> Android  4.3    ,
,    , , {@link android.content.Intent#ACTION_PICK}
 {@link android.content.Intent#ACTION_GET_CONTENT}.
-  ,   ,
,         . </p>

<p>  Android 4.4  ,
{@link android.content.Intent#ACTION_OPEN_DOCUMENT},
     ,  .
  ,    .    ,
        .</p>

<p> {@link android.content.Intent#ACTION_OPEN_DOCUMENT}
    {@link android.content.Intent#ACTION_GET_CONTENT}.
    ,     :</p>

<ul>
<li> {@link android.content.Intent#ACTION_GET_CONTENT},
   .       ,
 ,   .</li>

<li> {@link android.content.Intent#ACTION_OPEN_DOCUMENT},
   ,    ,
.       ,
,    . </li>

</ul>


<p>   ,    ,
{@link android.content.Intent#ACTION_OPEN_DOCUMENT}
{@link android.content.Intent#ACTION_CREATE_DOCUMENT}.</p>


<h3 id="search"> </h3>

<p>
     {@link android.content.Intent#ACTION_OPEN_DOCUMENT}
    ,
  :</p>

<pre>private static final int READ_REQUEST_CODE = 42;
...
/**
 * Fires an intent to spin up the &quot;file chooser&quot; 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 &quot;opened&quot;, 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.
    // If one wanted to search for ogg vorbis files, the type would be &quot;audio/ogg&quot;.
    // To search for all documents available via installed storage providers,
    // it would be &quot;*/*&quot;.
    intent.setType(&quot;image/*&quot;);

    startActivityForResult(intent, READ_REQUEST_CODE);
}</pre>

<p>   .</p>
<ul>
<li>    {@link android.content.Intent#ACTION_OPEN_DOCUMENT}
,    ,    ,   .</li>

<li>  {@link android.content.Intent#CATEGORY_OPENABLE}
       ,   , ,   .</li>

<li> {@code intent.setType("image/*")}   ,
    MIME- image.</li>
</ul>

<h3 id="results"> </h3>

<p>      ,
  {@link android.app.Activity#onActivityResult onActivityResult()}.
 URI,    ,   {@code resultData}.
   URI,   {@link android.content.Intent#getData getData()}.
 URI     ,  . :
</p>

<pre>&#64;Override
public void onActivityResult(int requestCode, int resultCode,
        Intent resultData) {

    // The ACTION_OPEN_DOCUMENT intent was sent with the request code
    // READ_REQUEST_CODE. If the request code seen here doesn't match, it's the
    // response to some other intent, and the code below shouldn't run at all.

    if (requestCode == READ_REQUEST_CODE && resultCode == Activity.RESULT_OK) {
        // The document selected by the user won't be returned in the intent.
        // Instead, a URI to that document will be contained in the return intent
        // provided to this method as a parameter.
        // Pull that URI using resultData.getData().
        Uri uri = null;
        if (resultData != null) {
            uri = resultData.getData();
            Log.i(TAG, "Uri: " + uri.toString());
            showImage(uri);
        }
    }
}
</pre>

<h3 id="metadata">  </h3>

<p>    URI ,      .
   ,   URI,     :</p>

<pre>public void dumpImageMetaData(Uri uri) {

    // The query, since it only applies to a single document, will only return
    // one row. There's no need to filter, sort, or select fields, since we want
    // all fields for one document.
    Cursor cursor = getActivity().getContentResolver()
            .query(uri, null, null, null, null, null);

    try {
    // moveToFirst() returns false if the cursor has 0 rows.  Very handy for
    // &quot;if there's anything to look at, look at it&quot; conditionals.
        if (cursor != null &amp;&amp; cursor.moveToFirst()) {

            // Note it's called &quot;Display Name&quot;.  This is
            // provider-specific, and might not necessarily be the file name.
            String displayName = cursor.getString(
                    cursor.getColumnIndex(OpenableColumns.DISPLAY_NAME));
            Log.i(TAG, &quot;Display Name: &quot; + displayName);

            int sizeIndex = cursor.getColumnIndex(OpenableColumns.SIZE);
            // If the size is unknown, the value stored is null.  But since an
            // int can't be null in Java, the behavior is implementation-specific,
            // which is just a fancy term for &quot;unpredictable&quot;.  So as
            // a rule, check if it's null before assigning to an int.  This will
            // happen often:  The storage API allows for remote files, whose
            // size might not be locally known.
            String size = null;
            if (!cursor.isNull(sizeIndex)) {
                // Technically the column stores an int, but cursor.getString()
                // will do the conversion automatically.
                size = cursor.getString(sizeIndex);
            } else {
                size = &quot;Unknown&quot;;
            }
            Log.i(TAG, &quot;Size: &quot; + size);
        }
    } finally {
        cursor.close();
    }
}
</pre>

<h3 id="open-client"> </h3>

<p> URI ,
   ,  .</p>

<h4>  </h4>

<p>      {@link android.graphics.Bitmap}:</p>

<pre>private Bitmap getBitmapFromUri(Uri uri) throws IOException {
    ParcelFileDescriptor parcelFileDescriptor =
            getContentResolver().openFileDescriptor(uri, "r");
    FileDescriptor fileDescriptor = parcelFileDescriptor.getFileDescriptor();
    Bitmap image = BitmapFactory.decodeFileDescriptor(fileDescriptor);
    parcelFileDescriptor.close();
    return image;
}
</pre>

<p> ,          .
 ,   {@link android.os.AsyncTask}.      ,
    {@link android.widget.ImageView}.
</p>

<h4>  InputStream</h4>

<p>   ,     {@link java.io.InputStream}   URI.
        :</p>

<pre>private String readTextFromUri(Uri uri) throws IOException {
    InputStream inputStream = getContentResolver().openInputStream(uri);
    BufferedReader reader = new BufferedReader(new InputStreamReader(
            inputStream));
    StringBuilder stringBuilder = new StringBuilder();
    String line;
    while ((line = reader.readLine()) != null) {
        stringBuilder.append(line);
    }
    fileInputStream.close();
    parcelFileDescriptor.close();
    return stringBuilder.toString();
}
</pre>

<h3 id="create">  </h3>

<p>       ,
{@link android.content.Intent#ACTION_CREATE_DOCUMENT}
.   ,     MIME-   ,
     .    :</p>


<pre>
// Here are some examples of how you might call this method.
// The first parameter is the MIME type, and the second parameter is the name
// of the file you are creating:
//
// createFile("text/plain", "foobar.txt");
// createFile("image/png", "mypicture.png");

// Unique request code.
private static final int WRITE_REQUEST_CODE = 43;
...
private void createFile(String mimeType, String fileName) {
    Intent intent = new Intent(Intent.ACTION_CREATE_DOCUMENT);

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

    // Create a file with the requested MIME type.
    intent.setType(mimeType);
    intent.putExtra(Intent.EXTRA_TITLE, fileName);
    startActivityForResult(intent, WRITE_REQUEST_CODE);
}
</pre>

<p>       URI
 {@link android.app.Activity#onActivityResult onActivityResult()},
   .</p>

<h3 id="delete"> </h3>

<p>    URI ,
{@link android.provider.DocumentsContract.Document#COLUMN_FLAGS Document.COLUMN_FLAGS}

{@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_DELETE SUPPORTS_DELETE},
   . :</p>

<pre>
DocumentsContract.deleteDocument(getContentResolver(), uri);
</pre>

<h3 id="edit"> </h3>

<p> SAF      .

 {@link android.content.Intent#ACTION_OPEN_DOCUMENT},
 {@link android.content.Intent#CATEGORY_OPENABLE} ,
,   .    ,     :</p>

<pre>
private static final int EDIT_REQUEST_CODE = 44;
/**
 * Open a file for writing and append some text to it.
 */
 private void editDocument() {
    // 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 &quot;opened&quot;, such as a
    // file (as opposed to a list of contacts or timezones).
    intent.addCategory(Intent.CATEGORY_OPENABLE);

    // Filter to show only text files.
    intent.setType(&quot;text/plain&quot;);

    startActivityForResult(intent, EDIT_REQUEST_CODE);
}
</pre>

<p>,   {@link android.app.Activity#onActivityResult onActivityResult()}
(. <a href="#results"> </a>)      .
     {@link java.io.FileOutputStream}
     {@link android.content.ContentResolver}.     .
     ,
/,      :</p>

<pre>private void alterDocument(Uri uri) {
    try {
        ParcelFileDescriptor pfd = getActivity().getContentResolver().
                openFileDescriptor(uri, "w");
        FileOutputStream fileOutputStream =
                new FileOutputStream(pfd.getFileDescriptor());
        fileOutputStream.write(("Overwritten by MyCloud at " +
                System.currentTimeMillis() + "\n").getBytes());
        // Let the document provider know you're done by closing the stream.
        fileOutputStream.close();
        pfd.close();
    } catch (FileNotFoundException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }
}</pre>

<h3 id="permissions">  </h3>

<p>       ,
 URI-   .      .
,     ,
       ,   .
 ,
. ,     .</p>

<p>   ,     ,
 .     URI-,
 .
 ,    :</p>


<pre>final int takeFlags = intent.getFlags()
            &amp; (Intent.FLAG_GRANT_READ_URI_PERMISSION
            | Intent.FLAG_GRANT_WRITE_URI_PERMISSION);
// Check for the freshest data.
getContentResolver().takePersistableUriPermission(uri, takeFlags);</pre>

<p>   .
URI-,    .   ,    ,
    .
{@code getContentResolver().takePersistableUriPermission()},
 .</p>

<h2 id="custom">   </h2>

<p>
  ,      (,
   ),
SAF,    .     ,
  .</p>


<h3 id="manifest"></h3>

<p>    ,
 :</p>
<ul>

<li> API-  19  .</li>

<li> <code>&lt;provider&gt;</code>,
 . </li>

<li> , ..,      .
: <code>com.example.android.storageprovider.MyCloudProvider</code>.</li>

<li>  , ..   (
<code>com.example.android.storageprovider</code>)
(<code>documents</code>). ,{@code com.example.android.storageprovider.documents}.</li>

<li> <code>android:exported</code>,    <code>&quot;true&quot;</code>.
   ,      .</li>

<li> <code>android:grantUriPermissions</code>,
<code>&quot;true&quot;</code>.
  .  ,
   .   <a href="#permissions">  </a>.</li>

<li> {@code MANAGE_DOCUMENTS}.
.          .
    .</li>

<li> {@code android:enabled},   ,
.           Android  4.3  .
 : {@code android:enabled="@bool/atLeastKitKat"}.
    ,   :
<ul>
<li>   {@code bool.xml},    {@code res/values/},
 <pre>&lt;bool name=&quot;atLeastKitKat&quot;&gt;false&lt;/bool&gt;</pre></li>

<li>   {@code bool.xml},    {@code res/values-v19/},
 <pre>&lt;bool name=&quot;atLeastKitKat&quot;&gt;true&lt;/bool&gt;</pre></li>
</ul></li>

<li>
{@code android.content.action.DOCUMENTS_PROVIDER},
   ,     .</li>

</ul>
<p>     ,    :</p>

<pre>&lt;manifest... &gt;
    ...
    &lt;uses-sdk
        android:minSdkVersion=&quot;19&quot;
        android:targetSdkVersion=&quot;19&quot; /&gt;
        ....
        &lt;provider
            android:name=&quot;com.example.android.storageprovider.MyCloudProvider&quot;
            android:authorities=&quot;com.example.android.storageprovider.documents&quot;
            android:grantUriPermissions=&quot;true&quot;
            android:exported=&quot;true&quot;
            android:permission=&quot;android.permission.MANAGE_DOCUMENTS&quot;
            android:enabled=&quot;&#64;bool/atLeastKitKat&quot;&gt;
            &lt;intent-filter&gt;
                &lt;action android:name=&quot;android.content.action.DOCUMENTS_PROVIDER&quot; /&gt;
            &lt;/intent-filter&gt;
        &lt;/provider&gt;
    &lt;/application&gt;

&lt;/manifest&gt;</pre>

<h4 id="43">    Android  4.3  </h4>

<p>
{@link android.content.Intent#ACTION_OPEN_DOCUMENT}
   Android  4.4  .
    {@link android.content.Intent#ACTION_GET_CONTENT},
  ,    Android 4.3  ,
   {@link android.content.Intent#ACTION_GET_CONTENT}
    Android  4.4  .
   {@link android.content.Intent#ACTION_GET_CONTENT}
.     ,
        ,
  .   .</p>

<p>
{@link android.content.Intent#ACTION_GET_CONTENT}
 Android  4.4     :</p>

<ol>
<li>   {@code bool.xml},    {@code res/values/},
 : <pre>&lt;bool name=&quot;atMostJellyBeanMR2&quot;&gt;true&lt;/bool&gt;</pre></li>

<li>   {@code bool.xml},    {@code res/values-v19/},
 : <pre>&lt;bool name=&quot;atMostJellyBeanMR2&quot;&gt;false&lt;/bool&gt;</pre></li>

<li>
<a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">
</a>,     {@link android.content.Intent#ACTION_GET_CONTENT}
  4.4 (API  19)  . :

<pre>
&lt;!-- This activity alias is added so that GET_CONTENT intent-filter
     can be disabled for builds on API level 19 and higher. --&gt;
&lt;activity-alias android:name=&quot;com.android.example.app.MyPicker&quot;
        android:targetActivity=&quot;com.android.example.app.MyActivity&quot;
        ...
        android:enabled=&quot;@bool/atMostJellyBeanMR2&quot;&gt;
    &lt;intent-filter&gt;
        &lt;action android:name=&quot;android.intent.action.GET_CONTENT&quot; /&gt;
        &lt;category android:name=&quot;android.intent.category.OPENABLE&quot; /&gt;
        &lt;category android:name=&quot;android.intent.category.DEFAULT&quot; /&gt;
        &lt;data android:mimeType=&quot;image/*&quot; /&gt;
        &lt;data android:mimeType=&quot;video/*&quot; /&gt;
    &lt;/intent-filter&gt;
&lt;/activity-alias&gt;
</pre>
</li>
</ol>
<h3 id="contract"></h3>

<p> ,
  -,
<a href="{@docRoot}guide/topics/providers/content-provider-creating.html#ContractClass">
 </a>. -    {@code public final},
      URI,  ,  MIME
  .  SAF
   -,
:</p>

<ul>
   <li>{@link android.provider.DocumentsContract.Document}</li>
   <li>{@link android.provider.DocumentsContract.Root}</li>
</ul>

<p>,
         ,      :</p>

<pre>private static final String[] DEFAULT_ROOT_PROJECTION =
        new String[]{Root.COLUMN_ROOT_ID, Root.COLUMN_MIME_TYPES,
        Root.COLUMN_FLAGS, Root.COLUMN_ICON, Root.COLUMN_TITLE,
        Root.COLUMN_SUMMARY, Root.COLUMN_DOCUMENT_ID,
        Root.COLUMN_AVAILABLE_BYTES,};
private static final String[] DEFAULT_DOCUMENT_PROJECTION = new
        String[]{Document.COLUMN_DOCUMENT_ID, Document.COLUMN_MIME_TYPE,
        Document.COLUMN_DISPLAY_NAME, Document.COLUMN_LAST_MODIFIED,
        Document.COLUMN_FLAGS, Document.COLUMN_SIZE,};
</pre>

<h3 id="subclass">   DocumentsProvider</h3>

<p>
  {@link android.provider.DocumentsProvider}.  ,
  :</p>

<ul>
<li>{@link android.provider.DocumentsProvider#queryRoots queryRoots()}</li>

<li>{@link android.provider.DocumentsProvider#queryChildDocuments queryChildDocuments()}</li>

<li>{@link android.provider.DocumentsProvider#queryDocument queryDocument()}</li>

<li>{@link android.provider.DocumentsProvider#openDocument openDocument()}</li>
</ul>

<p>  ,    ,
  , , ,   .     {@link android.provider.DocumentsProvider}
.</p>

<h4 id="queryRoots">  queryRoots</h4>

<p>  {@link android.provider.DocumentsProvider#queryRoots
queryRoots()}    {@link android.database.Cursor},
   ,  ,
{@link android.provider.DocumentsContract.Root}.</p>

<p>     {@code projection}
 ,   .     ,
     ,     (  ), ,
  .        .        ,
,     .
   .</p>

<pre>
&#64;Override
public Cursor queryRoots(String[] projection) throws FileNotFoundException {

    // Create a cursor with either the requested fields, or the default
    // projection if "projection" is null.
    final MatrixCursor result =
            new MatrixCursor(resolveRootProjection(projection));

    // If user is not logged in, return an empty root cursor.  This removes our
    // provider from the list entirely.
    if (!isUserLoggedIn()) {
        return result;
    }

    // It's possible to have multiple roots (e.g. for multiple accounts in the
    // same app) -- just add multiple cursor rows.
    // Construct one row for a root called &quot;MyCloud&quot;.
    final MatrixCursor.RowBuilder row = result.newRow();
    row.add(Root.COLUMN_ROOT_ID, ROOT);
    row.add(Root.COLUMN_SUMMARY, getContext().getString(R.string.root_summary));

    // FLAG_SUPPORTS_CREATE means at least one directory under the root supports
    // creating documents. FLAG_SUPPORTS_RECENTS means your application's most
    // recently used documents will show up in the &quot;Recents&quot; category.
    // FLAG_SUPPORTS_SEARCH allows users to search all documents the application
    // shares.
    row.add(Root.COLUMN_FLAGS, Root.FLAG_SUPPORTS_CREATE |
            Root.FLAG_SUPPORTS_RECENTS |
            Root.FLAG_SUPPORTS_SEARCH);

    // COLUMN_TITLE is the root title (e.g. Gallery, Drive).
    row.add(Root.COLUMN_TITLE, getContext().getString(R.string.title));

    // This document id cannot change once it's shared.
    row.add(Root.COLUMN_DOCUMENT_ID, getDocIdForFile(mBaseDir));

    // The child MIME types are used to filter the roots and only present to the
    //  user roots that contain the desired type somewhere in their file hierarchy.
    row.add(Root.COLUMN_MIME_TYPES, getChildMimeTypes(mBaseDir));
    row.add(Root.COLUMN_AVAILABLE_BYTES, mBaseDir.getFreeSpace());
    row.add(Root.COLUMN_ICON, R.drawable.ic_launcher);

    return result;
}</pre>

<h4 id="queryChildDocuments">  queryChildDocuments</h4>

<p>
{@link android.provider.DocumentsProvider#queryChildDocuments queryChildDocuments()}
  {@link android.database.Cursor},
 ,  ,
{@link android.provider.DocumentsContract.Document}.</p>

<p>  ,          .
  -     .
 ,      .
    .
    .
   ,   ,  ,  :</p>

<pre>&#64;Override
public Cursor queryChildDocuments(String parentDocumentId, String[] projection,
                              String sortOrder) throws FileNotFoundException {

    final MatrixCursor result = new
            MatrixCursor(resolveDocumentProjection(projection));
    final File parent = getFileForDocId(parentDocumentId);
    for (File file : parent.listFiles()) {
        // Adds the file's display name, MIME type, size, and so on.
        includeFile(result, null, file);
    }
    return result;
}
</pre>

<h4 id="queryDocument">  queryDocument</h4>

<p>
{@link android.provider.DocumentsProvider#queryDocument queryDocument()}
  {@link android.database.Cursor},    ,
 ,  {@link android.provider.DocumentsContract.Document}.
</p>

<p> {@link android.provider.DocumentsProvider#queryDocument queryDocument()}
   ,
{@link android.provider.DocumentsProvider#queryChildDocuments queryChildDocuments()},
   :</p>


<pre>&#64;Override
public Cursor queryDocument(String documentId, String[] projection) throws
        FileNotFoundException {

    // Create a cursor with the requested projection, or the default projection.
    final MatrixCursor result = new
            MatrixCursor(resolveDocumentProjection(projection));
    includeFile(result, documentId, null);
    return result;
}
</pre>

<h4 id="openDocument">  openDocument</h4>

<p>   {@link android.provider.DocumentsProvider#openDocument
openDocument()},    {@link android.os.ParcelFileDescriptor},
 .       {@link android.os.ParcelFileDescriptor}
   .    ,    ,
     ,
 {@link android.content.ContentResolver#openFileDescriptor openFileDescriptor()}.
:</p>

<pre>&#64;Override
public ParcelFileDescriptor openDocument(final String documentId,
                                         final String mode,
                                         CancellationSignal signal) throws
        FileNotFoundException {
    Log.v(TAG, &quot;openDocument, mode: &quot; + mode);
    // It's OK to do network operations in this method to download the document,
    // as long as you periodically check the CancellationSignal. If you have an
    // extremely large file to transfer from the network, a better solution may
    // be pipes or sockets (see ParcelFileDescriptor for helper methods).

    final File file = getFileForDocId(documentId);

    final boolean isWrite = (mode.indexOf('w') != -1);
    if(isWrite) {
        // Attach a close listener if the document is opened in write mode.
        try {
            Handler handler = new Handler(getContext().getMainLooper());
            return ParcelFileDescriptor.open(file, accessMode, handler,
                        new ParcelFileDescriptor.OnCloseListener() {
                &#64;Override
                public void onClose(IOException e) {

                    // Update the file with the cloud server. The client is done
                    // writing.
                    Log.i(TAG, &quot;A file with id &quot; +
                    documentId + &quot; has been closed!
                    Time to &quot; +
                    &quot;update the server.&quot;);
                }

            });
        } catch (IOException e) {
            throw new FileNotFoundException(&quot;Failed to open document with id &quot;
            + documentId + &quot; and mode &quot; + mode);
        }
    } else {
        return ParcelFileDescriptor.open(file, accessMode);
    }
}
</pre>

<h3 id="security"></h3>

<p>,           ,
   ,     ,        .
   ,     ?     ,
  {@link android.provider.DocumentsProvider#queryRoots
queryRoots()}    .  ,      :</p>

<pre>
public Cursor queryRoots(String[] projection) throws FileNotFoundException {
...
    // If user is not logged in, return an empty root cursor.  This removes our
    // provider from the list entirely.
    if (!isUserLoggedIn()) {
        return result;
}
</pre>

<p>      {@code getContentResolver().notifyChange()}.
  {@link android.provider.DocumentsContract}?
 URI.
 ,       .
 ,  {@link android.provider.DocumentsProvider#queryRoots queryRoots()}
 ,   .  ,
  ,   .</p>

<pre>private void onLoginButtonClick() {
    loginOrLogout();
    getContentResolver().notifyChange(DocumentsContract
            .buildRootsUri(AUTHORITY), null);
}
</pre>