com.nttdocomo.system
クラス ImageStore

Object
  com.nttdocomo.system.ImageStore

public final class ImageStore

extends Object

携帯電話のネイティブの画像データ管理機能にアクセスする手段を提供します。 このクラスのインスタンスは、 携帯電話のネイティブの画像データの 1 つのエントリを表します。

このクラスに定義されているクラスメソッドの使い方や、 ネイティブのデータへのアクセス方法に関する規定の大原則は com.nttdocomo.system パッケージの記述を参照して下さい。

画像データのエントリからは、エントリ ID を取得することが出来るほか、 画像をメディアイメージオブジェクトとして取り出したり、 画像のファイルイメージを取り出すための InputStream を取得することができます。 また、得られたエントリ ID を PhoneSystem.setImageTheme(int, int) メソッドの引数に指定することにより、 そのエントリの画像を待ち受け画像などに設定することができます。

[DoJa-3.0 (506i) 以降、ただし DoJa-3.5 (900i) を除く] addEntry(MediaImage image , boolean exclusive) の exclusive 引数に true を指定して(「独占する」と指定して)画像データを登録することで、 この(addEntry() を呼び出した)アプリケーション以外からの当該画像へ操作を禁止することができます。
加えて、exclusive 引数は、 画像保存時における再配布不可識別子の設定/削除の意味も持ち合わせています。
詳細は、addEntry(MediaImage, boolean) の説明を参照して下さい。

導入されたバージョン:

DoJa-3.0 (505i)

メソッドの概要

static int	addEntry(MediaImage image) ユーザ操作により画像データを新規登録します。
static int[]	addEntry(MediaImage[] images) [iアプリオプションAPI] ユーザ操作により複数の画像データを新規登録します。
static int	addEntry(MediaImage image, boolean exclusive) ユーザ操作により画像データを新規登録します。
static ImageStore	getEntry(int id) 画像データのエントリを取得します。
static int[]	getEntryIds(int folderId) 画像データのエントリ ID のリストを取得します。
int	getId() 画像データのエントリIDを取得します。
MediaImage	getImage() 画像データのエントリのイメージをメディアイメージとして取得します。
java.io.InputStream	getInputStream() 画像データのエントリのイメージをファイルイメージとして取り出すための 入力ストリームを取得します。
static ImageStore	selectEntry() ユーザ操作により画像データのエントリを取得します。
static int	selectEntryId() [iアプリオプションAPI] ユーザ操作により画像データのエントリIDを取得します。

クラス Object から継承したメソッド

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

メソッドの詳細

selectEntry

public static ImageStore selectEntry()
                              throws InterruptedOperationException

ユーザ操作により画像データのエントリを取得します。

ADFにAccessUserInfoキーの指定が必要です。 上記以外の動作の詳細については、このクラスの説明、 ならびにその説明から引用されている com.nttdocomo.system パッケージに記述されている 「エントリ取得時の振る舞い」の説明を参照して下さい。

[DoJa-4.1 (902i、902iS)、DoJa-5.0 (903i、904i)]
このメソッドによりベクターグラフィクスを取得することはできません。

[DoJa-5.1 (905i) 以降]
端末によっては、このメソッドによりベクターグラフィックスを取得できます。

戻り値:

取得した画像データのエントリを返します。 ユーザが選択操作をキャンセルするとnullを返します。 また、選択可能なエントリが存在しない場合にもnullを返します。

例外:

IllegalStateException - ダウンロード即起動アプリがこのメソッドを呼び出した場合に発生します。

IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。

SecurityException - ADFにAccessUserInfoキーの指定がないアプリケーションが このメソッドを呼び出した場合に発生します。

SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、 画像データのエントリを取得できない場合に発生します。

UIException - [DoJa-4.1 (902i) 以降] リソース不足により画像データを取得できなかった場合に発生します (NO_RESOURCES)。

InterruptedOperationException - 競合条件などにより、選択操作が異常終了した場合に発生します。

selectEntryId

public static int selectEntryId()
                         throws InterruptedOperationException [iアプリオプションAPI]

ユーザ操作により画像データのエントリIDを取得します。

このメソッドで得られたエントリ ID を PhoneSystem.setImageTheme(int, int) メソッドの引数に指定することにより、 そのエントリの画像を待ち受け画像などに設定することができます。

