src/cityinfo.h File Reference

Cityinfo library header. More...

Go to the source code of this file.

Data Structures
struct	_Cityinfo
	City Information Structure. More...
Defines
#define	CITYINFO_WRONG_ID   -1
	Integer indicating wrong ID of the city.
#define	CITYINFO_WRONG_POS   -1.0
	Double indicating wrong X/Y position of the city.
#define	CITYINFO_WRONG_LAT_LNG   -181.0
	Double indicating wrong latitude/longitude value.
Typedefs
typedef _Cityinfo	Cityinfo
	Typedef for City Information Structure.
typedef gboolean(*)	CityinfoFunc (const Cityinfo *city, gpointer data)
	Definition of action which could be taken on each city. Function cityinfo_foreach() use this type to define action which should be taken on each of the city in database.
Functions
gchar *	cityinfo_get_name (const Cityinfo *city)
	Get city name from the Cityinfo structure.
gchar *	cityinfo_get_code (const Cityinfo *city)
	Get country code from the Cityinfo structure.
gchar *	cityinfo_get_country (const Cityinfo *city)
	Get country name from the Cityinfo structure.
gchar *	cityinfo_get_zone (const Cityinfo *city)
	Get timezone name from the Cityinfo structure.
gchar *	cityinfo_get_locale (const Cityinfo *city)
	Get locale used in particular city.
gdouble	cityinfo_get_xpos (const Cityinfo *city)
	Get x position of the city on the map.
gdouble	cityinfo_get_ypos (const Cityinfo *city)
	Get y position of the city on the map.
gdouble	cityinfo_get_lat (const Cityinfo *city)
	Get latitude of the city.
gdouble	cityinfo_get_lng (const Cityinfo *city)
	Get longitude of the city.
gint	cityinfo_get_id (const Cityinfo *city)
	Get the ID of particular city.
Cityinfo *	cityinfo_new (void)
	Create new structure.
void	cityinfo_free (Cityinfo *city)
	Free Cityinfo structure.
Cityinfo *	cityinfo_clone (const Cityinfo *city)
	Create duplication of particular Cityinfo structure.
void	cityinfo_foreach (CityinfoFunc func, gpointer data)
	Make a defined action on each city in the database.
Cityinfo *	cityinfo_find_closest (gdouble x, gdouble y)
	Search for the nearest city to given point on the map.
Cityinfo *	cityinfo_from_id (gint id)
	Find and return city with particular ID.
Cityinfo **	cityinfo_get_all (void)
	Get an array with all cities available on the platform.
void	cityinfo_free_all (Cityinfo **cities)
	Free an array of pointers to Cityinfo structure.

---

Detailed Description

Cityinfo library header.

API for Cityinfo library, which provides basic informations about set of world cities.

---

Define Documentation

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

typedef gboolean(*) CityinfoFunc(const Cityinfo *city, gpointer data)

Definition of action which could be taken on each city. Function cityinfo_foreach() use this type to define action which should be taken on each of the city in database.

Parameters:

	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 Documentation

gchar* cityinfo_get_name

(

const Cityinfo *

city

)

Get city name from the Cityinfo structure.

Parameters:

city

Cityinfo structure from which we want to get information.

Returns:

Localized name of the city.

gchar* cityinfo_get_code

(

const Cityinfo *

city

)

Get country code from the Cityinfo structure.

Parameters:

city

Cityinfo structure from which we want to get information.

Returns:

Code of the country.

gchar* cityinfo_get_country

(

const Cityinfo *

city

)

Get country name from the Cityinfo structure.

Parameters:

city

Cityinfo structure from which we want to get information.

Returns:

Localized name of the country.

gchar* cityinfo_get_zone

(

const Cityinfo *

city

)

Get timezone name from the Cityinfo structure.

Parameters:

city

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

)

Get locale used in particular city.

Parameters:

city

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

)

Get x position of the city on the map.

Parameters:

city

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

)

Get y position of the city on the map.

Parameters:

city

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

)

Get latitude of the city.

Parameters:

city

Cityinfo structure from which we want to get information.

Returns:

latitude of the city.

gdouble cityinfo_get_lng

(

const Cityinfo *

city

)

Get longitude of the city.

Parameters:

city

Cityinfo structure from which we want to get information.

Returns:

longitude of the city.

gint cityinfo_get_id

(

const Cityinfo *

city

)

Get the ID of particular city.

Parameters:

city

Cityinfo structure from which we want to get information.

Returns:

ID of the given city.

Cityinfo* cityinfo_new

(

void

)

Create new structure.

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

)

Free Cityinfo structure.

Free an allocated Cityinfo structure.

Parameters:

city

The Cityinfo structure to be freed.

Cityinfo* cityinfo_clone

(

const Cityinfo *

city

)

Create duplication of particular Cityinfo structure.

Duplicate a Cityinfo structure. The newly created structure can be handled indepenently from the old one.

Parameters:

city

The source Cityinfo.

Returns:

A newly allocated Cityinfo with the same contents as old. NULL on any error.

void cityinfo_foreach	(	CityinfoFunc	func,
		gpointer	data
	)

Make a defined action on each city in the database.

Runs a function against every entry of the database. The iteration will end if func returns FALSE.

Parameters:

	func	The function
	data	Misc data to the function

Cityinfo* cityinfo_find_closest	(	gdouble	x,
		gdouble	y
	)

Search for the nearest city to given point on the map.

Finds the nearest city to given coordinates on the map.

Parameters:

	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

)

Find and return city with particular ID.

Get the whole Cityinfo structure from its ID number.

Parameters:

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

)

Get an array with all cities available on the platform.

Returns all cities available on the platform. Returned data could be used indepenently and should be freed with function cityinfo_free_all() when it is not needed any more.

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 an array of pointers to Cityinfo structure.

Free all cities array returned from cityinfo_get_all() function.

Parameters:

cities

An array of pointers to cities.

---