![]() |
![]() |
![]() |
libgweather-3.0 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
#include <libgweather/gweather.h> GWeatherLocation; enum GWeatherLocationLevel; GWeatherLocation * gweather_location_new_world (gboolean use_regions
); GWeatherLocation * gweather_location_ref (GWeatherLocation *loc
); void gweather_location_unref (GWeatherLocation *loc
); GVariant * gweather_location_serialize (GWeatherLocation *loc
); GWeatherLocation * gweather_location_deserialize (GWeatherLocation *world
,GVariant *serialized
); gboolean gweather_location_equal (GWeatherLocation *one
,GWeatherLocation *two
); GWeatherLocation * gweather_location_find_by_station_code (GWeatherLocation *world
,const gchar *station_code
); GWeatherLocationLevel gweather_location_get_level (GWeatherLocation *loc
); GWeatherLocation * gweather_location_get_parent (GWeatherLocation *loc
); GWeatherLocation ** gweather_location_get_children (GWeatherLocation *loc
); GWeatherLocation * gweather_location_ref_world (GWeatherLocation *loc
); const char * gweather_location_get_name (GWeatherLocation *loc
); const char * gweather_location_get_sort_name (GWeatherLocation *loc
); gboolean gweather_location_has_coords (GWeatherLocation *loc
); void gweather_location_get_coords (GWeatherLocation *loc
,double *latitude
,double *longitude
); double gweather_location_get_distance (GWeatherLocation *loc
,GWeatherLocation *loc2
); const char * gweather_location_get_country (GWeatherLocation *loc
); GWeatherTimezone * gweather_location_get_timezone (GWeatherLocation *loc
); GWeatherTimezone ** gweather_location_get_timezones (GWeatherLocation *loc
); const char * gweather_location_get_code (GWeatherLocation *loc
); char * gweather_location_get_city_name (GWeatherLocation *loc
);
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_new_world()
will never
create detached instances, but deserializing might.
A location representing the entire world. | |
A location representing a continent or other top-level region. | |
A location representing a "country" (or other geographic unit that has an ISO-3166 country code) | |
A location representing a "first-level administrative division"; ie, a state, province, or similar division. | |
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.
|
|
A location representing a city | |
A location representing a weather station. | |
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. |
GWeatherLocation * gweather_location_new_world (gboolean use_regions
);
Creates a new GWeatherLocation of type GWEATHER_LOCATION_WORLD
,
representing a hierarchy containing all of the locations from
Locations.xml.
If use_regions
is TRUE
, the immediate children of the returned
location will be GWEATHER_LOCATION_REGION
nodes, representing the
top-level "regions" of Locations.xml (the continents and a few
other divisions), and the country-level nodes will be the children
of the regions. If use_regions
is FALSE
, the regions will be
skipped, and the children of the returned location will be the
GWEATHER_LOCATION_COUNTRY
nodes.
|
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]
|
GWeatherLocation * gweather_location_ref (GWeatherLocation *loc
);
Adds 1 to loc
's reference count.
|
a GWeatherLocation |
Returns : |
loc |
void gweather_location_unref (GWeatherLocation *loc
);
Subtracts 1 from loc
's reference count, and frees it if the
reference count reaches 0.
|
a GWeatherLocation |
GVariant * gweather_location_serialize (GWeatherLocation *loc
);
|
a GWeatherLocation |
Returns : |
. [transfer none] |
GWeatherLocation * gweather_location_deserialize (GWeatherLocation *world
,GVariant *serialized
);
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.
|
a GWeatherLocation |
|
another GWeatherLocation |
Returns : |
TRUE if the two locations represent the same place as
far as libgweather can tell, and FALSE otherwise. |
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.
|
a GWeatherLocation at the world level |
|
a 4 letter METAR code |
Returns : |
a weather station level GWeatherLocation for station_code ,
or NULL if none exists in the database. |
GWeatherLocationLevel gweather_location_get_level (GWeatherLocation *loc
);
Gets loc
's level, from GWEATHER_LOCATION_WORLD
, to
GWEATHER_LOCATION_WEATHER_STATION
.
|
a GWeatherLocation |
Returns : |
loc 's level |
GWeatherLocation * gweather_location_get_parent (GWeatherLocation *loc
);
Gets loc
's parent location.
|
a GWeatherLocation |
Returns : |
loc 's parent, or NULL
if loc is a GWEATHER_LOCATION_WORLD node. [transfer none][allow-none]
|
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.
|
a GWeatherLocation |
Returns : |
loc 's
children. (May be empty, but will not be NULL .). [transfer none][array zero-terminated=1]
|
GWeatherLocation * gweather_location_ref_world (GWeatherLocation *loc
);
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?)
|
a GWeatherLocation |
Returns : |
loc 's 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.
|
a GWeatherLocation |
Returns : |
loc 's sort name |
gboolean gweather_location_has_coords (GWeatherLocation *loc
);
Checks if loc
has valid latitude and longitude.
|
a GWeatherLocation |
Returns : |
TRUE if loc has valid latitude and longitude. |
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.
|
a GWeatherLocation |
|
on return will contain loc 's latitude. [out]
|
|
on return will contain loc 's longitude. [out]
|
double gweather_location_get_distance (GWeatherLocation *loc
,GWeatherLocation *loc2
);
Determines the distance in kilometers between loc
and loc2
.
|
a GWeatherLocation |
|
a second GWeatherLocation |
Returns : |
the distance between loc and loc2 . |
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)
|
a GWeatherLocation |
Returns : |
loc 's country code (or NULL if loc
is a region- or world-level location). [allow-none]
|
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.
|
a GWeatherLocation |
Returns : |
loc 's timezone, or
NULL . [transfer none][allow-none]
|
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.
|
a GWeatherLocation |
Returns : |
an array
of timezones. May be empty but will not be NULL . [transfer full][array zero-terminated=1]
|
const char * gweather_location_get_code (GWeatherLocation *loc
);
Gets the METAR station code associated with a
GWEATHER_LOCATION_WEATHER_STATION
location.
|
a GWeatherLocation |
Returns : |
loc 's METAR station code, or NULL . [allow-none]
|
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
.
|
a GWeatherLocation |
Returns : |
(allow-none) loc 's city name, or NULL
|