GeocodeLocation

GeocodeLocation — Geocode location object

Synopsis

#include <geocode-glib/geocode-glib.h>

struct              GeocodeLocation;
struct              GeocodeLocationClass;
enum                GeocodeLocationURIScheme;
enum                GeocodeLocationCRS;
#define             GEOCODE_LOCATION_ALTITUDE_UNKNOWN
#define             GEOCODE_LOCATION_ACCURACY_UNKNOWN
#define             GEOCODE_LOCATION_ACCURACY_STREET
#define             GEOCODE_LOCATION_ACCURACY_CITY
#define             GEOCODE_LOCATION_ACCURACY_REGION
#define             GEOCODE_LOCATION_ACCURACY_COUNTRY
#define             GEOCODE_LOCATION_ACCURACY_CONTINENT
GeocodeLocation *   geocode_location_new                (gdouble latitude,
                                                         gdouble longitude,
                                                         gdouble accuracy);
GeocodeLocation *   geocode_location_new_with_description
                                                        (gdouble latitude,
                                                         gdouble longitude,
                                                         gdouble accuracy,
                                                         const char *description);
gboolean            geocode_location_equal              (GeocodeLocation *a,
                                                         GeocodeLocation *b);
gboolean            geocode_location_set_from_uri       (GeocodeLocation *loc,
                                                         const char *uri,
                                                         GError **error);
char *              geocode_location_to_uri             (GeocodeLocation *loc,
                                                         GeocodeLocationURIScheme scheme);
double              geocode_location_get_distance_from  (GeocodeLocation *loca,
                                                         GeocodeLocation *locb);
void                geocode_location_set_description    (GeocodeLocation *loc,
                                                         const char *description);
const char *        geocode_location_get_description    (GeocodeLocation *loc);
gdouble             geocode_location_get_latitude       (GeocodeLocation *loc);
gdouble             geocode_location_get_longitude      (GeocodeLocation *loc);
gdouble             geocode_location_get_altitude       (GeocodeLocation *loc);
GeocodeLocationCRS  geocode_location_get_crs            (GeocodeLocation *loc);
gdouble             geocode_location_get_accuracy       (GeocodeLocation *loc);
guint64             geocode_location_get_timestamp      (GeocodeLocation *loc);

Object Hierarchy

  GObject
   +----GeocodeLocation

Properties

  "accuracy"                 gdouble               : Read / Write
  "altitude"                 gdouble               : Read / Write
  "crs"                      GeocodeLocationCRS    : Read / Write / Construct Only
  "description"              gchar*                : Read / Write
  "latitude"                 gdouble               : Read / Write
  "longitude"                gdouble               : Read / Write
  "timestamp"                guint64               : Read / Write / Construct Only

Description

The GeocodeLocation instance represents a location on earth, with an optional description.

Details

struct GeocodeLocation

struct GeocodeLocation;

All the fields in the GeocodeLocation structure are private and should never be accessed directly.


struct GeocodeLocationClass

struct GeocodeLocationClass {
};

All the fields in the GeocodeLocationClass structure are private and should never be accessed directly.


enum GeocodeLocationURIScheme

typedef enum {
	GEOCODE_LOCATION_URI_SCHEME_GEO = 0
} GeocodeLocationURIScheme;

The URI scheme for this location.

GEOCODE_LOCATION_URI_SCHEME_GEO

The 'geo' URI scheme, RFC 5870

enum GeocodeLocationCRS

typedef enum {
	GEOCODE_LOCATION_CRS_WGS84 = 0
} GeocodeLocationCRS;

Coordinate Reference System Identification for a location.

GEOCODE_LOCATION_CRS_WGS84

CRS is World Geodetic System, standard for Earth.

GEOCODE_LOCATION_ALTITUDE_UNKNOWN

#define GEOCODE_LOCATION_ALTITUDE_UNKNOWN -G_MAXDOUBLE

Constant representing unknown altitude.


GEOCODE_LOCATION_ACCURACY_UNKNOWN

#define GEOCODE_LOCATION_ACCURACY_UNKNOWN -1

Constant representing unknown accuracy.


GEOCODE_LOCATION_ACCURACY_STREET

#define GEOCODE_LOCATION_ACCURACY_STREET 1000 /* 1 km */

Constant representing street-level accuracy.


GEOCODE_LOCATION_ACCURACY_CITY

#define GEOCODE_LOCATION_ACCURACY_CITY 15000 /* 15 km */

Constant representing city-level accuracy.


GEOCODE_LOCATION_ACCURACY_REGION

#define GEOCODE_LOCATION_ACCURACY_REGION 50000 /* 50 km */

Constant representing region-level accuracy.


GEOCODE_LOCATION_ACCURACY_COUNTRY

#define GEOCODE_LOCATION_ACCURACY_COUNTRY 300000 /* 300 km */

Constant representing country-level accuracy.


GEOCODE_LOCATION_ACCURACY_CONTINENT

#define GEOCODE_LOCATION_ACCURACY_CONTINENT 3000000 /* 3000 km */

Constant representing continent-level accuracy.


geocode_location_new ()

GeocodeLocation *   geocode_location_new                (gdouble latitude,
                                                         gdouble longitude,
                                                         gdouble accuracy);

Creates a new GeocodeLocation object.

latitude :

a valid latitude

longitude :

a valid longitude

accuracy :

accuracy of location in meters

Returns :

a new GeocodeLocation object. Use g_object_unref() when done.

geocode_location_new_with_description ()

