Differences

This shows you the differences between two versions of the page.

--- android:android_agtek_lib [2011/03/24 21:59]
mjallison
+++ android:android_agtek_lib [2012/10/10 07:16] (current)
@@ Line 41: / Line 41: @@
 The Android LocationManager interface isolates the application from the details of dealing with the built in Location Provider devices. Android currently support approximately three different providers; built in GPS, computed locations (based on WIFI & Cell Tower), and mock locations. Only the first two provide semi-reliable location information for applications, while the "mock" device is only useful for application development.
-The Android LocationManager doesn't currently allow the ability to extend or add providers for additional devices, a key AGTEK requirement.
+The Android LocationManager doesn't currently allow the ability to extend or add providers for additional devices, a key AGTEK requirement. The AGTEK LocationManager was designed with following goals in mind:
+   * Support additional location devices
+   * Follow the basic LocationListener pattern
+   * Allow application packaging choice. Applications have varying footprint requirements, the manager must be small.
+The Android LocationManager provides interface methods for working with testing, development, and "normal" use. Our approach is to treat all of these factors the same. Testing and development all provide locations through the same interfaces as the "normal" devices. The LocationManager represents physical location providing instruments with two different object types; LocationDevice and LocationProvider. The LocationDevice class describes the instrument, but doesn't interact with it, and can be thought of as a "File Descriptor". A LocationProvider will consume the data stream from the location instrument, and actually provide the Location updates to the application (mediated by the LocationFramework).
+The Application generally does not interact directly with the LocationProvider in use. Rather the Application will do most of the work using the LocationManager. The AGTEK LocationManager is retrieved using a Singleton pattern instead of using an Android OS interface;
+<code>
+import com.agtek.location.LocationManager;
+public MyClass extends activity implements LocationListener
+{
+   // ...
+   LocationManager m_locationManager = LocationManager.GetInstance(this);
+   // ...
+}
+</code>
+When getting the instance of the LocationManager, you must pass in an Activity context. This is required so the LocationManager can access the Bluetooth manager. The Bluetooth manager is required in order to support most of the RTK based devices.
+The Application needs to get a LocationDevice to request updates. To get the device initialized and running, the user must first choose a device, then the application can request updates (although depending on the application, some devices may be hardwired);
+<code>
+   public class MyClass
+   {
+      // ...
+      LocationDevice deviceChoices[] = m_locationManager.getDevices();
+      // ...
+      // Do UI stuff to allow the user to pick a device
+      m_device = myUI.getSelectedDevice();
+      // ...
+   }
+</code>To be informed of location changes, an application must implement the Location listener interface, then register for location updates;
+<code>
+import android.location.LocationListener;
+public MyClass implements LocationListener
+{
+    public void onLocationChanged(Location location)
+   {
+      /* Do something useful */
+   }
+   // ...
+   m_locationManager.requestLocationUpdates( m_device,
+                                             GPS_MINIMUM_TIME,
+                                             GPS_MINIMUM_DISTANCE,
+                                             this );
+   // ...
+}
+</code>
+When the Location provider device has a new location for the application, the location manager will call this method. Because the listener method onLocationChanged will be called by another LocationProvider thread, the application must not use much CPU time. The application must use proper thread synchronization and notification techniques to pass the location object to the working parts of the Application.
+The application is mostly isolated from the details of the actual devices being used, except for a couple of areas. The Location object, a normalized location in terms of Lat/Lon/Altitude, may contain device specific information. Currently the LocationManager defines extensions for Northing/Easting, and extended status information may be passed back. All extended information is returned in the Location object as "Extras".
+Applications may record streams of locations using the following methods:
+<code>
+   public void record( OutputStream strm, String comment )
+      throws IOException
+</code>
+Typically the output stream is sent to persistent storage, but any legal stream is acceptable, provided it has enough space for the recording. The output of the stream is an extended GPX format file. The extensions provide the ability to include Northing/Easting, and other AGTEK unique data to the location stream. Call **stopRecord** to complete the recording stream.
+Applications may playback the location stream using the PlaybackDevice/PlaybackProvider. These function exactly the same as a normal LocationManager capable instrument. The PlaybackProvider will send updates back to the application at exactly the same rate as they were recorded.
+==== LocationManager Cautions ====
+The LocationManager is still relatively early in its development, so changes are to be expected. In particular areas of device initialization/startup and reporting status to applications are not well developed. These are expected to mature as new devices are added to the framework.
+==== LocationManager Summary ====
+It is beyond the scope of this short introduction to detail each an every method on objects within the LocationManager framework. The best way to understand individual methods is to read the JavaDocs for the Lib and package **com.agtek.location**.
+Interested readers are directed to the [[AGTEK_Lib_Location_Manager_Architecture|Location Manager Architecture]] page for detailed implementation information.

AGTEK R & D Wiki

User Tools

Site Tools

Differences

Page Tools