Differences

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

--- android:android_agtek_lib [2011/03/24 22:44]
mjallison
+++ android:android_agtek_lib [2012/10/10 07:16] (current)
@@ Line 46: / Line 46: @@
    * Allow application packaging choice. Applications have varying footprint requirements, the manager must be small.
-The Android LocationManager provides many 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 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).
-To be informed of location changes, an application must implement the Locations listener interface;
+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 android.location.LocationListener;\\
+import com.agtek.location.LocationManager;
+public MyClass extends activity implements LocationListener
+{
+   // ...
+   LocationManager m_locationManager = LocationManager.GetInstance(this);
+   // ...
+}
+</code>
-public MyClass implements LocationListener\\
+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)\\
+    public void onLocationChanged(Location location)
    {
       /* Do something useful */
    }
+   // ...
+   m_locationManager.requestLocationUpdates( m_device,
+                                             GPS_MINIMUM_TIME,
+                                             GPS_MINIMUM_DISTANCE,
+                                             this );
+   // ...
 }
 </code>
@@ Line 64: / Line 96: @@
 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 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;
+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>
-import com.agtek.location.LocationManager;
+   public void record( OutputStream strm, String comment )
-public MyClass extends activity implements LocationListener\\
+      throws IOException
-{
-   // ...
-   LocationManager m_locationManager = LocationManager.GetInstance(this);
-   // ...
-}
 </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.
-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 the RTK based devices.

AGTEK R & D Wiki

User Tools

Site Tools

Differences

Page Tools