Class RWorldServer

class RWorldServer : public RSessionBase;

Description

Defines the client side API to the world server.

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.

Derivation

• RHandleBase - A handle to an object

• RSessionBase - Client-side handle to a session with a server

• RWorldServer - Defines the client side API to the world server

Members

Defined in RWorldServer:
AddCity(), AddCountry(), CalculateDistance(), CalculateSunlight(), CityData(), Connect(), CountryData(), DataFileRevertToSaved(), DataFileSave(), DefaultCountry(), DeleteCity(), DeleteCountry(), DistanceUnits(), Find(), FindCity(), FindCountry(), FirstCity(), FirstCountry(), GetCountryNameByISOCode(), Home(), IsCityDeletable(), IsCountryDeletable(), LastCity(), LastCountry(), NearestCity(), NextCity(), NextCountry(), NextNearestCity(), NotifyOnChange(), NotifyOnChangeCancel(), NumberCities(), NumberCountries(), PrevCity(), PrevCountry(), ResetAllData(), RomTitle(), SetCollationLevelForFind(), SetDefaultCountry(), SetDistanceUnits(), SetHome(), UpdateCity(), UpdateCountry(), Version()

Inherited from RHandleBase:
Attributes(), Close(), Duplicate(), FullName(), Handle(), HandleInfo(), Name(), SetHandle(), SetHandleNC(), iHandle

Inherited from RSessionBase:
CreateSession(), EAutoAttach, EExplicitAttach, Open(), Send(), SendReceive(), SetReturnedHandle(), ShareAuto(), ShareProtected(), TAttachMode

Capability:

Illegal

IMPORT_C TInt Connect();

Description

Connects the client process to the world server.

Note: as with any server, the connection should be closed after use. RHandleBase provides the necessary Close() function.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TVersion Version() const;

Description

Gets the version number of the world server.

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 documentation.

Return value

TVersion The version number.

Capability:

Illegal

IMPORT_C void RomTitle(TDes &aText) const;

Description

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

Parameters

TDes &aText On return, contains the title of the world database.

Capability:

Illegal

IMPORT_C TInt NumberCities() const;

Description

Gets the number of cities in the world database.

Return value

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

Capability:

Illegal

IMPORT_C TInt NumberCountries() const;

Description

Gets the number of countries in the world database.

Return value

TInt The number of countries in the world database.

Capability:

Illegal

IMPORT_C void NotifyOnChange(TRequestStatus &aStatus);

Description

Provides notification of changes to the home city, default country, system time, or database files, asynchronously.

Parameters

TRequestStatus &aStatus A variable that indicates the completion status of the request.

Capability:

Illegal

IMPORT_C void NotifyOnChangeCancel();

Description

Cancels an outstanding notification request made using NotifyOnChange().

Capability:	WriteDeviceData
Capability:	WriteUserData

IMPORT_C TInt ResetAllData();

Description

Resets the database to the state it had when first opened, and notifies the clients.

Note: when the database is first opened it contains only the information in the read-only file. This file may have originated either from ROM (Z:\System\Data directory) or RAM (C:\System\Localization directory).

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:	WriteDeviceData
Capability:	WriteUserData

IMPORT_C TInt DataFileSave();

Description

Saves the data added by the user, to the current world database.

Notes:

This function exports a world server data file.

To save the file to another location, use DataFileSaveAs().

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:	WriteDeviceData
Capability:	WriteUserData

IMPORT_C TInt DataFileRevertToSaved();

Description

Reverts the world database to its state when the data file was last saved, discarding data which was not saved.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt DefaultCountry(TWorldId &aCountry) const;

Description

Gets the ID of the default country.

Parameters

TWorldId &aCountry On return, contains the ID of the default country.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt SetDefaultCountry(const TWorldId &aId);

Description

Sets the default country.

Parameters

const TWorldId &aId The ID of the country which is to become the default country.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

ReadUserData

IMPORT_C TInt Home(TWorldId &aHome) const;

Description

Gets the ID of the home city.

Parameters

TWorldId &aHome On return, contains the ID of the home city.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:	WriteDeviceData
Capability:	WriteUserData

IMPORT_C TInt SetHome(const TWorldId &aId);

Description

Sets the home city.

Parameters

const TWorldId &aId The ID of the city which is to become the home city.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt AddCity(const TCityData &aCity);

Description

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, although the same name may be used for cities in different countries.

Parameters

