Ubuntu Platform API  2.0.0
A library helping with tight integration into the Ubuntu platform
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Functions and types to provide location services to applications.

Typedefs

typedef void(* UALocationServiceStatusChangedHandler )(UALocationServiceStatusFlags flags, void *context)
 Callback type that is invoked when the location service status changes. More...
 
typedef struct
UbuntuApplicationLocationServiceController 
UALocationServiceController
 Opaque type encapsulating a controller the location service. More...
 
typedef struct
UbuntuApplicationLocationHeadingUpdate 
UALocationHeadingUpdate
 Opaque type encapsulating a heading update. More...
 
typedef struct
UbuntuApplicationLocationPositionUpdate 
UALocationPositionUpdate
 Opaque type encapsulating a location update. More...
 
typedef unsigned int UALocationServiceRequirementsFlags
 Bitfield type for summarizing an application's requirements. More...
 
typedef struct
UbuntuApplicationLocationServiceSession 
UALocationServiceSession
 Opaque type encapsulating a session with the location service. More...
 
typedef void(* UALocationServiceSessionPositionUpdatesHandler )(UALocationPositionUpdate *position, void *context)
 Callback type that is invoked for position updates. More...
 
typedef void(* UALocationServiceSessionHeadingUpdatesHandler )(UALocationHeadingUpdate *heading, void *context)
 Callback type that is invoked for heading updates. More...
 
typedef void(* UALocationServiceSessionVelocityUpdatesHandler )(UALocationVelocityUpdate *heading, void *context)
 Callback type that is invoked for velocity updates. More...
 
typedef struct
UbuntuApplicationLocationVelocityUpdate 
UALocationVelocityUpdate
 Opaque type encapsulating a velocity update. More...
 

Enumerations

enum  UbuntuApplicationLocationServiceStatus {
  UA_LOCATION_SERVICE_ENABLED = 1 << 0,
  UA_LOCATION_SERVICE_DISABLED = 1 << 1,
  UA_LOCATION_SERVICE_GPS_ENABLED = 1 << 2,
  UA_LOCATION_SERVICE_GPS_DISABLED = 1 << 3
}
 Location service status. More...
 
enum  UbuntuApplicationLocationServiceRequirement {
  UA_LOCATION_SERVICE_REQUIRE_ALTITUDE = 1 << 0,
  UA_LOCATION_SERVICE_REQUIRE_HEADING = 1 << 1,
  UA_LOCATION_SERVICE_REQUIRE_VELOCITY = 1 << 2
}
 Application-specific requirements. More...
 

Functions

UBUNTU_DLL_PUBLIC void ua_location_service_controller_ref (UALocationServiceController *controller)
 Increments the reference count of the controller instance. More...
 
UBUNTU_DLL_PUBLIC void ua_location_service_controller_unref (UALocationServiceController *controller)
 Decrements the reference count of the controller instance. More...
 
UBUNTU_DLL_PUBLIC void ua_location_service_controller_set_status_changed_handler (UALocationServiceController *controller, UALocationServiceStatusChangedHandler handler, void *context)
 Sets the status changed handler of the controller instance. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_location_service_controller_query_status (UALocationServiceController *controller, UALocationServiceStatusFlags *out_flags)
 Query the status of the location service. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_location_service_controller_enable_service (UALocationServiceController *controller)
 Enables the location service. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_location_service_controller_disable_service (UALocationServiceController *controller)
 Disables the location service completely. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_location_service_controller_enable_gps (UALocationServiceController *controller)
 Enables all gps providers known to the location service. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_location_service_controller_disable_gps (UALocationServiceController *controller)
 Disables all gps providers known to the location service. More...
 
UBUNTU_DLL_PUBLIC void ua_location_heading_update_ref (UALocationHeadingUpdate *update)
 Increments the reference count of the heading update instance. More...
 
UBUNTU_DLL_PUBLIC void ua_location_heading_update_unref (UALocationHeadingUpdate *update)
 Decrements the reference count of the heading update instance. More...
 
UBUNTU_DLL_PUBLIC uint64_t ua_location_heading_update_get_timestamp (UALocationHeadingUpdate *update)
 Queries the timestamp of the heading update. More...
 
UBUNTU_DLL_PUBLIC double ua_location_heading_update_get_heading_in_degree (UALocationHeadingUpdate *update)
 Queries the new heading from the update. More...
 
UBUNTU_DLL_PUBLIC void ua_location_position_update_ref (UALocationPositionUpdate *update)
 Increments the reference count of the position update instance. More...
 
