![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Section Contents
RHandleBase |
Abstract: handle to an object |
RSessionBase |
Abstract: base class for handle to a session |
t32wld.h
ealwl.lib
This class defines the world servers client side API.
Clients can use this API to connect to the server, add, update and delete cities/countries, retrieve city/country information, navigate and search the world database, set the home city, default country, and the units used in distance comparisons. In addition, clients can use the file handling functions to import and export database data files.
TInt Connect();
This function connects the client process to the world server.
TInt |
An error code: see System error codes. |
TVersion Version() const;
The version number may be incremented in future releases of the world server. If extra features are added in such releases, the version number may be used by application programs as a basis for assessing the capabilities of the world server. Version-specific functions will be marked as such in the SDK documentation.
TVersion |
The version number. |
This section contains the functions used to add, update, and delete city information.
To update or delete a city, the session must first obtain the correct TWldID. A TCityData is filled with the data and the server is called to add the information.
TInt AddCity(const TCityData& aCity);
This function adds a new city to the world database.
Cities must be in a valid country, and have a valid DST zone. City names must be unique within a country though the same city name may be used for cities in different countries.
const TCityData& aCity |
The new city information. |
TInt |
An error code: see System error codes. |
TInt UpdateCity(TWorldId& aId,const TCityData& aCity);
This function updates the information for a city.
The new information must also be valid cities must be in a valid country, and have a valid DST zone. City names must be unique within a country though the same city name may be used for cities in different countries.
TWorldId& aId |
The ID of the city to be updated. |
const TCityData& aCity |
The new city information |
TInt |
An error code: see System error codes. |
TInt IsCityDeletable(TInt& aDeleteDeniedFlags,const TWorldId& aId) const;
This function determines whether a given city can be deleted. Capital cities, the home city, and all cities from the read-only file cannot be deleted.
TInt& aDeleteDeniedFlags |
Bitmask of the TWldDeleteDeniedFlags flags. Gives the reasons why the specified TWorldID cannot be deleted. The value returned is 0 if the country can be deleted. |
const TWorldId& aId |
The ID of the city which is being queried. |
TInt |
An error code: see System error codes. |
TInt DeleteCity(TWorldId& aId);
This function deletes a city from the world database.
Capital cities, the home city, and all cities from the read-only file cannot be deleted.
TWorldId& aId |
The ID of the city which is to be deleted. |
TInt |
An error code: see System error codes. |
The cities are sorted according to their name by the locale alphabet order.
TInt NumberCities() const;
This function returns the number of cities in the world database.
TInt |
On return, contains the number of cities in the database. |
TInt FirstCity(TWorldId& aId) const;
This function retrieves the ID of the first city in the selected locale.
The locale can either be the current country or the whole world database, and is defined by the Select mode of the TWorldId.
TWorldId& aId |
Specifies the locale for which the search is to be carried out over the whole database, or in the current country. On return, contains the ID of the first city within the specified locale. |
TInt |
An error code: see System error codes. |
TInt NextCity(TWorldId& aId) const;
This function retrieves the ID of the next city in the selected locale.
The locale can either be the current country or the whole world database, and is defined by the Select mode of the TWorldId.
TWorldId& aId |
Specifies the locale within which the next city is to be found over the whole database, or in the current country. On return, contains the ID of the next city in the specified locale. |
TInt |
An error code: see System error codes. |
TInt PrevCity(TWorldId& aId) const;
This function retrieves the ID of the previous city in the selected locale.
The locale can either be the current country or the whole world database, and is defined by the Select mode of the TWorldId.
TWorldId& aId |
Specifies the locale within which the previous city is to be found over the whole database, or in the current country. On return, contains the ID of the previous city within the specified locale. |
TInt |
An error code: see System error codes. |
TInt LastCity(TWorldId& aId) const;
This function retrieves the ID of the last city in the selected locale.
The locale can either be the current country or the whole world database, and is defined by the Select mode of the TWorldId.
TWorldId& aId |
Specifies the locale within which the last city is to be found over the whole database, or in the current country. On return, contains the ID of the last city in the specified locale. |
TInt |
An error code: see System error codes. |
TInt FindCity(TWorldId& aCity,const TDesC& aPartialCity) const;
This function locates the ID of the first city that has a name which starts with the search string.
The search string can contain a partial name or the full name. The string may be capitalised, uncapitalised, or a combination of the two. If several cities have names matching the search string, then the first city found is returned the lowest in the alphabetic order.
TWorldId& aCity |
Specifies the locale within which the city is to be found over the whole database, or in the current country. On return, contains the ID of the first city matching the partial name within the specified locale. |
const TDesC& aPartialCity |
A descriptor containing the search string for the city. |
TInt |
An error code: see System error codes. |
TInt Find(TWorldId& aId,const TDesC& aCity,const TDesC& aCountry) const;
This function finds the ID of the city which precisely matches the specified city and country names.
TWorldId& aId |
On return, contains the ID of the specified city. |
const TDesC& aCity |
The city name. |
const TDesC& aCountry |
The country name. |
TInt |
An error code: see System error codes. |
This section contains the functions used to add, update, and delete country information.
To update or delete a country, the session must first obtain the correct TWldID. To add a country, a TCountryData is filled with the data and the server is called to add the information.
TInt AddCountry(const TCountryData& aCountry,const TCityData& aCapital);
This function adds a new country, with its capital city, to the world database. Country names must be unique.
const TCountryData& aCountry |
The country to be added to the database. |
const TCityData& aCapital |
The countrys capital. |
TInt |
An error code: see System error codes. |
TInt UpdateCountry(TWorldId& aId,const TCountryData& aCountry);
This function updates the data of an existing country. Updated country names must be unique.
TWorldId& aId |
The ID of the country to be updated. |
const TCountryData& aCountry |
The new country data. |
TInt |
An error code: see System error codes. |
TInt IsCountryDeletable(TInt& aDeleteDeniedFlags,const TWorldId& aId) const;
This function determines whether a given country can be deleted. The home country, default country, and all countries from the read-only file cannot be deleted.
TInt& aDeleteDeniedFlags |
Bitmask of the TWldDeleteDeniedFlags flags. Gives the reasons why the specified TWorldID cannot be deleted. The value returned is 0 if the country can be deleted. |
const TWorldId& aId |
The ID of the country which is being queried. |
TInt |
An error code: see System error codes. |
TInt DeleteCountry(TWorldId& aId);
This function deletes a country from the world database.
The home country, default country, and all countries from the read-only file cannot be deleted.
TWorldId& aId |
The ID of the country to be deleted. |
TInt |
An error code: see System error codes. |
The countries are sorted according to their name by alphabetic order.
TInt NumberCountries() const;
This function returns the number of countries in the world database.
TInt |
The number of countries in the world database. |
TInt FirstCountry(TWorldId& aId) const;
This function retrieves the ID of the first country in the world database.
TWorldId& aId |
On return, contains the ID of the first country. |
TInt |
An error code: see System error codes. |
TInt NextCountry(TWorldId& aId) const;
This function retrieves the ID of the next country in the world database.
TWorldId& aId |
On return, contains the ID of the next country. |
TInt |
An error code: see System error codes. |
TInt PrevCountry(TWorldId& aId) const;
This function retrieves the ID of the previous country in the world database.
TWorldId& aId |
On return, contains the ID of the previous country. |
TInt |
An error code: see System error codes. |
TInt LastCountry(TWorldId& aId) const;
This function retrieves the ID of the last country in the world database.
TWorldId& aId |
On return, contains the ID of the last country. |
TInt |
An error code: see System error codes. |
TInt FindCountry(TWorldId& aCountry,const TDesC& aPartialCountry) const;
This function locates the ID of the first country which starts with the search string.
The search string can contain a partial name or the full name. The string may be capitalised, uncapitalised, or a combination of the two. If several countries have names matching the search string, then the first country found is returned the lowest in the alphabetic order.
TWorldId& aCountry |
On return, contains the ID of the country. |
const TDesC& aPartialCountry |
A descriptor containing the search string, or partial country name. |
TInt |
An error code: see System error codes. |
New cities and countries can be added to the world server by importing a data file. Importing data updates any information of existing cities or countries. The import method cannot be used to delete any data that is set already, and can import only those cities or countries that obey referential integrity e.g. cities must always be added to a country, a country cannot be added without a capital city etc.
This section describes the functions which can be used to locate, import, export, and delete the effects of data files.
TInt DataFileLocation(TFileName& aDataFile) const;
This function returns the location of the most recently imported user data file.
TFileName& aDataFile |
On return, contains the name and path of the most recently imported data file. |
TInt |
An error code: see System error codes. |
TInt DataFileOpen(const TDesC& aDataFile);
This function allows clients to import a specified world database data file.
const TDesC& aDataFile |
The location of the data file to be imported, including drive, path and file name. |
TInt |
An error code: see System error codes. |
TInt DataFileRevertToSaved();
This function reverts the world database to its state when the data file was last saved discarding data which was not saved.
TInt |
An error code: see System error codes. |
TInt DataFileSave();
This function saves the world database data added by the user to the current data file.
TInt |
An error code: see System error codes. |
TInt DataFileSaveAs(const TDesC& aDataFile,TBool aReplace=EFalse);
This function saves the world database data added by the user to a specified data file.
const TDesC& aDataFile |
The name, including path, of the data file in which the user added data is to be saved. |
TBool aReplace=EFalse |
This specifies whether or not the function will allow an existing data file to be over-written. By default the function does not over-write data files. |
TInt |
An error code: see System error codes. |
TInt ResetAllData();
This function resets the database to the state it had when first opened, and notifies the clients.
TInt |
An error code: see System error codes. |
Z:\System\Data\
directory) or RAM (C:\System\Localization\
directory).TInt Home(TWorldId& aHome) const;
This function retrieves the ID of the home city.
TWorldId& aHome |
On return, contains the ID of the home city. |
TInt |
An error code: see System error codes. |
TInt SetHome(const TWorldId& aId);
This function sets the home city.
const TWorldId& aId |
The ID of the city which is to become the home city. |
TInt |
An error code: see System error codes. |
TInt DefaultCountry(TWorldId& aCountry) const;
This function retrieves the ID of the default country.
TWorldId& aCountry |
On return, contains the ID of the default country. |
TInt |
An error code: see System error codes. |
TInt SetDefaultCountry(const TWorldId& aId);
This function sets the default country.
const TWorldId& aId |
The ID of the country which is to become the default country. |
TInt |
An error code: see System error codes. |
TInt CityData(TCityData& aCity,const TWorldId& aId) const;
This function retrieves the city data associated with the specified ID.
TCityData& aCity |
On return, contains the city data. |
const TWorldId& aId |
The ID of the city. |
TInt |
An error code: see System error codes. |
TInt CountryData(TCountryData& aCountry,const TWorldId& aId) const;
This function retrieves the country data associated with the specified ID.
TCountryData& aCountry |
On return, contains the country data. |
const TWorldId& aId |
The ID of the country. |
TInt |
An error code: see System error codes. |
TInt DistanceUnits(TWldDistanceUnits& aDistanceUnit) const;
This function retrieves the distance units used by the session.
TWldDistanceUnits& aDistanceUnit |
On return, contains the sessions distance units. |
TInt |
An error code: see System error codes. |
TInt SetDistanceUnits(TWldDistanceUnits aUnit);
This function sets the distance units used by the session.
TWldDistanceUnits aUnit |
The new distance units. |
TInt |
An error code: see System error codes. |
TInt CalculateDistance(TInt& aDistance,const TWorldId& aLeft,const TWorldId& aRight) const;
This function calculates the distance between two cities using the currently selected distance units.
TInt& aDistance |
On return, contains the distance between the two cities. |
const TWorldId& aLeft |
The ID of the first city. |
const TWorldId& aRight |
The ID of the second city. |
TInt |
An error code: see System error codes. |
TInt CalculateSunlight(TTime& aSunrise,TTime& aSunset,const TWorldId& aId,const TTime& aDate=Time::NullTTime()) const;
This function retrieves a citys sunset and sunrise time on a specified date.
TTime& aSunrise |
On return, contains the sunrise time. |
TTime& aSunset |
On return, contains the sunset time. |
const TWorldId& aId |
The ID of the city for which the sunset and sunrise times are to be calculated. |
const TTime& aDate=Time::NullTTime() |
The date for which the sunrise/sunset times are to be calculated. |
TInt |
An error code: see System error codes. |
TInt NearestCity(const TPoint& aMapCoord,const TWorldId* aCityToBeat=NULL);
This function initialises the parameters for a next city search. To actually start the search, use the NextNearestCity() function.
const TPoint& aMapCoord |
The map co-ordinate for which the nearest city is to be found (pixels). |
const TWorldId* aCityToBeat=NULL |
The ID of the reference city. The search spans a specified number of cites, starting from this ID. |
TInt |
An error code: see System error codes. |
TInt NextNearestCity(TWorldId& aId,TInt aMaxNumberToCompare=KMaxTInt);
This function retrieves the results of a search for the city nearest to a map co-ordinate the co-ordinate is specified using the NearestCity() function.
The search compares the distance between each city and the map co-ordinate. It starts at the reference city and continues the comparison until it reaches a specified number of cities. By default, the search spans KMaxTInt cities, which is effectively the entire database.
TWorldId& aId |
On return, contains the ID of the nearest city. |
TInt aMaxNumberToCompare=KMaxTInt |
The number of cities to compare in the search. |
TInt |
An error code: see System error codes. |
void NotifyOnChange(TRequestStatus& aStatus);
This function asynchronously provides notification of changes to the home city, default country, system time, and database files.
TRequestStatus& aStatus |
A variable that indicates the completion status of the request. |
void NotifyOnChangeCancel();
This function cancels an outstanding request for notification of changes to the home city, default country, system time, and database files.
void RomTitle(TDes& aText) const;
This function retrieves the title of the currently loaded world database, which is defined in the read-only file..
TDes& aText |
On return, contains the title of the world database. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |