ファイルピッカーAPI概要

ファイルピッカー（ContentsManagerの利用）について

ContentsManager（以下CM)とは、実機に保存されているユーザーデータ、プリセットデータ、および、SDカード挿入時にはSDカード内のデータを管理するAPIです。
アプリケーションで、保存されている各種データを取り扱いたい場合、CMを起動してファイル情報を取得することが可能です。

CMの起動方法について

CMは明示的起動と、暗黙的起動の2種類の起動方法があります。

○明示的起動
ファイルのカテゴリ、種類、一覧にした際のソート順、ファイルの選択方法など、CMの表示仕様を詳細に指定して起動することが可能です。
指定パラメータおよび、起動方法については詳細を参照してください。
(2.外部アプリからのContentsManager起動仕様)

○暗黙的起動
アプリケーションが取り扱うファイルのMIMEtypeを指定し、このファイルを取り扱うことができる全てのアプリケーションを呼び出す起動方法です。
CM以外に使用可能なアプリケーションがある場合、どのアプリケーションを起動するか選択するダイアログが開きます。
CM以外に使用可能なアプリケーションがない場合、直接CMが起動します。
指定パラメータおよび、起動方法については詳細を参照してください。
(2.外部アプリからのContentsManager起動仕様)

CMからのファイル取得について

CM上でファイルを選択すると、選択したファイルのURIが返却されます。
呼び出し元のアプリでは、このURIをもとにContentProvider経由でファイルの詳細情報を取得します。

複数選択の場合、CMは選択された全てのファイルのURIを一時ファイルとして書き出し、Intentにそのファイルパスを付随させて呼び出し元へ返却します。
呼び出し元のアプリでは、ファイルパスから一時ファイルを取得し、書き込まれたURIを1行ずつ読み出すことで読み込んだURIを元にContentProvider経由で、選択したファイルの詳細情報を取得することができます。

このAPIを使用するには

SDKへAddOnを追加する必要があります。

CMの起動

CMの起動および、CMからの戻り値の取り扱いについては、2.外部アプリからのContentsManager起動仕様 と 3.データ仕様書 コンテンツ種別タブ-ファイル対応表 を参照してください。

起動したCMについて

CMを起動している間は、CMの操作法に従ってファイルを選択してください。

CM画面構成

CMの画面は、大きく「タブエリア」、「コンテンツ表示エリア」、「検索条件エリア」、「ガイドエリア」に分けられます。
「コンテンツ表示エリア」については、リストビュー形式とグリッドビュー形式の表示切替が可能です。

タブエリアについて

タブエリアには対象になっているコンテンツのカテゴリが表示されます。
端末（microSDを含む）に存在するコンテンツを、カテゴリ（コンテンツ種別）に分類して表示することで、ユーザにとって検索・選択しやすい環境を提供します。

タブエリアに表示されるコンテンツは、CM起動時に設定したカテゴリです。
何も指定しない場合、全てのカテゴリのタブが表示されます。
カテゴリの指定をファイルの種別で詳細に設定した場合、検索条件エリアの種別が、指定された種別に限定されます。

最初に表示するカテゴリのタブは、MIMEtypeを指定することで設定可能です。
未指定の場合は初期値としてフォトを表示します。
また、カテゴリ指定とMIMEtype指定が異なっている場合は、カテゴリ指定を優先して表示します。

コンテンツ表示エリアについて

コンテンツ表示エリアは、「リストビュー」、「グリッドビュー」の2種類の表示形式が存在します。
表示形式は「MENU」－「グリッド/リスト切り替え」から切り替えが可能です。

コンテンツ表示エリアにはタブエリアで選択中のカテゴリーに属するファイルを、検索条件エリアで選択している条件に従って表示されます。

検索条件エリアについて

タブ毎に分類されたコンテンツを、さらに細かい条件で絞り込むことを目的とする、画面上部に設置された検索条件群です。

保存場所

コンテンツの保存場所を指定することができます。
保存場所は、本体、microSD、プリセットのうち、起動時に指定したものから選択可能です。
何も指定しない場合、本体、microSDが対象となります。

日付

コンテンツのタイムスタンプ（保存日時）にて、コンテンツの検索を行います。リストから選択できる日付の種類は下記の通りです。

• 指定なし：日付の指定なしで、コンテンツ表示を行う。最新タブが選択されている場合はソート条件として、必ず日付の降順が選択される。
• 1週間以内：タブを選択した日の１週間前の日（同一曜日）の0時以降に保存されたコンテンツを表示する。
• 1ヶ月以内：タブを選択した日のひと月前の日の0時以降に保存されたコンテンツ表示する。
  （タブを選択した日が6/10日であれば、5/10日になる。タブを選択した日が3/31日の場合、2/31日はないため3/1日になる：直近の日）
• 日付指定：カレンダーを表示して、日付を選択する。

何も指定しない場合、指定なしとなります。

種別

タブに表示されたコンテンツを、「種別」により、さらに細かく絞り込むためのエリアです。
各タブ毎に選択できる種別リストの中身は下記の通りです。

タブ名称	種別
フォト	指定なし/デジタルカメラ画像/絵文字/その他
ムービー	指定なし/撮影動画/ダウンロード動画/その他
ミュージック	指定なし/ミュージック/ サウンド
ドキュメント	指定なし/Office文書/PDF/txt
その他	指定なし

ソート

検索エリアに、リストからソート条件を選択できる機能を提供します。
ソート条件を選択すると、検索条件が変更されたとして検索を再実行されます。

ソート条件として以下の項目を一つだけ選択することができます。
　1)ファイルサイズ 昇順
　2)ファイルサイズ 降順
　3)保存日付 昇順
　4)保存日付 降順
　5)タイトル 昇順
　6)タイトル 降順
何も指定しない場合、保存日時降順となります。

検索ボックス

「検索文字列」を入力するテキストボックスです。
検索の対象となるコンテンツは、検索実施タブにおける、検索エリアの他条件(「保存場所」「日付」「種別」)で絞り込まれた現在の表示コンテンツを対象とします。
入力した「検索文字列」から、タイトル名（タブによってはタイトル以外もある）に合致するコンテンツをインクリメンタル絞込み（部分一致）します。
検索時の文字数制限は、100byteまでとされ、100byteを超えた入力はできません。

検索ボックスに入力不可な文字は「絵文字」「改行」です。

検索文字にて検索を行うコンテンツの情報は下記の通りです。

タブ名称	検索を行うコンテンツの情報
フォト	タイトル名
ムービー	タイトル名
ミュージック	タイトル名 / アーティスト名 (*)
ドキュメント	タイトル名
その他	タイトル名

 (*) 1つでも検索条件でマッチすれば表示されます。

ファイルの選択方法について

起動したCMでは、一覧表示中のファイルに対し、1件選択もしくは複数選択を行うことが可能です。
CM起動パラメータの選択モードを指定することで、ファイルの選択方法を決定します。
デフォルトは1件選択となっており、選択モードを何も指定しない場合は1件選択で起動されます。

○1件選択
任意のファイルを1件選択し、そのURIを起動元アプリケーションへ返却します。

○複数選択
任意のファイルを複数件選択し、そのURIを書き込んだ一次ファイルのURIを起動元アプリケーションへ返却します。
複数選択を起動し、1件しか選択しなかった場合、一次ファイルは作成されず、1件選択時と同様にURIが返却されます。

複数選択時に、選択できる最大に達すると、CMはこれ以上選択できないことを通知します。

【サンプルコードへ】
　【公開API一覧へ】