UBUNTU_DLL_PUBLIC void ua_location_position_update_unref (UALocationPositionUpdate *update)
 Decrements the reference count of the position update instance. More...
 
UBUNTU_DLL_PUBLIC uint64_t ua_location_position_update_get_timestamp (UALocationPositionUpdate *update)
 Queries the timestamp of the position update. More...
 
UBUNTU_DLL_PUBLIC double ua_location_position_update_get_latitude_in_degree (UALocationPositionUpdate *update)
 Queries the latitude contained in the position update. More...
 
UBUNTU_DLL_PUBLIC double ua_location_position_update_get_longitude_in_degree (UALocationPositionUpdate *update)
 Queries the longitude contained in the position update. More...
 
UBUNTU_DLL_PUBLIC bool ua_location_position_update_has_altitude (UALocationPositionUpdate *update)
 Checks if the position update contains an altitude. More...
 
UBUNTU_DLL_PUBLIC double ua_location_position_update_get_altitude_in_meter (UALocationPositionUpdate *update)
 Queries the altitude contained in the position update. More...
 
UBUNTU_DLL_PUBLIC
UALocationServiceSession
ua_location_service_create_session_for_low_accuracy (UALocationServiceRequirementsFlags flags)
 Creates a new session with the location service for low positional accuracy requirements. More...
 
UBUNTU_DLL_PUBLIC
UALocationServiceSession
ua_location_service_create_session_for_high_accuracy (UALocationServiceRequirementsFlags flags)
 Creates a new session with the location service for high positional accuracy requirements. More...
 
UBUNTU_DLL_PUBLIC
UALocationServiceController
ua_location_service_create_controller ()
 Creates a new controller for the location service. More...
 
UBUNTU_DLL_PUBLIC void ua_location_service_session_ref (UALocationServiceSession *session)
 Increments the reference count of the session instance. More...
 
UBUNTU_DLL_PUBLIC void ua_location_service_session_unref (UALocationServiceSession *session)
 Decrements the reference count of the session instance. More...
 
UBUNTU_DLL_PUBLIC void ua_location_service_session_set_position_updates_handler (UALocationServiceSession *session, UALocationServiceSessionPositionUpdatesHandler handler, void *context)
 Installs an app-specific position update handler for the session. More...
 
UBUNTU_DLL_PUBLIC void ua_location_service_session_set_heading_updates_handler (UALocationServiceSession *session, UALocationServiceSessionHeadingUpdatesHandler handler, void *context)
 Installs an app-specific heading update handler for the session. More...
 
UBUNTU_DLL_PUBLIC void ua_location_service_session_set_velocity_updates_handler (UALocationServiceSession *session, UALocationServiceSessionVelocityUpdatesHandler handler, void *context)
 Installs an app-specific velocity update handler for the session. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_location_service_session_start_position_updates (UALocationServiceSession *session)
 Starts position updates for the supplied session. More...
 
UBUNTU_DLL_PUBLIC void ua_location_service_session_stop_position_updates (UALocationServiceSession *session)
 Stops position updates for the supplied session. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_location_service_session_start_heading_updates (UALocationServiceSession *session)
 Starts heading updates for the supplied session. More...
 
UBUNTU_DLL_PUBLIC void ua_location_service_session_stop_heading_updates (UALocationServiceSession *session)
 Stops heading updates for the supplied session. More...
 
UBUNTU_DLL_PUBLIC UStatus ua_location_service_session_start_velocity_updates (UALocationServiceSession *session)
 Starts velocity updates for the supplied session. More...
 
UBUNTU_DLL_PUBLIC void ua_location_service_session_stop_velocity_updates (UALocationServiceSession *session)
 Stops velocity updates for the supplied session. More...
 
UBUNTU_DLL_PUBLIC void ua_location_velocity_update_ref (UALocationVelocityUpdate *update)
 Increments the reference count of the velocity update instance. More...
 
UBUNTU_DLL_PUBLIC void ua_location_velocity_update_unref (UALocationVelocityUpdate *update)
 Decrements the reference count of the velocity update instance. More...
 
UBUNTU_DLL_PUBLIC uint64_t ua_location_velocity_update_get_timestamp (UALocationVelocityUpdate *update)
 Queries the timestamp of the velocity update. More...
 
UBUNTU_DLL_PUBLIC double ua_location_velocity_update_get_velocity_in_meters_per_second (UALocationVelocityUpdate *update)
 Queries the velocity contained in the position update. More...
 

