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

page.title=Khun kh Truy cp Kho lu tr
@jd:body
<div id="qv-wrapper">
<div id="qv">

<h2>Trong ti liu ny
 <a href="#" onclick="hideNestedItems('#toc44',this);return false;" class="header-toggle">
        <span class="more">hin nhiu hn</span>
        <span class="less" style="display:none">hin t hn</span></a></h2>
<ol id="toc44" class="hide-nested">
    <li>
        <a href="#overview">Tng quan</a>
    </li>
    <li>
        <a href="#flow">Dng iu khin</a>
    </li>
    <li>
        <a href="#client">Ghi mt ng dng My khch</a>
        <ol>
        <li><a href="#search">Tm kim ti liu</a></li>
        <li><a href="#process">Kt qu tin trnh</a></li>
        <li><a href="#metadata">Kim tra siu d liu ti liu</a></li>
        <li><a href="#open">M mt ti liu</a></li>
        <li><a href="#create">To mt ti liu mi</a></li>
        <li><a href="#delete">Xa mt ti liu</a></li>
        <li><a href="#edit">Chnh sa mt ti liu</a></li>
        <li><a href="#permissions">C nh cc quyn</a></li>
        </ol>
    </li>
    <li><a href="#custom">Ghi mt Trnh cung cp Ti liu Ty chnh</a>
        <ol>
        <li><a href="#manifest">Bn k khai</a></li>
        <li><a href="#contract">Hp ng</a></li>
        <li><a href="#subclass">Phn lp con DocumentsProvider</a></li>
        <li><a href="#security">Bo mt</a></li>
        </ol>
    </li>

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

<h2>Video</h2>

<ol>
    <li><a href="http://www.youtube.com/watch?v=zxHVeXbK1P4">
DevBytes: Khun kh Truy cp Kho lu tr Android 4.4: Trnh cung cp</a></li>
     <li><a href="http://www.youtube.com/watch?v=UFj9AEz0DHQ">
DevBytes: Khun kh Truy cp Kho lu tr Android 4.4: My khch</a></li>
</ol>


<h2>M V d</h2>

<ol>
    <li><a href="{@docRoot}samples/StorageProvider/index.html">
Trnh cung cp Lu tr</a></li>
     <li><a href="{@docRoot}samples/StorageClient/index.html">
StorageClient</a></li>
</ol>

<h2>Xem thm</h2>
<ol>
    <li>
        <a href="{@docRoot}guide/topics/providers/content-provider-basics.html">
        Ni dung C bn v Trnh cung cp Ni dung
        </a>
    </li>
</ol>

</div>
</div>


<p>Android 4.4 (API mc 19) gii thiu Khun kh Truy cp Kho lu tr (SAF). SAF
 gip ngi dng n gin ha vic duyt v m ti liu, hnh nh v cc tp khc
gia tt c trnh cung cp lu tr ti liu m h thch. UI tiu chun, d s dng
cho php ngi dng duyt tp v truy cp hot ng gn y mt cch nht qun gia cc ng dng v trnh cung cp.</p>

<p>Dch v lu tr m my hoc cc b c th tham gia vo h sinh thi ny bng cch trin khai mt
{@link android.provider.DocumentsProvider}  gi gn cc dch v ca mnh. Nhng ng dng
my khch cn truy cp vo ti liu ca mt trnh cung cp c th tch hp vi SAF ch bng mt vi
dng m.</p>

<p>SAF bao gm:</p>

<ul>
<li><strong>Trnh cung cp ti liu</strong>&mdash;Mt trnh cung cp ni dung cho php mt
dch v lu tr (chng hn nh Google Drive) pht hin cc tp m n qun l. Trnh cung cp ti liu c
trin khai thnh mt lp con ca lp {@link android.provider.DocumentsProvider}.
S  ti liu-trnh cung cp s c da trn mt phn cp tp truyn thng,
cho d cch thc trnh cung cp ti liu ca bn trc tip lu tr d liu l hon ton do bn.
Nn tng Android bao gm mt vi trnh cung cp ti liu tch hp, chng hn nh
Downloads, Images, v Videos.</li>

