com.nttdocomo.system.MailAgent
Object
携帯電話のネイティブのメール機能にアクセスする手段を提供します。
メールの取得および送信(または保存)機能を提供します。
メール機能では、
メールの取得や送信を行うクラスと、
メールそのものを表すクラスが区別されています。
このクラスはメールの取得や送信を行いますが、
メールそのものは Mail および
MailDraft・
DecomailDraft クラスのオブジェクトとして表されます。
getLastIncoming() メソッドにより、
最新のメールが未読メールの場合、そのメールを取得することができます。
取得されたメール(Mail オブジェクト)には、
サブジェクト (XString)、
日付 (XStringとして取得可能)、
宛先アドレス (XString)、
差出人アドレス (XString) およびその電話帳 ID が設定されています。
テキストメールを新規に作成し、送信(または保存)するためには、
send(String, String[], String) メソッドまたは
send(String, XString, String) メソッドを直接呼び出すか、
MailDraft オブジェクトに対して宛先等を設定して
send(MailDraft) メソッドを呼び出します。
また、デコメールの場合は、
DecomailDraft オブジェクトに対して宛先等を設定して
send(DecomailDraft) メソッドを呼び出します。
DecomailDraft オブジェクトの状態は変化しません。
なお、
テキストメールの send 時に設定するサブジェクト、宛先アドレス、メール本文と、 デコメールの場合に DecomailDraft
クラスで設定するサブジェクト、宛先アドレス、メール本文の文字列の扱いについては、以下の通りです。
サブジェクト、宛先アドレス、メール本文の全てにおいて 「i モードメール(デコメール)の仕様に準拠していない」という理由で例外が発生します。 ただし、メール本文については、テキストメールとデコメールで以下のように振る舞いが異なります。
なお、上記例外を除いては、改行文字を含む制御文字 (0x00 〜 0x1F、0x7F) は 「ネイティブのメーラで扱えない文字」に含まれます。
サブジェクト、宛先アドレス、メール本文の全てにおいて 「i モードメール(デコメール)の仕様に準拠していない」という理由で 例外が発生します。 なお、各最大バイト数は以下になります。
なお、テキストメールの本文は、send メソッドが呼び出された直後に本文中の改行文字が全て正規化され、 正規化後のデータに対してiモードメールの仕様に準拠しているかどうかのチェックが行われます。
[DoJa-5.0 (903i) 以降]
機種によっては、デコメールの送信も行うことができます。
Mail,
MailDraft| メソッドの概要 | |
static Mail |
getLastIncoming()
最新の未読メールを取得します。 |
static int |
getRemainingBytes(DecomailDraft mail) [iアプリオプションAPI]
デコメール本文に設定できる HTML パートとテキストパートの残りバイト数を返します。 |
static int |
getRemainingBytes(MailDraft mail) [iアプリオプションAPI]
メール本文に設定できる残りバイト数を返します。 |
static boolean |
send(DecomailDraft mail) [iアプリオプションAPI]
ユーザ操作によりデコメールを送信します。 |
static boolean |
send(MailDraft mail)
ユーザ操作によりメールを送信します。 |
static boolean |
send(String subject,
String[] addresses,
String body)
ユーザ操作によりメールを送信します。 |
static boolean |
send(String subject,
XString address,
String body)
ユーザ操作によりメールを送信します。 |
| クラス Object から継承したメソッド |
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| メソッドの詳細 |
public static Mail getLastIncoming()
取得されたメール(Mailオブジェクト)には、
サブジェクト(XString)、
日付(XStringとして取得可能)、
宛先アドレス(XString)、
差出人アドレス(XString)およびその電話帳IDが設定されています。
このメソッドを利用して最新の未読メールを取得しても、 端末のメールピクトやそのメールの未読情報は変化しません。
パーミッションとして携帯電話情報の参照が許可されている トラステッドiアプリのみこのメソッドを呼び出すことができます。
SecurityException - パーミッションとして携帯電話情報の参照が許可されているが、
iアプリ個別のユーザ設定により許可されない場合に発生します。
SecurityException - メールロックにより拒否される場合に発生します。
SecurityException - ネイティブ独自のセキュリティ設定により、
メールを取得できない場合に発生します。
IllegalStateException -
[DoJa-4.0 (901i) 以降] FOMA端末で、UIM読み込み中の場合に発生します。
public static boolean send(String subject,
String[] addresses,
String body)
throws MailException,
InterruptedOperationException,
StoreException
このクラスの説明を参照して下さい。
送信処理においてサーバが正常応答を返した場合、true を返します。 送信処理中にサーバがエラーを返した場合、MailExceptionをスローします。 送信せずに保存した場合も含めて、それ以外の場合には false を返します。 宛先が複数の場合、いずれかの宛先へのメールの送信に失敗した場合、 その失敗の原因に応じて例外を発生またはfalseを返します。 すべての宛先への送信が成功した場合、true を返します。
パーミッションとしてネイティブメーラの利用が許可されている トラステッドiアプリのみこのメソッドを呼び出すことができます。 このメソッドを呼び出すとサスペンドします。
[DoJa-3.5 (900i) 以降]
FOMA 端末で、マルチタスク機能によってメーラが起動されていて未保存のデータがある状態の時にこのメソッドが呼ばれた場合、
現在実行中のJavaアプリケーションはサスペンドされ、
ユーザ確認のダイアログが表示されます。
ユーザがメーラの起動を許可した場合は、
ユーザ操作によりメールを送信します。
ユーザが起動を許可しなかった場合は、
このメソッドから戻ってJavaアプリケーションの実行を継続します。
subject - サブジェクト(通常文字列)を指定します。addresses - 宛先アドレス(通常文字列)を配列で指定します。body - 本文(通常文字列)を指定します。
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
NullPointerException - 引数 addresses が null でない場合に、
配列中に null の要素があった場合に発生します。
IllegalArgumentException - 実装がサポートしている数以上のメールアドレスを指定した場合に
発生します。
IllegalArgumentException - 引数 subject、addresses、bodyの内容のいずれかが、
iモードメールの仕様に準拠していない場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、
メールを送信できない場合に発生します。
StoreException - 送信または未送信フォルダにメールを追加できないため、
メールを送信できない場合に発生します(STORE_FULL)。
IllegalStateException -
[DoJa-4.0 (901i) 以降] FOMA端末で、UIM読み込み中の場合に発生します。
MailException - User Unknownなどによりサーバ側からメール送信を拒否された場合に発生します。
InterruptedOperationException - 競合条件などにより、送信操作が異常終了した場合に発生します。
public static boolean send(String subject,
XString address,
String body)
throws MailException,
InterruptedOperationException,
StoreException
このクラスの説明を参照して下さい。
送信処理においてサーバが正常応答を返した場合、true を返します。 送信処理中にサーバがエラーを返した場合、MailExceptionをスローします。 送信せずに保存した場合も含めて、それ以外の場合には false を返します。 宛先が複数の場合、いずれかの宛先へのメールの送信に失敗した場合、 その失敗の原因に応じて例外を発生またはfalseを返します。 すべての宛先への送信が成功した場合、true を返します。
パーミッションとしてネイティブメーラの利用が許可されている トラステッドiアプリのみこのメソッドを呼び出すことができます。 このメソッドを呼び出すとサスペンドします。
[DoJa-3.5 (900i) 以降]
FOMA 端末で、マルチタスク機能によってメーラが起動されていて未保存のデータがある状態の時にこのメソッドが呼ばれた場合、
現在実行中のJavaアプリケーションはサスペンドされ、
ユーザ確認のダイアログが表示されます。
ユーザがメーラの起動を許可した場合は、
ユーザ操作によりメールを送信します。
ユーザが起動を許可しなかった場合は、
このメソッドから戻ってJavaアプリケーションの実行を継続します。
subject - サブジェクト(通常文字列)を指定します。address - 宛先アドレス(XString)を指定します。body - 本文(通常文字列)を指定します。
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
IllegalArgumentException - 引数 subject、address、bodyの内容のいずれかが、
iモードメールの仕様に準拠していない場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、
メールを送信できない場合に発生します。
StoreException - 送信または未送信フォルダにメールを追加できないため、
メールを送信できない場合に発生します(STORE_FULL)。
IllegalStateException -
[DoJa-4.0 (901i) 以降] FOMA端末で、UIM読み込み中の場合に発生します。
MailException - User Unknownなどによりサーバ側からメール送信を拒否された場合に発生します。
InterruptedOperationException - 競合条件などにより、送信操作が異常終了した場合に発生します。
public static boolean send(MailDraft mail)
throws MailException,
InterruptedOperationException,
StoreException
送信処理においてサーバが正常応答を返した場合、true を返します。 送信処理中にサーバがエラーを返した場合、MailExceptionをスローします。 送信せずに保存した場合も含めて、それ以外の場合には false を返します。 宛先が複数の場合、いずれかの宛先へのメールの送信に失敗した場合、 その失敗の原因に応じて例外を発生またはfalseを返します。 すべての宛先への送信が成功した場合、true を返します。
パーミッションとしてネイティブメーラの利用が許可されている トラステッドiアプリのみこのメソッドを呼び出すことができます。 このメソッドを呼び出すとサスペンドします。
[DoJa-3.5 (900i) 以降]
FOMA 端末で、マルチタスク機能によってメーラが起動されていて未保存のデータがある状態の時にこのメソッドが呼ばれた場合、
現在実行中のJavaアプリケーションはサスペンドされ、
ユーザ確認のダイアログが表示されます。
ユーザがメーラの起動を許可した場合は、
ユーザ操作によりメールを送信します。
ユーザが起動を許可しなかった場合は、
このメソッドから戻ってJavaアプリケーションの実行を継続します。
[DoJa-5.0 (903i) 以降]
引数の実行時の型が DecomailDraft である場合は、
send(DecomailDraft) が呼び出されます。
この場合の例外については、このメソッドの「例外」欄には記載していません。
send(DecomailDraft) の「例外」欄の記述を参照してください。
mail - 送信するメールを指定します。
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
NullPointerException - 引数 mail が null の場合に発生します。
IllegalArgumentException -
引数の mail にシステムが提供している以外のオブジェクト
(MailDraftクラスを継承した未知のクラスのオブジェクト)
が渡された場合に発生します。
IllegalArgumentException - メール本文中の改行文字の正規化処理の結果、メール全体のサイズが
i モードメールの仕様を超過した場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、
メールを送信できない場合に発生します。
StoreException - 送信または未送信フォルダにメールを追加できないため、
メールを送信できない場合に発生します(STORE_FULL)。
IllegalStateException -
[DoJa-4.0 (901i) 以降] FOMA端末で、UIM読み込み中の場合に発生します。
MailException - User Unknownなどによりサーバ側からメール送信を拒否された場合に発生します。
InterruptedOperationException - 競合条件などにより、送信操作が異常終了した場合に発生します。
public static int getRemainingBytes(MailDraft mail) [iアプリオプションAPI]
引数に指定されたメールについて、メール本文の正規化後のバイト数を計算し、
その値と i モードメール仕様上のメール本文の最大バイト数とを比較して、
メール本文の残りに設定できるバイト数を返します。
ただし、このメソッドは実際にメール本文の正規化処理を行うわけではありません。
実際の正規化処理は send(MailDraft) 時に行われます。
[DoJa-5.0 (903i) 以降]
引数の実行時の型が DecomailDraft である場合は、
getRemainingBytes(DecomailDraft) が呼び出されます。
この場合の例外については、このメソッドの「例外」欄には記載していません。
getRemainingBytes(DecomailDraft) の「例外」欄の記述を参照してください。
端末によっては、以下の場合に例外 UnsupportedOperationException が発生します。
MailDraft である場合
DecomailDraft である場合
mail - 送信用のメールを指定します。
UnsupportedOperationException - 端末が
通常のメールの残りバイト数を取得する機能をサポートしていない場合に発生します。
NullPointerException - 引数 mail が null の場合に発生します。
IllegalArgumentException -
引数の mail にシステムが提供している以外のオブジェクト
(MailDraftクラスを継承した未知のクラスのオブジェクト)
が渡された場合に発生します。
public static int getRemainingBytes(DecomailDraft mail) [iアプリオプションAPI]
引数に指定されたデコメール本文について、
デコメール本文がネイティブで整形された後の
HTML パートとテキストパートを合計したバイト数を計算し、
その値とデコメール仕様上の
HTML パートとテキストパートを合計した最大バイト数とを比較して、
HTML パートとテキストパートの残りに設定できるバイト数を返します。
ただし、このメソッドは実際にデコメール本文の整形を行うわけではありません。
実際の整形処理は send(DecomailDraft) 時に行われます。
ここで返される残りバイト数は、 HTML パート・テキストパートの合計で利用できる残りバイト数です。 テキストパートはネイティブ機能によって自動的に付加されてしまうため、 ここで返される残りバイト数の全てを HTML パートのみで利用できないことに注意してください。
デコメール本文の記述がデコメールの仕様に準拠していない場合に、 デコメール本文を整形し処理が続行されるか、 例外 IllegalArgumentException が発生するかは機種依存です。
端末によっては、 i アプリからデコメールを利用する機能をサポートしていない場合があります。 その場合には、例外 UnsupportedOperationException が発生します。
mail - 送信用のデコメールを指定します。
UnsupportedOperationException - 端末が i アプリからデコメールを利用する機能をサポートしていない場合に発生します。
NullPointerException - 引数 mail が null の場合に発生します。
IllegalArgumentException - インライン画像数、添付ファイル数の上限を超えた場合も含めて、
デコメール本文の記述がデコメールの仕様に準拠していない場合(ただし、サイズ超過を除く)に発生します。
public static boolean send(DecomailDraft mail)
throws MailException,
InterruptedOperationException,
StoreException [iアプリオプションAPI]
送信処理においてサーバが正常応答を返した場合、true を返します。 送信処理中にサーバがエラーを返した場合、MailExceptionをスローします。 送信せずに保存した場合も含めて、それ以外の場合には false を返します。 宛先が複数の場合、いずれかの宛先へのデコメールの送信に失敗した場合、 その失敗の原因に応じて例外を発生またはfalseを返します。 すべての宛先への送信が成功した場合、true を返します。
パーミッションとしてネイティブメーラの利用が許可されている トラステッドiアプリのみこのメソッドを呼び出すことができます。 このメソッドを呼び出すとサスペンドします。
マルチタスク機能によってメーラが起動されていて未保存のデータがある状態の時に、 このメソッドが呼ばれた場合、 現在実行中の Java アプリケーションはサスペンドされ、 ユーザ確認のダイアログが表示されます。 ユーザがメーラの起動を許可した場合は、 ユーザ操作によりデコメールを送信します。 ユーザが起動を許可しなかった場合は、 このメソッドから戻ってJavaアプリケーションの実行を継続します。
デコメールの本文では、MIME マルチパートにおいて HTML パートが必須となります。
HTML パートはネイティブにより整形されます。
また、テキストパートは、ネイティブによって HTML パートから作成されます。
なお、テキストパートが記述されていた場合には、
ネイティブで HTML パートから作成されるテキストパートに書き換えられます。
ただし、DecomailDraft オブジェクトの内容が変更されることはありません。
デコメール本文の記述がデコメールの仕様に準拠していない場合に、 デコメール本文を整形し処理が続行されるか、 例外 IllegalArgumentException が発生するかは機種依存です。
端末によっては、 i アプリからデコメールを利用する機能をサポートしていない場合があります。 その場合には、例外 UnsupportedOperationException が発生します。
mail - 送信するデコメールを指定します。
UnsupportedOperationException - 端末が i アプリからデコメールを利用する機能をサポートしていない場合に発生します。
IllegalStateException - 待ち受け実行時の非活性化状態で呼び出された場合に発生します。
NullPointerException - 引数 mail が null の場合に発生します。
IllegalArgumentException - インライン画像数、添付ファイル数の上限を超えた場合も含めて、
デコメール本文の記述がデコメールの仕様に準拠していない場合(ただし、サイズ超過を除く)に発生します。
IllegalArgumentException - デコメール本文のネイティブによる整形の結果、
デコメール本文、添付ファイル、インライン画像のそれぞれのサイズがデコメールの仕様を超過した場合に発生します。
SecurityException - ロック機能などのネイティブ独自のセキュリティ設定により、
デコメールを送信できない場合に発生します。
StoreException - 送信または未送信フォルダにデコメールを追加できないため、
デコメールを送信できない場合に発生します(STORE_FULL)。
IllegalStateException - UIM読み込み中の場合に発生します。
MailException - User Unknown などによりサーバ側からデコメール送信を拒否された場合に発生します。
InterruptedOperationException - 競合条件などにより、送信操作が異常終了した場合に発生します。