Ubuntu Platform API  2.7.0
A library helping with tight integration into the Ubuntu platform
gps.h File Reference
#include <ubuntu/visibility.h>
#include <stdint.h>
#include <stddef.h>
+ Include dependency graph for gps.h:

Go to the source code of this file.

Data Structures

struct  UHardwareGpsLocation
 
struct  UHardwareGpsSvInfo
 
struct  UHardwareGpsSvStatus
 
struct  UHardwareGpsAGpsStatus
 
struct  UHardwareGpsAGpsRefLocationCellID
 Describes a cell ID as understood by the GPS chipset. More...
 
struct  UHardwareGpsAGpsRefLocationMac
 Describes a wifi ID as understood by the GPS chipset. More...
 
struct  UHardwareGpsAGpsRefLocation
 Describes a reference location, either a radio cell or a wifi. More...
 
struct  UHardwareGpsNiNotification
 
struct  UHardwareGpsParams
 

Macros

#define U_HARDWARE_GPS_MAX_SVS   32
 
#define U_HARDWARE_GPS_CAPABILITY_SCHEDULING   0x0000001
 
#define U_HARDWARE_GPS_CAPABILITY_MSB   0x0000002
 
#define U_HARDWARE_GPS_CAPABILITY_MSA   0x0000004
 
#define U_HARDWARE_GPS_CAPABILITY_SINGLE_SHOT   0x0000008
 
#define U_HARDWARE_GPS_CAPABILITY_ON_DEMAND_TIME   0x0000010
 
#define U_HARDWARE_GPS_NI_NEED_NOTIFY   0x0001
 
#define U_HARDWARE_GPS_NI_NEED_VERIFY   0x0002
 
#define U_HARDWARE_GPS_NI_PRIVACY_OVERRIDE   0x0004
 
#define U_HARDWARE_GPS_NI_SHORT_STRING_MAXLEN   256
 
#define U_HARDWARE_GPS_NI_LONG_STRING_MAXLEN   2048
 
#define U_HARDWARE_GPS_DELETE_EPHEMERIS   0x0001
 
#define U_HARDWARE_GPS_DELETE_ALMANAC   0x0002
 
#define U_HARDWARE_GPS_DELETE_POSITION   0x0004
 
#define U_HARDWARE_GPS_DELETE_TIME   0x0008
 
#define U_HARDWARE_GPS_DELETE_IONO   0x0010
 
#define U_HARDWARE_GPS_DELETE_UTC   0x0020
 
#define U_HARDWARE_GPS_DELETE_HEALTH   0x0040
 
#define U_HARDWARE_GPS_DELETE_SVDIR   0x0080
 
#define U_HARDWARE_GPS_DELETE_SVSTEER   0x0100
 
#define U_HARDWARE_GPS_DELETE_SADATA   0x0200
 
#define U_HARDWARE_GPS_DELETE_RTI   0x0400
 
#define U_HARDWARE_GPS_DELETE_CELLDB_INFO   0x8000
 
#define U_HARDWARE_GPS_DELETE_ALL   0xFFFF
 
#define U_HARDWARE_GPS_AGPS_TYPE_SUPL   1
 
#define U_HARDWARE_GPS_AGPS_TYPE_C2K   2
 
#define U_HARDWARE_GPS_AGPS_REF_LOCATION_TYPE_GSM_CELLID   1
 
#define U_HARDWARE_GPS_AGPS_REF_LOCATION_TYPE_UMTS_CELLID   2
 
#define U_HARDWARE_GPS_AGPS_REG_LOCATION_TYPE_MAC   3
 
#define U_HARDWARE_GPS_LOCATION_HAS_LAT_LONG   0x0001
 
#define U_HARDWARE_GPS_LOCATION_HAS_ALTITUDE   0x0002
 
#define U_HARDWARE_GPS_LOCATION_HAS_SPEED   0x0004
 