<li><strong>ng dng my khch</strong>&mdash;Mt ng dng ty chnh c chc nng gi ra  nh
{@link android.content.Intent#ACTION_OPEN_DOCUMENT} v/hoc
{@link android.content.Intent#ACTION_CREATE_DOCUMENT} v nhn cc tp
c tr v bi trnh cung cp ti liu.</li>

<li><strong>B chn</strong>&mdash;Mt UI h thng cho php ngi dng truy cp ti liu t tt c
trnh cung cp ti liu m tha mn cc tiu ch tm kim ca ng dng my khch.</li>
</ul>

<p>Mt s tnh nng c SAF cung cp bao gm:</p>
<ul>
<li>Cho php ngi dng duyt ni dung t tt c trnh cung cp ti liu, khng ch mt ng dng duy nht.</li>
<li>Gip ng dng ca bn c th c quyn truy cp lu di, c nh vo
 cc ti liu c s hu bi mt trnh cung cp ti liu. Thng qua truy cp ny, ngi dng c th thm, chnh sa,
 lu v xa tp trn trnh cung cp.</li>
<li>H tr nhiu ti khon ngi dng v cc phn gc tm thi chng hn nh trnh cung cp
b nh USB, n ch xut hin nu  a c cm vo. </li>
</ul>

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

<p>SAF tp trung xoay quanh mt trnh cung cp ni dung l mt lp con
ca lp {@link android.provider.DocumentsProvider}. Trong mt <em>trnh cung cp ti liu</em>, d liu c
cu trc thnh mt phn cp tp truyn thng:</p>
<p><img src="{@docRoot}images/providers/storage_datamodel.png" alt="data model" /></p>
<p class="img-caption"><strong>Hnh 1.</strong> M hnh d liu ca trnh cung cp ti liu. Mt Phn gc ch n mt Ti liu duy nht,
sau  n bt u xe ra ton b cy.</p>

<p>Lu  iu sau y:</p>
<ul>

<li>Mi mt trnh cung cp ti liu s bo co mt hoc nhiu
"phn gc" l im bt u khm ph cy ti liu.
Mi phn gc c mt {@link android.provider.DocumentsContract.Root#COLUMN_ROOT_ID} duy nht,
v n tr n mt ti liu (th mc)
biu din ni dung bn di phn gc .
Phn gc c th linh hot theo thit k  h tr cc trng hp s dng nh nhiu ti khon,
thit b lu tr USB tm thi, hoc ng nhp/ng xut ngi dng.</li>

<li>Di mi phn gc l mt ti liu n l. Ti liu  s tr ti 1 n <em>N</em> ti liu,
mi ti liu li c th tr ti 1 n <em>N</em> ti liu khc. </li>

<li>Mi b nh ph tr ph b mt
cc tp v th mc ring l bng cch tham chiu chng bng mt
{@link android.provider.DocumentsContract.Document#COLUMN_DOCUMENT_ID} duy nht.
ID ca ti liu phi l duy nht v khng thay i sau khi c pht hnh, do chng c s dng  cp URI
khng thay i gia cc ln khi ng li thit b.</li>


<li>Ti liu c th l mt tp m c (c mt kiu MIME c th), hoc mt
th mc cha cc ti liu b sung (c kiu MIME 
{@link android.provider.DocumentsContract.Document#MIME_TYPE_DIR}).</li>

<li>Mi ti liu c th c cc kh nng khc nhau nh c m t bi
{@link android.provider.DocumentsContract.Document#COLUMN_FLAGS COLUMN_FLAGS}.
V d, {@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_WRITE},
{@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_DELETE}, v
{@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_THUMBNAIL}.
{@link android.provider.DocumentsContract.Document#COLUMN_DOCUMENT_ID} cng c th
c trong nhiu th mc.</li>
</ul>

<h2 id="flow">Dng iu khin</h2>
<p>Nh nu trn, m hnh d liu ca trnh cung cp ti liu c da trn mt phn cp
tp truyn thng. Tuy nhin, bn c th thc t lu tr d liu ca mnh bng bt k cch no m mnh thch, min
l n c th c truy cp thng qua API {@link android.provider.DocumentsProvider}. V d, bn
c th s dng kho lu tr m my da trn tag cho d liu ca mnh.</p>

<p>Hnh 2 minh ha mt v d v cch m mt ng dng nh c th s dng SAF
 truy cp d liu c lu tr:</p>
<p><img src="{@docRoot}images/providers/storage_dataflow.png" alt="app" /></p>

<p class="img-caption"><strong>Hnh 2.</strong> Dng Khun kh Truy cp Kho lu tr</p>

<p>Lu  iu sau y:</p>
<ul>

<li>Trong SAF, trnh cung cp v my khch khng tng tc
trc tip vi nhau. Mt my khch yu cu quyn  tng tc
vi tp (c th l quyn c, chnh sa, to hoc xa tp).</li>

<li>Tng tc bt u khi mt ng dng (trong v d ny ny mt ng dng nh) th hin  nh 
{@link android.content.Intent#ACTION_OPEN_DOCUMENT} hoc {@link android.content.Intent#ACTION_CREATE_DOCUMENT}.  nh c th bao gm cc b lc
 c th hn cc tiu ch&mdash;v d, "cp cho ti tt c tp m c
c kiu MIME l 'image'."</li>

<li>Sau khi  nh th hin, b chn ca h thng s i n tng trnh cung cp c ng k
v hin th cho ngi dng xem cc phn gc ni dung khp vi tiu ch.</li>

<li>B chn cp cho ngi dng mt giao din tiu chun  truy cp ti liu, mc
d cc trnh cung cp ti liu lin quan c th rt khc nhau. V d, hnh 2
minh ha mt trnh cung cp Google Drive, mt trnh cung cp USB, v mt trnh cung cp m my.</li>
</ul>

<p>Hnh 3 minh ha mt b chn m trong  mt ngi dng ang tm kim hnh nh  chn mt
ti khon 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>Hnh 3.</strong> B chn</p>

<p>Khi ngi dng chn Google Drive, hnh nh c hin th nh minh ha trong
hnh 4. T im  tr i, ngi dng c th tng tc vi chng theo bt k cch no
c h tr bi trnh cung cp v ng dng my khch.

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

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

<h2 id="client">Ghi mt ng dng My khch</h2>

<p>Trn phin bn Android 4.3 v thp hn, nu bn mun ng dng ca mnh truy xut mt tp t mt ng dng
khc, n phi gi ra mt  nh chng hn nh {@link android.content.Intent#ACTION_PICK}
hay {@link android.content.Intent#ACTION_GET_CONTENT}. Khi , ngi dng phi chn
mt ng dng duy nht m t  h chn mt tp v ng dng c chn phi cung cp mt
giao din ngi dng  ngi dng duyt v chn t cc tp c sn. </p>

<p>Trn phin bn Android 4.4 tr ln, bn c thm mt ty chn l s dng  nh
{@link android.content.Intent#ACTION_OPEN_DOCUMENT},
n hin th mt UI b chn c iu khin bi h thng, cho php ngi dng
duyt tt c tp m cc ng dng khc  cung cp. T UI duy nht ny, ngi dng
c th chn mt tp t bt k ng dng no c h tr.</p>

<p>{@link android.content.Intent#ACTION_OPEN_DOCUMENT} khng
nhm mc ch thay th cho {@link android.content.Intent#ACTION_GET_CONTENT}.
Bn nn s dng ci no s ph thuc vo nhu cu ca ng dng ca bn:</p>

<ul>
<li>S dng {@link android.content.Intent#ACTION_GET_CONTENT} nu bn mun ng dng ca mnh
ch n thun c/nhp d liu. Bng cch ny, ng dng nhp mt bn sao d liu,
chng hn nh mt tp hnh nh.</li>

<li>S dng {@link android.content.Intent#ACTION_OPEN_DOCUMENT} nu bn mun ng dng
ca mnh c quyn truy cp lu di, c nh vo cc ti liu c s hu bi mt
trnh cung cp ti liu. V d nh trng hp mt ng dng chnh sa nh cho php ngi dng chnh sa
cc hnh nh c lu tr trong mt trnh cung cp ti liu. </li>

</ul>


<p>Phn ny m t cch ghi cc ng dng my khch da trn
{@link android.content.Intent#ACTION_OPEN_DOCUMENT} v
cc  nh {@link android.content.Intent#ACTION_CREATE_DOCUMENT}.</p>


<h3 id="search">Tm kim ti liu</h3>

<p>
on m HTML sau s dng {@link android.content.Intent#ACTION_OPEN_DOCUMENT}
 tm kim cc trnh cung cp ti liu m
cha tp hnh nh:</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>Lu  iu sau y:</p>
<ul>
<li>Khi ng dng th hin  nh {@link android.content.Intent#ACTION_OPEN_DOCUMENT}
, n s khi chy mt b chn  hin th tt c trnh cung cp ti liu khp vi tiu ch.</li>

<li>Thm th loi {@link android.content.Intent#CATEGORY_OPENABLE} vo
 nh s lc kt qu  ch hin th nhng ti liu c th m c, chng hn nh tp hnh nh.</li>

<li>Cu lnh {@code intent.setType("image/*")} s lc thm 
ch hin th nhng ti liu c kiu d liu MIME hnh nh.</li>
</ul>

<h3 id="results">Kt qu Tin trnh</h3>

<p>Sau khi ngi dng chn mt ti liu trong b chn,
{@link android.app.Activity#onActivityResult onActivityResult()} s c gi.
URI tro ti ti liu c chn s nm trong tham s {@code resultData}
. Trch xut UI bng cch s dng {@link android.content.Intent#getData getData()}.
Sau khi c n, bn c th s dng n  truy xut ti liu m ngi dng mun. V
d:</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">Kim tra siu d liu ti liu</h3>

<p>Sau khi c URI cho mt ti liu, bn c quyn truy cp siu d liu ca n. on m HTML
ny bt siu d liu cho mt ti liu c quy nh bi URI, v ghi li n:</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">M mt ti liu</h3>

<p>Sau khi c URI cho mt ti liu, bn c th m n hoc lm bt k iu g
m bn mun.</p>

<h4>Bitmap</h4>

<p>Sau y l mt v d v cch bn c th m mt {@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>Lu  rng bn khng nn thc hin thao tc ny trn lung UI. Thc hin iu ny di
nn bng cch s dng {@link android.os.AsyncTask}. Sau khi m bitmap, bn c th
hin th n trong mt {@link android.widget.ImageView}.
</p>

<h4>Nhn mt InputStream</h4>

<p>Sau y l mt v d v cch m bn c th nhn mt {@link java.io.InputStream} t URI. Trong on m HTML
ny, cc dng tp ang c c thnh mt xu:</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">To mt ti liu mi</h3>

<p>ng dng ca bn c th to mt ti liu mi trong mt trnh cung cp ti liu bng cch s dng  nh
{@link android.content.Intent#ACTION_CREATE_DOCUMENT}
.  to mt tp, bn cp cho  nh ca mnh mt kiu MIME v tn tp, v
khi chy n bng mt m yu cu duy nht. Phn cn li s c lm h bn:</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>Sau khi to mt ti liu mi, bn c th nhn URI ca ti liu trong
{@link android.app.Activity#onActivityResult onActivityResult()}, sao cho bn
c th tip tc ghi n.</p>

<h3 id="delete">Xa mt ti liu</h3>

<p>Nu bn c URI cho mt ti liu v
{@link android.provider.DocumentsContract.Document#COLUMN_FLAGS Document.COLUMN_FLAGS}
ca ti liu cha
{@link android.provider.DocumentsContract.Document#FLAG_SUPPORTS_DELETE SUPPORTS_DELETE},
bn c th xa ti liu . V d:</p>

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

<h3 id="edit">Chnh sa mt ti liu</h3>

<p>Bn c th s dng SAF  chnh sa mt ti liu vn bn ngay ti ch.
on m HTML ny th hin
 nh {@link android.content.Intent#ACTION_OPEN_DOCUMENT} v s dng
th loi {@link android.content.Intent#CATEGORY_OPENABLE}  ch hin th
nhng ti liu c th m c. N lc thm  ch hin th nhng tp vn bn:</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>Tip theo, t {@link android.app.Activity#onActivityResult onActivityResult()}
(xem <a href="#results">Kt qu tin trnh</a>) bn c th gi m  thc hin chnh sa.
on m HTML sau nhn c mt {@link java.io.FileOutputStream}
t {@link android.content.ContentResolver}. Theo mc nh, n s dng ch  ghi.
Cch tt nht l yu cu lng quyn truy cp bn cn  mc t nht, v th ng yu cu
quyn c/ghi nu bn ch cn quyn ghi:</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">C nh cc quyn</h3>

<p>Khi ng dng ca bn m mt tp  c hoc ghi, h thng s cp cho
ng dng ca bn mt quyn URI c cp cho tp . Quyn ny s ko di ti khi thit b ca bn khi ng li.
Nhng gi s ng dng ca bn l mt ng dng chnh sa hnh nh, v bn mun ngi dng c th
truy cp 5 hnh nh cui cng m h  chnh sa, trc tip t ng dng ca bn. Nu thit b ca ngi dng
 khi ng li, bn s phi gi ngi dng tr li b chn h thng  tm
cc tp , y r rng khng phi l cch l tng.</p>

<p> trnh iu ny xy ra, bn c th c nh cc quyn m h thng
cp cho ng dng ca bn. ng dng ca bn s "nhn" cp quyn URI c th c nh
m h thng cung cp mt cch hiu qu. iu ny cho php ngi dng c quyn lin tc truy cp cc tp 
thng qua ng dng ca bn, ngay c khi thit b  b khi ng li:</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>Cn mt bc cui cng. Bn c th  lu cc
URI gn y nht m ng dng ca bn  truy cp, nhng chng cn th khng cn hp l&mdash;mt ng dng khc
c th  xa hoc sa i ti liu. V th, bn lun nn gi
{@code getContentResolver().takePersistableUriPermission()}  kim tra
d liu mi nht.</p>

<h2 id="custom">Ghi mt Trnh cung cp Ti liu Ty chnh</h2>

<p>
Nu bn ang pht trin mt ng dng cung cp dch v lu tr cho tp (chng hn nh
mt dch v lu tr m my), bn c th cung cp cc tp ca mnh thng qua
SAF bng cch ghi mt trnh cung cp ti liu ty chnh.  Phn ny m t cch lm iu
ny.</p>


<h3 id="manifest">Bn k khai</h3>

<p> trin khai mt trnh cung cp ti liu ty chnh, hy thm ni dung sau vo bn k khai
ca ng dng ca bn:</p>
<ul>

<li>Mt mc tiu API mc 19 hoc cao hn.</li>

<li>Mt phn t <code>&lt;provider&gt;</code> khai bo trnh cung cp lu tr
ty chnh ca bn. </li>

<li>Tn ca trnh cung cp ca bn, l tn lp ca n, bao gm tn gi.
V d: <code>com.example.android.storageprovider.MyCloudProvider</code>.</li>

<li>Tn thm quyn ca bn, tc l tn gi ca bn (trong v d ny l
<code>com.example.android.storageprovider</code>) cng vi kiu ca trnh cung cp ni dung
(<code>documents</code>). V d, {@code com.example.android.storageprovider.documents}.</li>

<li>Thuc tnh <code>android:exported</code> c t thnh <code>&quot;true&quot;</code>.
Bn phi xut trnh cung cp ca mnh  cc ng dng khc c th thy n.</li>

<li>Thuc tnh <code>android:grantUriPermissions</code> c t thnh
<code>&quot;true&quot;</code>. Thit t ny cho php h thng cp cho cc ng dng khc quyn truy cp
vo ni dung trong trnh cung cp ca bn.  tho lun v cch c nh quyn c cp cho
mt ti liu c th, hy xem phn<a href="#permissions">C nh cc quyn</a>.</li>

<li>Quyn {@code MANAGE_DOCUMENTS}. Theo mc nh, mt trnh cung cp s c sn
i vi mi ngi. Vic thm quyn ny s hn ch trnh cung cp ca bn vo h thng.
Hn ch ny c  ngha quan trng i vi vn  bo mt.</li>

<li>Thuc tnh {@code android:enabled} c t thnh mt gi tr boolean c nh ngha trong mt tp
ti nguyn. Mc ch ca thuc tnh ny l  v hiu ha trnh cung cp trn cc thit b chy phin bn Android 4.3 hoc thp hn.
V d, {@code android:enabled="@bool/atLeastKitKat"}. Bn
cnh vic nu thuc tnh ny trong bn k khai, bn cn lm nh sau:
<ul>
<li>Trong tp ti nguyn {@code bool.xml} ca bn bn di {@code res/values/}, hy thm
dng sau: <pre>&lt;bool name=&quot;atLeastKitKat&quot;&gt;false&lt;/bool&gt;</pre></li>

<li>Trong tp ti nguyn {@code bool.xml} ca bn bn di {@code res/values-v19/}, hy thm
dng sau: <pre>&lt;bool name=&quot;atLeastKitKat&quot;&gt;true&lt;/bool&gt;</pre></li>
</ul></li>

<li>Mt b lc  nh cha hnh ng
{@code android.content.action.DOCUMENTS_PROVIDER}, sao cho trnh cung cp ca bn
xut hin trong b chn khi h thng tm kim trnh cung cp.</li>

</ul>
<p>Sau y l cc on trch t mt bn k khai mu cha mt trnh cung cp:</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">H tr cc thit b chy phin bn Android 4.3 v thp hn</h4>

<p> nh
{@link android.content.Intent#ACTION_OPEN_DOCUMENT} ch c sn
trn cc thit b chy phin bn Android 4.4 tr ln.
Nu bn mun ng dng ca mnh h tr {@link android.content.Intent#ACTION_GET_CONTENT}
 to iu kin cho cc thit b ang chy phin bn Android 4.3 v thp hn, bn nn
v hiu ha b lc  nh {@link android.content.Intent#ACTION_GET_CONTENT} trong
bn k khai ca bn cho cc thit b chy phin bn Android 4.4 tr ln. Mt
trnh cung cp ti liu v {@link android.content.Intent#ACTION_GET_CONTENT} nn c xem xt
 loi tr ln nhau. Nu bn h tr c hai ng thi, ng dng ca bn s
xut hin hai ln trong UI ca b chn h thng, a ra hai cch khc nhau  truy cp
d liu  lu ca bn. iu ny c th khin ngi dng b nhm ln.</p>

<p>Sau y l cch c khuyn co  v hiu ha b lc  nh
{@link android.content.Intent#ACTION_GET_CONTENT} i vi cc thit b
chy phin bn Android 4.4 hoc cao hn:</p>

<ol>
<li>Trong tp ti nguyn {@code bool.xml} ca bn bn di {@code res/values/}, hy thm
dng sau: <pre>&lt;bool name=&quot;atMostJellyBeanMR2&quot;&gt;true&lt;/bool&gt;</pre></li>

<li>Trong tp ti nguyn {@code bool.xml} ca bn bn di {@code res/values-v19/}, hy thm
dng sau: <pre>&lt;bool name=&quot;atMostJellyBeanMR2&quot;&gt;false&lt;/bool&gt;</pre></li>

<li>Thm mt
<a href="{@docRoot}guide/topics/manifest/activity-alias-element.html">b danh
hot ng</a>  v hiu ha b lc  nh {@link android.content.Intent#ACTION_GET_CONTENT}
i vi cc phin bn 4.4 (API mc 19) tr ln. V d:

<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">Hp ng</h3>

<p>Thng khi bn ghi mt trnh cung cp ni dung ty chnh, mt trong nhng tc v  l
trin khai cc lp hp ng nh c m t trong hng dn cho nh pht trin
<a href="{@docRoot}guide/topics/providers/content-provider-creating.html#ContractClass">
Trnh cung cp Ni dung</a>. Lp hp ng l mt lp {@code public final} m
cha cc nh ngha hng s cho URI, tn ct, kiu MIME v
siu d liu khc lin quan ti trnh cung cp. SAF
cung cp nhng lp hp ng ny cho bn, v th bn khng cn t
ghi:</p>

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

<p>V d, sau y l cc ct bn c th tr v trong mt con chy khi
trnh cung cp ti liu ca bn c truy vn v ti liu hoc phn gc:</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">Phn lp con DocumentsProvider</h3>

<p>Bc tip theo trong khi ghi mt trnh cung cp ti liu ty chnh  l phn lp con
cho lp tm tt {@link android.provider.DocumentsProvider}. Ti thiu, bn cn trin khai
cc phng php sau:</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>y l nhng phng php duy nht m bn c yu cu phi trin khai, nhng cn
nhiu phng php na m bn c th mun trin khai. Xem {@link android.provider.DocumentsProvider}
 bit chi tit.</p>

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

<p>Vic bn trin khai {@link android.provider.DocumentsProvider#queryRoots
queryRoots()} phi tr v mt {@link android.database.Cursor} tr v tt c
th mc gc trong trnh cung cp ti liu ca bn, bng cch s dng cc ct c nh ngha trong
{@link android.provider.DocumentsContract.Root}.</p>

<p>Trong on m HTML sau, tham s {@code projection} biu din cc trng c th
m hm gi mun nhn v. on m HTML to mt con chy mi
v thm mt hng vo n&mdash;mt th mc gc, mc cao nht, nh
Downloads hoc Images.  Hu ht cc trnh cung cp ch c mt phn gc. Bn c th c nhiu hn mt,
v d, trong trng hp nhiu ti khon ngi dng. Trong trng hp , ch cn thm mt
hng th hai vo con chy.</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">Trin khai queryChildDocuments</h4>

<p>Vic bn trin khai
{@link android.provider.DocumentsProvider#queryChildDocuments queryChildDocuments()}
phi tr v mt {@link android.database.Cursor} m ch n tt c tp trong
th mc c ch nh, bng cch s dng cc ct c nh ngha trong
{@link android.provider.DocumentsContract.Document}.</p>

<p>Phng php ny c gi khi bn chn mt th mc gc ng dng trong UI b chn.
N nhn c ti liu con ca mt th mc nm di phn gc.  N c th c gi  bt k mc no trong phn cp tp
, khng ch phn gc. on m HTML
ny to mt con chy mi bng cc ct c yu cu, sau  thm thng tin v
mi tp con trc tip trong th mc m vo con chy.
Tp con c th l mt hnh nh, mt th mc khc&mdash;bt k tp no:</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">Trin khai queryDocument</h4>

<p>Vic bn trin khai
{@link android.provider.DocumentsProvider#queryDocument queryDocument()}
phi tr v mt {@link android.database.Cursor} m ch n tp c ch nh,
bng cch s dng cc ct c nh ngha trong {@link android.provider.DocumentsContract.Document}.
</p>

<p>Phng php {@link android.provider.DocumentsProvider#queryDocument queryDocument()}
tr v cng thng tin  c chuyn trong
{@link android.provider.DocumentsProvider#queryChildDocuments queryChildDocuments()},
nhng l i vi mt tp c th:</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">Trin khai openDocument</h4>

<p>Bn phi trin khai {@link android.provider.DocumentsProvider#openDocument
openDocument()}  tr v mt {@link android.os.ParcelFileDescriptor} biu din
tp c ch nh. Cc ng dng khc c th s dng {@link android.os.ParcelFileDescriptor}
c tr v  truyn pht d liu. H thng gi phng php ny sau khi ngi dng chn mt tp
v ng dng my khch yu cu truy cp n bng cch gi
{@link android.content.ContentResolver#openFileDescriptor openFileDescriptor()}.
V d:</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">Bo mt</h3>

<p>Gi s trnh cung cp ti liu ca bn l mt dch v lu tr m my c bo v bng mt khu
v bn mun m bo rng ngi dng c ng nhp trc khi bn bt u chia s tp ca h.
ng dng ca bn nn lm g nu ngi dng khng ng nhp?  Gii php l tr v
phn gc 0 trong trin khai {@link android.provider.DocumentsProvider#queryRoots
queryRoots()} ca bn. C th l mt con chy gc trng:</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>Bc cn li l gi {@code getContentResolver().notifyChange()}.
Bn cn nh {@link android.provider.DocumentsContract} ch?  Chng ta ang s dng n  to
URI ny. on m HTML sau bo cho h thng truy vn cc phn gc trong
trnh cung cp ti liu ca bn bt c khi no trng thi ng nhp ca ngi dng thay i. Nu ngi dng khng c
ng nhp, lnh gi ti {@link android.provider.DocumentsProvider#queryRoots queryRoots()} s tr v mt
con chy trng nh minh ha bn trn. iu ny m bo rng ti liu ca mt trnh cung cp ch
c sn nu ngi dng ng nhp vo trnh cung cp .</p>

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