GWeatherLocation

typedef struct _GWeatherLocation GWeatherLocation;

enum GWeatherLocationLevel

typedef enum {
 /*< underscore_name=gweather_location_level >*/
    GWEATHER_LOCATION_WORLD,
    GWEATHER_LOCATION_REGION,
    GWEATHER_LOCATION_COUNTRY,
    /* ADM1 = first-order administrative division = state/province, etc */
    GWEATHER_LOCATION_ADM1,
    /* ADM2 = second-order division = county, etc */
    GWEATHER_LOCATION_ADM2,
    GWEATHER_LOCATION_CITY,
    GWEATHER_LOCATION_WEATHER_STATION,
    GWEATHER_LOCATION_DETACHED
} 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.

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.

gweather_location_ref ()

GWeatherLocation *  gweather_location_ref               (GWeatherLocation *loc);

Adds 1 to loc's reference count.

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.

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.

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

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.

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.

gweather_location_get_level ()

GWeatherLocationLevel gweather_location_get_level       (GWeatherLocation *loc);

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

gweather_location_get_parent ()

GWeatherLocation *  gweather_location_get_parent        (GWeatherLocation *loc);

Gets loc's parent location.

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.

gweather_location_get_name ()

const char *        gweather_location_get_name          (GWeatherLocation *loc);

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

Note that GWEATHER_LOCATION_WEATHER_STATION nodes are not localized, and so the name returned for those nodes will always be in English, and should therefore not be displayed to the user. (FIXME: should we just not return a 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.

gweather_location_has_coords ()

gboolean            gweather_location_has_coords        (GWeatherLocation *loc);

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

gweather_location_get_distance ()

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

Determines the distance in kilometers 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)

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.

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.

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.

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.