com.docomostar.system
クラス MailAgent

Object
  com.docomostar.system.MailAgent

public final class MailAgent
extends Object

携帯電話のネイティブのメール機能にアクセスする手段を提供します。

メールの取得および送信(または保存)機能を提供します。

メール機能では、 メールの取得や送信を行うクラスと、 メールそのものを表すクラスが区別されています。 このクラスはメールの取得や送信を行いますが、 メールそのものは Mail および MailDraft クラスのオブジェクトとして表されます。

getLastIncoming() メソッドにより、 最新のメールが未読メールの場合、そのメールを取得することができます。 取得されたメール(Mail オブジェクト)には、 サブジェクト (XString)、 日付 (XStringとして取得可能)、 宛先アドレス (XString)、 差出人アドレス (XString) およびその電話帳 ID が設定されています。

テキストメールを新規に作成し、送信(または保存)するためには、 send(String, String[], String) メソッドまたは send(String, XString, String) メソッドを直接呼び出すか、 MailDraft オブジェクトに対して宛先等を設定して send(MailDraft) メソッドを呼び出します。

これらのメソッドを呼び出すと、 アプリケーションがサスペンドしてネイティブのメール作成画面が起動します。 その時、引数に指定した内容はメール作成画面に反映されています。 ユーザは、メール作成画面を通じて、そのメールをそのまま、 あるいは変更してから、 送信(または保存)を行うことができます。 送信の成否にかかわらず、 送信に使用した MailDraft オブジェクトの状態は変化しません。 なお、 テキストメールの send 時に設定するサブジェクト、宛先アドレス、メール本文の文字列の扱いについては、以下の通りです。

ネイティブのメーラで扱えない文字が含まれている場合:

宛先アドレスにおいて「i モードメールの仕様に準拠していない」という理由で例外が発生します。 サブジェクト、メール本文については以下のような振る舞いとなります。

• [Star-1.1 まで] サブジェクト、メール本文の全てにおいて 「i モードメールの仕様に準拠していない」という理由で例外が発生します。
  
• [Star-1.2 以降] サブジェクト、メール本文において、ネイティブのメーラで扱えない文字が含まれている場合は、 それらの文字を半角中点(U+FF65)に置換した文字列がネイティブのメール作成画面に設定されます。
  

テキストメールの本文においては、 改行文字(単独の "¥r"、単独の "¥n"、 または "¥r¥n")、 ならびにタブ文字("¥t")を指定可能です。 改行文字は全て "¥r¥n" に正規化した文字列がネイティブのメール作成画面に設定されます。
なお、上記例外を除いては、改行文字を含む制御文字 (0x00 〜 0x1F、0x7F) は 「ネイティブのメーラで扱えない文字」に含まれます。

ネイティブのメーラで扱える最大バイト数を超える文字列が指定された場合:

サブジェクト、宛先アドレス、メール本文の全てにおいて 「i モードメールの仕様に準拠していない」という理由で 例外が発生します。 なお、各最大バイト数は以下になります。

• テキストメールの宛先アドレスの最大バイト数は、 デフォルトエンコーディングで評価して、 1 アドレスあたり 50 バイトです。
• テキストメールのサブジェクトの最大バイト数は 200 バイトです。
  • [Star-1.1 まで] バイト数は、デフォルトエンコーディングで評価されます。
  • [Star-1.2 以降] バイト数は 含まれている文字の種類や端末の設定、あるいは端末のマルチリンガル言語サポート有無によって、 デフォルトエンコーディング、または UTF-8 で評価されます。
• テキストメール本文の最大バイト数は 10000 バイトです。
  • [Star-1.1 まで] バイト数は、改行文字を "¥r¥n" に正規化したものについてデフォルトエンコーディングで評価されます。
  • [Star-1.2 以降] バイト数は、以下の処理が全て完了したものについて、 含まれている文字の種類や端末の設定、あるいは端末のマルチリンガル言語サポート有無によって、 デフォルトエンコーディング、または UTF-8 で評価されます。
    1. 改行文字を "¥r¥n" に正規化する
    2. ネイティブのメーラで扱えない文字を半角中点(U+FF65)に置換する

null や空文字列("")が指定された場合:

• サブジェクト、メール本文には指定可能です。 その場合は、その項目には何も入力されていない状態でメーラが起動します。
• 配列型でない宛先アドレスには null は指定可能です。 その場合は、その項目には何も入力されていない状態でメーラが起動します。 空文字列を指定すると例外が発生します (空文字列のアドレスは 「i モードメールの仕様に準拠していない」とみなされます)。
• 宛先アドレスの配列には null や長さ 0 の配列が指定可能です。 その場合にも、メールアドレスが入力されていない状態でメーラが起動します。
• 宛先アドレスの配列のいずれかの要素に null や 空文字列を指定すると例外が発生します (空文字列のアドレスは 「i モードメールの仕様に準拠していない」とみなされます)。

なお、テキストメールの本文は、send メソッドが呼び出された直後に本文中の改行文字が全て正規化され、 正規化後のデータに対してiモードメールの仕様に準拠しているかどうかのチェックが行われます。
[Star-1.2 以降]
改行文字の正規化後、ネイティブのメーラで扱えない文字は半角中点(U+FF65)へ置換されます。

ミニマムスペック:

[Star-1.5 (2011年春以降発売モデル) まで] ミニマムスペックでは、5件までの宛先アドレスに送信することができます。
[Star-2.0 以降] ミニマムスペックでは、50件までの宛先アドレスに送信することができます。

導入されたバージョン:

Star-1.0

関連項目:

Mail, MailDraft

メソッドの概要