#define U_HARDWARE_GPS_LOCATION_HAS_BEARING   0x0008
 
#define U_HARDWARE_GPS_LOCATION_HAS_ACCURACY   0x0010
 

Typedefs

typedef uint32_t UHardwareGpsNiNotifyFlags
 
typedef int UHardwareGpsUserResponseType
 
typedef int UHardwareGpsNiEncodingType
 
typedef uint16_t UHardwareGpsAidingData
 
typedef uint16_t UHardwareGpsAGpsType
 
typedef struct UHardwareGps_ * UHardwareGps
 
typedef void(* UHardwareGpsLocationCallback) (UHardwareGpsLocation *location, void *context)
 
typedef void(* UHardwareGpsStatusCallback) (uint16_t status, void *context)
 
typedef void(* UHardwareGpsSvStatusCallback) (UHardwareGpsSvStatus *sv_info, void *context)
 
typedef void(* UHardwareGpsNmeaCallback) (int64_t timestamp, const char *nmea, int length, void *context)
 
typedef void(* UHardwareGpsSetCapabilities) (uint32_t capabilities, void *context)
 
typedef void(* UHardwareGpsRequestUtcTime) (void *context)
 
typedef void(* UHardwareGpsXtraDownloadRequest) (void *context)
 
typedef void(* UHardwareGpsAGpsStatusCallback) (UHardwareGpsAGpsStatus *status, void *context)
 
typedef void(* UHardwareGpsNiNotifyCallback) (UHardwareGpsNiNotification *notification, void *context)
 
typedef void(* UHardwareGpsAGpsRilRequestSetId) (uint32_t flags, void *context)
 
typedef void(* UHardwareGpsAGpsRilRequestRefLoc) (uint32_t flags, void *context)
 

Enumerations

enum  {
  U_HARDWARE_GPS_STATUS_NONE = 0,
  U_HARDWARE_GPS_STATUS_SESSION_BEGIN = 1,
  U_HARDWARE_GPS_STATUS_SESSION_END = 2,
  U_HARDWARE_GPS_STATUS_ENGINE_ON = 3,
  U_HARDWARE_GPS_STATUS_ENGINE_OFF = 4
}
 
enum  {
  U_HARDWARE_GPS_NI_RESPONSE_ACCEPT = 1,
  U_HARDWARE_GPS_NI_RESPONSE_DENY = 2,
  U_HARDWARE_GPS_NI_RESPONSE_NORESP = 3
}
 
enum  {
  U_HARDWARE_GPS_NI_TYPE_VOICE = 1,
  U_HARDWARE_GPS_NI_TYPE_UMTS_SUPL = 2,
  U_HARDWARE_GPS_NI_TYPE_UMTS_CTRL_PLANE = 3
}
 
enum  {
  U_HARDWARE_GPS_ENC_NONE = 0,
  U_HARDWARE_GPS_ENC_SUPL_GSM_DEFAULT = 1,
  U_HARDWARE_GPS_ENC_SUPL_UTF8 = 2,
  U_HARDWARE_GPS_ENC_SUPL_UCS2 = 3,
  U_HARDWARE_GPS_ENC_UNKNOWN = -1
}
 
enum  {
  U_HARDWARE_GPS_AGPS_TYPE_SUPL = 1,
  U_HARDWARE_GPS_AGPS_TYPE_C2K = 2
}
 
enum  {
  U_HARDWARE_GPS_POSITION_MODE_STANDALONE = 0,
  U_HARDWARE_GPS_POSITION_MODE_MS_BASED = 1,
  U_HARDWARE_GPS_POSITION_MODE_MS_ASSISTED = 2
}
 
enum  {
  U_HARDWARE_GPS_POSITION_RECURRENCE_PERIODIC = 0,
  U_HARDWARE_GPS_POSITION_RECURRENCE_SINGLE = 1
}
 