GeocodeLocation *   geocode_location_new_with_description
                                                        (gdouble latitude,
                                                         gdouble longitude,
                                                         gdouble accuracy,
                                                         const char *description);

Creates a new GeocodeLocation object.

latitude :

a valid latitude

longitude :

a valid longitude

accuracy :

accuracy of location in meters

description :

a description for the location

Returns :

a new GeocodeLocation object. Use g_object_unref() when done.

geocode_location_equal ()

gboolean            geocode_location_equal              (GeocodeLocation *a,
                                                         GeocodeLocation *b);

Compare two GeocodeLocation instances for equality. This compares all fields and only returns TRUE if the instances are exactly equal. For example, if both locations have the same physical coordinates, but one location has its "description" property set and the other does not, FALSE will be returned. Similarly, if both locations have the same "latitude", "longitude" and "altitude", but a different "accuracy" or "timestamp", FALSE will be returned. Or if both locations have the same"latitude" and "longitude" but a different "altitude", FALSE will be returned.

Both instances must be non-NULL.

a :

a location

b :

another location

Returns :

TRUE if the instances are equal, FALSE otherwise

Since 3.23.1


geocode_location_set_from_uri ()

gboolean            geocode_location_set_from_uri       (GeocodeLocation *loc,
                                                         const char *uri,
                                                         GError **error);

Initialize a GeocodeLocation object with the given uri.

The URI should be in the geo scheme (RFC 5870) which in its simplest form looks like:

  • geo:latitude,longitude

An Android extension to set a description is also supported in the form of:

  • geo:0,0?q=latitude,longitude(description)

loc :

a GeocodeLocation

uri :

a URI mapping out a location

error :

GError for error reporting, or NULL to ignore

Returns :

TRUE on success and FALSE on error.

geocode_location_to_uri ()

char *              geocode_location_to_uri             (GeocodeLocation *loc,
                                                         GeocodeLocationURIScheme scheme);

Creates a URI representing loc in the scheme specified in scheme.

loc :

a GeocodeLocation

scheme :

the scheme of the requested URI

Returns :

a URI representing the location. The returned string should be freed with g_free() when no longer needed.

geocode_location_get_distance_from ()

double              geocode_location_get_distance_from  (GeocodeLocation *loca,
                                                         GeocodeLocation *locb);

Calculates the distance in km, along the curvature of the Earth, between 2 locations. Note that altitude changes are not taken into account.

loca :

a GeocodeLocation

locb :

a GeocodeLocation

Returns :

a distance in km.

geocode_location_set_description ()

void                geocode_location_set_description    (GeocodeLocation *loc,
                                                         const char *description);

Sets the description of loc to description.

loc :

a GeocodeLocation

description :

a description for the location

geocode_location_get_description ()

const char *        geocode_location_get_description    (GeocodeLocation *loc);

Gets the description of location loc.

loc :

a GeocodeLocation

Returns :

The description of location loc.

geocode_location_get_latitude ()

gdouble             geocode_location_get_latitude       (GeocodeLocation *loc);

Gets the latitude of location loc.

loc :

a GeocodeLocation

Returns :

The latitude of location loc.

geocode_location_get_longitude ()

gdouble             geocode_location_get_longitude      (GeocodeLocation *loc);

Gets the longitude of location loc.

loc :

a GeocodeLocation

Returns :

The longitude of location loc.

geocode_location_get_altitude ()

gdouble             geocode_location_get_altitude       (GeocodeLocation *loc);

Gets the altitude of location loc.

loc :

a GeocodeLocation

Returns :

The altitude of location loc.

geocode_location_get_crs ()

GeocodeLocationCRS  geocode_location_get_crs            (GeocodeLocation *loc);

Gets the Coordinate Reference System Identification of location loc.

loc :

a GeocodeLocation

Returns :

The CRS of location loc.

geocode_location_get_accuracy ()

gdouble             geocode_location_get_accuracy       (GeocodeLocation *loc);

Gets the accuracy (in meters) of location loc.

loc :

a GeocodeLocation

Returns :

The accuracy of location loc.

geocode_location_get_timestamp ()

guint64             geocode_location_get_timestamp      (GeocodeLocation *loc);

Gets the timestamp (in seconds since the Epoch) of location loc. See "timestamp".

loc :

a GeocodeLocation

Returns :

The timestamp of location loc.

Property Details

The "accuracy" property

  "accuracy"                 gdouble               : Read / Write

The accuracy of this location in meters.

Allowed values: >= -1

Default value: -1


The "altitude" property

  "altitude"                 gdouble               : Read / Write

The altitude of this location in meters.

Default value: -1.79769e+308


The "crs" property

  "crs"                      GeocodeLocationCRS    : Read / Write / Construct Only

The Coordinate Reference System Identification of this location. Only the value 'wgs84' is currently valid.

Default value: GEOCODE_LOCATION_CRS_WGS84


The "description" property

  "description"              gchar*                : Read / Write

The description of this location.

Default value: NULL


The "latitude" property

  "latitude"                 gdouble               : Read / Write

The latitude of this location in degrees.

Allowed values: [-90,90]

Default value: 0


The "longitude" property

  "longitude"                gdouble               : Read / Write

The longitude of this location in degrees.

Allowed values: [-180,180]

Default value: 0


The "timestamp" property

  "timestamp"                guint64               : Read / Write / Construct Only

A timestamp in seconds since Epoch, giving when the location was resolved from an address.

A value of 0 (zero) will be interpreted as the current time.

Allowed values: <= G_MAXLONG64

Default value: 0