OBEXクライアントAPI

第 9 章待ち受けアプリケーション

10.2 OBEX 外部接続API

10.2.1 OBEXクライアントAPI

OBEX クライアントが使用するコネクションオブジェクトは ClientObexConnection インタフェースを実装しています。このコネクションオブジェクトを取得するには、アプリケーションプログラムは URL 文字列 "obex:/irclient" を指定して Connector.open()メソッドを呼び出します。

以下に、アプリケーションプログラムで ClientObexConnection 実装インスタンスを取得、使用する例を示します。

例：ClientObexConnection の利用

ClientObexConnection coc;

int response;

try {

// ClientObexConnectionインスタンスを取得し、OBEXサーバーに接続する coc = (ClientObexConnection)Connector.open("obex:/irclient",

Connector.READ_WRITE, true);

coc.connect();

// GETオペレーションの実行

coc.setOperation(ObexConnection.GET); // オペレーションにGETを設定 coc.setName("userdata_1"); // GET対象オブジェクトの名前を設定

coc.sendRequest(); // オペレーションを送信

// OBEXサーバーから返却されたレスポンスコードをチェックし、正常であれば受信した // オブジェクト本体を読み込む

response = coc.getResponseCode();

if (response==ObexConnection.SUCCESS) {

InputStream in = coc.openInputStream();

： // GETオペレーションで要求したデータの読み込み処理

in.close();

} else {

throw new IOException();

}

// PUTオペレーションの実行

coc.setOperation(ObexConnection.PUT); // オペレーションにPUTを設定 coc.setName("userdata_2"); // PUT対象オブジェクトの名前を設定 coc.setType("text/plain"); // PUT対象オブジェクトのタイプを設定 coc.setTime(System.currentTimeMillis()); // PUT対象オブジェクトのタイムスタンプを設定

OutputStream out = coc.openOutputStream();

： // PUTオペレーションで送信するデータの書き込み処理 out.close();

coc.sendRequest(); // オペレーションを送信

// レスポンスコードが正常であればClientObexConnectionを閉じて処理終了 response = coc.getResponseCode();

if (response!=ObexConnection.SUCCESS) { throw new IOException();

}

coc.close();

} catch (IOException ioe) { // 例外処理

// APIがスローするIOException、ConnectionException、

// アプリケーションプログラムがスローするIOExceptionの処理を行う

：

}

アプリケーションプログラムは ClientObexConnection を使用する際に、まず connect()メソッドを呼び出して OBEX サーバーとの間に赤外線通信のリンクを確立します。いったん確立された通信リンク上では、複数のオペレーションを連続して処理することができます。前出のサンプルコードでは、1 回確立した通信リンク上で GET オペレーションと PUT オペレーションを 1 回ずつ処理し、その後 ClientObexConnection.close()を呼び出して通信リンクを切断しています。

OBEX クライアントでは、オペレーションの処理は以下の手順に従って行います。

1. setOperation()メソッドを使用してオペレーション種別を設定します。

2. ObexConnectionで定義されているアクセスメソッドを使用して、OBEXリクエストヘッダの設定を行います。アクセスメソッドを使用して設定することのできるOBEXリクエストヘッダには、Nameヘッダ、Typeヘッダ、Timeヘッダがあります。

3. PUTオペレーションの場合、送信するオブジェクトボディの内容を書き込みます。この操作は、コネクションオブジェクトのopenOutputStream()またはopenDataOutputStream()メソッドで取り出した出力ストリームを使用して行います。

4. sendRequest()メソッドを使用してオペレーション処理要求をOBEXサーバーに送信します。このメソッドはOBEXサーバーから応答が返されるまでブロックします。このメソッド呼び出しから復帰すると、必要に応じてOBEXサーバーから返却されたOBEXレスポンスコードやOBEXレスポンスヘッダの内容を参照することができます。OBEXクライアントが参照することのできるOBEXレスポンスヘッダには、Nameヘッダ、Typeヘッダ、Timeヘッダがあります。また、OBEXレスポンスコードは ObexConnectionで定義されています。ObexConnectionで定義されているOBEXレスポンスコードは、OBEX規格におけるレスポンスコードの規定に準拠しています。各コードの意味などの詳細についてはOBEX規格を参照してください。OBEXサーバーがOBEXクライアントの要求を正常に処理できた場合、一般的にはOBEXクライアントアプリケーションは、OBEXレスポンスコードとしてｉアプリ実行環境（CrientObexConnection.getResponseCode()メソッド）からObexConnection.SUCCESS を受け取ります。

5. GETオペレーションの場合、返却されたオブジェクトボディの内容を読み出します。この操作は、コネクションオブジェクトのopenInputStream()またはopenDataInputStream()メソッドで取り出した入力ストリームを使用して行います。オブジェクトボディの長さは、コネクションオブジェクトの getContentLength()メソッドを使用して取得することができます。