enum  {
  U_HARDWARE_GPS_REQUEST_AGPS_DATA_CONN = 1,
  U_HARDWARE_GPS_RELEASE_AGPS_DATA_CONN = 2,
  U_HARDWARE_GPS_AGPS_DATA_CONNECTED = 3,
  U_HARDWARE_GPS_AGPS_DATA_CONN_DONE = 4,
  U_HARDWARE_GPS_AGPS_DATA_CONN_FAILED = 5
}
 

Functions

UBUNTU_DLL_PUBLIC UHardwareGps u_hardware_gps_new (UHardwareGpsParams *params)
 
UBUNTU_DLL_PUBLIC void u_hardware_gps_delete (UHardwareGps handle)
 
UBUNTU_DLL_PUBLIC bool u_hardware_gps_start (UHardwareGps self)
 
UBUNTU_DLL_PUBLIC bool u_hardware_gps_stop (UHardwareGps self)
 
UBUNTU_DLL_PUBLIC void u_hardware_gps_inject_time (UHardwareGps self, int64_t time, int64_t time_reference, int uncertainty)
 Injects a new reference time into the GPS chipset. More...
 
UBUNTU_DLL_PUBLIC void u_hardware_gps_inject_location (UHardwareGps self, UHardwareGpsLocation location)
 Injects a new reference location into the GPS chipset. More...
 
UBUNTU_DLL_PUBLIC void u_hardware_gps_agps_set_reference_location (UHardwareGps self, UHardwareGpsAGpsRefLocation *location, size_t size_of_struct)
 Informs the GPS chipset about wifi ap's or radio cells to be used in AGPS calls. More...
 
UBUNTU_DLL_PUBLIC void u_hardware_gps_agps_notify_connection_is_open (UHardwareGps self, const char *apn)
 Notifies the chipset that a data connection is availble. More...
 
UBUNTU_DLL_PUBLIC void u_hardware_gps_agps_notify_connection_is_closed (UHardwareGps self)
 Notifies the chipset that an AGPS data connection has been closed. More...
 
UBUNTU_DLL_PUBLIC void u_hardware_gps_agps_notify_connection_not_available (UHardwareGps self)
 Notifies the chipset that an AGPS data connection is not available. More...
 
UBUNTU_DLL_PUBLIC void u_hardware_gps_agps_set_server_for_type (UHardwareGps self, UHardwareGpsAGpsType type, const char *hostname, uint16_t port)
 Sets the hostname and port for the AGPS server. More...
 
UBUNTU_DLL_PUBLIC void u_hardware_gps_delete_aiding_data (UHardwareGps self, UHardwareGpsAidingData flags)
 Requests the chipset to delete the aiding data specified in flags. More...
 
UBUNTU_DLL_PUBLIC bool u_hardware_gps_set_position_mode (UHardwareGps self, uint32_t mode, uint32_t recurrence, uint32_t min_interval, uint32_t preferred_accuracy, uint32_t preferred_time)
 Sets the positioning mode of the chipset. More...
 
UBUNTU_DLL_PUBLIC void u_hardware_gps_inject_xtra_data (UHardwareGps self, char *data, int length)
 

Macro Definition Documentation

#define U_HARDWARE_GPS_AGPS_REF_LOCATION_TYPE_GSM_CELLID   1

Known types for AGps reference locations. A GSM cell ID.

Definition at line 208 of file gps.h.

#define U_HARDWARE_GPS_AGPS_REF_LOCATION_TYPE_UMTS_CELLID   2

A UMTS cell ID.

Definition at line 210 of file gps.h.

#define U_HARDWARE_GPS_AGPS_REG_LOCATION_TYPE_MAC   3

The BSSID of a visible access point.

Definition at line 212 of file gps.h.

#define U_HARDWARE_GPS_AGPS_TYPE_C2K   2

Definition at line 204 of file gps.h.

#define U_HARDWARE_GPS_AGPS_TYPE_SUPL   1

