EPOC   SDK Home Glossary Indexes Previous Next Up

RWorldServer class


Contents


RWorldServer class — World server session

Section Contents


Overview

Derivation

RHandleBase

Abstract: handle to an object

RSessionBase

Abstract: base class for handle to a session

Defined in

t32wld.h

Link against

ealwl.lib

Description

This class defines the world server’s 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.


Connecting to the world server


Connect() — Connect to the world server

TInt Connect();

Description

This function connects the client process to the world server.

Return value

TInt

An error code: see System error codes.

Note

Version() — Get version number

TVersion Version() const;

Description

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.

Return value

TVersion

The version number.


City modifying

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.


AddCity() — Add a city to the world database

TInt AddCity(const TCityData& aCity);

Description

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.

Arguments

const TCityData& aCity

The new city information.

Return value

TInt

An error code: see System error codes.

Notes:

UpdateCity() — Update city

TInt UpdateCity(TWorldId& aId,const TCityData& aCity);

Description

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.

Arguments

TWorldId& aId

The ID of the city to be updated.

const TCityData& aCity

The new city information

Return value

TInt

An error code: see System error codes.

Notes:

IsCityDeletable() — Is city deletable?

TInt IsCityDeletable(TInt& aDeleteDeniedFlags,const TWorldId& aId) const;

Description

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.

Arguments

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.

Return value

TInt

An error code: see System error codes.


DeleteCity() — Delete city

TInt DeleteCity(TWorldId& aId);

Description

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.

Arguments

TWorldId& aId

The ID of the city which is to be deleted.

Return value

TInt

An error code: see System error codes.

Notes

City navigation

The cities are sorted according to their name by the locale alphabet order.


NumberCities() — Get the number of cities

TInt NumberCities() const;

Description

This function returns the number of cities in the world database.

Return value

TInt

On return, contains the number of cities in the database.


FirstCity() — Get the first city

TInt FirstCity(TWorldId& aId) const;

Description

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.

Arguments

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.

Return value

TInt

An error code: see System error codes.

Notes

NextCity() — Get the next city

TInt NextCity(TWorldId& aId) const;

Description

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.

Arguments

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.

Return value

TInt

An error code: see System error codes.

Notes

PrevCity() — Get the previous city

TInt PrevCity(TWorldId& aId) const;

Description

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.

Arguments

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.

Return value

TInt

An error code: see System error codes.

Notes

LastCity() — Get last city

TInt LastCity(TWorldId& aId) const;

Description

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.

Arguments

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.

Return value

TInt

An error code: see System error codes.

Notes

FindCity() — Find city using partial name

TInt FindCity(TWorldId& aCity,const TDesC& aPartialCity) const;

Description

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.

Arguments

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.

Return value

TInt

An error code: see System error codes.

Note:

Find() — Find a particular city

TInt Find(TWorldId& aId,const TDesC& aCity,const TDesC& aCountry) const;

Description

This function finds the ID of the city which precisely matches the specified city and country names.

Arguments

TWorldId& aId

On return, contains the ID of the specified city.

const TDesC& aCity

The city name.

const TDesC& aCountry

The country name.

Return value

TInt

An error code: see System error codes.

Note:

Country modifying

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.


AddCountry() — Add a country to the world database

TInt AddCountry(const TCountryData& aCountry,const TCityData& aCapital);

Description

This function adds a new country, with its capital city, to the world database. Country names must be unique.

Arguments

const TCountryData& aCountry

The country to be added to the database.

const TCityData& aCapital

The country’s capital.

Return value

TInt

An error code: see System error codes.

Notes:

UpdateCountry() — Update country

TInt UpdateCountry(TWorldId& aId,const TCountryData& aCountry);

Description

This function updates the data of an existing country. Updated country names must be unique.

Arguments

TWorldId& aId

The ID of the country to be updated.

const TCountryData& aCountry

The new country data.

Return value

TInt

An error code: see System error codes.

Notes:

IsCountryDeletable() — Is country deleteable?

