Network Information プラグイン

テスト環境 ( バージョン番号 ) : 2.0.2

このプラグインの詳細は、こちらの原文 ( GitHub ) をご確認ください。

プラグイン ID

cordova-plugin-network-information

プラグインの追加方法

このプラグインを使用する場合には、Monaca クラウド IDE の [ Cordova プラグインの管理 ] 上で、Network Information プラグインを有効にします。

対象プラットフォーム

Android
iOS

Connection

connection オブジェクトを使用して、セルラー、WiFi 接続などのネットワーク情報を取得します ( navigator.connection 経由で情報にアクセスします )。

プロパティ

connection.type

定数

Connection.UNKNOWN
Connection.ETHERNET
Connection.WIFI
Connection.CELL_2G
Connection.CELL_3G
Connection.CELL_4G
Connection.CELL
Connection.NONE

connection.type

このプロパティを使用して、ネットワーク接続の状態と接続のタイプを確認します。

例

function checkConnection() {
    var networkState = navigator.connection.type;

    var states = {};
    states[Connection.UNKNOWN]  = 'Unknown connection';
    states[Connection.ETHERNET] = 'Ethernet connection';
    states[Connection.WIFI]     = 'WiFi connection';
    states[Connection.CELL_2G]  = 'Cell 2G connection';
    states[Connection.CELL_3G]  = 'Cell 3G connection';
    states[Connection.CELL_4G]  = 'Cell 4G connection';
    states[Connection.CELL]     = 'Cell generic connection';
    states[Connection.NONE]     = 'No network connection';

    alert('Connection type: ' + states[networkState]);
}

checkConnection();

API の変更点

Cordova 2.3.0 までは、navigator.network.connection 経由で Connection オブジェクトにアクセスしていましたが、W3C の仕様に準拠するため、navigator.connection 経由に変更しました。 navigator.network.connection は利用できますが、将来的には廃止します。

iOS 特有の動作

iOS では、セルラー接続のタイプを識別できません。
- モバイルデータ通信 ( セルラーを使用したデータ通信 )に関しては、navigator.connection.type は Connection.CELLになります。

ネットワーク関連のイベント

offline

アプリがオフラインになったときに、このイベントが発火します。端末は、インターネットに接続されていません。

document.addEventListener("offline", yourCallbackFunction, false);

詳細

デバイスのネットワーク接続が切れたときに、offline ( オフライン ) イベントが発火します ( connection.type が NONE に変わったときに発火します )。ネットワーク接続が切れているため、アプリは、インターネットへアクセスできません。Connection API と同じ情報を使用します。

原則、イベントリスナーの登録には、 document.addEventListener を使用します。また、JavaScript からネイティブ機能へのアクセスは、deviceready イベントの発火後に行います。

例

document.addEventListener("offline", onOffline, false);

function onOffline() {
    // Handle the offline event
}

iOS 特有の動作

初回起動時は、offline ( オフライン ) イベントが発火するまで ( 発火の条件が揃ってること )、最低 1 秒かかります。

online

アプリがオンラインになったときに、このイベントが発火します。端末は、インターネットに接続されています。

document.addEventListener("online", yourCallbackFunction, false);

詳細

端末がネットワークに接続して、アプリからインターネットが使用できる状態になったときに、online ( オンライン ) イベントが発火します ( connection.type が NONE から他の値に変わったときに発火します )。Connection API と同じ情報を使用します。

例

document.addEventListener("online", onOnline, false);

function onOnline() {
    // Handle the online event
}

iOS 特有の動作

初回起動時は、online ( オンライン ) イベントが発火するまで ( 発火の条件が揃ってること )、最低 1 秒かかります ( connection.type が UNKNOWN になる前に )。

サンプル

このセクションのコード例は、オンラインイベントとオフラインイベント、およびネットワーク接続ステータスを使用しているアプリケーションの動作を変更する例を示しています。

まず、サンプルデータ用に新しい FileEntry オブジェクト（ data.txt ）を作成します。この関数を deviceready ハンドラから呼び出します。

このコード例では、File プラグインが必要です。

var dataFileEntry;

function createSomeData() {

    window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {

        console.log('file system open: ' + fs.name);
        // Creates a new file or returns an existing file.
        fs.root.getFile("data.txt", { create: true, exclusive: false }, function (fileEntry) {

          dataFileEntry = fileEntry;

        }, onErrorCreateFile);

    }, onErrorLoadFs);
}

次に、deviceready で online と offline イベントリスナーを追加します。

document.addEventListener("offline", onOffline, false);
document.addEventListener("online", onOnline, false);

アプリの onOnline 関数は、online イベントを処理します。イベントハンドラで、現在のネットワーク状態を確認します。このアプリでは、Connection.NONE 以外のすべての接続タイプを good として扱います。接続している場合は、ファイルをアップロードしようとします。

function onOnline() {
    // Handle the online event
    var networkState = navigator.connection.type;

    if (networkState !== Connection.NONE) {
        if (dataFileEntry) {
            tryToUploadFile();
        }
    }
    display('Connection type: ' + networkState);
}

前のコードで online イベントが発生した場合は、アプリの tryToUploadFile 関数を呼び出します。 FileTransfer オブジェクトのアップロード機能が失敗した場合は、アプリケーションの offlineWrite 関数を呼び出して、現在のデータを保存します。

この例では、FileTransfer プラグインが必要です。

function tryToUploadFile() {
    // !! Assumes variable fileURL contains a valid URL to a text file on the device,
    var fileURL = getDataFileEntry().toURL();

    var success = function (r) {
        console.log("Response = " + r.response);
        display("Uploaded. Response: " + r.response);
    }

    var fail = function (error) {
        console.log("An error has occurred: Code = " + error.code);
        offlineWrite("Failed to upload: some offline data");
    }

    var options = new FileUploadOptions();
    options.fileKey = "file";
    options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
    options.mimeType = "text/plain";

    var ft = new FileTransfer();
    // Make sure you add the domain of your server URL to the
    // Content-Security-Policy <meta> element in index.html.
    ft.upload(fileURL, encodeURI(SERVER), success, fail, options);
};

offlineWrite 関数のコードは次のとおりです。

このコード例では、File プラグインが必要です。

function offlineWrite(offlineData) {
    // Create a FileWriter object for our FileEntry.
    dataFileEntry.createWriter(function (fileWriter) {

        fileWriter.onwriteend = function () {
            console.log("Successful file write...");
            display(offlineData);
        };

        fileWriter.onerror = function (e) {
            console.log("Failed file write: " + e.toString());
        };

        fileWriter.write(offlineData);
    });
}

offline イベントが発生した場合は、ユーザーに通知する（この例では単にログに記録する）操作を行います。

function onOffline() {
    // Handle the offline event
    console.log("lost connection");
}