赤外線データ転送API概要｜リファレンス（API）｜開発者向け情報

【APIの説明】

OBEX APIについて

OBEX APIは、アプリケーションに赤外線データ送受信機能を追加します。
追加された機能により、赤外線ポートを用いて、任意のデータを他のデバイスへ送信あるいは、他のデバイスから受信することが可能になります。
IrSimple™規格(IrSimple™は、Infrared Data Association®の商標です)にも準拠しているため、他のデバイスとのデータ連携を高速に行うことができます。
また、OBEXの認証接続にも対応していますので、他のデバイスとを行ったうえで通信を行うことが可能です。
送受信可能なデータサイズには制限があります。また、データによっては送受信できない場合もあります。

※基本的には10MByte以下となります。一部データはそれより小さくなる可能性があります。

PushClientクラスについて

データを他のデバイスへ送信する場合、PushClientクラスを使用します。
import jp.co.sharp.android.io.obex.client.PushClient;

PushServerクラスについて

データを他のデバイスから受信する場合、PushServerクラスを使用します。
import jp.co.sharp.android.io.obex.server.PushServer;

赤外線送受信の開始と終了について

赤外線送受信は、ブロードキャストインテントを用いた、次のようなイベント遷移を行います。

(1)相手機器との接続確認
接続完了、切断完了を受け取り、接続完了の場合、(2)に進みます。
(2)送受信開始
オブジェクトの送受信が開始され、送受信中は(3)が繰り返されます。
(3)送受信状況の確認
送受信が開始されると、オブジェクトのサイズに応じて複数回、状況確認のIntent受信が発生します。
(4)送受信の完了
全てのオブジェクトの送受信が完了したか、エラーが発生して終了すると、接続を切断し、赤外線送受信を終了します。

このAPIを使用するには