Definition at line 203 of file gps.h.

#define U_HARDWARE_GPS_CAPABILITY_MSA   0x0000004

GPS supports MS-Assisted AGPS mode

Definition at line 68 of file gps.h.

#define U_HARDWARE_GPS_CAPABILITY_MSB   0x0000002

GPS supports MS-Based AGPS mode

Definition at line 66 of file gps.h.

#define U_HARDWARE_GPS_CAPABILITY_ON_DEMAND_TIME   0x0000010

GPS supports on demand time injection

Definition at line 72 of file gps.h.

#define U_HARDWARE_GPS_CAPABILITY_SINGLE_SHOT   0x0000008

GPS supports single-shot fixes

Definition at line 70 of file gps.h.

#define U_HARDWARE_GPS_DELETE_ALL   0xFFFF

Definition at line 199 of file gps.h.

#define U_HARDWARE_GPS_DELETE_ALMANAC   0x0002

Definition at line 188 of file gps.h.

#define U_HARDWARE_GPS_DELETE_CELLDB_INFO   0x8000

Definition at line 198 of file gps.h.

#define U_HARDWARE_GPS_DELETE_EPHEMERIS   0x0001

Definition at line 187 of file gps.h.

#define U_HARDWARE_GPS_DELETE_HEALTH   0x0040

Definition at line 193 of file gps.h.

#define U_HARDWARE_GPS_DELETE_IONO   0x0010

Definition at line 191 of file gps.h.

#define U_HARDWARE_GPS_DELETE_POSITION   0x0004

Definition at line 189 of file gps.h.

#define U_HARDWARE_GPS_DELETE_RTI   0x0400

Definition at line 197 of file gps.h.

#define U_HARDWARE_GPS_DELETE_SADATA   0x0200

Definition at line 196 of file gps.h.

#define U_HARDWARE_GPS_DELETE_SVDIR   0x0080

Definition at line 194 of file gps.h.

#define U_HARDWARE_GPS_DELETE_SVSTEER   0x0100

Definition at line 195 of file gps.h.

#define U_HARDWARE_GPS_DELETE_TIME   0x0008

Definition at line 190 of file gps.h.

#define U_HARDWARE_GPS_DELETE_UTC   0x0020

Definition at line 192 of file gps.h.

#define U_HARDWARE_GPS_LOCATION_HAS_ACCURACY   0x0010

UHardwareGpsLocation has valid accuracy.

Definition at line 223 of file gps.h.

#define U_HARDWARE_GPS_LOCATION_HAS_ALTITUDE   0x0002

UHardwareGpsLocation has valid altitude.

Definition at line 217 of file gps.h.

#define U_HARDWARE_GPS_LOCATION_HAS_BEARING   0x0008

UHardwareGpsLocation has valid bearing.

Definition at line 221 of file gps.h.

#define U_HARDWARE_GPS_LOCATION_HAS_LAT_LONG   0x0001

UHardwareGpsLocation has valid latitude and longitude.

Definition at line 215 of file gps.h.

#define U_HARDWARE_GPS_LOCATION_HAS_SPEED   0x0004

UHardwareGpsLocation has valid speed.

Definition at line 219 of file gps.h.

#define U_HARDWARE_GPS_NI_LONG_STRING_MAXLEN   2048

Definition at line 112 of file gps.h.

#define U_HARDWARE_GPS_NI_NEED_NOTIFY   0x0001

NI requires notification

Definition at line 80 of file gps.h.

#define U_HARDWARE_GPS_NI_NEED_VERIFY   0x0002

NI requires verification

Definition at line 82 of file gps.h.

#define U_HARDWARE_GPS_NI_PRIVACY_OVERRIDE   0x0004

NI requires privacy override, no notification/minimal trace

Definition at line 84 of file gps.h.

Typedef Documentation

typedef struct UHardwareGps_* UHardwareGps