パーミッションとしてテーマ設定が許可されているトラステッドiアプリのみ このメソッドを呼び出すことができます。 上記以外の動作の詳細については、 com.nttdocomo.system パッケージに記述されている説明を参照してください。

端末によっては、このメソッドをサポートしていない場合があります。 その場合には、例外 UnsupportedOperationException が発生します。

戻り値:

取得した画像データのエントリIDを返します。 ユーザが選択操作をキャンセルすると -1 を返します。 また、選択可能なエントリが存在しない場合にも -1 を返します。

例外:

UnsupportedOperationException - 端末がこのメソッドをサポートしていない場合に発生します。

IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。

SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、 画像データのエントリIDを取得できない場合に発生します。

InterruptedOperationException - 競合条件などにより、選択操作が異常終了した場合に発生します。

導入されたバージョン:

DoJa-4.1 (902i)

getEntry

public static ImageStore getEntry(int id)
                           throws StoreException

画像データのエントリを取得します。

ADFにAccessUserInfoキーの指定が必要です。 上記以外の動作の詳細については、このクラスの説明、 ならびにその説明から引用されている com.nttdocomo.system パッケージに記述されている 「エントリ取得時の振る舞い」の説明を参照して下さい。

[DoJa-4.1 (902i、902iS)、DoJa-5.0 (903i、904i)]
このメソッドによりベクターグラフィクスを取得することはできません。

[DoJa-5.1 (905i) 以降]
端末によっては、このメソッドによりベクターグラフィックスを取得できます。

パラメータ:

id - 取得する画像データのエントリIDを指定します。

戻り値:

取得した画像データのエントリを返します。

例外:

IllegalStateException - ダウンロード即起動アプリがこのメソッドを呼び出した場合に発生します。

SecurityException - ADFにAccessUserInfoキーの指定がないアプリケーションが このメソッドを呼び出した場合に発生します。

SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、 画像データのエントリを取得できない場合に発生します。
[DoJa-3.5 (900i) のみ] UIM内情報を用いた実行制限がかけられている場合や、 画像データに再配布不可識別子が設定されている場合も含みます。

[DoJa-3.5 (900iC) 以降] 以下の場合も含みます。

• UIM 内情報を用いた実行制限がかけられている場合
• 指定された ID の画像が、 このアプリケーション自身が保存したものではなく、 かつ、その画像データに再配布不可識別子が設定されている場合

StoreException - 指定された ID の画像エントリが存在しない場合に発生します(NOT_FOUND)。
[DoJa-4.1 (902i、902iS)、DoJa-5.0 (903i、904i)] 指定された ID の画像が ベクターグラフィックスであった場合にも発生します。
[DoJa-5.1 (905i) 以降] ベクターグラフィックスの取得をサポートしていない端末において、 指定された ID の画像が ベクターグラフィックスであった場合にも発生します。

UIException - [DoJa-4.1 (902i) 以降] リソース不足により画像データを取得できなかった場合に発生します (NO_RESOURCES)。

getEntryIds

public static int[] getEntryIds(int folderId)
                         throws StoreException

画像データのエントリ ID のリストを取得します。

ユーザの選択によらず、 フォルダのエントリ ID を引数 folderId に指定して、 フォルダ直下にある画像データのエントリ ID のリストを取得します。 なお、アプリケーションがサスペンドすることなく、エントリ ID のリストを取得できます。

フォルダのエントリ ID は DataBoxFolder クラスのメソッドにより取得することができます。 引数で指定したエントリ ID のフォルダが、 データ BOX フォルダ配下のマイピクチャフォルダ直下に存在しない場合に例外が発生します。

このメソッドでエントリ ID のリストの対象となる画像データは、 getEntry(int)、 selectEntry() で取得可能な画像データです。 エントリ ID のリストの対象とならない画像データが、 引数 folderId で指定されたフォルダ直下にある場合には、 このメソッドは例外を発生せずに、それらのエントリ ID を除いたリストを返します。

ADF に AccessUserInfo キーの指定が必要です。

パラメータ:

folderId - フォルダのエントリ ID を指定します。

戻り値:

取得した画像データのエントリ ID のリストを返します。 取得可能なエントリ ID が存在しない場合には null を返します。

