AGTEK R & D Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== C++ API for tracking ======

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. 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

Page Tools
