1page.title=特定のディレクトリへのアクセス
2page.keywords=preview,sdk,scoped directory access
3page.tags=androidn
4
5@jd:body
6
7<div id="qv-wrapper">
8<div id="qv">
9  <h2>このドキュメントの内容</h2>
10  <ol>
11    <li><a href="#accessing">外部ストレージのディレクトリへのアクセス</a></li>
12    <li><a href="#removable">リムーバブル メディアのディレクトリへのアクセス</a></li>
13    <li><a href="#best">ベスト プラクティス</a></li>
14  </ol>
15</div>
16</div>
17
18<p>写真アプリなどは通常、外部ストレージの特定のディレクトリ（<code>Pictures</code> ディレクトリなど）のみにアクセスする必要があります。
19外部ストレージへのアクセスに関する従来のアプローチでは、このようなアプリに目的のディレクトリへのアクセスを容易に提供できる設計にはなっていませんでした。
20
21次に例を示します。</p>
22
23<ul>
24<li>マニフェストで {@link android.Manifest.permission#READ_EXTERNAL_STORAGE} または {@link android.Manifest.permission#WRITE_EXTERNAL_STORAGE} を要求すると、外部ストレージ上のすべての公開ディレクトリにアクセスできますが、この場合、アプリが必要な場所以外にもアクセスできることになります。
25
26
27</li>
28<li><a href="{@docRoot}guide/topics/providers/document-provider.html">ストレージ アクセス フレームワーク</a>を使用すると、通常、ユーザーはシステム UI を使用してディレクトリを選択できますが、アプリが常に同じ外部ディレクトリにアクセスする場合、この選択は不要です。
29
30
31
32</li>
33</ul>
34
35<p>Android N では、一般的な外部ストレージ ディレクトリにアクセスできる、新しいシンプルな API を提供します。
36 </p>
37
38<h2 id="accessing">外部ストレージのディレクトリへのアクセス</h2>
39
40<p><code>StorageManager</code> クラスを使用して、適切な
41<code>StorageVolume</code> インスタンスを取得します。次に、そのインスタンスの
42<code>StorageVolume.createAccessIntent()</code> メソッドを呼び出して、インテントを作成します。このインテントを使用して、外部ストレージのディレクトリにアクセスします。
43リムーバブル メディア ボリュームなど、使用できるすべてのボリュームのリストを取得するには、<code>StorageManager.getVolumesList()</code> を使用します。
44
45</p>
46
47<p>特定のファイルに関する情報がある場合は、
48<code>StorageManager.getStorageVolume(File)</code> を使用して、そのファイルを含む
49<code>StorageVolume</code> を取得します。この <code>StorageVolume</code> で
50<code>createAccessIntent()</code> を呼び出し、このファイルの外部ストレージ ディレクトリにアクセスします。
51</p>
52
53<p>
54外部 SD カードなどのセカンダリ ボリュームで、
55<code>StorageVolume.createAccessIntent()</code> を呼び出すときに null を渡し、特定のディレクトリではなくボリューム全体へのアクセスをリクエストします。プライマリ ボリュームに null を渡すか、無効なディレクトリ名を渡すと、
56<code>StorageVolume.createAccessIntent()</code> は null を返します。
57
58
59</p>
60
61<p>次のコード スニペットは、プライマリ共有ストレージの
62<code>Pictures</code> ディレクトリを開く方法の例を示しています。</p>
63
64<pre>
65StorageManager sm = (StorageManager)getSystemService(Context.STORAGE_SERVICE);
66StorageVolume volume = sm.getPrimaryVolume();
67Intent intent = volume.createAccessIntent(Environment.DIRECTORY_PICTURES);
68startActivityForResult(intent, request_code);
69</pre>
70
71<p>システムは外部ディレクトリへのアクセスの付与を試行し、必要に応じてシンプルな UI で、ユーザーにアクセスを確認します。
72</p>
73
74<img src="{@docRoot}preview/images/scoped-folder-access-framed.png" srcset="{@docRoot}preview/images/scoped-folder-access-framed.png 1x,
75{@docRoot}preview/images/scoped-folder-access-framed_2x.png 2x" />
76<p class="img-caption"><strong>図 1.</strong> Pictures ディレクトリへのアクセスを要求するアプリ
77</p>
78
79<p>ユーザーがアクセスを付与すると、
80<code>Activity.RESULT_OK</code> の結果コードと、URI を含むインテント データを指定して、
81<code>onActivityResult()</code> のオーバーライドを呼び出します。提供された URI を使用して、ディレクトリの情報にアクセスします。これは、<a href="{@docRoot}guide/topics/providers/document-provider.html">ストレージ アクセス フレームワーク</a>で返された URI を使用する場合と同様です。
82
83
84
85</p>
86
87<p>ユーザーがアクセスを付与しなかった場合は、
88<code>Activity.RESULT_CANCELED</code> の結果コードと、null のインテント データを指定して、
89<code>onActivityResult()</code> のオーバーライドを呼び出します。</p>
90
91<p class="note"><b>注</b>:特定の外部ディレクトリへのアクセスを取得すると、そのディレクトリ内のサブディレクトリへのアクセスも取得します。
92</p>
93
94<h2 id="removable">リムーバブル メディアのディレクトリへのアクセス</h2>
95
96<p>特定のディレクトリへのアクセスを使用してリムーバブル メディア上のディレクトリにアクセスするには、まず {@link android.os.Environment#MEDIA_MOUNTED} 通知をリッスンする {@link android.content.BroadcastReceiver} を追加します。次に例を示します。
97
98</p>
99
100<pre>
101&lt;receiver
102    android:name=".MediaMountedReceiver"
103    android:enabled="true"
104    android:exported="true" &gt;
105    &lt;intent-filter&gt;
106        &lt;action android:name="android.intent.action.MEDIA_MOUNTED" /&gt;
107        &lt;data android:scheme="file" /&gt;
108    &lt;/intent-filter&gt;
109&lt;/receiver&gt;
110</pre>
111
112<p>ユーザーが SD カードなどのリムーバブル メディアをマウントすると、システムは
113{@link android.os.Environment#MEDIA_MOUNTED} 通知を送信します。この通知は、インテント データ内の <code>StorageVolume</code> オブジェクトを提供します。このオブジェクトを使用して、リムーバブル メディア上のディレクトリにアクセスできます。
114
115次の例では、リムーバブル メディア上の <code>Pictures</code> ディレクトリにアクセスします。
116</p>
117
118<pre>
119// BroadcastReceiver has already cached the MEDIA_MOUNTED
120// notification Intent in mediaMountedIntent
121StorageVolume volume = (StorageVolume)
122    mediaMountedIntent.getParcelableExtra(StorageVolume.EXTRA_STORAGE_VOLUME);
123volume.createAccessIntent(Environment.DIRECTORY_PICTURES);
124startActivityForResult(intent, request_code);
125</pre>
126
127<h2 id="best">ベスト プラクティス</h2>
128
129<p>外部ディレクトリのアクセス URI はできる限り保持してください。そうすれば、ユーザーに何度もアクセス要求をする必要がなくなります。
130ユーザーがアクセスを付与したら、ディレクトリのアクセス URI を指定して
131<code>getContentResolver().takePersistableUriPermssion()</code> を呼び出します。
132システムが URI を保持し、以降のアクセス要求では <code>RESULT_OK</code> を返して、ユーザーに確認の UI を表示しません。
133
134</p>
135
136<p>ユーザーが外部ディレクトリへのアクセスを拒否した直後に、またアクセスをリクエストしないようにしてください。
137何度もアクセスを要求すると、ユーザー エクスペリエンスが低下します。
138リクエストがユーザーにより拒否され、アプリが再度アクセスをリクエストすると、UI に [<b>Don't ask again</b>] チェックボックスが表示されます。
139</p>
140
141<img src="{@docRoot}preview/images/scoped-folder-access-dont-ask.png" srcset="{@docRoot}preview/images/scoped-folder-access-dont-ask.png 1x,
142{@docRoot}preview/images/scoped-folder-access-dont-ask_2x.png 2x" />
143<p class="img-caption"><strong>図 1.</strong> リムーバブル メディアへのアクセスに対して 2 回目のリクエストを行うアプリ。
144</p>
145
146<p>ユーザーが [<b>Don't ask again</b>] を選択してリクエストを拒否すると、特定のディレクトリに対するアプリからの今後のすべてのリクエストは自動的に拒否され、リクエストに関する UI は表示されなくなります。
147
148</p>