例外:

IllegalStateException - ダウンロード即起動アプリがこのメソッドを呼び出した場合に発生します。

SecurityException - ADF に AccessUserInfo キーの指定がないアプリケーションがこのメソッドを呼び出した場合に発生します。

SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、 画像データのエントリ ID を取得できない場合に発生します。

StoreException - 指定されたエントリ ID のフォルダが、マイピクチャフォルダ直下に存在しない場合に発生します(NOT_FOUND)。

導入されたバージョン:

DoJa-5.0 (903i)

addEntry

public static int addEntry(MediaImage image)
                    throws InterruptedOperationException

ユーザ操作により画像データを新規登録します。

このメソッドを用いて登録された画像は、 引数に指定された画像が保持している再配布可能かどうかの設定のままで保存されます。 すなわち、addEntry(image, !image.isRedistributable()) を呼び出すことと等価です。

パラメータ:

image - 登録する画像のメディアイメージを指定します。

戻り値:

登録されたエントリのIDを返します。 ユーザが登録操作をキャンセルした場合、-1 を返します。

例外:

IllegalStateException - ダウンロード即起動アプリがこのメソッドを呼び出した場合に発生します。

IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。

NullPointerException - 引数 image が null の場合に発生します。

UIException - 引数の image にシステムが提供している以外のメディアイメージ (MediaImageインタフェースを実装した未知のクラスのオブジェクト) が渡された場合に発生します(UNSUPPORTED_FORMAT)。

UIException - 指定されているメディアイメージが use 状態でない場合に発生します (ILLEGAL_STATE)。

UIException - [DoJa-5.0 (903i) 以降] 指定されているメディアイメージの利用が「一度きり」 である場合に発生します(ILLEGAL_STATE)。

SecurityException - ADFにAccessUserInfoキーの指定がないアプリケーションが このメソッドを呼び出した場合に発生します。

SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、 画像データを登録できない場合に発生します。

UIException - [DoJa-4.0 (901i) 以降] 指定された画像の縦もしくは横のいずれかが、 登録可能な画像サイズよりも大きい場合に発生します (UNSUPPORTED_FORMAT)。

UIException - [DoJa-4.0 (901i) 以降] 指定された画像のデータサイズが、 登録可能なデータサイズ(bytes)よりも大きい場合に発生します (UNSUPPORTED_FORMAT)。

UIException - [DoJa-4.0 (901i) 以降] 動画が指定された場合に発生します (UNSUPPORTED_FORMAT)。

UIException - 指定された画像が、データ BOX に登録できない画像フォーマットである場合に発生します (UNSUPPORTED_FORMAT)。

InterruptedOperationException - 競合条件などにより、登録操作が異常終了した場合に発生します。

addEntry

public static int[] addEntry(MediaImage[] images)
                      throws InterruptedOperationException [iアプリオプションAPI]

ユーザ操作により複数の画像データを新規登録します。

引数に指定された配列内の全ての画像データを、 それぞれの画像が保持している再配布可能かどうかの設定のままで保存します。

原理的には、

 int[] ret = new int[images.length];
 for (int i = 0; i < images.length; i++) {
     ret[i] = addEntry(images[i], !images[i].isRedistributable());
 }

を行うことで、同等な処理を実現出来ますが、以下の点が異なります。

• 登録画面への遷移(とそれに伴なうサスペンド)や、 登録の際に行われるユーザ確認は、全ての画像データを一括して、 一度しか行われません。 確認画面においてユーザキャンセルがなされた場合には、 画像データは1つも登録されません。
• 何らかの理由により、 指定された画像データの1つでも登録に失敗した場合には、 全ての画像データ登録処理が行われなかったことになり、 結果として画像データは1つも登録されません。 言い換えると、 例外が発生した場合には、画像データは1つも登録されていません。

このメソッドをサポートしていない実装も存在します。 その場合には、例外 UnsupportedOperationException が発生します。 また、一度に登録できる画像の数は機種依存です。 実装が一度に登録可能な画像数を超える長さの配列が指定された場合には、例外が発生します。 また、実装が一度に登録可能な画像合計データサイズを超える配列が指定された場合にも、例外が発生します。