TInt IsCountryDeletable(TInt& aDeleteDeniedFlags,const TWorldId& aId) const;

Description

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.

Arguments

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.

Return value

TInt

An error code: see System error codes.


DeleteCountry() — Delete country

TInt DeleteCountry(TWorldId& aId);

Description

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.

Arguments

TWorldId& aId

The ID of the country to be deleted.

Return value

TInt

An error code: see System error codes.

Notes

Country navigation

The countries are sorted according to their name by alphabetic order.


NumberCountries() — Get the number of countries

TInt NumberCountries() const;

Description

This function returns the number of countries in the world database.

Return value

TInt

The number of countries in the world database.


FirstCountry() — Get the first country

TInt FirstCountry(TWorldId& aId) const;

Description

This function retrieves the ID of the first country in the world database.

Arguments

TWorldId& aId

On return, contains the ID of the first country.

Return value

TInt

An error code: see System error codes.

Notes

NextCountry() — Get the next country

TInt NextCountry(TWorldId& aId) const;

Description

This function retrieves the ID of the next country in the world database.

Arguments

TWorldId& aId

On return, contains the ID of the next country.

Return value

TInt

An error code: see System error codes.

Notes

PrevCountry() — Get previous country

TInt PrevCountry(TWorldId& aId) const;

Description

This function retrieves the ID of the previous country in the world database.

Arguments

TWorldId& aId

On return, contains the ID of the previous country.

Return value

TInt

An error code: see System error codes.

Notes

LastCountry() — Get last country

TInt LastCountry(TWorldId& aId) const;

Description

This function retrieves the ID of the last country in the world database.

Arguments

TWorldId& aId

On return, contains the ID of the last country.

Return value

TInt

An error code: see System error codes.

Notes

FindCountry() — Find country using partial name

TInt FindCountry(TWorldId& aCountry,const TDesC& aPartialCountry) const;

Description

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.

Arguments

TWorldId& aCountry

On return, contains the ID of the country.

const TDesC& aPartialCountry

A descriptor containing the search string, or partial country name.

Return value

TInt

An error code: see System error codes.

Notes

File functions

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.


DataFileLocation() — Get the location of the most recently imported data file

TInt DataFileLocation(TFileName& aDataFile) const;

Description

This function returns the location of the most recently imported user data file.

Arguments

TFileName& aDataFile

On return, contains the name and path of the most recently imported data file.

Return value

TInt

An error code: see System error codes.


DataFileOpen() — Import a data file

TInt DataFileOpen(const TDesC& aDataFile);

Description

This function allows clients to import a specified world database data file.

Arguments

const TDesC& aDataFile

The location of the data file to be imported, including drive, path and file name.

Return value

TInt

An error code: see System error codes.


DataFileRevertToSaved() — Revert to saved data file

TInt DataFileRevertToSaved();

Description

This function reverts the world database to its state when the data file was last saved — discarding data which was not saved.

Return value

TInt

An error code: see System error codes.


DataFileSave() — Save user data file

TInt DataFileSave();

Description

This function saves the world database data — added by the user — to the current data file.

Return value

TInt

An error code: see System error codes.

Note

DataFileSaveAs() — Save user data to a named file

TInt DataFileSaveAs(const TDesC& aDataFile,TBool aReplace=EFalse);

Description

This function saves the world database data — added by the user — to a specified data file.

Arguments

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.

Return value

TInt

An error code: see System error codes.

Note

ResetAllData() — Reset all data

TInt ResetAllData();

Description

This function resets the database to the state it had when first opened, and notifies the clients.

Return value

TInt

An error code: see System error codes.

Note

Home location


Home() — Get the ID of the home city

TInt Home(TWorldId& aHome) const;

Description

This function retrieves the ID of the home city.

Arguments

TWorldId& aHome

On return, contains the ID of the home city.

Return value

TInt

An error code: see System error codes.


SetHome() — Set the home city

TInt SetHome(const TWorldId& aId);

Description

This function sets the home city.

Arguments

const TWorldId& aId

The ID of the city which is to become the home city.