Detailed Description

Applications in Ubuntu do not access positioning hardware directly but instead rely on a system-wide location service to be provided with position, heading and velocity updates. An application that wants to receive position, heading or velocity updates needs to start a session with the location service and specify its requirements with the help UALocationServiceRequirementsFlags. After the session has been created, position, heading and velocity updates need to be started by the application for its session. The actual updates are delivered via callbacks. Please note that the location service caches updates as good as possible. That is, if an application is only interested in a single position fix, and a reasonable fix is already known to the service, the information is immediately delivered to the application when the respecitve updates are started.

Typedef Documentation

typedef struct UbuntuApplicationLocationHeadingUpdate UALocationHeadingUpdate

Opaque type encapsulating a heading update.

Definition at line 36 of file heading_update.h.

typedef struct UbuntuApplicationLocationPositionUpdate UALocationPositionUpdate

Opaque type encapsulating a location update.

Definition at line 36 of file position_update.h.

typedef struct UbuntuApplicationLocationServiceController UALocationServiceController

Opaque type encapsulating a controller the location service.

Definition at line 58 of file controller.h.

typedef unsigned int UALocationServiceRequirementsFlags

Bitfield type for summarizing an application's requirements.

Definition at line 69 of file service.h.

typedef struct UbuntuApplicationLocationServiceSession UALocationServiceSession

Opaque type encapsulating a session with the location service.

Definition at line 38 of file session.h.

typedef void(* UALocationServiceSessionHeadingUpdatesHandler)(UALocationHeadingUpdate *heading, void *context)

Callback type that is invoked for heading updates.

Definition at line 52 of file session.h.

typedef void(* UALocationServiceSessionPositionUpdatesHandler)(UALocationPositionUpdate *position, void *context)

Callback type that is invoked for position updates.

Definition at line 44 of file session.h.

typedef void(* UALocationServiceSessionVelocityUpdatesHandler)(UALocationVelocityUpdate *heading, void *context)

Callback type that is invoked for velocity updates.

Definition at line 60 of file session.h.

typedef void(* UALocationServiceStatusChangedHandler)(UALocationServiceStatusFlags flags, void *context)

Callback type that is invoked when the location service status changes.

Definition at line 50 of file controller.h.

typedef struct UbuntuApplicationLocationVelocityUpdate UALocationVelocityUpdate

Opaque type encapsulating a velocity update.

Definition at line 36 of file velocity_update.h.

Enumeration Type Documentation

Application-specific requirements.

Enumerator
UA_LOCATION_SERVICE_REQUIRE_ALTITUDE 

The application requires altitude updates.

UA_LOCATION_SERVICE_REQUIRE_HEADING 

The application requires heading updates.

UA_LOCATION_SERVICE_REQUIRE_VELOCITY 

The application requires velocity updates.

Definition at line 56 of file service.h.

Location service status.

Enumerator
UA_LOCATION_SERVICE_ENABLED 

The service is enabled.

UA_LOCATION_SERVICE_DISABLED 

The service is disabled.

UA_LOCATION_SERVICE_GPS_ENABLED 

GPS providers are enabled.

UA_LOCATION_SERVICE_GPS_DISABLED 

GPS providers are disabled.

Definition at line 34 of file controller.h.

Function Documentation

UBUNTU_DLL_PUBLIC double ua_location_heading_update_get_heading_in_degree ( UALocationHeadingUpdate update)

Queries the new heading from the update.

Returns
The new heading from the update in [°].
Parameters
[in]updateThe heading update instance to be queried.
UBUNTU_DLL_PUBLIC uint64_t ua_location_heading_update_get_timestamp ( UALocationHeadingUpdate update)

Queries the timestamp of the heading update.

Returns
The timestamp of the heading update in [µs].
Parameters
[in]updateThe heading update instance to be queried.
UBUNTU_DLL_PUBLIC void ua_location_heading_update_ref ( UALocationHeadingUpdate update)

Increments the reference count of the heading update instance.

Parameters
[in]updateThe heading update instance to increment the reference count for.
UBUNTU_DLL_PUBLIC void ua_location_heading_update_unref ( UALocationHeadingUpdate update)

Decrements the reference count of the heading update instance.

Parameters
[in]updateThe heading update instance to decrement the reference count for.
UBUNTU_DLL_PUBLIC double ua_location_position_update_get_altitude_in_meter ( UALocationPositionUpdate update)