Definition at line 225 of file gps.h.

typedef void(* UHardwareGpsAGpsRilRequestRefLoc) (uint32_t flags, void *context)

Callback invoked by the driver to request a reference location (typically cell ID).

Definition at line 438 of file gps.h.

typedef void(* UHardwareGpsAGpsRilRequestSetId) (uint32_t flags, void *context)

Callback invoked by the driver to set the set id.

Definition at line 436 of file gps.h.

typedef void(* UHardwareGpsAGpsStatusCallback) (UHardwareGpsAGpsStatus *status, void *context)

Callback with AGPS status information.

Definition at line 430 of file gps.h.

typedef uint16_t UHardwareGpsAGpsType

AGPS type

Definition at line 202 of file gps.h.

typedef uint16_t UHardwareGpsAidingData

Flags used to specify which aiding data to delete when calling delete_aiding_data().

Definition at line 185 of file gps.h.

typedef void(* UHardwareGpsLocationCallback) (UHardwareGpsLocation *location, void *context)

Definition at line 419 of file gps.h.

typedef void(* UHardwareGpsNiNotifyCallback) (UHardwareGpsNiNotification *notification, void *context)

Callback with NI notification.

Definition at line 433 of file gps.h.

typedef void(* UHardwareGpsNmeaCallback) (int64_t timestamp, const char *nmea, int length, void *context)

Definition at line 422 of file gps.h.

typedef void(* UHardwareGpsRequestUtcTime) (void *context)

Definition at line 424 of file gps.h.

typedef void(* UHardwareGpsSetCapabilities) (uint32_t capabilities, void *context)

Definition at line 423 of file gps.h.

typedef void(* UHardwareGpsStatusCallback) (uint16_t status, void *context)

Definition at line 420 of file gps.h.

typedef void(* UHardwareGpsSvStatusCallback) (UHardwareGpsSvStatus *sv_info, void *context)

Definition at line 421 of file gps.h.

typedef void(* UHardwareGpsXtraDownloadRequest) (void *context)

Callback to request the client to download XTRA data. The client should download XTRA data and inject it by calling inject_xtra_data().

Definition at line 427 of file gps.h.

Enumeration Type Documentation

anonymous enum
Enumerator
U_HARDWARE_GPS_NI_RESPONSE_ACCEPT 
U_HARDWARE_GPS_NI_RESPONSE_DENY 
U_HARDWARE_GPS_NI_RESPONSE_NORESP 

Definition at line 93 of file gps.h.

anonymous enum
Enumerator
U_HARDWARE_GPS_NI_TYPE_VOICE 
U_HARDWARE_GPS_NI_TYPE_UMTS_SUPL 
U_HARDWARE_GPS_NI_TYPE_UMTS_CTRL_PLANE 

Definition at line 100 of file gps.h.

anonymous enum
Enumerator
U_HARDWARE_GPS_REQUEST_AGPS_DATA_CONN 

GPS requests data connection for AGPS.

U_HARDWARE_GPS_RELEASE_AGPS_DATA_CONN 

GPS releases the AGPS data connection.

U_HARDWARE_GPS_AGPS_DATA_CONNECTED 

AGPS data connection initiated

U_HARDWARE_GPS_AGPS_DATA_CONN_DONE 

AGPS data connection completed

U_HARDWARE_GPS_AGPS_DATA_CONN_FAILED 

AGPS data connection failed

Definition at line 169 of file gps.h.

Function Documentation

UBUNTU_DLL_PUBLIC void u_hardware_gps_agps_notify_connection_is_closed ( UHardwareGps  self)

Notifies the chipset that an AGPS data connection has been closed.

Parameters
selfThe instance to be notified.
UBUNTU_DLL_PUBLIC void u_hardware_gps_agps_notify_connection_is_open ( UHardwareGps  self,
const char *  apn 
)

