CB-5658 Add doc.index.md for netinfo plugin
Project: http://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information/commit/130ebd37 Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information/tree/130ebd37 Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information/diff/130ebd37 Branch: refs/heads/master Commit: 130ebd37533cf91bbe6ddb72c8d70f43e25a2c5c Parents: d71b83e Author: Andrew Grieve <[email protected]> Authored: Wed Dec 18 16:17:29 2013 -0500 Committer: Andrew Grieve <[email protected]> Committed: Wed Dec 18 16:17:29 2013 -0500 ---------------------------------------------------------------------- README.md | 25 +++++-- doc/index.md | 190 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 211 insertions(+), 4 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information/blob/130ebd37/README.md ---------------------------------------------------------------------- diff --git a/README.md b/README.md index e1681b5..43167f7 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,22 @@ -cordova-plugin-network-information ----------------------------------- -To install this plugin, follow the [Command-line Interface Guide](http://cordova.apache.org/docs/en/edge/guide_cli_index.md.html#The%20Command-line%20Interface). +<!--- + license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at -If you are not using the Cordova Command-line Interface, follow [Using Plugman to Manage Plugins](http://cordova.apache.org/docs/en/edge/plugin_ref_plugman.md.html). + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +# org.apache.cordova.network-information + +Plugin documentation: [doc/index.md](doc/index.md) http://git-wip-us.apache.org/repos/asf/cordova-plugin-network-information/blob/130ebd37/doc/index.md ---------------------------------------------------------------------- diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 0000000..577af74 --- /dev/null +++ b/doc/index.md @@ -0,0 +1,190 @@ +<!--- + license: Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. +--> + +# org.apache.cordova.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. + +## Installation + + cordova plugin add org.apache.cordova.network-information + +## Supported Platforms + +- Amazon Fire OS +- Android +- BlackBerry 10 +- iOS +- Windows Phone 7 and 8 +- Tizen +- Windows 8 + +# Connection + +> The `connection` object, exposed via `navigator.connection`, provides information about the device's cellular and wifi connection. + +## Properties + +- connection.type + +## Constants + +- Connection.UNKNOWN +- Connection.ETHERNET +- Connection.WIFI +- Connection.CELL_2G +- Connection.CELL_3G +- Connection.CELL_4G +- Connection.CELL +- Connection.NONE + +## connection.type + +This property offers a fast way to determine the device's network +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'; + + alert('Connection type: ' + states[networkState]); + } + + checkConnection(); + + +### API Change + +Until Cordova 2.3.0, the `Connection` object was accessed via +`navigator.network.connection`, after which it was changed to +`navigator.connection` to match the W3C specification. It's still +available at its original location, but is deprecated and will +eventually be removed. + +### iOS Quirks + +- iOS can't detect the type of cellular network connection. + - `navigator.connection.type` is set to `Connection.CELL` for all cellular data. + +### Windows Phone Quirks + +- When running in the emulator, always detects `navigator.connection.type` as `Connection.UNKNOWN`. + +- Windows Phone can't detect the type of cellular network connection. + - `navigator.connection.type` is set to `Connection.CELL` for all cellular data. + +### Tizen Quirks + +- Tizen can only detect a WiFi or cellular connection. + - `navigator.connection.type` is set to `Connection.CELL_2G` for all cellular data. + +# Network-related Events + +## offline + +The event fires when an application goes offline, and the device is +not connected to the Internet. + + document.addEventListener("offline", yourCallbackFunction, false); + +### Details + +The `offline` event fires when a previously connected device loses a +network connection so that an application can no longer access the +Internet. It relies on the same information as the Connection API, +and fires when the `connection.type` changes from `NONE` to any other +value. + +Applications typically should use `document.addEventListener` to +attach an event listener once the `deviceready` event fires. + +### Quick Example + + document.addEventListener("offline", onOffline, false); + + function onOffline() { + // Handle the offline event + } + + +### iOS Quirks + +During initial startup, the first offline event (if applicable) takes at least a second to fire. + +### Windows Phone 7 Quirks + +When running in the Emulator, the `connection.status` is always unknown, so this event does _not_ fire. + +### Windows Phone 8 Quirks + +The Emulator reports the connection type as `Cellular`, which does not change, so the event does _not_ fire. + +## online + +This event fires when an application goes online, and the device +becomes connected to the Internet. + + document.addEventListener("online", yourCallbackFunction, false); + +### Details + +The `online` event fires when a previously unconnected device receives +a network connection to allow an application access to the Internet. +It relies on the same information as the Connection API, and fires +when the value of `connection.type` becomes `NONE`. + +Applications typically should use `document.addEventListener` to +attach an event listener once the `deviceready` event fires. + +### Quick Example + + document.addEventListener("online", onOnline, false); + + function onOnline() { + // Handle the online event + } + + +### iOS Quirks + +During initial startup, the first `online` event (if applicable) takes +at least a second to fire, prior to which `connection.type` is +`UNKNOWN`. + +### Windows Phone 7 Quirks + +When running in the Emulator, the `connection.status` is always unknown, so this event does _not_ fire. + +### Windows Phone 8 Quirks + +The Emulator reports the connection type as `Cellular`, which does not change, so events does _not_ fire.
