xref: /frameworks/base/docs/html-intl/intl/pt-br/guide/topics/providers/document-provider.jd

page.title=Estrutura de acesso ao armazenamento
@jd:body
<div id="qv-wrapper">
<div id="qv">

<h2>Neste documento
 <a href="#" onclick="hideNestedItems('#toc44',this);return false;" class="header-toggle">
        <span class="more">mostrar mais</span>
        <span class="less" style="display:none">mostrar menos</span></a></h2>
<ol id="toc44" class="hide-nested">
    <li>
        <a href="#overview">Viso geral</a>
    </li>
    <li>
        <a href="#flow">Controlar fluxo</a>
    </li>
    <li>
        <a href="#client">Programao de um aplicativo cliente</a>
        <ol>
        <li><a href="#search">Busca de documentos</a></li>
        <li><a href="#process">Processamento de resultados</a></li>
        <li><a href="#metadata">Examinao de metadados de documentos</a></li>
        <li><a href="#open">Abertura de um documento</a></li>
        <li><a href="#create">Criao de um novo documento</a></li>
        <li><a href="#delete">Excluso de um documento</a></li>
        <li><a href="#edit">Edio de um documento</a></li>
        <li><a href="#permissions">Manuteno de permisses</a></li>
        </ol>
    </li>
    <li><a href="#custom">Criao de um provedor de documentos personalizado</a>
        <ol>
        <li><a href="#manifest">Manifesto</a></li>
        <li><a href="#contract">Contratos</a></li>
        <li><a href="#subclass">Subclasse DocumentsProvider</a></li>
        <li><a href="#security">Segurana</a></li>
        </ol>
    </li>

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

<h2>Vdeos</h2>

<ol>
    <li><a href="http://www.youtube.com/watch?v=zxHVeXbK1P4">
DevBytes: estrutura de acesso ao armazenamento do Android 4.4: Provedor</a></li>
     <li><a href="http://www.youtube.com/watch?v=UFj9AEz0DHQ">
DevBytes: estrutura de acesso ao armazenamento do Android 4.4: Cliente</a></li>
</ol>


<h2>Amostras de cdigo</h2>

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

<h2>Veja tambm</h2>
<ol>
    <li>
        <a href="{@docRoot}guide/topics/providers/content-provider-basics.html">
        Preceitos do provedor de contedo
        </a>
    </li>
</ol>

</div>
</div>


<p>O Android 4.4 (API de nvel 19) introduz a Estrutura de Acesso ao Armazenamento (SAF). A SAF
 simplifica para os usurios a busca e abertura de documentos, imagens e outros arquivos
dentre todos os provedores de armazenamento de documentos de preferncia. A interface grfica padro  fcil de usar
e permite aos usurios buscar arquivos e acessar arquivos recentes de modo coerente em todos os aplicativos e provedores.</p>

<p>Servios de armazenamento local ou em nuvem podem participar desse ecossistema por meio da implementao
de um {@link android.provider.DocumentsProvider} que encapsula os servios. Aplicativos
clientes que precisam acessar documentos de um provedor podem integrar-se com a SAF com apenas algumas
linhas de cdigo.</p>

<p>A SAF contm:</p>

<ul>
<li><strong>Provedor de documentos</strong> &mdash; Provedor de contedo que oferece
um servio de armazenamento (como o Google Drive) para exibir os arquivos que gerencia. O provedor de documentos
 implementado como uma subclasse da classe {@link android.provider.DocumentsProvider}.
O esquema do provedor de documento se baseia em uma hierarquia de arquivo tradicional,
embora o modo de armazenamento fsico de dados do provedor de documentos seja definido pelo programador.
A plataforma do Android contm diversos provedores de documento embutidos, como
Downloads, Imagens e Vdeos.</li>

