gps.h

Go to the documentation of this file.

/*
 * Copyright © 2013 Canonical Ltd.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License version 3 as
 * published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 *
 * Authored by: Daniel d'Andrada <daniel.dandrada@canonical.com>
 * Authored by: Thomas Voß <thomas.voss@canonical.com>
 */
#ifndef UBUNTU_HARDWARE_GPS_H_
#define UBUNTU_HARDWARE_GPS_H_

#include <ubuntu/visibility.h>

#include <stdint.h>
#include <stddef.h>

#ifdef __cplusplus
extern "C" {
#endif

#define U_HARDWARE_GPS_MAX_SVS 32

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
};

#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

typedef uint32_t UHardwareGpsNiNotifyFlags;
#define U_HARDWARE_GPS_NI_NEED_NOTIFY          0x0001

#define U_HARDWARE_GPS_NI_NEED_VERIFY          0x0002

#define U_HARDWARE_GPS_NI_PRIVACY_OVERRIDE     0x0004

typedef int UHardwareGpsUserResponseType;

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
};

#define U_HARDWARE_GPS_NI_SHORT_STRING_MAXLEN      256
#define U_HARDWARE_GPS_NI_LONG_STRING_MAXLEN       2048

typedef int UHardwareGpsNiEncodingType;

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
};

#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

typedef struct UHardwareGps_* UHardwareGps;

typedef struct
{
    size_t size;
    uint16_t flags;
    double latitude;
    double longitude;
    double altitude;
    float speed;
    float bearing;
    float accuracy;
    int64_t timestamp;
} UHardwareGpsLocation;

typedef struct {
    size_t size;
    int prn;
    float snr;
    float elevation;
    float azimuth;
} UHardwareGpsSvInfo;

typedef struct {
    size_t size;

    int num_svs;

    UHardwareGpsSvInfo sv_list[U_HARDWARE_GPS_MAX_SVS];

    uint32_t ephemeris_mask;

    uint32_t almanac_mask;

    uint32_t used_in_fix_mask;
} UHardwareGpsSvStatus;

typedef struct {
    size_t size;

    uint16_t type;
    uint16_t status;
    uint32_t ipaddr;
} UHardwareGpsAGpsStatus;

typedef struct {
    size_t size;

    int notification_id;

    uint32_t ni_type;

    UHardwareGpsNiNotifyFlags notify_flags;

    int timeout;

    UHardwareGpsUserResponseType default_response;

    char requestor_id[U_HARDWARE_GPS_NI_SHORT_STRING_MAXLEN];

    char text[U_HARDWARE_GPS_NI_LONG_STRING_MAXLEN];

    UHardwareGpsNiEncodingType requestor_id_encoding;

    UHardwareGpsNiEncodingType text_encoding;

    char extras[U_HARDWARE_GPS_NI_LONG_STRING_MAXLEN];

} UHardwareGpsNiNotification;

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);

/*
 Callback for AGPS RIL (Radio Interface Library) set id
*/
typedef void (*UHardwareGpsAGpsRilRequestSetId)(uint32_t flags, void *context);
typedef void (*UHardwareGpsAGpsRilRequestRefLoc)(uint32_t flags, void *context);

typedef struct
{

    UHardwareGpsLocationCallback location_cb;
    UHardwareGpsStatusCallback status_cb;
    UHardwareGpsSvStatusCallback sv_status_cb;
    UHardwareGpsNmeaCallback nmea_cb;
    UHardwareGpsSetCapabilities set_capabilities_cb;
    UHardwareGpsRequestUtcTime request_utc_time_cb;

    UHardwareGpsXtraDownloadRequest xtra_download_request_cb;

    UHardwareGpsAGpsStatusCallback agps_status_cb;

    UHardwareGpsNiNotifyCallback gps_ni_notify_cb;

    UHardwareGpsAGpsRilRequestSetId request_setid_cb;
    UHardwareGpsAGpsRilRequestRefLoc request_refloc_cb;

    void* context;
} UHardwareGpsParams;

/*
 You must create only one instance per process/application.
*/
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);

/*
    \param time NTP time, in milliseconds since Jan 1st 1970.
    \param time_reference time from the internal clock at the moment that NTP time was taken.
    \param uncertainty possible deviation in the time supplied (uncertainty) in milliseconds.
 */
UBUNTU_DLL_PUBLIC void
u_hardware_gps_inject_time(
    UHardwareGps self,
    int64_t time,
    int64_t time_reference,
    int uncertainty);

UBUNTU_DLL_PUBLIC void
u_hardware_gps_inject_location(
    UHardwareGps self,
    double latitude,
    double longitude,
    float accuracy);

UBUNTU_DLL_PUBLIC void
u_hardware_gps_delete_aiding_data(
    UHardwareGps self,
    uint16_t flags);

/*
    \param mode One of the U_HARDWARE_GPS_POSITION_MODE_* values
    \param recurrence One of the U_HARDWARE_GPS_POSITION_RECURRENCE_* values
    \param min_interval represents the time between fixes in milliseconds.
    \param preferred_accuracy The requested fix accuracy in meters. Can be zero.
    \param preferred_time The requested time to first fix in milliseconds. Can be zero.
 */
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);

UBUNTU_DLL_PUBLIC void
u_hardware_gps_inject_xtra_data(
    UHardwareGps self,
    char* data,
    int length);

#ifdef __cplusplus
}
#endif

#endif // UBUNTU_HARDWARE_GPS_H_