diff options
Diffstat (limited to 'StoneIsland/plugins/cordova-plugin-network-information/README.md')
| -rw-r--r--[-rwxr-xr-x] | StoneIsland/plugins/cordova-plugin-network-information/README.md | 187 |
1 files changed, 160 insertions, 27 deletions
diff --git a/StoneIsland/plugins/cordova-plugin-network-information/README.md b/StoneIsland/plugins/cordova-plugin-network-information/README.md index c78f3b02..394058c4 100755..100644 --- a/StoneIsland/plugins/cordova-plugin-network-information/README.md +++ b/StoneIsland/plugins/cordova-plugin-network-information/README.md @@ -1,3 +1,7 @@ +--- +title: Network Information +description: Get information about wireless connectivity. +--- <!-- # license: Licensed to the Apache Software Foundation (ASF) under one # or more contributor license agreements. See the NOTICE file @@ -17,15 +21,24 @@ # under the License. --> +|Android|iOS| Windows 8.1 Store | Windows 8.1 Phone | Windows 10 Store | Travis CI | +|:-:|:-:|:-:|:-:|:-:|:-:| +|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-network-information/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-network-information/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-store,PLUGIN=cordova-plugin-network-information/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-8.1-phone,PLUGIN=cordova-plugin-network-information/)|[](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-network-information/)|[](https://travis-ci.org/apache/cordova-plugin-network-information)| + # cordova-plugin-network-information -[](https://travis-ci.org/apache/cordova-plugin-network-information) This plugin provides an implementation of an old version of the [Network Information API](http://www.w3.org/TR/2011/WD-netinfo-api-20110607/). It provides information about the device's cellular and wifi connection, and whether the device has an internet connection. +> To get a few ideas how to use the plugin, check out the [sample](#sample) at the bottom of this page or go straight to the [reference](#reference) content. + +Report issues with this plugin on the [Apache Cordova issue tracker][Apache Cordova issue tracker]. + +##<a name="reference"></a>Reference + ## Installation cordova plugin add cordova-plugin-network-information @@ -68,24 +81,25 @@ connection state, and type of connection. ### Quick Example - 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'; +```js +function checkConnection() { + var networkState = navigator.connection.type; - alert('Connection type: ' + states[networkState]); - } + 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'; - checkConnection(); + alert('Connection type: ' + states[networkState]); +} +checkConnection(); +``` ### API Change @@ -97,7 +111,7 @@ eventually be removed. ### iOS Quirks -- iOS can't detect the type of cellular network connection. +- <iOS7 can't detect the type of cellular network connection. - `navigator.connection.type` is set to `Connection.CELL` for all cellular data. ### Windows Phone Quirks @@ -147,12 +161,13 @@ attach an event listener once the `deviceready` event fires. ### Quick Example - document.addEventListener("offline", onOffline, false); - - function onOffline() { - // Handle the offline event - } +```js +document.addEventListener("offline", onOffline, false); +function onOffline() { + // Handle the offline event +} +``` ### iOS Quirks @@ -186,12 +201,13 @@ attach an event listener once the `deviceready` event fires. ### Quick Example - document.addEventListener("online", onOnline, false); - - function onOnline() { - // Handle the online event - } +```js +document.addEventListener("online", onOnline, false); +function onOnline() { + // Handle the online event +} +``` ### iOS Quirks @@ -206,3 +222,120 @@ When running in the Emulator, the `connection.status` is always unknown, so this ### Windows Phone 8 Quirks The Emulator reports the connection type as `Cellular`, which does not change, so events does _not_ fire. + +## Sample: Upload a File Depending on your Network State <a name="sample"></a> + +The code examples in this section show examples of changing app behavior using the online and offline events and your network connection status. + +To start with, create a new FileEntry object (data.txt) to use for sample data. Call this function from the `deviceready` handler. + +>*Note* This code example requires the File plugin. + +```js +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); +} +``` + +Next, add listeners for the online and offline events in the `deviceready` handler. + +```js +document.addEventListener("offline", onOffline, false); +document.addEventListener("online", onOnline, false); +``` + +The app's `onOnline` function handles the online event. In the event handler, check the current network state. In this app, treat any connection type as good except Connection.NONE. If you have a connection, you try to upload a file. + +```js +function onOnline() { + // Handle the online event + var networkState = navigator.connection.type; + + if (networkState !== Connection.NONE) { + if (dataFileEntry) { + tryToUploadFile(); + } + } + display('Connection type: ' + networkState); +} +``` + +When the online event fires in the preceding code, call the app's `tryToUploadFile` function. + +If the FileTransfer object's upload function fails, call the app's `offlineWrite` function to save the current data somewhere. + +>*Note* This example requires the FileTransfer plugin. + +```js +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); +}; +``` + +Here is the code for the `offlineWrite` function. + +>*Note* This code examples requires the File plugin. + +```js +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); + }); +} +``` + +If the offline event occurs, just do something like notify the user (for this example, just log it). + +```js +function onOffline() { + // Handle the offline event + console.log("lost connection"); +} +``` + +[Apache Cordova issue tracker]: https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20Network%20Information%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC |