GWeatherLocation

GWeatherLocation

Functions

Types and Values

Object Hierarchy

    GBoxed
    ╰── GWeatherLocation

Includes

#include <libgweather/gweather.h>

Description

A GWeatherLocation represents a "location" of some type known to libgweather; anything from a single weather station to the entire world. See GWeatherLocationLevel for information about how the hierarchy of locations works.

Functions

gweather_location_get_world ()

GWeatherLocation *
gweather_location_get_world (void);

Obtains the shared GWeatherLocation of type GWEATHER_LOCATION_WORLD, representing a hierarchy containing all of the locations from Locations.xml.

Returns

a GWEATHER_LOCATION_WORLD location, or NULL if Locations.xml could not be found or could not be parsed. The return value is owned by libgweather and should not be modified or freed.

[allow-none][transfer none]


gweather_location_new_detached ()

GWeatherLocation *
gweather_location_new_detached (const char *name,
                                const char *icao,
                                gdouble latitude,
                                gdouble longitude);

Construct a new location from the given data, supplementing any missing information from the static database.

Parameters

name

the user visible location name

 

icao

the ICAO code of the location.

[nullable]

latitude

the latitude of the location

 

longitude

the longitude of the location

 

gweather_location_ref ()

GWeatherLocation *
gweather_location_ref (GWeatherLocation *loc);

Adds 1 to loc 's reference count.

Parameters

loc

a GWeatherLocation

 

Returns

loc


gweather_location_unref ()

void
gweather_location_unref (GWeatherLocation *loc);

Subtracts 1 from loc 's reference count, and frees it if the reference count reaches 0.

Parameters

loc

a GWeatherLocation

 

gweather_location_serialize ()

GVariant *
gweather_location_serialize (GWeatherLocation *loc);

Transforms a GWeatherLocation into a GVariant, in a way that calling gweather_location_deserialize() will hold an equivalent GWeatherLocation. The resulting variant can then be stored into GSettings or on disk. This call is only valid for cities, weather stations and detached locations. The format of the resulting GVariant is private to libgweather, and it is subject to change. You should use the "v" format in GSettings, to ensure maximum compatibility with future versions of the library.

Parameters

loc

a city, weather station or detached GWeatherLocation

 

Returns

the serialization of location .

[transfer none]


gweather_location_deserialize ()

GWeatherLocation *
gweather_location_deserialize (GWeatherLocation *world,
                               GVariant *serialized);

This call undoes the effect of gweather_location_serialize(), that is, it turns a GVariant into a GWeatherLocation. The conversion happens in the context of world (i.e, for a city or weather station, the resulting location will be attached to a administrative division, country and region as appropriate).

Parameters

world

a world-level GWeatherLocation

 

serialized

the GVariant representing the GWeatherLocation

 

Returns

the deserialized location.

[transfer full]


gweather_location_equal ()

gboolean
gweather_location_equal (GWeatherLocation *one,
                         GWeatherLocation *two);

Compares two GWeatherLocation and sees if they represent the same place. It is only legal to call this for cities, weather stations or detached locations. Note that this function only checks for geographical characteristics, such as coordinates and METAR code. It is still possible that the two locations belong to different worlds (in which case care must be taken when passing them GWeatherLocationEntry and GWeatherInfo), or if one is them is detached it could have a custom name.

Parameters

one

a GWeatherLocation

 

two

another GWeatherLocation

 

Returns

TRUE if the two locations represent the same place as far as libgweather can tell, and FALSE otherwise.


gweather_location_find_by_station_code ()

GWeatherLocation *
gweather_location_find_by_station_code
                               (GWeatherLocation *world,
                                const gchar *station_code);

Retrieves the weather station identifier by station_code . Note that multiple instances of the same weather station can exist in the database, and this function will return any of them, so this not usually what you want.

See gweather_location_deserialize() to recover a stored GWeatherLocation.

Parameters

world

a GWeatherLocation at the world level

 

station_code

a 4 letter METAR code

 

Returns

a weather station level GWeatherLocation for station_code , or NULL if none exists in the database.

[transfer none]


gweather_location_find_nearest_city ()

GWeatherLocation *
gweather_location_find_nearest_city (GWeatherLocation *loc,
                                     double lat,
                                     double lon);

Finds the nearest city to the passed latitude and longitude, among the descendants of loc .

loc must be at most a GWEATHER_LOCATION_ADM2 location. This restriction may be lifted in a future version.

Note that this function does not check if (lat , lon ) fall inside loc , or are in the same region and timezone as the return value.

Parameters

loc

The parent location, which will be searched recursively.

[allow-none]

lat

Latitude, in degrees

 

lon

Longitude, in degrees

 

Returns

the city closest to (lat , lon ), in the region or administrative district of loc .

[transfer full]

Since: 3.12


GWeatherFilterFunc ()

gboolean
(*GWeatherFilterFunc) (GWeatherLocation *location,
                       gpointer user_data);

gweather_location_find_nearest_city_full ()

GWeatherLocation *
gweather_location_find_nearest_city_full
                               (GWeatherLocation *loc,
                                double lat,
                                double lon,
                                GWeatherFilterFunc func,
                                gpointer user_data,
                                GDestroyNotify destroy);

Finds the nearest city to the passed latitude and longitude, among the descendants of loc .

Supports the use of own filter function to filter out locations. Geocoding should be done on the application side if needed.

loc must be at most a GWEATHER_LOCATION_ADM2 location. This restriction may be lifted in a future version.

Parameters

loc

The parent location, which will be searched recursively.

[allow-none]

lat

Latitude, in degrees

 

lon

Longitude, in degrees

 

func

returns true to continue check for the location and false to filter the location out.

[scope notified][allow-none]

user_data

for customization

 

destroy

to destroy user_data

 

Returns

the city closest to (lat , lon ), in the region or administrative district of loc with validation of filter function.

[transfer full]

Since: 3.12


gweather_location_detect_nearest_city ()

void
gweather_location_detect_nearest_city (GWeatherLocation *loc,
                                       double lat,
                                       double lon,
                                       GCancellable *cancellable,
                                       GAsyncReadyCallback callback,
                                       gpointer user_data);

Initializes geocode reversing to find place for (lat , lon ) coordinates. Calls the callback function passed by user when the result is ready.

loc must be at most a GWEATHER_LOCATION_ADM2 location. This restriction may be lifted in a future version.

Parameters

loc

The parent location, which will be searched recursively.

[allow-none]

lat

Latitude, in degrees

 

lon

Longitude, in degrees

 

cancellable

optional, NULL to ignore

 

callback

callback function for GAsyncReadyCallback argument for GAsyncResult

 

user_data

user data passed to callback

 

Since: 3.12


gweather_location_detect_nearest_city_finish ()

GWeatherLocation *
gweather_location_detect_nearest_city_finish
                               (GAsyncResult *result,
                                GError **error);

gweather_location_get_level ()

GWeatherLocationLevel
gweather_location_get_level (GWeatherLocation *loc);

Gets loc 's level, from GWEATHER_LOCATION_WORLD, to GWEATHER_LOCATION_WEATHER_STATION.

Parameters

loc

a GWeatherLocation

 

Returns

loc 's level


gweather_location_get_parent ()

GWeatherLocation *
gweather_location_get_parent (GWeatherLocation *loc);

Gets loc 's parent location.

Parameters

loc

a GWeatherLocation

 

Returns

loc 's parent, or NULL if loc is a GWEATHER_LOCATION_WORLD node.

[transfer none][allow-none]


gweather_location_get_children ()

GWeatherLocation **
gweather_location_get_children (GWeatherLocation *loc);

Gets an array of loc 's children; this is owned by loc and will not remain valid if loc is freed.

Parameters

loc

a GWeatherLocation

 

Returns

loc 's children. (May be empty, but will not be NULL.).

[transfer none][array zero-terminated=1]


gweather_location_get_name ()

const char *
gweather_location_get_name (GWeatherLocation *loc);

Gets loc 's name, localized into the current language.

Parameters

loc

a GWeatherLocation

 

Returns

loc 's name


gweather_location_get_sort_name ()

const char *
gweather_location_get_sort_name (GWeatherLocation *loc);

Gets loc 's "sort name", which is the name after having g_utf8_normalize() (with G_NORMALIZE_ALL) and g_utf8_casefold() called on it. You can use this to sort locations, or to comparing user input against a location name.

Parameters

loc

a GWeatherLocation

 

Returns

loc 's sort name


gweather_location_has_coords ()

gboolean
gweather_location_has_coords (GWeatherLocation *loc);

Checks if loc has valid latitude and longitude.

Parameters

loc

a GWeatherLocation

 

Returns

TRUE if loc has valid latitude and longitude.


gweather_location_get_coords ()

void
gweather_location_get_coords (GWeatherLocation *loc,
                              double *latitude,
                              double *longitude);

Gets loc 's coordinates; you must check gweather_location_has_coords() before calling this.

Parameters

loc

a GWeatherLocation

 

latitude

on return will contain loc 's latitude.

[out]

longitude

on return will contain loc 's longitude.

[out]

gweather_location_get_distance ()

double
gweather_location_get_distance (GWeatherLocation *loc,
                                GWeatherLocation *loc2);

Determines the distance in kilometers between loc and loc2 .

Parameters

loc

a GWeatherLocation

 

loc2

a second GWeatherLocation

 

Returns

the distance between loc and loc2 .


gweather_location_get_country ()

const char *
gweather_location_get_country (GWeatherLocation *loc);

Gets the ISO 3166 country code of loc (or NULL if loc is a region- or world-level location)

Parameters

loc

a GWeatherLocation

 

Returns

loc 's country code (or NULL if loc is a region- or world-level location).

[allow-none]


gweather_location_get_timezone ()

GWeatherTimezone *
gweather_location_get_timezone (GWeatherLocation *loc);

Gets the timezone associated with loc , if known.

The timezone is owned either by loc or by one of its parents. FIXME.

Parameters

loc

a GWeatherLocation

 

Returns

loc 's timezone, or NULL.

[transfer none][allow-none]


gweather_location_get_timezones ()

GWeatherTimezone **
gweather_location_get_timezones (GWeatherLocation *loc);

Gets an array of all timezones associated with any location under loc . You can use gweather_location_free_timezones() to free this array.

Parameters

loc

a GWeatherLocation

 

Returns

an array of timezones. May be empty but will not be NULL.

[transfer full][array zero-terminated=1]


gweather_location_get_code ()

const char *
gweather_location_get_code (GWeatherLocation *loc);

Gets the METAR station code associated with a GWEATHER_LOCATION_WEATHER_STATION location.

Parameters

loc

a GWeatherLocation

 

Returns

loc 's METAR station code, or NULL.

[allow-none]


gweather_location_get_city_name ()

char *
gweather_location_get_city_name (GWeatherLocation *loc);

For a GWEATHER_LOCATION_CITY or GWEATHER_LOCATION_DETACHED location, this is equivalent to gweather_location_get_name(). For a GWEATHER_LOCATION_WEATHER_STATION location, it is equivalent to calling gweather_location_get_name() on the location's parent. For other locations it will return NULL.

Parameters

loc

a GWeatherLocation

 

Returns

loc 's city name, or NULL.

[allow-none]


gweather_location_get_country_name ()

char *
gweather_location_get_country_name (GWeatherLocation *loc);

Gets the country name of loc. For a GWEATHER_LOCATION_COUNTRY location, this is equivalent to gweather_location_get_name(). For a GWEATHER_LOCATION_REGION and GWEATHER_LOCATION_WORLD location it will return NULL. For other locations it will find the parent GWEATHER_LOCATION_COUNTRY and return its name.

Parameters

loc

a GWeatherLocation

 

Returns

loc 's country name, or NULL.

[allow-none]

Types and Values

GWeatherLocation

typedef struct _GWeatherLocation GWeatherLocation;

enum GWeatherLocationLevel

The size/scope of a particular GWeatherLocation.

Locations form a hierarchy, with a GWEATHER_LOCATION_WORLD location at the top, divided into regions or countries, and so on. Countries may or may not be divided into "adm1"s, and "adm1"s may or may not be divided into "adm2"s. A city will have at least one, and possibly several, weather stations inside it. Weather stations will never appear outside of cities.

Building a database with gweather_location_get_world() will never create detached instances, but deserializing might.

Members

GWEATHER_LOCATION_WORLD

A location representing the entire world.

 

GWEATHER_LOCATION_REGION

A location representing a continent or other top-level region.

 

GWEATHER_LOCATION_COUNTRY

A location representing a "country" (or other geographic unit that has an ISO-3166 country code)

 

GWEATHER_LOCATION_ADM1

A location representing a "first-level administrative division"; ie, a state, province, or similar division.

 

GWEATHER_LOCATION_ADM2

A location representing a subdivision of a GWEATHER_LOCATION_ADM1 location, or a direct subdivision of a country that is not represented in a GWeatherLocationEntry.

 

GWEATHER_LOCATION_CITY

A location representing a city

 

GWEATHER_LOCATION_WEATHER_STATION

A location representing a weather station.

 

GWEATHER_LOCATION_DETACHED

A location that is detached from the database, for example because it was loaded from external storage and could not be fully recovered. The parent of this location is the nearest weather station.

 

GWEATHER_LOCATION_NAMED_TIMEZONE

A location representing a named or special timezone in the world, such as UTC