GWeatherLocation: libgweather Reference Manual

## GWeatherLocation GWeatherLocation |

## Functions

GWeatherLocation * | gweather_location_get_world ()
GWeatherLocation * | gweather_location_new_world ()
GWeatherLocation * | gweather_location_new_detached ()
GWeatherLocation * | gweather_location_ref ()
void | gweather_location_unref ()
GVariant * | gweather_location_serialize ()
GWeatherLocation * | gweather_location_deserialize ()
gboolean | gweather_location_equal ()
GWeatherLocation * | gweather_location_find_by_station_code ()
GWeatherLocation * | gweather_location_find_nearest_city ()
gboolean | (*GWeatherFilterFunc) ()
GWeatherLocation * | gweather_location_find_nearest_city_full ()
void | gweather_location_detect_nearest_city ()
GWeatherLocation * | gweather_location_detect_nearest_city_finish ()
GWeatherLocationLevel | gweather_location_get_level ()
GWeatherLocation * | gweather_location_get_parent ()
GWeatherLocation ** | gweather_location_get_children ()
const char * | gweather_location_get_name ()
const char * | gweather_location_get_sort_name ()
gboolean | gweather_location_has_coords ()
void | gweather_location_get_coords ()
double | gweather_location_get_distance ()
const char * | gweather_location_get_country ()
GWeatherTimezone * | gweather_location_get_timezone ()
GWeatherTimezone ** | gweather_location_get_timezones ()
const char * | gweather_location_get_code ()
char * | gweather_location_get_city_name ()
char * | gweather_location_get_country_name ()

## Types and Values

| GWeatherLocation
enum | GWeatherLocationLevel

## 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_world ()

    GWeatherLocation *
    gweather_location_new_world (gboolean use_regions);

`gweather_location_new_world` has been deprecated since version 3.10 and should not be used in newly-written code.

Use `gweather_location_get_world()` instead.

Creates a new GWeatherLocation of type `GWEATHER_LOCATION_WORLD`, representing a hierarchy containing all of the locations from Locations.xml.

#### Parameters

use_regions | whether or not to divide the world into regions |

#### Returns

a `GWEATHER_LOCATION_WORLD` location, or `NULL` if Locations.xml could not be found or could not be parsed.

[allow-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.

### 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` |

#### Returns

void

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. |