From 51704bed795b5b0e5e3c7b792dcdc2bf2d96a9e9 Mon Sep 17 00:00:00 2001 From: The Android Open Source Project Date: Wed, 17 Dec 2008 18:05:50 -0800 Subject: Code drop from //branches/cupcake/...@124589 --- include/hardware/gps.h | 125 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 84 insertions(+), 41 deletions(-) (limited to 'include/hardware/gps.h') diff --git a/include/hardware/gps.h b/include/hardware/gps.h index 54b50a5..5f8740f 100644 --- a/include/hardware/gps.h +++ b/include/hardware/gps.h @@ -23,36 +23,58 @@ extern "C" { #endif -/** milliseconds since January 1, 1970 */ +/** Milliseconds since January 1, 1970 */ typedef int64_t GpsUtcTime; -/** maximum number of Space Vehicles for gps_sv_status_callback */ +/** Maximum number of SVs for gps_sv_status_callback(). */ #define GPS_MAX_SVS 32 - +/** Requested mode for GPS operation. */ typedef uint16_t GpsPositionMode; +// IMPORTANT: Note that the following values must match +// constants in GpsLocationProvider.java. +/** Mode for running GPS standalone (no assistance). */ #define GPS_POSITION_MODE_STANDALONE 0 +/** SUPL MS-Based mode. */ #define GPS_POSITION_MODE_MS_BASED 1 +/** SUPL MS-Assisted mode. */ #define GPS_POSITION_MODE_MS_ASSISTED 2 +/** GPS status event values. */ typedef uint16_t GpsStatusValue; -// IMPORTANT - these symbols here must match constants in GpsLocationProvider.java +// IMPORTANT: Note that the following values must match +// constants in GpsLocationProvider.java. +/** GPS status unknown. */ #define GPS_STATUS_NONE 0 +/** GPS has begun navigating. */ #define GPS_STATUS_SESSION_BEGIN 1 +/** GPS has stopped navigating. */ #define GPS_STATUS_SESSION_END 2 +/** GPS has powered on but is not navigating. */ #define GPS_STATUS_ENGINE_ON 3 +/** GPS is powered off. */ #define GPS_STATUS_ENGINE_OFF 4 +/** Flags to indicate which values are valid in a GpsLocation. */ typedef uint16_t GpsLocationFlags; -// IMPORTANT - these symbols here must match constants in GpsLocationProvider.java +// IMPORTANT: Note that the following values must match +// constants in GpsLocationProvider.java. +/** GpsLocation has valid latitude and longitude. */ #define GPS_LOCATION_HAS_LAT_LONG 0x0001 +/** GpsLocation has valid altitude. */ #define GPS_LOCATION_HAS_ALTITUDE 0x0002 +/** GpsLocation has valid speed. */ #define GPS_LOCATION_HAS_SPEED 0x0004 +/** GpsLocation has valid bearing. */ #define GPS_LOCATION_HAS_BEARING 0x0008 +/** GpsLocation has valid accuracy. */ #define GPS_LOCATION_HAS_ACCURACY 0x0010 +/** Flags used to specify which aiding data to delete + when calling delete_aiding_data(). */ typedef uint16_t GpsAidingData; -// IMPORTANT - these symbols here must match constants in GpsLocationProvider.java +// IMPORTANT: Note that the following values must match +// constants in GpsLocationProvider.java. #define GPS_DELETE_EPHEMERIS 0x0001 #define GPS_DELETE_ALMANAC 0x0002 #define GPS_DELETE_POSITION 0x0004 @@ -68,73 +90,88 @@ typedef uint16_t GpsAidingData; #define GPS_DELETE_ALL 0xFFFF /** - * names for GPS XTRA interface + * Name for the GPS XTRA interface. */ #define GPS_XTRA_INTERFACE "gps-xtra" /** - * names for GPS supplemental interface - * TODO: Remove not used. + * Name for the GPS SUPL interface. */ #define GPS_SUPL_INTERFACE "gps-supl" -/** The location */ +/** Represents a location. */ typedef struct { - /** contains GpsLocationFlags bits */ + /** Contains GpsLocationFlags bits. */ uint16_t flags; + /** Represents latitude in degrees. */ double latitude; + /** Represents longitude in degrees. */ double longitude; + /** Represents altitude in meters above the WGS 84 reference + * ellipsoid. */ double altitude; + /** Represents speed in meters per second. */ float speed; + /** Represents heading in degrees. */ float bearing; + /** Represents expected accuracy in meters. */ float accuracy; + /** Timestamp for the location fix. */ GpsUtcTime timestamp; } GpsLocation; -/** The status */ +/** Represents the status. */ typedef struct { GpsStatusValue status; } GpsStatus; -/** Space Vehicle info */ +/** Represents SV information. */ typedef struct { + /** Pseudo-random number for the SV. */ int prn; + /** Signal to noise ratio. */ float snr; + /** Elevation of SV in degrees. */ float elevation; + /** Azimuth of SV in degrees. */ float azimuth; } GpsSvInfo; -/** Space Vehicle status */ +/** Represents SV status. */ typedef struct { - /** number of SVs currently visible */ + /** Number of SVs currently visible. */ int num_svs; - /** Array of space vehicle info */ + /** Contains an array of SV information. */ GpsSvInfo sv_list[GPS_MAX_SVS]; - /** bit mask indicating which SVs have ephemeris data */ + /** Represents a bit mask indicating which SVs + * have ephemeris data. + */ uint32_t ephemeris_mask; - /** bit mask indicating which SVs have almanac data */ + /** Represents a bit mask indicating which SVs + * have almanac data. + */ uint32_t almanac_mask; /** - * bit mask indicating which SVs were used for - * computing the most recent position fix + * Represents a bit mask indicating which SVs + * were used for computing the most recent position fix. */ uint32_t used_in_fix_mask; } GpsSvStatus; -/** Callback with location information */ +/** Callback with location information. */ typedef void (* gps_location_callback)(GpsLocation* location); -/** Callback with the status information */ +/** Callback with status information. */ typedef void (* gps_status_callback)(GpsStatus* status); -/** Callback with the space vehicle status information */ +/** Callback with SV status information. */ typedef void (* gps_sv_status_callback)(GpsSvStatus* sv_info); -/** GPS call back structure */ +/** GPS callback structure. */ typedef struct { gps_location_callback location_cb; gps_status_callback status_cb; @@ -142,40 +179,40 @@ typedef struct { } GpsCallbacks; -/** Standard GPS interface */ +/** Represents the standard GPS interface. */ typedef struct { /** - * Open the interface and provide the callback routines + * Opens the interface and provides the callback routines * to the implemenation of this interface. */ int (*init)( GpsCallbacks* callbacks ); - /** Start navigating */ + /** Starts navigating. */ int (*start)( void ); - /** Stop navigating */ + /** Stops navigating. */ int (*stop)( void ); - /** Set requested frequency of fixes in seconds */ + /** Sets requested frequency of fixes in seconds. */ void (*set_fix_frequency)( int frequency ); - /** Close the interface */ + /** Closes the interface. */ void (*cleanup)( void ); - /** Inject the current time */ + /** Injects the current time. */ int (*inject_time)(GpsUtcTime time, int64_t timeReference, int uncertainty); /** - * The next call to start will not use the information - * defined in the flags. GPS_DELETE_ALL is passed for + * Specifies that the next call to start will not use the + * information defined in the flags. GPS_DELETE_ALL is passed for * a cold start. */ void (*delete_aiding_data)(GpsAidingData flags); /** - * fix_frequency is time between fixes in seconds. - * set fix_frequency to zero for a single shot fix. + * fix_frequency represents the time between fixes in seconds. + * Set fix_frequency to zero for a single-shot fix. */ int (*set_position_mode)(GpsPositionMode mode, int fix_frequency); @@ -183,31 +220,37 @@ typedef struct { const void* (*get_extension)(const char* name); } GpsInterface; -/** The download request callback routine. */ +/** Callback to request the client to download XTRA data. + The client should download XTRA data and inject it by calling + inject_xtra_data(). */ typedef void (* gps_xtra_download_request)(); -/** The download request callback structure. */ +/** Callback structure for the XTRA interface. */ typedef struct { gps_xtra_download_request download_request_cb; } GpsXtraCallbacks; /** Extended interface for XTRA support. */ typedef struct { + /** + * Opens the XTRA interface and provides the callback routines + * to the implemenation of this interface. + */ int (*init)( GpsXtraCallbacks* callbacks ); + /** Injects XTRA data into the GPS. */ int (*inject_xtra_data)( char* data, int length ); } GpsXtraInterface; -/** returns the hardware GPS interface. */ +/** Returns the hardware GPS interface. */ const GpsInterface* gps_get_hardware_interface(); /** - * returns the qemu hardware interface GPS interface. + * Returns the qemu emulated GPS interface. */ const GpsInterface* gps_get_qemu_interface(); /** - * returns the default GPS interface, - * implemented in lib/hardware/gps.cpp. + * Returns the default GPS interface. */ const GpsInterface* gps_get_interface(); -- cgit v1.1