static Mail	getLastIncoming() 最新の未読メールを取得します。
static int	getRemainingBytes(MailDraft 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

メソッドの詳細

getLastIncoming

public static Mail getLastIncoming()

最新の未読メールを取得します。 メッセージ Star アプリ向けのメールや、SMS、エリアメールも含めて、 すべての受信メール中の最新のメールが未読の場合、 そのメールを取得することができます。

取得されたメール(Mailオブジェクト)には、 サブジェクト(XString)、 日付(XStringとして取得可能)、 宛先アドレス(XString)、 差出人アドレス(XString)およびその電話帳IDが設定されています。

このメソッドを利用して最新の未読メールを取得しても、 端末のメールピクトやそのメールの未読情報は変化しません。

パーミッションとして携帯電話情報の参照が許可されている トラステッドStar アプリのみこのメソッドを呼び出すことができます。

戻り値:

最新の未読メールを返します。 最新のメールが未読ではない場合、nullを返します。

例外:

SecurityException -
パーミッションとして携帯電話情報の参照が許可されているが、 Star アプリ個別のユーザ設定により許可されない場合に発生します。

SecurityException -
メールロックにより拒否される場合に発生します。

SecurityException -
ネイティブ独自のセキュリティ設定により、 メールを取得できない場合に発生します。

IllegalStateException -
UIM 読み込み中の場合に発生します。

send

public static boolean send(String subject,
                           String[] addresses,
                           String body)
                    throws MailException,
                           InterruptedOperationException,
                           StoreException

ユーザ操作によりメールを送信します。 各引数に指定できる文字列については、 このクラスの説明を参照して下さい。

送信処理においてサーバが正常応答を返した場合、true を返します。 送信処理中にサーバがエラーを返した場合、MailExceptionをスローします。 送信せずに保存した場合も含めて、それ以外の場合には false を返します。 宛先が複数の場合、いずれかの宛先へのメールの送信に失敗した場合、 その失敗の原因に応じて例外を発生またはfalseを返します。 すべての宛先への送信が成功した場合、true を返します。

パーミッションとしてネイティブメーラの利用が許可されている トラステッドStar アプリのみこのメソッドを呼び出すことができます。 このメソッドを呼び出すとサスペンドします。

マルチタスク機能によってメーラが起動されていて未保存のデータがある状態の時にこのメソッドが呼ばれた場合、 現在実行中のStar アプリはサスペンドされ、 ユーザ確認のダイアログが表示されます。 ユーザがメーラの起動を許可した場合は、 ユーザ操作によりメールを送信します。 ユーザが起動を許可しなかった場合は、 このメソッドから戻ってStar アプリの実行を継続します。

パラメータ:

subject - サブジェクト(通常文字列)を指定します。

addresses - 宛先アドレス(通常文字列)を配列で指定します。

body - 本文(通常文字列)を指定します。

戻り値:

送信が完了した場合、true を返します。 それ以外の場合、false を返します。

例外:

IllegalStateException -
ミニアプリ実行時の Focused または Unfocused 状態で呼び出された場合に発生します。

NullPointerException -
引数 addresses が null でない場合に、 配列中に null の要素があった場合に発生します。

IllegalArgumentException -
実装がサポートしている数以上のメールアドレスを指定した場合に 発生します。

IllegalArgumentException -
引数 subject、addresses、bodyの内容のいずれかが、 iモードメールの仕様に準拠していない場合に発生します。

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

StoreException -
(STORE_FULL)
送信または未送信フォルダにメールを追加できないため、 メールを送信できない場合に発生します。

IllegalStateException -
UIM 読み込み中の場合に発生します。

MailException -
User Unknownなどによりサーバ側からメール送信を拒否された場合に発生します。

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

send

public static boolean send(String subject,
                           XString address,
                           String body)
                    throws MailException,
                           InterruptedOperationException,
                           StoreException

ユーザ操作によりメールを送信します。 各引数に指定できる文字列については、 このクラスの説明を参照して下さい。

送信処理においてサーバが正常応答を返した場合、true を返します。 送信処理中にサーバがエラーを返した場合、MailExceptionをスローします。 送信せずに保存した場合も含めて、それ以外の場合には false を返します。 宛先が複数の場合、いずれかの宛先へのメールの送信に失敗した場合、 その失敗の原因に応じて例外を発生またはfalseを返します。 すべての宛先への送信が成功した場合、true を返します。

パーミッションとしてネイティブメーラの利用が許可されている トラステッドStar アプリのみこのメソッドを呼び出すことができます。 このメソッドを呼び出すとサスペンドします。

マルチタスク機能によってメーラが起動されていて未保存のデータがある状態の時にこのメソッドが呼ばれた場合、 現在実行中のStar アプリはサスペンドされ、 ユーザ確認のダイアログが表示されます。 ユーザがメーラの起動を許可した場合は、 ユーザ操作によりメールを送信します。 ユーザが起動を許可しなかった場合は、 このメソッドから戻ってStar アプリの実行を継続します。

パラメータ:

subject - サブジェクト(通常文字列)を指定します。

address - 宛先アドレス(XString)を指定します。

body - 本文(通常文字列)を指定します。

戻り値:

送信が完了した場合、true を返します。 それ以外の場合、false を返します。

例外:

IllegalStateException -
ミニアプリ実行時の Focused または Unfocused 状態で呼び出された場合に発生します。

IllegalArgumentException -
引数 subject、address、bodyの内容のいずれかが、 iモードメールの仕様に準拠していない場合に発生します。

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

StoreException -
(STORE_FULL)
送信または未送信フォルダにメールを追加できないため、 メールを送信できない場合に発生します。

IllegalStateException -
UIM 読み込み中の場合に発生します。

MailException -
User Unknownなどによりサーバ側からメール送信を拒否された場合に発生します。

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

send

public static boolean send(MailDraft mail)
                    throws MailException,
                           InterruptedOperationException,
                           StoreException

ユーザ操作によりメールを送信します。

[Star-1.1 まで]
MailDraft に指定されたサブジェクト、宛先アドレス、メール本文の文字列の扱いについては、 MailDraft クラスの説明を参照してください。
[Star-1.2 以降]
MailDraft に指定されたサブジェクト、宛先アドレス、メール本文の文字列の扱いについては、 このクラスの説明を参照してください。

送信処理においてサーバが正常応答を返した場合、true を返します。 送信処理中にサーバがエラーを返した場合、MailExceptionをスローします。 送信せずに保存した場合も含めて、それ以外の場合には false を返します。 宛先が複数の場合、いずれかの宛先へのメールの送信に失敗した場合、 その失敗の原因に応じて例外を発生またはfalseを返します。 すべての宛先への送信が成功した場合、true を返します。

パーミッションとしてネイティブメーラの利用が許可されている トラステッドStar アプリのみこのメソッドを呼び出すことができます。 このメソッドを呼び出すとサスペンドします。

マルチタスク機能によってメーラが起動されていて未保存のデータがある状態の時にこのメソッドが呼ばれた場合、 現在実行中のStar アプリはサスペンドされ、 溷