Notifies the chipset that a data connection is availble.

Parameters
selfThe instance to be notified.
apnName of the apn to be used for SUPL.
UBUNTU_DLL_PUBLIC void u_hardware_gps_agps_notify_connection_not_available ( UHardwareGps  self)

Notifies the chipset that an AGPS data connection is not available.

Parameters
selfThe instance to be notified.
UBUNTU_DLL_PUBLIC void u_hardware_gps_agps_set_reference_location ( UHardwareGps  self,
UHardwareGpsAGpsRefLocation location,
size_t  size_of_struct 
)

Informs the GPS chipset about wifi ap's or radio cells to be used in AGPS calls.

Parameters
selfThe instance to inform.
locationThe reference location, that is a wifi ap or a radio cell.
size_of_structThe size of the reference location struct.
UBUNTU_DLL_PUBLIC void u_hardware_gps_agps_set_server_for_type ( UHardwareGps  self,
UHardwareGpsAGpsType  type,
const char *  hostname,
uint16_t  port 
)

Sets the hostname and port for the AGPS server.

Parameters
selfThe instance to be altered.
typeType of the server, one of U_HARDWARE_GPS_AGPS_TYPE_SUPL or U_HARDWARE_GPS_AGPS_TYPE_C2K.
hostnameThe hostname of the AGPS server.
portThe post of the AGPS server.
UBUNTU_DLL_PUBLIC void u_hardware_gps_delete ( UHardwareGps  handle)
UBUNTU_DLL_PUBLIC void u_hardware_gps_delete_aiding_data ( UHardwareGps  self,
UHardwareGpsAidingData  flags 
)

Requests the chipset to delete the aiding data specified in flags.

Parameters
selfThe instance to apply the change to.
flagsSpecifies the aiding data that should be deleted.
UBUNTU_DLL_PUBLIC void u_hardware_gps_inject_location ( UHardwareGps  self,
UHardwareGpsLocation  location 
)

Injects a new reference location into the GPS chipset.

Parameters
selfThe instance to apply the change to.
locationNew location to me injected. The structure must have the following details, any others are ignored:
  • location: New coordinate, in [°].
  • longitude: New coordinate, [°].
  • accuracy: Accuracy estimate of the location, in [m].
UBUNTU_DLL_PUBLIC void u_hardware_gps_inject_time ( UHardwareGps  self,
int64_t  time,
int64_t  time_reference,
int  uncertainty 
)

Injects a new reference time into the GPS chipset.

Parameters
timeNTP time, in milliseconds since Jan 1st 1970.
time_referencetime from the internal clock at the moment that NTP time was taken.
uncertaintypossible deviation in the time supplied (uncertainty) in milliseconds.
UBUNTU_DLL_PUBLIC void u_hardware_gps_inject_xtra_data ( UHardwareGps  self,
char *  data,
int  length 
)
UBUNTU_DLL_PUBLIC UHardwareGps u_hardware_gps_new ( UHardwareGpsParams params)
UBUNTU_DLL_PUBLIC bool u_hardware_gps_set_position_mode ( UHardwareGps  self,
uint32_t  mode,
uint32_t  recurrence,
uint32_t  min_interval,
uint32_t  preferred_accuracy,
uint32_t  preferred_time 
)

Sets the positioning mode of the chipset.

Parameters
modeOne of the U_HARDWARE_GPS_POSITION_MODE_* values
recurrenceOne of the U_HARDWARE_GPS_POSITION_RECURRENCE_* values
min_intervalrepresents the time between fixes in milliseconds.
preferred_accuracyThe requested fix accuracy in meters. Can be zero.
preferred_timeThe requested time to first fix in milliseconds. Can be zero.
UBUNTU_DLL_PUBLIC bool u_hardware_gps_start ( UHardwareGps  self)
UBUNTU_DLL_PUBLIC bool u_hardware_gps_stop ( UHardwareGps  self)