access:cpp_track_api
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision Next revision | Previous revision | ||
|
access:cpp_track_api [2015/07/01 18:06] mjallison |
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 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. |
| - | ''class ITrackApi { | + | <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: | public: | ||
| virtual ~ITrackApi(void) {} | virtual ~ITrackApi(void) {} | ||
| Line 21: | Line 52: | ||
| // clientp - A pointer to client data passed to the callback function. | // clientp - A pointer to client data passed to the callback function. | ||
| virtual AccessError download(const std::string& serial, | virtual AccessError download(const std::string& serial, | ||
| - | int start, | + | time_t start, |
| - | int end, | + | time_t end, |
| bool allFields, | bool allFields, | ||
| PositionCallback cb, | PositionCallback cb, | ||
| Line 37: | Line 68: | ||
| // passed in if an error occurs. | // passed in if an error occurs. | ||
| virtual AccessError upload(const std::string& serial, | virtual AccessError upload(const std::string& serial, | ||
| - | int count, | + | int count, |
| - | GpsPos* points, | + | GpsPos* points, |
| - | int* uploaded) = 0; | + | 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 | // Retrieves the list of tracks from the server according to | ||
| Line 50: | Line 97: | ||
| // tracks - The list the retrieved tracks will be added to. | // tracks - The list the retrieved tracks will be added to. | ||
| virtual AccessError getTracks(const std::string& serial, | virtual AccessError getTracks(const std::string& serial, | ||
| - | int project, | + | int project, |
| - | TrackList& tracks) = 0; | + | 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. | // Moves a track to a project. | ||
| Line 65: | Line 115: | ||
| // handle - The handle of the track to be deleted. | // handle - The handle of the track to be deleted. | ||
| virtual AccessError deleteTrack(int handle) = 0; | 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 | // Returns the list of device serial numbers the server knows about | ||
| Line 72: | Line 137: | ||
| // serials - The list the retrieved serial numbers will be added to. | // serials - The list the retrieved serial numbers will be added to. | ||
| virtual AccessError getSerialNumbers(SerialList& serials) = 0; | 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: | protected: | ||
| Line 81: | Line 174: | ||
| }; | }; | ||
| - | '' | + | </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 | ||
| + | |||
access/cpp_track_api.1435773971.txt.gz · Last modified: 2015/07/01 18:06 by mjallison
Page Tools
