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 struct _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.
Cityinfocityinfo_new (void)
 Create new structure.
void cityinfo_free (Cityinfo *city)
 Free Cityinfo structure.
Cityinfocityinfo_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.
Cityinfocityinfo_find_closest (gdouble x, gdouble y)
 Search for the nearest city to given point on the map.
Cityinfocityinfo_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.

This file is part of City Info

Copyright © 2007-2008 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. Contact: Qi Ouyang <[email protected]>

This software, including documentation, is protected by copyright controlled by Nokia Corporation. All rights are reserved. Copying, including reproducing, storing, adapting or translating, any or all of this material requires the prior written consent of Nokia Corporation. This material also contains confidential information which may not be disclosed to others without the prior written consent of Nokia. 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.


Generated on Wed Sep 30 21:58:19 2009 for libcityinfo by  doxygen 1.5.6