const TCityData &aCity The new city information.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes. KErrArgument is returned if the city already exists, or if the data doesn't specify a city name. It is also returned if the named country does not exist, or if the country name is not specified.

Capability:

Illegal

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

Description

Adds a new country, with its capital city, to the world database.

Country names must be unique.

Parameters

const TCountryData &aCountry The country to be added to the database. const TCityData &aCapital The country's capital.

Return value

TInt KErrNone if successful, KErrArgument if the name of the new country is not specified or if the capital city information indicates that it is not in the country, otherwise another of the system-wide error codes.

Capability:

Illegal

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

Description

Gets the city data associated with the specified ID.

Parameters

TCityData &aCity On return, contains the city data. const TWorldId &aId The ID of the city.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

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

Description

Gets the country data associated with the specified ID.

Parameters

TCountryData &aCountry On return, contains the country data. const TWorldId &aId The ID of the country.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

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

Description

Calculates the distance between two cities, using the currently selected distance units.

Parameters

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 KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

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

Description

Gets a city's sunset and sunrise time on a specified date.

Parameters

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 The date for which the sunrise/sunset times are to be calculated.

Return value

TInt KErrNotSupported

Capability:

Illegal

IMPORT_C TInt DeleteCity(TWorldId &aId);

Description

Deletes a city from the world database.

Note:

An error will occur if an attempt is made to delete a city which cannot be, or is already, deleted. Capital cities, the home city, and cities in the read-only file cannot be deleted.

Parameters

TWorldId &aId The ID of the city which is to be deleted.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt DeleteCountry(TWorldId &aId);

Description

Deletes a country from the world database.

Note:

An error will occur if an attempt is made to delete a country which cannot be, or is already deleted. The home country, default country, and all countries from the read-only file cannot be deleted.

If a country is deleted, its cities are added to the null country.

Parameters

TWorldId &aId The ID of the country to be deleted.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt DistanceUnits(TWldDistanceUnits &aDistanceUnit) const;

Description

Gets the distance units used by the session.

Parameters

TWldDistanceUnits &aDistanceUnit On return, contains the session's distance units.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt SetDistanceUnits(TWldDistanceUnits aUnit);

Description

Sets the distance units used by the session.

Parameters

TWldDistanceUnits aUnit The new distance units.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

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

Description

Finds the ID of the city which precisely matches the specified city and country names.

Parameters

TWorldId &aId On return, contains the ID of the requested city. const TDesC &aCity The city name. const TDesC &aCountry The country name.

Return value

TInt KErrNone if successful, KErrNotFound if there is no match between the city and country names and those of a city in the world database, otherwise another of the system-wide error codes.

Capability:

Illegal

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

Description

Finds the ID of the first city that has a name which starts with the specified search string.

The search string can contain a partial or full name. The search is case-insensitive. If several cities have names matching the search string, then the first city found is returned (the lowest in the alphabetic order).

Note: the function cannot locate strings in the middle of city names.

Parameters

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 KErrNone if successful, KErrNotFound if no city matches the search string, otherwise another of the system-wide error codes.

Capability:

Illegal

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

Description

Finds the ID of the first country whose name starts with the specified search string.

The search string can contain a partial or full name. The search is case-insensitive. If several countries have names matching the search string, then the first country found is returned (the lowest in the alphabetic order).

Note: the function cannot locate strings in the middle of country names.

Parameters

TWorldId &aCountry On return, contains the ID of the country. const TDesC &aPartialCountry The search string.

Return value

TInt KErrNone if successful, KErrNotFound if no country matches the search string, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt FirstCity(TWorldId &aId) const;

Description

Gets the ID of the first city found, either in the current country or the whole world database.

Note: the first city is the one with the lowest alphabetic order.

Parameters

TWorldId &aId Specifies whether the search is to be carried out over the whole database, or just the current country. On return, contains the ID of the first city found.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt FirstCountry(TWorldId &aId) const;

Description

Gets the ID of the first country in the world database.

Note: the first country is the one with the lowest alphabetic order.

Country searches always span the whole world database. This function ignores the search mode select state defined in aID.

Parameters

TWorldId &aId On return, contains the ID of the first country.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

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

Description

Tests whether a specified city can be deleted.

Capital cities, the home city, and cities from the read-only file cannot be deleted.

Parameters

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

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

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

Description

Tests whether a specified country can be deleted.

The home country, default country, and all countries from the read-only file cannot be deleted.

Parameters

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 KErrNone if successful, otherwise another of the system-wide error codes

Capability:

Illegal

IMPORT_C TInt LastCity(TWorldId &aId) const;

Description

Gets the ID of the last city found, either in the current country or the whole world database.

Note: the last city is the one with the highest alphabetic order.

Parameters

TWorldId &aId Specifies whether the search is to be carried out over the whole database, or just the current country. On return, contains the ID of the last city found.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt LastCountry(TWorldId &aId) const;

Description

Gets the ID of the last country in the world database.

The last country is the one with the highest alphabetic order.

Country searches span the whole world database. This function ignores the search mode select state defined in aID.

Parameters

TWorldId &aId On return, contains the ID of the last country.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

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

Description

Initialises the parameters for a next city search.

To start the search, use the NextNearestCity() function.

Parameters

const TPoint &aMapCoord The map co-ordinate in pixels for which the nearest city is to be found. const TWorldId *aCityToBeat The ID of the reference city. The search spans a specified number of cites, starting from this ID.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

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

Description

Gets 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.

Parameters

TWorldId &aId On return, contains the ID of the nearest city. TInt aMaxNumberToCompare The number of cities to compare in the search.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt NextCity(TWorldId &aId) const;

Description

Gets the ID of the next city, either in the current country or the whole world database, as defined by the select mode of aID.

The cities are ordered alphabetically.

Parameters

TWorldId &aId Specifies whether the search is over the whole database, or just in the current country. On return, contains the ID of the next city.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes. KErrNotFound is returned if this function is called when the current city is the last city.

Capability:

Illegal

IMPORT_C TInt NextCountry(TWorldId &aId) const;

Description

Gets the ID of the next country in the world database.

Note: the database is ordered alphabetically.

Country searches span the whole world database. This function ignores the search mode select state defined in aID.

Parameters

TWorldId &aId On return, contains the ID of the next country.

Return value

TInt KErrNone if successful, KErrNotFound when the current country is the last country, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt PrevCity(TWorldId &aId) const;

Description

Gets the ID of the previous city, either in the current country or in the whole world database, as defined by the Select mode of aID.

Note: the cities are ordered alphabetically.

Parameters

TWorldId &aId Specifies whether the search is over the whole database, or just the current country. On return, contains the ID of the previous city.

Return value

TInt KErrNone if successful, KErrNotFound when the current city is the first city, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt PrevCountry(TWorldId &aId) const;

Description

Gets the ID of the previous country in the world database.

Note: the database is ordered alphabetically.

Country searches span the whole world database. This function ignores the search mode select state defined in aID.

Parameters

TWorldId &aId On return, contains the ID of the previous country.

Return value

TInt KErrNone if successful, KErrNotFound when the current country is the first country, otherwise another of the system-wide error codes.

Capability:	WriteDeviceData
Capability:	WriteUserData

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

Description

Updates the information for a city.

The new information must be valid. Cities must be in a valid country, and have a valid DST zone. City names must be unique within a country, although the same city name may be used for cities in different countries.

Parameters

TWorldId &aId The ID of the city to be updated. const TCityData &aCity The new city information

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes. KErrArgument is returned if the updated city name overwrites an existing city, or if it isn't specified. It is also returned if the updated country name does not exist, or if the country name is not specified.

Capability:	WriteDeviceData
Capability:	WriteUserData

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

Description

Updates the data for a country.

Updated country names must be unique.

Parameters

TWorldId &aId The ID of the country to be updated. const TCountryData &aCountry The new country data.

Return value

TInt KErrNone if successful, KErrArgument is returned if the updated country name is not specified or if it is not unique, otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt GetCountryNameByISOCode(const TDesC &aCode, TDes &aCountry) const;

Description

Gets the country name for the given 2 character ISO country code.

Note: not all country names returned by this method represent countries in the World database.

ISO country codes are defined in ISO3166-1, and are most commonly used as country extensions in email addresses, e.g. UK, LU.

Parameters

const TDesC &aCode The ISO country code. TDes &aCountry On return, contains the name of the country.

Return value

TInt KErrNone if successful or KErrNotFound if there is an attempt to get a country name with an undefined country code. Otherwise another of the system-wide error codes.

Capability:

Illegal

IMPORT_C TInt SetCollationLevelForFind(TInt aCollationLevel);

Description

Set the collation level used by the RWorldServer::Find* functions

Parameters

TInt aCollationLevel

Return value

TInt