|
|
|
cityinfo Reference Manual | |
|---|---|---|---|---|
#include <cityinfo.h> #define CITYINFO_WRONG_ID #define CITYINFO_WRONG_POS #define CITYINFO_WRONG_LAT_LNG Cityinfo; gboolean (*CityinfoFunc) (const Cityinfo *city, gpointer data); gchar* cityinfo_get_name (const Cityinfo *city); gchar* cityinfo_get_code (const Cityinfo *city); gchar* cityinfo_get_country (const Cityinfo *city); gchar* cityinfo_get_zone (const Cityinfo *city); gchar* cityinfo_get_locale (const Cityinfo *city); gdouble cityinfo_get_xpos (const Cityinfo *city); gdouble cityinfo_get_ypos (const Cityinfo *city); gdouble cityinfo_get_lat (const Cityinfo *city); gdouble cityinfo_get_lng (const Cityinfo *city); gint cityinfo_get_id (const Cityinfo *city); Cityinfo* cityinfo_new (void); void cityinfo_free (Cityinfo *city); Cityinfo* cityinfo_clone (const Cityinfo *city); void cityinfo_foreach (CityinfoFunc func, gpointer data); Cityinfo* cityinfo_find_closest (gdouble x, gdouble y); Cityinfo* cityinfo_from_id (gint id); Cityinfo** cityinfo_get_all (void); void cityinfo_free_all (Cityinfo **cities);
Database
You can get informations such as:
city name
country name (in which the city is placed)
country code
time zone
geographical position
position on the map
locale used in country
All informations You get from library are already localized according to currently set language on the system (city and country names).
Example 1. ASCII art diagram of database record/fields:
raw data: "id|city_name|country_code|country_name|linux_timezone|lat|lng|x_position|y_position|locale" example of raw data from file: "0|osso_db_city_abu_dhabi|AE|osso_db_country_united_arab_emirates|Asia/Muscat|0|0|0.623333|0.488400|ar_AE" logic view: +---+-----+-------------+-------------+---------------+----------+-----------+----------------------+----------------------+-----------------------+ |id |city |country code |country name |linux timezone |latitiude |longtidute |X postion on the map |Y postion on the map* |locale used in country | +---+-----+-------------+-------------+---------------+----------+-----------+----------------------+----------------------+-----------------------+
positions on the map are in relative coordinates (0.0 - most left/top to 1.0 most right/bottom) and are synchronized with Clock's world map image.
#define CITYINFO_WRONG_ID -1
Integer indicating wrong ID of the city.
If You get this ID from some Cityinfo structure that means that this
particular structure does not represent any real city - it is useless (the
reason for this might be some errors while reading database, cloning city or
simply because structure is only allocated - returned from cityinfo_new())
#define CITYINFO_WRONG_POS -1.0
Double indicating wrong X/Y position of the city.
If You get x/y postion of the city and You will get smaller value than this it means that there were some problems and the whole source Cityinfo structure is meaningless.
#define CITYINFO_WRONG_LAT_LNG -181.0
Double indicating wrong latitude/longitude value.
If You get lat/lng postion of the city and You will get smaller value than this it means that there were some problems and the whole source Cityinfo structure is meaningless.
typedef struct {
gchar *name;
gchar *code;
gchar *country;
gchar *zone;
gchar *locale;
gdouble lat;
gdouble lng;
gdouble x;
gdouble y;
gint id;
} Cityinfo;
Cityinfo is a structure which represents the city.
gchar *name; |
Name of the city |
gchar *code; |
Country code |
gchar *country; |
Name of the country |
gchar *zone; |
Name of the timezone used in particular city |
gchar *locale; |
Locale used in the given city |
gdouble lat; |
Latitude of the city |
gdouble lng; |
Longitude of the city |
gdouble x; |
X position of the city (on the clock's map) |
gdouble y; |
Y position of the city (on the clock's map) |
gint id; |
ID of the city |
gboolean (*CityinfoFunc) (const Cityinfo *city, gpointer data);
city : |
Currently proccessed city. |
data : |
Pointer to user data. |
| Returns : | TRUE if function cityinfo_foreach() should working further on next
cities in the databse, and FALSE if function should stop executing after this one
Function cityinfo_foreach() use this type to define action which should be
taken on each of the city in database.
|
gchar* cityinfo_get_name (const Cityinfo *city);
city : |
Pointer to Cityinfo structure from which we want to get information. |
| Returns : | Localized name of the given city. |
gchar* cityinfo_get_code (const Cityinfo *city);
city : |
Pointer to Cityinfo structure from which we want to get information. |
| Returns : | Code of the country. |
gchar* cityinfo_get_country (const Cityinfo *city);
city : |
Pointer to Cityinfo structure from which we want to get information. |
| Returns : | Localized name of the country. |
gchar* cityinfo_get_zone (const Cityinfo *city);
city : |
Pointer to Cityinfo structure from which we want to get information. |
| Returns : | Name of the timezone used in particular city. |
gchar* cityinfo_get_locale (const Cityinfo *city);
city : |
Pointer to Cityinfo structure from which we want to get information. |
| Returns : | String describing locale used in the given city. |
gdouble cityinfo_get_xpos (const Cityinfo *city);
city : |
Pointer to Cityinfo structure from which we want to get information. |
| Returns : | X Position of the city (on the clock's map). |
gdouble cityinfo_get_ypos (const Cityinfo *city);
city : |
Pointer to Cityinfo structure from which we want to get information. |
| Returns : | Y Position of the city (on the clock's map). |
gdouble cityinfo_get_lat (const Cityinfo *city);
city : |
Pointer to Cityinfo structure from which we want to get information. |
| Returns : | latitude of the city. |
gdouble cityinfo_get_lng (const Cityinfo *city);
city : |
Pointer to Cityinfo structure from which we want to get information. |
| Returns : | longitude of the city. |
gint cityinfo_get_id (const Cityinfo *city);
city : |
Pointer to Cityinfo structure from which we want to get information. |
| Returns : | ID of the given city. |
Cityinfo* cityinfo_new (void);
Allocate a new empty Cityinfo structure.
| Returns : | A newly allocated Cityinfo or NULL if could not allocate memory. Free with cityinfo_free when no longer needed. |
void cityinfo_free (Cityinfo *city);
city : |
The Cityinfo structure to be freed. Free an allocated Cityinfo structure. |
Cityinfo* cityinfo_clone (const Cityinfo *city);
city : |
The source Cityinfo. Duplicate a Cityinfo structure. The newly created structure can be handled indepenently from the old one. |
| Returns : | A newly allocated Cityinfo with the same contents as old. NULL on any error. |
void cityinfo_foreach (CityinfoFunc func, gpointer data);
Runs a function against every entry of the database. The iteration will end if func returns FALSE.
func : |
The user defined callback function CityinfoFunc |
data : |
Misc data to the function |
Cityinfo* cityinfo_find_closest (gdouble x, gdouble y);
Finds the nearest city to given coordinates on the map.
x : |
Searched x coordinate (0.0 - 1.0) |
y : |
Searched y coordinate (0.0 - 1.0) |
| Returns : | The closest city to x, y position on the map. |
Cityinfo* cityinfo_from_id (gint id);
Get the whole Cityinfo structure from its ID number.
id : |
ID of the city You want to get informations about. |
| Returns : | Newly allocated Cityinfo about the city, or NULL if no match or error |
Cityinfo** cityinfo_get_all (void);
| Returns : | An array of pointers to Cityinfo structures describing every city available on the platform. The last element of the array is NULL. |
void cityinfo_free_all (Cityinfo **cities);
Free all cities array returned from cityinfo_get_all() function.
cities : |
cities An array of pointers to cities. |