OBEX クライアントの処理は、全体として上記のシーケンスに合致するようにしてください。例えばオペレーション処理要求を OBEX サーバーに送信していない状態で OBEX レスポンスヘッダを取得しようとすると例外が発生します。

次の図に、ClientObexConnection の状態遷移を示します。

図 13: ClientObexConnection の状態遷移

注意事項：

● OBEX外部接続においては、Connectorクラスから直接openInputStream()、

openDataInputStream()、openOutputStream()、openDataOutputStream()の各メソッドにより入出力ストリームを取り出すことはできません。アプリケーションプログラムはConnector.open()メソッドでClientObexConnectionオブジェクトを取得し、そのオブジェクトから入出力ストリームを取り出す必要があります。

● 携帯電話の赤外線ポートへの通電は、アプリケーションプログラムから

ClientObexConnection.connect()を呼び出した際に、システムにより自動的に行われます。

● OBEXサーバーに対し1度のオペレーションで、オブジェクトを送信するとともにOBEXサーバーからオブジェクトを受信することはできません。OBEXクライアントは、PUTオペレーションではオブジェクトの送信、GETオペレーションではオブジェクトの受信のみ行うことができます。

● OBEXクライアントにおけるコネクションオブジェクトのオープンモードは、READモードがGETオペレーションに、WRITEモードがPUTオペレーションに対応します。1回の接続でGET、PUTの両オペレーションを使用する場合は、READ_WRITEモードを使用するようにしてください。

● Nameヘッダ、Typeヘッダの値にはそれぞれ最大63文字まで指定可能です。また、Typeヘッダの値にはASCII 文字のみ使用することができます。

● 1つのｉアプリから同時に確立可能な通信リンクは1つだけです。また、ｉアプリのバックグラウンドで動作しているネイティブ機能を含め、パケット通信が行われている状況では、OBEX外部接続の通信リンクを確立することはできません。

● あるスレッドがconnect()メソッドやsendRequest()メソッドを呼び出してOBEXサーバーのアクションを待っている時、他のスレッドがClientObexConnectionオブジェクトのclose()メソッドを呼び出すと通信は切断されます。また、タイムアウト発生やユーザーの中断操作といった要因により、通信が切断されることがあります。

● GET、PUTの両オペレーションとも、1回につき100Kバイトまでのオブジェクトを取り扱うことができます。

この制限を越えたサイズのオブジェクトを送受信することはできません。

【DoJa-3.0】

送受信可能なオブジェクトサイズの制限は、DoJa-3.0プロファイルで緩和されました。DoJa-2.0プロファイルでは、送受信可能なオブジェクトサイズは30Kバイトまでに制限されています。

接続状態

Connector.open()

通信完了 ClientObexConnection.openInputStream()

読み取り可能読み取り完了

InputStream.read()

InputStream.close() 初期状態

ClientObexConnection.openOutputStream()

書き込み可能書き込み完了

OutputStream.write()

OutputStream.close()

クローズ

ClientObexConnection.sendRequest()

ClientObexConnection.close()

凡例

状態状態遷移

● アプリケーションプログラムが設定したオペレーション種別やOBEXヘッダ、オブジェクトデータの内容は、

1回のオペレーションでのみ有効です。1回の接続で連続してオペレーションを実行する場合、その都度これらを設定しなおすようにしてください。

● OBEXサーバーから返却されたレスポンスコードが異常を示す値（0x20番台以外のコード）であった場合、

ｉアプリ実行環境は例外をスローします。

● DoJa-2.0プロファイル以降に対応した携帯電話では、外部との通信機能を一切停止して、通信を使用しない

機能のみ利用可能とするセルフモード機能が搭載されます。ユーザーが携帯電話をセルフモードにしている状態では、ｉアプリの起動を行うことはできますが起動されたｉアプリがOBEX外部接続を行うことはできません。

● 非活性化状態の待ち受けアプリケーションは、OBEX外部接続を行うことはできません。また、活性化状態の待ち受けアプリケーションがOBEX外部接続を行っている際に非活性化状態に遷移しようとすると、

OBEX外部接続は失敗します。

● ｉアプリが赤外線通信を行っている間は、ｉアプリ実行環境は通信を実行中である旨のメッセージを表示します。また通信リンクの確立が行えなかった場合や、タイムアウト、ユーザー操作などにより通信が中断された場合には、ｉアプリ実行環境はその旨をユーザーに伝えるメッセージを表示します。これらのメッセージを非表示とすることはできません。

ドキュメント内 iアプリコンテンツ開発ガイド for Doja-5.x/5.x LE ～詳細編～ (ページ 148-151)

第 9 章 待ち受けアプリケーション