SDKへAddOnの追加と、Manifestファイルへライブラリの参照を記述する必要があります。
また、Android4.4(KK/API Lv15）以降の端末では、microSD、ストレージに保存されたデータを送信する際、データを読み込むためのパーミッションを記述する必要があります。

【パッケージ/クラス一覧】

パッケージ名	クラス名	備考
jp.co.sharp.android.io.obex.client	PushClient	赤外線送信
jp.co.sharp.android.io.obex.server	PushServer	赤外線受信

【APIの使い方】

Manifestファイルの記述

まず、Manifestファイルへ、アプリケーションが参照するライブラリの参照設定を行います。
Manifestファイルの<application>要素の子要素に<user-library>を追加します。
<user-library>のandroid:name属性にjp.co.sharp.android.io.obexを設定します。

これらの宣言がなければ、OBEXクラスを使用することができないため、注意してください。

さらに、Android4.4以降が搭載された端末用には、microSD、本体ストレージにあるデータを参照するために、上記に加えて<uses-permission>で、android.permission.READ_EXTERNAL_STORAGE を追加してください。

PushClientの使用方法（赤外線データ送信）

○まず、ブロードキャストインテントの受信設定を行います。

IntentFilter filter = new IntentFilter();
filter.addAction(PushClient.CONNECTION_STATUS);
filter.addAction(PushClient.PUT_STARTED);
filter.addAction(PushClient.PUT_PROGRESS);
filter.addAction(PushClient.PUT_FINISHED);
registerReceiver(mBroadcastReceiver, filter);

○次に、PushClientインスタンスを生成し、相手機器でのオブジェクト送信を開始します。

PushClient client = new PushClient();
client.put(
    PushClient.TYPE_AUTO,
    null,
    "sample.jpg",
    null,
    Uri.parse("file:///sdcard/sample.jpg")
);

put()メソッドは、用途によって引数の種類が異なります。詳細はリファレンスを参照してください。
上記サンプルコードでは、SDカード内に保存されているsample.jpgというファイルを送信しています。

○以後はブロードキャストインテントを受信し、送信状況の画面表示などを行うことができます。
通常は以下の順序で受信されます。

(1) CONNECTION_STATUS
相手機器への接続完了、あるいは切断完了を表します。
接続完了後オブジェクトの送信が始ります。
(2) PUT_STARTED
オブジェクトの送信が始まることを表します。
(3) PUT_PROGRESS
オブジェクト送信中の送信状況を表します。オブジェクトのサイズに応じて複数回このインテントが受信されます。
このインテントは受信されない場合もあります。
(4) PUT_FINISHED
送信完了を表します。全てのオブジェクトを送信完了したかエラーが発生して終了すると接続は切断されます。

private BroadcastReceiver mBroadcastReceiver = new BroadcastReceiver() {
    public void onReceive(Context context, Intent intent) {
        String action = intent.getAction();
        if (action.equals(PushClient.CONNECTION_STATUS)) {
            int status = intent.getIntExtra(
                "status", PushClient.STATUS_NOT_CONNECTED
            );
            int result = intent.getIntExtra(
                "result", PushClient.RESULT_ERROR_OTHER
            );
            if (status == PushClient.STATUS_NOT_CONNECTED) {
                if (result == PushClient.RESULT_SUCCESS) {
                    // 送信が終了し、切断完了です。
                } else {
                    // エラー終了です。
                }
            } else {
                // 接続完了です。
            }
        } else if (action.equals(PushClient.PUT_STARTED)) {
            // オブジェクトの送信を開始します。
        } else if (action.equals(PushClient.PUT_PROGRESS)) {
            // 送信処理中。送信済みサイズを取得可能です。
        } else if (action.equals(PushClient.PUT_FINISHED)) {
            // オブジェクトの送信終了です。
            // 複数オブジェクトを送信している場合は、
            // 1件ごとにこのIntentを受信します。
            int result = intent.getIntExtra(
                "result", PushClient.RESULT_ERROR_OTHER
            );
            if (result == PushClient.RESULT_SUCCESS) {
                // 送信中のオブジェクトの送信に成功した場合の処理を
                // 記述します。
            } else {
                // 送信中のオブジェクトの送信に失敗した場合の処理を
                // 記述します。
            }
        }
    }
};

PushServerの使用方法（赤外線データ受信）

○まず、インテントの受信設定を行います。

IntentFilter filter = new IntentFilter();
filter.addAction(PushServer.CONNECTION_STATUS);
filter.addAction(PushServer.PUT_STARTED);
filter.addAction(PushServer.PUT_PROGRESS);
filter.addAction(PushServer.PUT_FINISHED);
registerReceiver(mBroadcastReceiver, filter);

○次に、インスタンスを生成し、相手機器との接続待ちを開始します。

PushServer server = new PushServer();
server.connect(PushServer.TYPE_AUTO);

○以後は、ブロードキャストインテントの受信を契機にオブジェクト受信を行います。
通常は以下の順序で受信されます。

(1) CONNECTION_STATUS
相手機器からの接続が完了したこと、あるいは切断されたことを表します。
(2) PUT_STARTED
相手からのオブジェクトの受信が始まることを表します。
(3) PUT_PROGRESS
オブジェクト受信中の受信状況を表します。オブジェクトのサイズに応じて複数回このインテントが受信されます。
このインテントは受信されない場合もあります。
(4) PUT_FINISHED
オブジェクトの受信が終了したことを表します。

private BroadcastReceiver mBroadcastReceiver = new BroadcastReceiver() {
    public void onReceive(Context context, Intent intent) {
        String action = intent.getAction();
        if (action.equals(PushServer.CONNECTION_STATUS)) {
            int status = intent.getIntExtra(
                "status", PushServer.STATUS_NOT_CONNECTED
            );
            int result = intent.getIntExtra(
                "result", PushServer.RESULT_ERROR_OTHER
            );
            if (status == PushServer.STATUS_NOT_CONNECTED) {
                if (result == PushServer.RESULT_SUCCESS) {
                    // 送信が終了し、切断完了です。
                } else {
                    // エラー終了です。
                }
            } else {
                // 接続完了です。
            }
        } else if (action.equals(PushServer.PUT_STARTED)) {
            // 相手からの送信が開始されたので保存先ファイル名を指定します。
            String name = intent.getStringExtra("name");
            String filePath = "/sdcard/" + name;
            server.accept(filepath);
            // 受信・保存しない場合は下記を呼び出します。
            // server.reject();
        } else if (action.equals(PushServer.PUT_PROGRESS)) {
            // 受信処理中。受信済みサイズを取得可能です。
        } else if (action.equals(PushServer.PUT_FINISHED)) {
            // オブジェクトの受信終了です。
            int result = intent.getIntExtra(
                "result", PushServer.RESULT_ERROR_OTHER
            );
            if (result == PushServer.RESULT_SUCCESS) {
                // 受信中のオブジェクトの受信に成功した場合の処理を
                // 記述します。
            } else {
                // 受信中のオブジェクトの受信に失敗した場合の処理を
                // 記述します。
            }
        }
    }
};

accept()メソッドは、用途によって引数の種類が異なります。
詳細はリファレンスを参照してください。
上記サンプルコードでは、受信したファイルをSDカード内に保存しています。

○相手機器との接続待ちを終了します。

server.disconnect();

受信したオブジェクトの保存について

データ保存について特に規定はなく、PushServer#acceptを呼び出す際にファイルパスあるいはUriを指定しておけば、そこにデータを保存します。
コールバックを指定した場合は、受信データを順次アプリ側にコールバックしますので、アプリで自由にデータを処理することができます。

OBEX認証接続の使用方法

このクラスではOBEXの認証接続にも対応していますので、本機（自分）と相手機側で同じ認証コードを入力してから通信を開始することができます。
本機の側ではPushClient#putおよびPushServer#connectの引数String authCodeに認証コード（4桁の数値)を渡しておくだけでこの処理を行うことができます。
サンプルアプリでは、認証コードはnull（認証接続しない）になっています。

【その他の特記事項】

OBEXクラス使用時の注意事項

このクラスは赤外線OBEX通信のみ行うことができます。
Bluetooth OBEX通信(OPP)などは行うことができません。
また、既に他のOBEX通信が行われているときは、同時に本機能でのOBEX通信を行うことはできません。

PushClientでは、相手からの応答を最大30秒程度待ちます。
送信途中で中止する場合はPushClient#cancelを呼び出してください。

PushServerでは、相手からの接続、送信を最大30秒程度待ちます。
PushServerの利用終了時は必ずPushServer#disconnectを呼び出してください。

これらを行わない場合、最大30秒程度、次のOBEX通信を開始できない場合があります。

【リファレンスへ】
　【サンプルコードへ】
　【公開API一覧へ】