Class RWorldServer

RWorldServer

Support

Supported from 5.0

Description

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.

Derivation

RHandleBase Handle to an object RSessionBase Client-side handle to a session with a server RWorldServer Defines the world server's client side API

Defined in RWorldServer:
AddCity(), AddCountry(), CalculateDistance(), CalculateSunlight(), CityData(), Connect(), CountryData(), DataFileLocation(), DataFileOpen(), DataFileRevertToSaved(), DataFileSave(), DataFileSaveAs(), 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(), SetDefaultCountry(), SetDistanceUnits(), SetHome(), UpdateCity(), UpdateCountry(), Version()

Inherited from RHandleBase:
Close(), Duplicate(), Handle(), SetHandle()

Inherited from RSessionBase:
Attach(), CreateSession(), EAutoAttach, EExplicitAttach, Send(), SendReceive(), SetRetry(), Share(), TAttachMode

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, which should be called when the server session is no longer required.

Return value

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

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

Return value

TVersion The version number.

Description

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.

Contains the functions used to add, update, and delete city information.

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 — though the same city 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 city 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.

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

Description

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.

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.

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

Description

Tests whether a given city can be deleted. Capital cities, the home city, and all 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 The ID of the city which is being queried.

Return value

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

TInt DeleteCity(TWorldId& aId);

Description

Deletes a city from the world database. Capital cities, the home city, and all cities from the read-only file cannot be deleted.

Note:

• An error will occur if an attempt is made to delete a city which cannot be, or is already, 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.

Description

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

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.

TInt FirstCity(TWorldId& aId) const;

Description

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

Notes:

•  The first city is the one with the lowest alphabetic order.

• A search in the country locale will display the first city in the country. A search in the world local gets the first city in the whole database.

Parameters

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

TInt NextCity(TWorldId& aId) const;

Description

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

Notes:

• The next city is the next within the selected locale, where the cities are ordered alphabetically.

• A search in the country locale will display the next city in the country. A search in the world locale gets the next city in the whole database.

Parameters

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

TInt PrevCity(TWorldId& aId) const;

Description

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

Notes:

• The previous city is the city before the current city within the selected locale, where the cities are ordered alphabetically.

• A search in the country locale will display the previous city within the country. A search in the world locale gets the previous city for the whole database.

Parameters

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 KErrNone if successful, KErrNotFound when the current city is the first city, otherwise another of the system-wide error codes.

TInt LastCity(TWorldId& aId) const;

Description

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

Notes:

• The last city is the one with the highest alphabetic order.

• A search in the country locale will display the last city in the country. A search in the world locale gets the last city in the whole database.

Parameters

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

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

Description

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.

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.

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

Description

To update or delete a country, the session must first obtain the correctTWldID. To add a country, a TCountryData is filled with the data and the server is called to add the information.

Contains the functions used to add, update, and delete country information.

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.

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

Description

Updates the data of an existing 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.

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

Description

Determines whether a given 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

TInt DeleteCountry(TWorldId& aId);

Description

Deletes a country from the world database.

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

Notes:

• An error will occur if an attempt is made to delete a country which is already 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.

Description

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

TInt NumberCountries() const;

Description

Gets the number of countries in the world database.

Return value

TInt The number of countries in the world database.

TInt FirstCountry(TWorldId& aId) const;

Description

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

Notes:

• The first country is the one with the lowest alphabetic order.

• Country searches are not locale specific — searches span the whole world database. This function ignores the search mode select state defined in the TWorldId.

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.

TInt NextCountry(TWorldId& aId) const;

Description

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

Notes:

• The next country is the country after the current country, where the database is ordered alphabetically.

• Country searches are not locale specific — searches span the whole world database. This function ignores the search mode select state defined in the TWorldId.

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

TInt PrevCountry(TWorldId& aId) const;

Description

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

Notes:

• The previous country is the country preceding the current country, where the database is ordered alphabetically.

• Country searches are not locale specific — searches span the whole world database. This function ignores the search mode select state defined in the TWorldId.

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.

TInt LastCountry(TWorldId& aId) const;

Description

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

Notes:

• The last country in the database is the one with the highest alphabetic order.

• Country searches are not locale specific — searches span the whole world database. This function ignores the search mode select state defined in the TWorldId.

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.

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

Description

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.

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 A descriptor containing the search string, or partial country name.

Return value

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

Description

This section describes the functions which can be used to locate, import, export, and delete the effects of data files.

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.

TInt DataFileLocation(TFileName& aDataFile) const;

Description

Gets the location of the most recently imported user data file.

Parameters

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

Return value

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

TInt DataFileOpen(const TDesC& aDataFile);

Description

Allows clients to import a specified world database data file.

Parameters

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

Return value

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

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.

TInt DataFileSave();

Description

Saves the world database data — added by the user — to the current data file.

Notes:

• This function exports a world server data file.

• To save the file to another location, useDataFileSaveAs().

Return value

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

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

Description

Saves the world database data — added by the user — to a specified data file.

Parameters

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 KErrNone if successful, otherwise another of the system-wide error codes. KErrAlreadyExists is returned if the data file exists and aReplace is set to disallow overwriting.

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.

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.

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.

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.

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.

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.

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.

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

Support

Supported from 6.0

Description

Gets the country name for the given 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, au.

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.

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.

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.

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.

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=Time::NullTTime() The date for which the sunrise/sunset times are to be calculated.

Return value

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

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

Description

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

Parameters

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

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 theNearestCity() 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 spansKMaxTInt cities, which is effectively the entire database.

Parameters

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

void NotifyOnChange(TRequestStatus& aStatus);

Description

Provides notification of changes to the home city, default country, system time, and database files — asynchronous.

Parameters

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

void NotifyOnChangeCancel();

Description

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

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.