引数 images に、長さ 0 の配列を指定しても、 それを理由に例外が発生することはありません。 その場合はサスペンドせずに null が返されます。

パラメータ:

images - 登録する画像のメディアイメージの配列を指定します。

戻り値:

登録されたエントリの ID の配列を返します。 戻り値を int[] ids とすると、 images[i] に対応するエントリ ID は、 ids[i] に格納されています。
ユーザが登録操作をキャンセルした場合や、 データ保存領域の容量を超えているために登録できない場合 （データBOXに登録可能な残り画像データサイズ、もしくは残り画像数を超えた場合) には null を返します。

例外:

UnsupportedOperationException - 端末がこのメソッドをサポートしていない場合に発生します。

IllegalStateException - ダウンロード即起動アプリがこのメソッドを呼び出した場合に発生します。

IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。

NullPointerException - 引数 images が null の場合に発生します。

UIException - 引数 images に、 一度に登録可能な画像数を超える長さの配列が指定された場合に発生します (NO_RESOURCES)。

NullPointerException - 引数 images のいずれかの要素に null が含まれていた場合に発生します。

UIException - 引数 images のいずれかの要素にシステムが提供している以外のメディアイメージ (MediaImageインタフェースを実装した未知のクラスのオブジェクト) が渡された場合に発生します(UNSUPPORTED_FORMAT)。

UIException - 指定されている配列のいずれかの要素に use 状態でないメディアイメージが含まれていた場合に発生します (ILLEGAL_STATE)。

UIException - [DoJa-5.0 (903i) 以降] 指定されている配列のいずれかの要素に、 利用が「一度きり」 と指定されたメディアイメージが含まれていた場合に発生します (ILLEGAL_STATE)。

SecurityException - ADFにAccessUserInfoキーの指定がないアプリケーションが このメソッドを呼び出した場合に発生します。

SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、 画像データを登録できない場合に発生します。

UIException - 指定されている配列のいずれかの要素に、 縦もしくは横のいずれかが、 登録可能な画像サイズよりも大きい画像が含まれていた場合に発生します (UNSUPPORTED_FORMAT)。

UIException - 指定されている配列のいずれかの要素に、 登録可能なデータサイズ (bytes) よりも大きい画像が含まれていた場合に発生します (UNSUPPORTED_FORMAT)。

UIException - 配列要素のデータサイズ (bytes) の合計が、 一度に登録可能なデータサイズを越えた場合に発生します (UNSUPPORTED_FORMAT)。

UIException - 指定されている配列のいずれかの要素に、 動画が含まれていた場合に発生します(UNSUPPORTED_FORMAT)。

UIException - 指定された画像が、データ BOX に登録できない画像フォーマットである場合に発生します (UNSUPPORTED_FORMAT)。

InterruptedOperationException - 競合条件などにより、登録操作が異常終了した場合に発生します。

導入されたバージョン:

DoJa-4.0 (901iS)

addEntry

public static int addEntry(MediaImage image,
                           boolean exclusive)
                    throws InterruptedOperationException

ユーザ操作により画像データを新規登録します。 指定した画像を、 このアプリケーション自身で独占するかどうかを指定することができます。

独占すると指定して保存された画像に対しては、 以下の操作を行う権限を、このアプリケーションが独占します。

[DoJa-4.0 (901iS) まで]

• getEntry(int)、selectEntry() を用いて当該画像にアクセスすること
• PhoneSystem.setImageTheme(int, int) を用いて、当該画像を待ち受け画像等に設定すること

[DoJa-4.1 (902i) 以降]

• getEntry(int)、selectEntry() を用いて当該画像にアクセスすること

例えば、 他の Java アプリケーションが getEntry(int) を用いて当該画像を取得しようとすると、 例外が発生します。
また、ネイティブ機能においては、 当該画像はブラウザからダウンロードした再配布不可識別子が設定されている画像として扱われ、 メールや赤外線を用いて送信することなどができなくなります。

一方、独占しないとして保存された画像は、 他の Java アプリケーションからも、ネイティブ機能からも、 自由に操作可能です。

加えて、この独占指定は、 保存する画像の再配布不可識別子の設定/削除の意味も持ち合わせています。 すなわち、このメソッドにより保存された画像には、 以下のように再配布不可識別子が設定されています。