Queries the altitude contained in the position update.

Returns
The altitude of the position update in [m].
Parameters
[in]updateThe position update instance to be queried.
UBUNTU_DLL_PUBLIC double ua_location_position_update_get_latitude_in_degree ( UALocationPositionUpdate update)

Queries the latitude contained in the position update.

Returns
The latitude of the position update in [°].
Parameters
[in]updateThe position update instance to be queried.
UBUNTU_DLL_PUBLIC double ua_location_position_update_get_longitude_in_degree ( UALocationPositionUpdate update)

Queries the longitude contained in the position update.

Returns
The longitude of the position update in [°].
Parameters
[in]updateThe position update instance to be queried.
UBUNTU_DLL_PUBLIC uint64_t ua_location_position_update_get_timestamp ( UALocationPositionUpdate update)

Queries the timestamp of the position update.

Returns
The timestamp of the position update in [µs].
Parameters
[in]updateThe position update instance to be queried.
UBUNTU_DLL_PUBLIC bool ua_location_position_update_has_altitude ( UALocationPositionUpdate update)

Checks if the position update contains an altitude.

Returns
TRUE if the update contains an altitude, else FALSE.
Parameters
[in]updateThe position update instance to be queried.
UBUNTU_DLL_PUBLIC void ua_location_position_update_ref ( UALocationPositionUpdate update)

Increments the reference count of the position update instance.

Parameters
[in]updateThe position update instance to increment the reference count for.
UBUNTU_DLL_PUBLIC void ua_location_position_update_unref ( UALocationPositionUpdate update)

Decrements the reference count of the position update instance.

Parameters
[in]updateThe position update instance to decrement the reference count for.
UBUNTU_DLL_PUBLIC UStatus ua_location_service_controller_disable_gps ( UALocationServiceController controller)

Disables all gps providers known to the location service.

Parameters
[in]controllerThe controller instance.
UBUNTU_DLL_PUBLIC UStatus ua_location_service_controller_disable_service ( UALocationServiceController controller)

Disables the location service completely.

Parameters
[in]controllerThe controller instance.
UBUNTU_DLL_PUBLIC UStatus ua_location_service_controller_enable_gps ( UALocationServiceController controller)

Enables all gps providers known to the location service.

Parameters
[in]controllerThe controller instance.
UBUNTU_DLL_PUBLIC UStatus ua_location_service_controller_enable_service ( UALocationServiceController controller)

Enables the location service.

Parameters
[in]controllerThe controller instance.
UBUNTU_DLL_PUBLIC UStatus ua_location_service_controller_query_status ( UALocationServiceController controller,
UALocationServiceStatusFlags out_flags 
)

Query the status of the location service.

Parameters
[in]controllerThe controller instance.
[out]flagsFlags indicating the service status.
UBUNTU_DLL_PUBLIC void ua_location_service_controller_ref ( UALocationServiceController controller)

Increments the reference count of the controller instance.

Parameters
[in]controllerThe controller instance to increment the reference count for.
UBUNTU_DLL_PUBLIC void ua_location_service_controller_set_status_changed_handler ( UALocationServiceController controller,
UALocationServiceStatusChangedHandler  handler,
void *  context 
)

Sets the status changed handler of the controller instance.

Parameters
[in]controllerThe controller instance.
[in]handlerThe status changed handler to invoke.
[in]contextThe context pointer to pass in the status changed handler
UBUNTU_DLL_PUBLIC void ua_location_service_controller_unref ( UALocationServiceController controller)

Decrements the reference count of the controller instance.

Parameters
[in]controllerThe controller instance to decrement the reference count for.
UBUNTU_DLL_PUBLIC UALocationServiceController* ua_location_service_create_controller ( )

Creates a new controller for the location service.

Returns
A controller or NULL if the calling process does not have sufficient privileges.
UBUNTU_DLL_PUBLIC UALocationServiceSession* ua_location_service_create_session_for_high_accuracy ( UALocationServiceRequirementsFlags  flags)

Creates a new session with the location service for high positional accuracy requirements.

Returns
A new session or NULL if the requirements cannot be satisfied or if the app lacks permissions to access the location service.
Parameters
[in]Bitfielddescribing the application's requirements.
UBUNTU_DLL_PUBLIC UALocationServiceSession* ua_location_service_create_session_for_low_accuracy ( UALocationServiceRequirementsFlags  flags)

Creates a new session with the location service for low positional accuracy requirements.

