Merge pull request #11 from andygup/v0.4

v0.4

CHANGELOG.md

@@ -1,5 +1,16 @@
 # cordova-plugin-advanced-geolocation - Changelog
 
+## Version 0.4.0 - May 6, 2016
+
+No breaking changes.
+
+**Enhancements**
+* Updated API docs to correctly reflect what data is returns by GPS and Network.
+
+**Bug Fixes**
+* GPSController no longer returns a fake location if parsedLocation is null.
+* NetworkController also no longer returns a fake location if parsedLocation is null. 
+
 ## Version 0.3.1 - May 4, 2016
 
 No breaking changes.

README.md

@@ -135,7 +135,7 @@ Click [here](api_reference.md) to read all about it.
 ## FAQ
 
 * **Which location providers does this plugin use?** The plugin can be configured to use both [GPS](http://developer.android.com/reference/android/location/LocationManager.html#GPS_PROVIDER) and [NETWORK](http://developer.android.com/reference/android/location/LocationManager.html#NETWORK_PROVIDER) location providers. NETWORK location providers require access to the internet whether it's via cellular or WiFi connection. The plugin does not use [PASSIVE](http://developer.android.com/reference/android/location/LocationManager.html#PASSIVE_PROVIDER) location providers because you have no direct control over those.
-* **What is the difference between `CellInfo` and `CellLocation` data?** It can be confusing because they have a lot of overlapping capabilities and may provide slightly different data, as well. They are both focused on providing cell tower location information. `CellLocation` comes in two flavors and is only triggered during an [PhoneStateListener.LISTEN_CELL_LOCATION](http://developer.android.com/reference/android/telephony/PhoneStateListener.html#LISTEN_CELL_LOCATION) event: [CdmaCellLocation](http://developer.android.com/reference/android/telephony/cdma/CdmaCellLocation.html) and [GsmCellLocation](http://developer.android.com/reference/android/telephony/gsm/GsmCellLocation.html). `CellInfo` contains a sub-set of information focused on the cell tower's id and its signal strength and is derived by querying [TelephonyManager.getAllCellInfo()](http://developer.android.com/reference/android/telephony/TelephonyManager.html#getAllCellInfo()). The current version of this library does not return signal strength info. This comes in four flavors: [CellInfoCdma](http://developer.android.com/reference/android/telephony/CellInfoCdma.html), [CellInfoWcmda](http://developer.android.com/reference/android/telephony/CellInfoWcdma.html), [CellInfoGsm](http://developer.android.com/reference/android/telephony/CellInfoGsm.html) and [CellInfoLte](http://developer.android.com/reference/android/telephony/CellInfoLte.html). 
+* **What is the difference between `CellInfo` and `CellLocation` data?** It can be confusing because they have a lot of overlapping capabilities and may provide slightly different data, as well. They are both focused on providing cell tower information. `CellLocation` comes in two flavors and is only triggered during an [PhoneStateListener.LISTEN_CELL_LOCATION](http://developer.android.com/reference/android/telephony/PhoneStateListener.html#LISTEN_CELL_LOCATION) event: [CdmaCellLocation](http://developer.android.com/reference/android/telephony/cdma/CdmaCellLocation.html) and [GsmCellLocation](http://developer.android.com/reference/android/telephony/gsm/GsmCellLocation.html). `CellInfo` contains a sub-set of information focused on the cell tower's id and its signal strength and is derived by querying [TelephonyManager.getAllCellInfo()](http://developer.android.com/reference/android/telephony/TelephonyManager.html#getAllCellInfo()). The current version of this library does not return signal strength info. This comes in four flavors: [CellInfoCdma](http://developer.android.com/reference/android/telephony/CellInfoCdma.html), [CellInfoWcmda](http://developer.android.com/reference/android/telephony/CellInfoWcdma.html), [CellInfoGsm](http://developer.android.com/reference/android/telephony/CellInfoGsm.html) and [CellInfoLte](http://developer.android.com/reference/android/telephony/CellInfoLte.html). 
 * **Will this library work as a background process?** No. This library is **not** designed to be used while minimized. Because of its potential to consume large amounts of memory and CPU cycles it will only provide locations, by default, while the application is in the foreground and active.
 * **I got a plugin not supported error, what do I do?** If you get the following error `Plugin doesn't support this project's cordova-android version. cordova-android: 4.1.1, failed version requirement: >=5.0.0
 Skipping 'cordova-plugin-advanced-geolocation' for android`, then you most likely need to upgrade your version of cordova-android. You can explicitly upgrade by running the following command in your cordova project directory `cordova platform update [email protected]`. 

api_reference.md

@@ -32,6 +32,8 @@ Option | Type | Description
 
 Whenever a location event is successful, this plugin will return the following location data in the form of a JSON payload. This section provides a description of the attribute/value pairs that are returned.
 
+Note: All locations generated by the native LocationManager are guaranteed to have a valid latitude, longitude, and timestamp (both UTC time and elapsed real-time since boot), all other parameters are optional.
+
 Example:
 
 ```javascript
@@ -53,12 +55,12 @@ Example:
 Property | Type |  Value | Description
 --- | --- | --- | ---
 `provider` | String | `"gps"` or `"network"` | Let's you determine where this data is coming from.
-`latitude` | String | number | Latitude in degrees. Be sure to check for `0.0`. values if no location was returned. `0.0` is a valid [WGS 84 location off the coast of Africa](https://en.wikipedia.org/wiki/Null_Island). 
-`longitude` | String | number | Longitude in degrees. Be sure to check for `0.0`. values if no location was returned.
-`altitude` | String | number | Altitude if available, in meters above the WGS 84 reference ellipsoid. If this location does not have an altitude then `0.0` is returned.
-`accuracy` | String | number | Get the estimated accuracy of this location, in meters. <br><br>Android defines accuracy as the radius of 68% confidence. In other words, if you draw a circle centered at this location's latitude and longitude, and with a radius equal to the accuracy, then there is a 68% probability that the true location is inside the circle.<br><br>In statistical terms, it is assumed that location errors are random with a normal distribution, so the 68% confidence circle represents one standard deviation. Note that in practice, location errors do not always follow such a simple distribution.<br><br>This accuracy estimation is only concerned with horizontal accuracy, and does not indicate the accuracy of bearing, velocity or altitude if those are included in this Location.<br><br>If this location does not have an accuracy, then `0.0` is returned. All locations generated by the LocationManager include an accuracy.
-`bearing` | String | number | The bearing, in degrees. Bearing is the horizontal direction of travel of this device, and is not related to the device orientation. It is guaranteed to be in the range (0.0, 360.0] if the device has a bearing.<br><br>If a location does not have a bearing then `0.0` is returned.
-`speed` | String | number | The speed if it is available, in meters/second over ground. If this location does not have a speed then `0.0` is returned.
+`latitude` | String | number | Latitude in degrees. `0.0` is a valid [WGS 84 location off the coast of Africa](https://en.wikipedia.org/wiki/Null_Island). 
+`longitude` | String | number | Longitude in degrees. `0.0` is a valid [WGS 84 location off the coast of Africa](https://en.wikipedia.org/wiki/Null_Island).
+`altitude` | String | number | Altitude if available, in meters above the WGS 84 reference ellipsoid. 
+`accuracy` | String | number | Get the estimated accuracy of this location, in meters. <br><br>Android defines accuracy as the radius of 68% confidence. In other words, if you draw a circle centered at this location's latitude and longitude, and with a radius equal to the accuracy, then there is a 68% probability that the true location is inside the circle.<br><br>In statistical terms, it is assumed that location errors are random with a normal distribution, so the 68% confidence circle represents one standard deviation. Note that in practice, location errors do not always follow such a simple distribution.<br><br>This accuracy estimation is only concerned with horizontal accuracy, and does not indicate the accuracy of bearing, velocity or altitude if those are included in this Location.
+`bearing` | String | number | The bearing, in degrees. Bearing is the horizontal direction of travel of this device, and is not related to the device orientation. It is guaranteed to be in the range (0.0, 360.0] if the device has a bearing.
+`speed` | String | number | The speed if it is available, in meters/second over ground. 
 `timestamp` | String | number | Return the UTC time of this fix, in milliseconds since January 1, 1970.<br><br>Note that the UTC time on a device is not monotonic: it can jump forwards or backwards unpredictably.<br><br>All locations generated by the LocationManager are guaranteed to have a valid UTC time, however remember that the system time may have changed since the location was generated.
 `cached` | String | boolean | Whether or not the location data, either GPS or Network, was returned from the device cache.<br><br>Note: cached data can be very unpredictable, use with caution and make sure to compare the timestamp with current time to establish the age of the cached location.
 
@@ -99,8 +101,8 @@ Property | Type |  Value | Description
 --- | --- | --- | ---
 `buffer` | String | boolean | Indicates whether or not buffering has been activated.
 `bufferSize` | String | integer | Indicates the number of elements within the buffer. You can compare this value against the `maxBufferSize` as set in the configuration options.
-`bufferedLatitude` | String | number | The buffer's geometric latitudinal center. Value is latitude in degrees. Be sure to check for `0.0` values indicating that no latitude data was provided.
-`bufferedLongitude` | String | number | The buffer's geometric longitudinal center. Value is longitude in degrees. Be sure to check for `0.0` values indicating that no longitude data was provided.
+`bufferedLatitude` | String | number | The buffer's geometric latitudinal center. Value is latitude in degrees. 
+`bufferedLongitude` | String | number | The buffer's geometric longitudinal center. Value is longitude in degrees. 
 `bufferedAccuracy` | String | number | The buffer's average horizontal accuracy in meters. It may be possible to have a buffered accuracy equal to `0.0`.
 
 ##Satellite Data

package.json

@@ -1,6 +1,6 @@
 {
   "name": "cordova-plugin-advanced-geolocation",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Android geolocation plugin for both GPS or NETWORK-based location providers.",
   "cordova": {
     "id": "cordova-plugin-advanced-geolocation",

plugin.xml

@@ -3,7 +3,7 @@
 <plugin xmlns="http://apache.org/cordova/ns/plugins/1.0"
     xmlns:android="http://schemas.android.com/apk/res/android"
     id="cordova-plugin-advanced-geolocation"
-    version="0.3.1">
+    version="0.4.0">
 
     <name>Cordova Advanced Geolocation Plugin - Android</name>
     <description>

src/com/esri/cordova/geolocation/controllers/NetworkLocationController.java

@@ -112,14 +112,10 @@ public void uncaughtException(Thread thread, Throwable throwable) {
                     final String parsedLocation;
 
                     // If the provider is disabled or currently unavailable then null may be returned on some devices
-                    if(location == null) {
-                        // Basically return all zeros as a standard practice
-                        parsedLocation = "{\"provider\":\"network\",\"latitude\":\"0.0\",\"longitude\":\"0.0\",\"altitude\":\"0.0\",\"accuracy\":\"50.0\",\"bearing\":\"0.0\",\"speed\":\"0.0\",\"timestamp\":\"0\",\"cached\":\"true\"}";
-                    }
-                    else {
+                    if(location != null) {
                         parsedLocation = JSONHelper.locationJSON(LocationManager.NETWORK_PROVIDER, location, true);
+                        sendCallback(PluginResult.Status.OK, parsedLocation);
                     }
-                    sendCallback(PluginResult.Status.OK, parsedLocation);
                 }
             }
         }