CB-11734: Network Plugin uses Android Log class and not Cordova LOG class
[cordova-plugin-network-information.git] / README.md
1 ---
2 title: Network Information
3 description: Get information about wireless connectivity.
4 ---
5 <!--
6 # license: Licensed to the Apache Software Foundation (ASF) under one
7 #         or more contributor license agreements.  See the NOTICE file
8 #         distributed with this work for additional information
9 #         regarding copyright ownership.  The ASF licenses this file
10 #         to you under the Apache License, Version 2.0 (the
11 #         "License"); you may not use this file except in compliance
12 #         with the License.  You may obtain a copy of the License at
13 #
14 #           http://www.apache.org/licenses/LICENSE-2.0
15 #
16 #         Unless required by applicable law or agreed to in writing,
17 #         software distributed under the License is distributed on an
18 #         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
19 #         KIND, either express or implied.  See the License for the
20 #         specific language governing permissions and limitations
21 #         under the License.
22 -->
23
24 |Android|iOS| Windows 8.1 Store | Windows 8.1 Phone | Windows 10 Store | Travis CI |
25 |:-:|:-:|:-:|:-:|:-:|:-:|
26 |[![Build Status](http://cordova-ci.cloudapp.net:8080/buildStatus/icon?job=cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-network-information)](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=android,PLUGIN=cordova-plugin-network-information/)|[![Build Status](http://cordova-ci.cloudapp.net:8080/buildStatus/icon?job=cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-network-information)](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=ios,PLUGIN=cordova-plugin-network-information/)|[![Build Status](http://cordova-ci.cloudapp.net:8080/buildStatus/icon?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-store,PLUGIN=cordova-plugin-network-information/)|[![Build Status](http://cordova-ci.cloudapp.net:8080/buildStatus/icon?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-8.1-phone,PLUGIN=cordova-plugin-network-information/)|[![Build Status](http://cordova-ci.cloudapp.net:8080/buildStatus/icon?job=cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-network-information)](http://cordova-ci.cloudapp.net:8080/job/cordova-periodic-build/PLATFORM=windows-10-store,PLUGIN=cordova-plugin-network-information/)|[![Build Status](https://travis-ci.org/apache/cordova-plugin-network-information.svg?branch=master)](https://travis-ci.org/apache/cordova-plugin-network-information)|
27
28 # cordova-plugin-network-information
29
30
31 This plugin provides an implementation of an old version of the
32 [Network Information API](http://www.w3.org/TR/2011/WD-netinfo-api-20110607/).
33 It provides information about the device's cellular and
34 wifi connection, and whether the device has an internet connection.
35
36 > 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.
37
38 Report issues with this plugin on the [Apache Cordova issue tracker][Apache Cordova issue tracker].
39
40 ##<a name="reference"></a>Reference
41
42 ## Installation
43
44     cordova plugin add cordova-plugin-network-information
45
46 ## Supported Platforms
47
48 - Amazon Fire OS
49 - Android
50 - BlackBerry 10
51 - Browser
52 - iOS
53 - Windows Phone 7 and 8
54 - Tizen
55 - Windows
56 - Firefox OS
57
58 # Connection
59
60 > The `connection` object, exposed via `navigator.connection`,  provides information about the device's cellular and wifi connection.
61
62 ## Properties
63
64 - connection.type
65
66 ## Constants
67
68 - Connection.UNKNOWN
69 - Connection.ETHERNET
70 - Connection.WIFI
71 - Connection.CELL_2G
72 - Connection.CELL_3G
73 - Connection.CELL_4G
74 - Connection.CELL
75 - Connection.NONE
76
77 ## connection.type
78
79 This property offers a fast way to determine the device's network
80 connection state, and type of connection.
81
82 ### Quick Example
83
84 ```js
85 function checkConnection() {
86     var networkState = navigator.connection.type;
87
88     var states = {};
89     states[Connection.UNKNOWN]  = 'Unknown connection';
90     states[Connection.ETHERNET] = 'Ethernet connection';
91     states[Connection.WIFI]     = 'WiFi connection';
92     states[Connection.CELL_2G]  = 'Cell 2G connection';
93     states[Connection.CELL_3G]  = 'Cell 3G connection';
94     states[Connection.CELL_4G]  = 'Cell 4G connection';
95     states[Connection.CELL]     = 'Cell generic connection';
96     states[Connection.NONE]     = 'No network connection';
97
98     alert('Connection type: ' + states[networkState]);
99 }
100
101 checkConnection();
102 ```
103
104 ### API Change
105
106 Until Cordova 2.3.0, the `Connection` object was accessed via
107 `navigator.network.connection`, after which it was changed to
108 `navigator.connection` to match the W3C specification.  It's still
109 available at its original location, but is deprecated and will
110 eventually be removed.
111
112 ### iOS Quirks
113
114 - <iOS7 can't detect the type of cellular network connection.
115     - `navigator.connection.type` is set to `Connection.CELL` for all cellular data.
116
117 ### Windows Phone Quirks
118
119 - When running in the emulator, always detects `navigator.connection.type` as `Connection.UNKNOWN`.
120
121 - Windows Phone can't detect the type of cellular network connection.
122     - `navigator.connection.type` is set to `Connection.CELL` for all cellular data.
123
124 ### Windows Quirks
125
126 - When running in the Phone 8.1 emulator, always detects `navigator.connection.type` as `Connection.ETHERNET`.
127
128 ### Tizen Quirks
129
130 - Tizen can only detect a WiFi or cellular connection.
131     - `navigator.connection.type` is set to `Connection.CELL_2G` for all cellular data.
132
133 ### Firefox OS Quirks
134
135 - Firefox OS can't detect the type of cellular network connection.
136     - `navigator.connection.type` is set to `Connection.CELL` for all cellular data.
137
138 ### Browser Quirks
139
140 - Browser can't detect the type of network connection.
141 `navigator.connection.type` is always set to `Connection.UNKNOWN` when online.
142
143 # Network-related Events
144
145 ## offline
146
147 The event fires when an application goes offline, and the device is
148 not connected to the Internet.
149
150     document.addEventListener("offline", yourCallbackFunction, false);
151
152 ### Details
153
154 The `offline` event fires when a previously connected device loses a
155 network connection so that an application can no longer access the
156 Internet.  It relies on the same information as the Connection API,
157 and fires when the value of `connection.type` becomes `NONE`.
158
159 Applications typically should use `document.addEventListener` to
160 attach an event listener once the `deviceready` event fires.
161
162 ### Quick Example
163
164 ```js
165 document.addEventListener("offline", onOffline, false);
166
167 function onOffline() {
168     // Handle the offline event
169 }
170 ```
171
172 ### iOS Quirks
173
174 During initial startup, the first offline event (if applicable) takes at least a second to fire.
175
176 ### Windows Phone 7 Quirks
177
178 When running in the Emulator, the `connection.status` is always unknown, so this event does _not_ fire.
179
180 ### Windows Phone 8 Quirks
181
182 The Emulator reports the connection type as `Cellular`, which does not change, so the event does _not_ fire.
183
184 ## online
185
186 This event fires when an application goes online, and the device
187 becomes connected to the Internet.
188
189     document.addEventListener("online", yourCallbackFunction, false);
190
191 ### Details
192
193 The `online` event fires when a previously unconnected device receives
194 a network connection to allow an application access to the Internet.
195 It relies on the same information as the Connection API,
196 and fires when the `connection.type` changes from `NONE` to any other
197 value.
198
199 Applications typically should use `document.addEventListener` to
200 attach an event listener once the `deviceready` event fires.
201
202 ### Quick Example
203
204 ```js
205 document.addEventListener("online", onOnline, false);
206
207 function onOnline() {
208     // Handle the online event
209 }
210 ```
211
212 ### iOS Quirks
213
214 During initial startup, the first `online` event (if applicable) takes
215 at least a second to fire, prior to which `connection.type` is
216 `UNKNOWN`.
217
218 ### Windows Phone 7 Quirks
219
220 When running in the Emulator, the `connection.status` is always unknown, so this event does _not_ fire.
221
222 ### Windows Phone 8 Quirks
223
224 The Emulator reports the connection type as `Cellular`, which does not change, so events does _not_ fire.
225
226 ## Sample: Upload a File Depending on your Network State <a name="sample"></a>
227
228 The code examples in this section show examples of changing app behavior using the online and offline events and your network connection status.
229
230 To start with, create a new FileEntry object (data.txt) to use for sample data. Call this function from the `deviceready` handler.
231
232 >*Note* This code example requires the File plugin.
233
234 ```js
235 var dataFileEntry;
236
237 function createSomeData() {
238
239     window.requestFileSystem(window.TEMPORARY, 5 * 1024 * 1024, function (fs) {
240
241         console.log('file system open: ' + fs.name);
242         // Creates a new file or returns an existing file.
243         fs.root.getFile("data.txt", { create: true, exclusive: false }, function (fileEntry) {
244
245           dataFileEntry = fileEntry;
246
247         }, onErrorCreateFile);
248
249     }, onErrorLoadFs);
250 }
251 ```
252
253 Next, add listeners for the online and offline events in the `deviceready` handler.
254
255 ```js
256 document.addEventListener("offline", onOffline, false);
257 document.addEventListener("online", onOnline, false);
258 ```
259
260 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.
261
262 ```js
263 function onOnline() {
264     // Handle the online event
265     var networkState = navigator.connection.type;
266
267     if (networkState !== Connection.NONE) {
268         if (dataFileEntry) {
269             tryToUploadFile();
270         }
271     }
272     display('Connection type: ' + networkState);
273 }
274 ```
275
276 When the online event fires in the preceding code, call the app's `tryToUploadFile` function.
277
278 If the FileTransfer object's upload function fails, call the app's `offlineWrite` function to save the current data somewhere.
279
280 >*Note* This example requires the FileTransfer plugin.
281
282 ```js
283 function tryToUploadFile() {
284     // !! Assumes variable fileURL contains a valid URL to a text file on the device,
285     var fileURL = getDataFileEntry().toURL();
286
287     var success = function (r) {
288         console.log("Response = " + r.response);
289         display("Uploaded. Response: " + r.response);
290     }
291
292     var fail = function (error) {
293         console.log("An error has occurred: Code = " + error.code);
294         offlineWrite("Failed to upload: some offline data");
295     }
296
297     var options = new FileUploadOptions();
298     options.fileKey = "file";
299     options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
300     options.mimeType = "text/plain";
301
302     var ft = new FileTransfer();
303     // Make sure you add the domain of your server URL to the
304     // Content-Security-Policy <meta> element in index.html.
305     ft.upload(fileURL, encodeURI(SERVER), success, fail, options);
306 };
307 ```
308
309 Here is the code for the `offlineWrite` function.
310
311 >*Note* This code examples requires the File plugin.
312
313 ```js
314 function offlineWrite(offlineData) {
315     // Create a FileWriter object for our FileEntry.
316     dataFileEntry.createWriter(function (fileWriter) {
317
318         fileWriter.onwriteend = function () {
319             console.log("Successful file write...");
320             display(offlineData);
321         };
322
323         fileWriter.onerror = function (e) {
324             console.log("Failed file write: " + e.toString());
325         };
326
327         fileWriter.write(offlineData);
328     });
329 }
330 ```
331
332 If the offline event occurs, just do something like notify the user (for this example, just log it).
333
334 ```js
335 function onOffline() {
336     // Handle the offline event
337     console.log("lost connection");
338 }
339 ```
340  
341 [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