Returns
A new session or NULL if the requirements cannot be satisfied or if the app lacks permissions to access the location service.
Parameters
[in]Bitfielddescribing the application's requirements.
UBUNTU_DLL_PUBLIC void ua_location_service_session_ref ( UALocationServiceSession session)

Increments the reference count of the session instance.

Parameters
[in]sessionThe session instance to increment the reference count for.
UBUNTU_DLL_PUBLIC void ua_location_service_session_set_heading_updates_handler ( UALocationServiceSession session,
UALocationServiceSessionHeadingUpdatesHandler  handler,
void *  context 
)

Installs an app-specific heading update handler for the session.

Parameters
[in]sessionThe session instance to install the handler for.
[in]handlerThe heading update handler.
UBUNTU_DLL_PUBLIC void ua_location_service_session_set_position_updates_handler ( UALocationServiceSession session,
UALocationServiceSessionPositionUpdatesHandler  handler,
void *  context 
)

Installs an app-specific position update handler for the session.

Parameters
[in]sessionThe session instance to install the handler for.
[in]handlerThe position update handler.
UBUNTU_DLL_PUBLIC void ua_location_service_session_set_velocity_updates_handler ( UALocationServiceSession session,
UALocationServiceSessionVelocityUpdatesHandler  handler,
void *  context 
)

Installs an app-specific velocity update handler for the session.

Parameters
[in]sessionThe session instance to install the handler for.
[in]handlerThe velocity update handler.
UBUNTU_DLL_PUBLIC UStatus ua_location_service_session_start_heading_updates ( UALocationServiceSession session)

Starts heading updates for the supplied session.

Returns
U_STATUS_SUCCESS if the updates were successfully started on the service side, else U_STATUS_ERROR.
Parameters
[in]sessionThe session instance to start heading updates for.
UBUNTU_DLL_PUBLIC UStatus ua_location_service_session_start_position_updates ( UALocationServiceSession session)

Starts position updates for the supplied session.

Returns
U_STATUS_SUCCESS if the updates were successfully started on the service side, else U_STATUS_ERROR.
Parameters
[in]sessionThe session instance to start position updates for.
UBUNTU_DLL_PUBLIC UStatus ua_location_service_session_start_velocity_updates ( UALocationServiceSession session)

Starts velocity updates for the supplied session.

Returns
U_STATUS_SUCCESS if the updates were successfully started on the service side, else U_STATUS_ERROR.
Parameters
[in]sessionThe session instance to start velocity updates for.
UBUNTU_DLL_PUBLIC void ua_location_service_session_stop_heading_updates ( UALocationServiceSession session)

Stops heading updates for the supplied session.

Parameters
[in]sessionThe session instance to stop heading updates for.
UBUNTU_DLL_PUBLIC void ua_location_service_session_stop_position_updates ( UALocationServiceSession session)

Stops position updates for the supplied session.

Parameters
[in]sessionThe session instance to stop position updates for.
UBUNTU_DLL_PUBLIC void ua_location_service_session_stop_velocity_updates ( UALocationServiceSession session)

Stops velocity updates for the supplied session.

Parameters
[in]sessionThe session instance to stop velocity updates for.
UBUNTU_DLL_PUBLIC void ua_location_service_session_unref ( UALocationServiceSession session)

Decrements the reference count of the session instance.

Parameters
[in]sessionThe session instance to decrement the reference count for.
UBUNTU_DLL_PUBLIC uint64_t ua_location_velocity_update_get_timestamp ( UALocationVelocityUpdate update)

Queries the timestamp of the velocity update.

Returns
The timestamp of the position update in [µs].
Parameters
[in]updateThe velocity update instance to be queried.
UBUNTU_DLL_PUBLIC double ua_location_velocity_update_get_velocity_in_meters_per_second ( UALocationVelocityUpdate update)

Queries the velocity contained in the position update.

Returns
The velocity in the position update in [m/s].
Parameters
[in]updateThe velocity update instance to be queried.
UBUNTU_DLL_PUBLIC void ua_location_velocity_update_ref ( UALocationVelocityUpdate update)

Increments the reference count of the velocity update instance.

Parameters
[in]updateThe velocity update instance to increment the reference count for.
UBUNTU_DLL_PUBLIC void ua_location_velocity_update_unref ( UALocationVelocityUpdate update)

Decrements the reference count of the velocity update instance.

Parameters
[in]updateThe velocity update instance to decrement the reference count for.