<li><strong>Aplicativo cliente</strong> &mdash; Aplicativo personalizado que chama a inteno
{@link android.content.Intent#ACTION_OPEN_DOCUMENT}
e/ou {@link android.content.Intent#ACTION_CREATE_DOCUMENT} e recebe
os arquivos retornados pelos provedores de documentos.</li>

<li><strong>Seletor</strong> &mdash; IU de sistema que permite aos usurios acessar documentos de todos
os provedores de documentos que satisfazem os critrios de busca do aplicativo cliente.</li>
</ul>

<p>A seguir h alguns recursos oferecidos pela SAF:</p>
<ul>
<li>Permitir que usurios busquem contedo de todos os provedores de documentos, no somente de um nico aplicativo.</li>
<li>Possibilitar ao aplicativo a obteno de acesso persistente e de longo prazo
a documentos de propriedade de um provedor de documentos. Por meio deste acesso, os usurios podem adicionar, editar,
 salvar e excluir arquivos no provedor.</li>
<li> compatvel com diversas contas de usurio e razes transitrias como provedores
de armazenamento USB, que s aparecem se o dispositivo estiver plugado. </li>
</ul>

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

<p>A SAF consiste em um provedor de contedo que  uma
subclasse da classe {@link android.provider.DocumentsProvider}. Dentro de um <em>provedor de documentos</em>, os dados
so estruturados como uma hierarquia de arquivo tradicional:</p>
<p><img src="{@docRoot}images/providers/storage_datamodel.png" alt="data model" /></p>
<p class="img-caption"><strong>Figura 1.</strong> Modelo de dados do provedor de documentos Uma Raiz aponta para um nico Documento,
que ento inicia o fan-out de toda a rvore.</p>

<p>Observe o seguinte:</p>
<ul>

<li>Cada provedor de documentos relata uma ou mais
"razes", que so pontos de partida na explorao de uma rvore de documentos.
Cada raiz tem um {@link android.provider.DocumentsContract.Root#COLUMN_ROOT_ID} exclusivo
e ele aponta para um documento (um diretrio)
representando o contedo sob essa raiz.
As razes tm um projeto dinmico para oferecer compatibilidade a casos de uso como diversas contas,
dispositivos de armazenamento USB transitrios ou login/logout do usurio.</li>

<li>Sob cada raiz h um documento nico. Esse documento indica 1 a <em>N</em> documentos,
cada um deles, por sua vez, podem indicar 1 a <em>N</em> documentos. </li>

<li>Cada back-end de armazenamento apresenta
arquivos e diretrios individuais referenciando-os com um
{@link android.provider.DocumentsContract.Document#COLUMN_DOCUMENT_ID} exclusivo.
IDs de documentos devem ser exclusivos e no podem mudar depois de emitidos, pois so usados para concesses persistentes
da URI em reinicializaes do dispositivo.</li>


<li>Documentos podem ser um arquivo ou um diretrio que pode ser aberto (com um tipo MIME especfico)
 contendo documentos adicionais (com
o tipo MIME{@link android.provider.DocumentsContract.Document#MIME_TYPE_DIR}).</li>

<li>Cada documento tem diferentes recursos, como descrito por
{@link android.provider.DocumentsContract.Document#COLUMN_FLAGS COLUMN_FLAGS}.
Por exemplo,{@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_WRITE},
{@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_DELETE}
e {@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_THUMBNAIL}.
O mesmo {@link android.provider.DocumentsContract.Document#COLUMN_DOCUMENT_ID} pode ser
includo em diversos diretrios.</li>
</ul>

<h2 id="flow">Controle de fluxo</h2>
<p>Como indicado anteriormente, o modelo de dados do provedor de documentos se baseia
em uma hierarquia de arquivo tradicional. Contudo,  possvel armazenar os dados fisicamente como quiser desde
que eles possam ser acessados pela API {@link android.provider.DocumentsProvider}. Por exemplo: seria
possvel usar armazenamento em nuvem com base em tag para os dados.</p>

<p>A figura 2 ilustra um exemplo de um aplicativo de foto que usa a SAF
para acessar dados armazenados:</p>
<p><img src="{@docRoot}images/providers/storage_dataflow.png" alt="app" /></p>

<p class="img-caption"><strong>Figura 2.</strong> Fluxo da estrutura de acesso ao armazenamento</p>

<p>Observe o seguinte:</p>
<ul>

<li>Na SAF, provedores e clientes no interagem
diretamente. O cliente solicita permisso para interagir
com arquivos (ou seja, para ler, editar, criar ou excluir arquivos).</li>

<li>A interao comea quando um aplicativo (neste exemplo, um aplicativo de foto) dispara a inteno
{@link android.content.Intent#ACTION_OPEN_DOCUMENT} ou {@link android.content.Intent#ACTION_CREATE_DOCUMENT}. A inteno pode conter filtros
para refinar ainda mais os critrios &mdash; por exemplo: "quero todos os arquivos que podem ser abertos
e que tenham o tipo MIME de tal imagem".</li>

<li>Ao disparar a inteno, o seletor do sistema contata cada provedor registrado
e exibe as razes de contedo correspondentes ao usurio.</li>

<li>O seletor fornece aos usurios uma interface padro para acessar documentos,
embora os provedores de documentos subjacentes possam ser bem diferentes. Por exemplo: a figura 2
exibe um provedor do Google Drive, um provedor USB e um provedor de nuvem.</li>
</ul>

<p>A figura 3 exibe um seletor em que um usurio em busca de imagens selecionou
uma conta do Google Drive:</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>Figura 3.</strong> Seletor</p>

<p>Quando o usurio seleciona o Google Drive, as imagens so exibidas como ilustrado
na figura 4. Desse momento em diante, o usurio poder interagir com eles de todos os modos
compatveis com o provedor e o aplicativo cliente.

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

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

<h2 id="client">Programao de um aplicativo cliente</h2>

<p>No Android 4.3 e em verses anteriores, para o aplicativo recuperar um arquivo de outro
aplicativo, ele precisa chamar uma inteno como {@link android.content.Intent#ACTION_PICK}
ou {@link android.content.Intent#ACTION_GET_CONTENT}. Em seguida, o usurio deve selecionar
um nico aplicativo do qual deseja retirar um arquivo e o aplicativo selecionado deve fornecer uma interface
do usurio para a busca e a seleo dos arquivos disponveis. </p>

<p>No Android 4.4 e em verses posteriores, existe a opo adicional de usar
a inteno {@link android.content.Intent#ACTION_OPEN_DOCUMENT},
que exibe uma IU do seletor controlada pelo sistema que permite ao usurio
buscar todos os arquivos que outros aplicativos disponibilizaram. Nessa IU exclusiva,
o usurio pode selecionar um arquivo de qualquer aplicativo compatvel.</p>

<p>{@link android.content.Intent#ACTION_OPEN_DOCUMENT}
no substitui {@link android.content.Intent#ACTION_GET_CONTENT}.
O uso de cada um deles depende da necessidade do aplicativo:</p>

<ul>
<li>Use {@link android.content.Intent#ACTION_GET_CONTENT} se deseja que o aplicativo
simplesmente leia ou importe dados. Nessa abordagem, o aplicativo importa uma cpia dos dados,
assim como um arquivo de imagem.</li>

<li>Use {@link android.content.Intent#ACTION_OPEN_DOCUMENT} se deseja que o aplicativo
tenha acesso persistente e de longo prazo a documentos de propriedade de um provedor
de documentos. Um exemplo seria um aplicativo de edio de fotos que permite aos usurios editar
imagens armazenadas em um provedor de documentos. </li>

</ul>


<p>Esta seo descreve como programar aplicativos clientes com base nas intenes
{@link android.content.Intent#ACTION_OPEN_DOCUMENT}
e {@link android.content.Intent#ACTION_CREATE_DOCUMENT}.</p>


<h3 id="search">Busca de documentos</h3>

<p>
O fragmento a seguir usa {@link android.content.Intent#ACTION_OPEN_DOCUMENT}
para buscar provedores de documentos
que contenham arquivos de imagem:</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>Observe o seguinte:</p>
<ul>
<li>Quando o aplicativo dispara a inteno
{@link android.content.Intent#ACTION_OPEN_DOCUMENT}, ele aciona um seletor que exibe todos os provedores de documentos compatveis.</li>

<li>A adio da categoria {@link android.content.Intent#CATEGORY_OPENABLE}
 inteno filtra os resultados, que exibem somente documentos que podem ser abertos, como os arquivos de imagem.</li>

<li>A declarao {@code intent.setType("image/*")} filtra ainda mais
para exibir somente documentos que tm o tipo de dados MIME da imagem.</li>
</ul>

<h3 id="results">Processamento de resultados</h3>

<p>Quando o usurio seleciona um documento no seletor,
{@link android.app.Activity#onActivityResult onActivityResult()}  chamado.
A URI direcionada ao documento selecionado est presente no parmetro
{@code resultData}. Extraia a URI usando {@link android.content.Intent#getData getData()}.
Depois, ser possvel us-la para recuperar o documento que o usurio deseja. Por
exemplo:</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">Examinao de metadados de documentos</h3>

<p>Quando tiver a URI de um documento, voc ter acesso aos seus metadados. Este
fragmento apanha os metadados de um documento especificado pela URI e registra-os:</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">Abertura de um documento</h3>

<p>Assim que tiver a URI de um documento, voc poder abri-lo ou fazer o que
quiser com ele.</p>

<h4>Bitmap</h4>

<p>A seguir h um exemplo de como abrir um {@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>Observe que no se deve realizar essa operao no encadeamento da IU. Faa isso
em segundo plano usando {@link android.os.AsyncTask}. Assim que abrir o bitmap, voc
poder exibi-lo em uma {@link android.widget.ImageView}.
</p>

<h4>Obter uma InputStream</h4>

<p>Abaixo h um exemplo de como obter uma {@link java.io.InputStream} dessa URI.
Neste fragmento, as linhas do arquivo esto sendo lidas em uma string:</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">Criao de um novo documento</h3>

<p>O aplicativo pode criar um novo documento em um provedor de documentos usando
a inteno
{@link android.content.Intent#ACTION_CREATE_DOCUMENT}. Para criar um arquivo, deve-se fornecer um tipo MIME e um nome para o arquivo  inteno
e ativ-la com um cdigo de solicitao exclusivo. O resto voc no precisa fazer:</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>Ao criar um novo documento,  possvel obter sua URI
em {@link android.app.Activity#onActivityResult onActivityResult()} para que
seja possvel continuar a gravar nele.</p>

<h3 id="delete">Excluso de um documento</h3>

<p>Se voc tem uma URI de um documento
e os {@link android.provider.DocumentsContract.Document#COLUMN_FLAGS Document.COLUMN_FLAGS} do documento
 contm
{@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_DELETE SUPPORTS_DELETE},
voc pode excluir o documento. Por exemplo:</p>

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

<h3 id="edit">Edio de um documento</h3>

<p>Voc pode usar a SAF para editar o documento de texto no local em que est armazenado.
Esse fragmento dispara
a inteno {@link android.content.Intent#ACTION_OPEN_DOCUMENT} e usa
a categoria {@link android.content.Intent#CATEGORY_OPENABLE} para exibir somente
documentos que possam ser abertos. Ela filtra ainda mais para exibir somente arquivos de texto:</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>Em seguida, de {@link android.app.Activity#onActivityResult onActivityResult()}
(consulte <a href="#results">Processar resultados</a>), voc pode chamar o cdigo para realizar a edio.
O fragmento a seguir obtm um {@link java.io.FileOutputStream}
do {@link android.content.ContentResolver}. Por padro, ele usa o modo de "gravao".
Recomenda-se solicitar a menor quantidade de acesso necessria, portanto no solicite
acesso de leitura e programao se s for necessria a programao:</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">Manuteno de permisses</h3>

<p>Quando o aplicativo abre um arquivo para leitura ou programao, o sistema lhe fornece
uma concesso da permisso da URI para tal arquivo. Ela vigora at a reinicializao do dispositivo do usurio.
Contudo, suponhamos que seu aplicativo seja de edio de imagens e voc queira que os usurios
acessem as ltimas 5 imagens que editaram diretamente do aplicativo. Se o dispositivo do usurio
reiniciou, voc teria que enviar o usurio de volta ao seletor do sistema para encontrar
os arquivos, o que, obviamente, no  o ideal.</p>

<p>Para evitar que isso acontea, voc pode manter as permisses que o sistema
forneceu ao aplicativo. Efetivamente, o aplicativo "toma" a concesso de permisso da URI persistente
que o sistema est oferecendo. Isso concede ao usurio um acesso contnuo aos arquivos
por meio do aplicativo mesmo se o dispositivo for reiniciado:</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>H uma etapa final. Voc pode ter salvo as URIs
mais recentes acessadas pelo seu aplicativo, mas elas no sero mais vlidas &mdash; outro aplicativo
pode ter excludo ou modificado um documento. Portanto, deve-se sempre chamar
{@code getContentResolver().takePersistableUriPermission()} para verificar
se h dados mais recentes.</p>

<h2 id="custom">Criao de um provedor de documentos personalizado</h2>

<p>
Se voc est desenvolvimento um aplicativo que fornece servios de armazenamento para arquivos (como
um servio de armazenamento em nuvem),  possvel disponibilizar os arquivos
pela SAF criando um provedor de documentos personalizado.  Esta seo mostra
como faz-lo.</p>


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

<p>Para implementar um provedor de documentos personalizado, adicione ao manifesto
do aplicativo:</p>
<ul>

<li>Um alvo de API de nvel 19 ou posterior.</li>

<li>Um elemento <code>&lt;provider&gt;</code> que declare o provedor de armazenamento
personalizado. </li>

<li>O nome do provedor, que  o nome da classe, inclusive o nome do pacote.
Por exemplo: <code>com.example.android.storageprovider.MyCloudProvider</code>.</li>

<li>O nome da autoridade, que  o nome do pacote (neste exemplo,
<code>com.example.android.storageprovider</code>) e o tipo de provedor de contedo
(<code>documents</code>). Por exemplo: {@code com.example.android.storageprovider.documents}.</li>

<li>O atributo <code>android:exported</code> definido como <code>&quot;true&quot;</code>.
 necessrio exportar o provedor para que outros aplicativos possam v-lo.</li>

<li>O atributo <code>android:grantUriPermissions</code> definido como
<code>&quot;true&quot;</code>. Essa configurao permite ao sistema conceder acesso ao contedo
no provedor a outros aplicativos. Para ver como manter uma concesso
para determinado documento, consulte <a href="#permissions">Manuteno de permisses</a>.</li>

<li>A permisso {@code MANAGE_DOCUMENTS}. Por padro, um provedor est disponvel
para todos. A adio dessa permisso restringir o provedor em relao ao sistema.
Essa restrio  importante em termos de segurana.</li>

<li>O atributo {@code android:enabled} definido como um valor booleano determinado em um arquivo
de recursos. Esse atributo visa desativar o provedor em dispositivos que executam o Android 4.3 ou verses anteriores.
Por exemplo: {@code android:enabled="@bool/atLeastKitKat"}. Alm
disso, para incluir esse atributo no manifesto, deve-se fazer o seguinte:
<ul>
<li>No arquivo de recursos {@code bool.xml} em {@code res/values/}, adicione
esta linha: <pre>&lt;bool name=&quot;atLeastKitKat&quot;&gt;false&lt;/bool&gt;</pre></li>

<li>No arquivo de recursos {@code bool.xml} em {@code res/values-v19/}, adicione
esta linha: <pre>&lt;bool name=&quot;atLeastKitKat&quot;&gt;true&lt;/bool&gt;</pre></li>
</ul></li>

<li>Um filtro de intenes que contenha
a ao {@code android.content.action.DOCUMENTS_PROVIDER} para que o provedor
aparea no seletor quando o sistema procurar provedores.</li>

</ul>
<p>Abaixo h alguns excertos de amostra de um manifesto que contm um provedor:</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">Compatibilidade com dispositivos que executam Android 4.3 ou anterior</h4>

<p>
A inteno {@link android.content.Intent#ACTION_OPEN_DOCUMENT} est disponvel somente
em dispositivos que executam o Android 4.4 ou posteriores.
Se voc deseja que o aplicativo seja compatvel com {@link android.content.Intent#ACTION_GET_CONTENT}
para adaptar-se a dispositivos que executam o Android 4.3 ou verses anteriores,  necessrio
desativar o filtro de inteno {@link android.content.Intent#ACTION_GET_CONTENT}
no manifesto para dispositivos que executam Android 4.4 ou verses posteriores.
Um provedor de documentos e {@link android.content.Intent#ACTION_GET_CONTENT} devem ser avaliados
de forma mutuamente exclusiva. Se houver compatibilidade com ambos simultaneamente, o aplicativo
aparecer duas vezes na IU do seletor do sistema, oferecendo dois meios de acesso
diferentes aos dados armazenados. Isso pode confundir os usurios.</p>

<p>A seguir apresenta-se a forma recomendada de desativar
o filtro de intenes {@link android.content.Intent#ACTION_GET_CONTENT} para dispositivos
que executam o Android 4.4 ou verses posteriores:</p>

<ol>
<li>No arquivo de recursos {@code bool.xml} em {@code res/values/}, adicione
esta linha: <pre>&lt;bool name=&quot;atMostJellyBeanMR2&quot;&gt;true&lt;/bool&gt;</pre></li>

<li>No arquivo de recursos {@code bool.xml} em {@code res/values-v19/}, adicione
esta linha: <pre>&lt;bool name=&quot;atMostJellyBeanMR2&quot;&gt;false&lt;/bool&gt;</pre></li>

<li>Adicione
um <a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">alias
de atividade</a> para desativar o filtro de intenes
{@link android.content.Intent#ACTION_GET_CONTENT} para verses 4.4 (API de nvel 19) e posteriores. Por exemplo:

<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">Contratos</h3>

<p>Normalmente, ao criar um provedor de contedo personalizado, uma das tarefas
 implementar classes de contrato, como descrito
no guia dos desenvolvedores de<a href="{@docRoot}guide/topics/providers/content-provider-creating.html#ContractClass">
Provedores de contedo</a>. Classe de contrato  uma classe {@code public final}
que contm definies constantes das URIs, nomes de coluna, tipos MIME
e outros metadados que pertencem ao provedor. A SAF
fornece essas classes de contrato, portanto no  necessrio
program-las:</p>

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

<p>Por exemplo, eis as colunas que podem retornar em um cursor
ao consultar documentos ou a raiz do provedor de documentos:</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">Subclasse DocumentsProvider</h3>

<p>A prxima etapa na criao de um provedor de documentos personalizado  atribuir uma subclasse 
classe {@link android.provider.DocumentsProvider} abstrata. No mnimo,  necessrio
implementar os seguintes mtodos:</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>Esses so os nicos mtodos que obrigatoriamente devem ser implementados, mas h
muitos outros que podem ser usados. Consulte {@link android.provider.DocumentsProvider}
para ver mais detalhes.</p>

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

<p>A implementao de {@link android.provider.DocumentsProvider#queryRoots
queryRoots()} deve retornar um {@link android.database.Cursor} que aponta para todos
os diretrios raiz dos provedores de documentos, usando colunas definidas
em {@link android.provider.DocumentsContract.Root}.</p>

<p>No fragmento a seguir, o parmetro {@code projection} representa
os campos especficos que o autor da chamada quer receber de volta. O fragmento cria um novo cursor
e adiciona-lhe uma linha &mdash; uma raiz, um diretrio de nvel superior, como
Downloads ou Imagens.  A maioria dos provedores tem somente uma raiz.  possvel ter mais de uma,
por exemplo, no caso de diversas contas de usurio. Nesse caso, adicione somente
uma segunda linha ao cursor.</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">Implementao de queryChildDocuments</h4>

<p>A implementao
de {@link android.provider.DocumentsProvider#queryChildDocuments queryChildDocuments()}
deve retornar um {@link android.database.Cursor} que aponta para todos os arquivos
no diretrio especificado com colunas definidas em
{@link android.provider.DocumentsContract.Document}.</p>

<p>Esse mtodo  chamado quando uma raiz do aplicativo  escolhida na IU do seletor.
Ele coleta os documentos filhos de um diretrio na raiz.  Ele pode ser chamado em qualquer nvel
na hierarquia de arquivos, no somente na raiz. Esse fragmento
cria um novo cursor com as colunas solicitadas e, em seguida, adiciona informaes ao cursor
sobre cada filho imediato no diretrio pai.
O filho pode ser uma imagem, outro diretrio &mdash; qualquer arquivo:</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">Implementao de queryDocument</h4>

<p>A implementao de
{@link android.provider.DocumentsProvider#queryDocument queryDocument()}
deve retornar um {@link android.database.Cursor} que aponta para o arquivo especificado
com colunas definidas em {@link android.provider.DocumentsContract.Document}.
</p>

<p>O mtodo {@link android.provider.DocumentsProvider#queryDocument queryDocument()}
retorna as mesmas informaes passadas em
{@link android.provider.DocumentsProvider#queryChildDocuments queryChildDocuments()},
mas para um arquivo especfico.</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">Implementao de openDocument</h4>

<p>Deve-se implementar {@link android.provider.DocumentsProvider#openDocument
openDocument()} para retornar um {@link android.os.ParcelFileDescriptor} que represente
o arquivo especificado. Outros aplicativos podem usar o {@link android.os.ParcelFileDescriptor} retornado
para transmitir dados. O sistema chama esse mtodo quando o usurio seleciona um arquivo
e o aplicativo cliente solicita acesso a ele chamando
{@link android.content.ContentResolver#openFileDescriptor openFileDescriptor()}.
Por exemplo:</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">Segurana</h3>

<p>Suponha que o provedor de documentos seja um servio de armazenamento em nuvem protegido por senha
e que voc queira certificar-se de que os usurios estejam conectados antes de iniciar o compartilhamento dos arquivos.
O que o aplicativo deve fazer se o usurio no estiver conectado?  A soluo  retornar
zero raiz na implementao de {@link android.provider.DocumentsProvider#queryRoots
queryRoots()}, ou seja, um cursor de raiz vazio:</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>A outra etapa  chamar {@code getContentResolver().notifyChange()}.
Lembra-se do {@link android.provider.DocumentsContract}?  Estamos usando-o para criar
esta URI. O fragmento a seguir pede ao sistema que consulte as razes
do provedor de documentos sempre que o status de login do usurio mudar. Se o usurio no estiver
conectado, uma chamada de {@link android.provider.DocumentsProvider#queryRoots queryRoots()} retornar um
cursor vazio, como exibido anteriormente. Isso garante que os documentos do provedor estejam
disponveis somente se o usurio tiver acesso ao provedor.</p>

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