Return value

TInt

An error code: see System error codes.


Default country


DefaultCountry() — Get the default country

TInt DefaultCountry(TWorldId& aCountry) const;

Description

This function retrieves the ID of the default country.

Arguments

TWorldId& aCountry

On return, contains the ID of the default country.

Return value

TInt

An error code: see System error codes.


SetDefaultCountry() — Set the default country

TInt SetDefaultCountry(const TWorldId& aId);

Description

This function sets the default country.

Arguments

const TWorldId& aId

The ID of the country which is to become the default country.

Return value

TInt

An error code: see System error codes.


City/Country data


CityData() — Get city data

TInt CityData(TCityData& aCity,const TWorldId& aId) const;

Description

This function retrieves the city data associated with the specified ID.

Arguments

TCityData& aCity

On return, contains the city data.

const TWorldId& aId

The ID of the city.

Return value

TInt

An error code: see System error codes.


CountryData() — Get country data

TInt CountryData(TCountryData& aCountry,const TWorldId& aId) const;

Description

This function retrieves the country data associated with the specified ID.

Arguments

TCountryData& aCountry

On return, contains the country data.

const TWorldId& aId

The ID of the country.

Return value

TInt

An error code: see System error codes.


Distance units


DistanceUnits() — Get distance units

TInt DistanceUnits(TWldDistanceUnits& aDistanceUnit) const;

Description

This function retrieves the distance units used by the session.

Arguments

TWldDistanceUnits& aDistanceUnit

On return, contains the session’s distance units.

Return value

TInt

An error code: see System error codes.


SetDistanceUnits() — Set distance units

TInt SetDistanceUnits(TWldDistanceUnits aUnit);

Description

This function sets the distance units used by the session.

Arguments

TWldDistanceUnits aUnit

The new distance units.

Return value

TInt

An error code: see System error codes.


Distance, sunlight and city location calculations


CalculateDistance() — Calculate distance between cities

TInt CalculateDistance(TInt& aDistance,const TWorldId& aLeft,const TWorldId& aRight) const;

Description

This function calculates the distance between two cities — using the currently selected distance units.

Arguments

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.

Return value

TInt

An error code: see System error codes.


CalculateSunlight() — Calculate sunrise/sunset times

TInt CalculateSunlight(TTime& aSunrise,TTime& aSunset,const TWorldId& aId,const TTime& aDate=Time::NullTTime()) const;

Description

This function retrieves a city’s sunset and sunrise time on a specified date.

Arguments

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.

Return value

TInt

An error code: see System error codes.


NearestCity() — Initialise nearest city search

TInt NearestCity(const TPoint& aMapCoord,const TWorldId* aCityToBeat=NULL);

Description

This function initialises the parameters for a next city search. To actually start the search, use the NextNearestCity() function.

Arguments

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.

Return value

TInt

An error code: see System error codes.


NextNearestCity() — Get nearest city

TInt NextNearestCity(TWorldId& aId,TInt aMaxNumberToCompare=KMaxTInt);

Description

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.

Arguments

TWorldId& aId

On return, contains the ID of the nearest city.

TInt aMaxNumberToCompare=KMaxTInt

The number of cities to compare in the search.

Return value

TInt

An error code: see System error codes.


Notifications


NotifyOnChange() — Notification of changes

void NotifyOnChange(TRequestStatus& aStatus);

Description

This function asynchronously provides notification of changes to the home city, default country, system time, and database files.

Arguments

TRequestStatus& aStatus

A variable that indicates the completion status of the request.


NotifyOnChangeCancel() — Cancel notification of changes

void NotifyOnChangeCancel();

Description

This function cancels an outstanding request for notification of changes to the home city, default country, system time, and database files.


ROM title


RomTitle() — Get read-only file title

void RomTitle(TDes& aText) const;

Description

This function retrieves the title of the currently loaded world database, which is defined in the read-only file..

Arguments

TDes& aText

On return, contains the title of the world database.

EPOC       SDK Home Glossary Indexes Previous Next Up