Differences

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

--- access:cpp_track_api [2015/07/01 18:04]
mjallison created
+++ access:cpp_track_api [2016/07/13 00:36] (current)
mjallison [Post Mid-2015 extensions]
@@ Line 3: / Line 3: @@
 The C++ API contains the TrackAPI, which is useful for tracking applications. There isn't a lot of functionality, and the API is minimal in order to accomplish base tasks. It is possible that this API is extended in the future (e.g. later than mid-2015).
-The API allows an application to list tracks, trackers (more is needed), and track positions. Using the StorageServer object, the application requests an instance of the TrackAPI
+The API allows an application to list tracks, trackers (more is needed), and track positions. Using the StorageServer object, the application requests an instance of the TrackAPI. A track consuming application would use the method iTrackApi->getTracks(), possibly adding filters for serial or projects. A track uploading application would use iTrackApi->upload(). When uploading points the serial number should be an ASCII (do NOT use Unicode or UTF-8/16) valued string which uniquely identifies the tracking device. It need not be human readable (bonus points if it is). All serial numbers are limited to 32 characters.
+<code>
+/**
+ * Copyright (c) 2009-2015, AGTEK Development Company, Inc.
+ * All rights reserved.
+ * For questions please visit http://www.agtek.com
+ *
+ * The ITrackApi is the API for accessing the Agtek Access
+ * Server track functionality. This includes methods for
+ * for uploading and downloading GPS position data.
+ *
+ * To minimize memory allocation when downloading positions
+ * from the server, the client application must provide a
+ * callback function which each GPS position will be passed to.
+ */
+#include "access/AccessError.h"
+#include "access/GpsPos.h"
+#include "access/GpsStatistics.h"
+#include "access/GpsTelemetry.h"
+#include "access/Track.h"
+#include "access/TrackStatistics.h"
+#include <vector>
+#define ALL_PROJECTS  -1
+#define ALL_DEVICES   ""
+#define TrackList std::vector<Track>
+#define SerialList std::vector<std::string>
+typedef void (*PositionCallback)(void *clientp, const GpsPos& pos, int index, int total);
+class ITrackApi {
+ public:
+  virtual ~ITrackApi(void) {}
+  // Downloads GPS positions from the server according to the
+  // following arguments:
+  //
+  // serial    - The serial number of the GPS device
+  // start     - The time of the first GPS position
+  // end       - The time of the last GPS position
+  // allFields - Flag controlling which fields are retrieved.
+  //             true: Retrieves all fields listed in the GpsPos class
+  //             false: Retrieves only time, latitude and longitude
+  // cb        - The function called for each downloaded position
+  // clientp   - A pointer to client data passed to the callback function.
+  virtual AccessError download(const std::string& serial,
+              time_t start,
+              time_t end,
+              bool allFields,
+              PositionCallback cb,
+              void *clientp) = 0;
+  // Uploads GPS positions to the server according to the
+  // following arguments:
+  //
+  // serial   - The serial number of the GPS device
+  // count    - The number of GPS positions
+  // points   - An array of GPS positions
+  // uploaded - The number of points that were successfully uploaded.
+  //            This value will only be less than than the number of points
+  //            passed in if an error occurs.
+  virtual AccessError upload(const std::string& serial,
+                                   int          count,
+                                   GpsPos*      points,
+                                   int*         uploaded) = 0;
+  // Uploads GPS positions to the server according to the
+  // following arguments:
+  //
+  // project  - The project id (handle) to associate with the track.
+  // serial   - The serial number of the GPS device
+  // count    - The number of GPS positions
+  // points   - An array of GPS positions
+  // uploaded - The number of points that were successfully uploaded.
+  //            This value will only be less than than the number of points
+  //            passed in if an error occurs.
+  virtual AccessError upload(      int          projectHandle,
+	                         const std::string& serial,
+                                   int          count,
+                                   GpsPos*      points,
+                                   int*         uploaded) = 0;
+  // Retrieves the list of tracks from the server according to
+  // the following arguments:
+  //
+  // serial  - The serial number of the device that created the track.
+  //           Use the #define ALL_DEVICES to download tracks from all devices.
+  // project - The handle of the project containing the tracks.
+  //           Use the #define ALL_PROJECTS to download tracks from all projects.
+  // tracks  - The list the retrieved tracks will be added to.
+  virtual AccessError getTracks(const std::string& serial,
+				      int project,
+				      TrackList& tracks) = 0;
+  // Retrieve the single track specified by a handle.
+  virtual AccessError getTrack( const int handle, Track & out ) = 0;
+  // Moves a track to a project.
+  //
+  // track   - The handle of the track to move.
+  // project - The handle of the destination project.
+  // result  - A pointer to a track instance to store the result.
+  //           If the argument is null, no track is returned.
+  virtual AccessError moveTrack(int track, int project, Track* result) = 0;
+  // Deletes a track from the server.
+  //
+  // handle - The handle of the track to be deleted.
+  virtual AccessError deleteTrack(int handle) = 0;
+  // Update most fields of a track.
+  //
+  // tl - The list of track object to be updated.
+  virtual AccessError updateTrack( TrackList & tl ) = 0;
+  // Give a list of track handles, combine all the separate tracks into a single track.
+  // All the tracks must start on the same day, and must be associated with the same
+  // tracker serial. The first track in the list specifies the day/serial restrictions.
+  // Tracks not starting on the on the same day are ignored.
+  // tl - A list of track handle integers
+  // out - The single combined track
+  virtual AccessError combineTracks( std::vector<int> & tl, Track & out ) = 0;
+  /////////////////////////////////////// Tracker Methods //////////////////////////////////////////////////////////
+  // Returns the list of device serial numbers the server knows about
+  // for the customer. These include devices that are explicitly assigned
+  // to the customer and devices that have uploaded data.
+  //
+  // serials - The list the retrieved serial numbers will be added to.
+  virtual AccessError getSerialNumbers(SerialList& serials) = 0;
+  // Returns a list of GpsStatistics for all known trackers belonging to the company
+  virtual AccessError getGpsStats(GpsStatisticsVector& stats) = 0;
+  // Update fields for a specific Tracker. Normally these fields are automatically
+  // populated when the tracker uploads points. The only field not provided is the
+  // version of the firmware. For this reason, the tracker application should update
+  // GPS stats once per startup.
+  virtual AccessError updateGPSStats( GpsStatistics& stat ) = 0;
+  // Like the previous updateGPSStats, include a list of telemetry values to be recorded.
+  virtual AccessError updateGPSStats( GpsStatistics& stat, GpsTelemetryVector& telem) = 0;
+  // Returns a list of GpsTelemetry records for a specific tracker serial
+  virtual AccessError getGpsTelemetry(std::string serial, GpsTelemetryVector &outList) = 0;
+  // Return the statistics specified by a specific handle
+  virtual AccessError getTrackTotalStatistics( int trackHandle, TrackStatistics& out ) = 0;
+  // Return a list of the summary statistics of a track. Total stats are already returned
+  // with the track.
+  virtual AccessError getTrackSummaryStatistics( int trackHandle, TrackStatisticsVector& outList ) = 0;
+  // For a specific set of statistics, update the values.
+  virtual AccessError updateTrackSummaryStatistics( TrackStatistics& stat ) = 0;
+  // Update a set of statistics and attach them to a track
+  virtual AccessError updateTrackTotalStatistics( int track, TrackStatistics& stat ) = 0;
+ protected:
+  ITrackApi(void) {}
+ private:
+  ITrackApi(const ITrackApi& api);
+  ITrackApi& operator=(const ITrackApi& api);
+};
+</code>
+====== Post Mid-2015 extensions ======
+Bring C++ API on parity with Java API:
+  * Added telemetry channels
+  * Added setting the GPS stat update (with telemetry)
+  * Added ability to get GPS stat information

AGTEK R & D Wiki

User Tools

Site Tools

Differences

Page Tools