「独占しない」と指定して保存した場合:

保存された画像には再配布不可識別子が設定されていません。 すなわち、保存する画像に再配布不可識別子が設定されていた場合は、 その設定が削除された画像が保存されます。

「独占する」と指定して保存した場合:

保存された画像には再配布不可識別子が設定されています。 すなわち、保存する画像に再配布不可識別子が設定されていない場合には、 その設定が付加された画像が保存されます。

ただし、上記規定にかかわらず、 再配布不可識別子が設定できない画像を保存する場合には、 第 2 引数には常に !image.isRedistributable() が指定されているものとして扱われます。

ADFにAccessUserInfoキーの指定が必要です。 上記以外の動作の詳細については、このクラスの説明、 ならびに、その説明から引用されている com.nttdocomo.system パッケージに記述されている説明を参照して下さい。

[DoJa-4.0 (901i) 以降]
データ保存領域の容量を超えているために登録できない場合は、 ユーザが登録操作をキャンセルした場合と同様の値を返します。

パラメータ:

image - 登録する画像のメディアイメージを指定します。

exclusive - この画像をこのアプリケーションで独占して (再配布不可識別子も設定して)保存する場合には true を、 独占しないで (再配布不可識別子の設定も削除して) 保存する場合には false を指定します。

戻り値:

登録されたエントリのIDを返します。 ユーザが登録操作をキャンセルした場合、-1 を返します。

例外:

IllegalStateException - ダウンロード即起動アプリがこのメソッドを呼び出した場合に発生します。

IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。

NullPointerException - 引数 image が null の場合に発生します。

UIException - 引数の image にシステムが提供している以外のメディアイメージ (MediaImageインタフェースを実装した未知のクラスのオブジェクト) が渡された場合に発生します(UNSUPPORTED_FORMAT)。

UIException - 指定されているメディアイメージが use 状態でない場合に発生します (ILLEGAL_STATE)。

UIException - [DoJa-5.0 (903i) 以降] 指定されているメディアイメージの利用が「一度きり」 である場合に発生します(ILLEGAL_STATE)。

SecurityException - ADFにAccessUserInfoキーの指定がないアプリケーションが このメソッドを呼び出した場合に発生します。

SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、 画像データを登録できない場合に発生します。

UIException - [DoJa-4.0 (901i) 以降] 指定された画像の縦もしくは横のいずれかが、 登録可能な画像サイズよりも大きい場合に発生します (UNSUPPORTED_FORMAT)。

UIException - [DoJa-4.0 (901i) 以降] 指定された画像のデータサイズが、 登録可能なデータサイズ(bytes)よりも大きい場合に発生します (UNSUPPORTED_FORMAT)。

UIException - [DoJa-4.0 (901i) 以降] 動画が指定された場合に発生します (UNSUPPORTED_FORMAT)。

UIException - 指定された画像が、データ BOX に登録できない画像フォーマットである場合に発生します (UNSUPPORTED_FORMAT)。

InterruptedOperationException - 競合条件などにより、登録操作が異常終了した場合に発生します。

導入されたバージョン:

DoJa-3.0 (506i)、DoJa-3.5 (900iC)

getId

public int getId()

画像データのエントリIDを取得します。

戻り値:

画像データのエントリIDを返します。

getImage

public MediaImage getImage()

画像データのエントリのイメージをメディアイメージとして取得します。

取得されたメディアイメージは、disposeもuseもされていない状態です。

常に同じメディアイメージオブジェクトを返します。 このため、既にメディアイメージオブジェクトが利用不可状態(unuse() が実行された状態)、 リソース破棄状態(dispose() が実行された状態)である場合は、 同じ状態のメディアイメージオブジェクトが返ります。 dispose() 後にメディアイメージを利用するには、 getEntry(int) または selectEntry() によって画像データのエントリを再取得し、 本メソッドで別のメディアイメージオブジェクトを取得しなければなりません。

戻り値:

メディアイメージを返します。

getInputStream

public java.io.InputStream getInputStream()

画像データのエントリのイメージをファイルイメージとして取り出すための 入力ストリームを取得します。
このメソッドを呼び出すたびに異なる入力ストリームを返します。

戻り値:

画像のファイルイメージを取り出すための入力ストリームを返します。