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()Adds a new city to the world database
• AddCountry()Adds a new country, with its capital city, to the world database
• CalculateDistance()Calculates the distance between two cities, using the currently selected distance units
• CalculateSunlight()Gets a city's sunset and sunrise time on a specified date
• CityData()Gets the city data associated with the specified ID
• Connect()Connects the client process to the world server
• CountryData()Gets the country data associated with the specified ID
• DataFileRevertToSaved()Reverts the world database to its state when the data file was last saved, discarding data which was not saved
• DataFileSave()Saves the data added by the user, to the current world database
• DefaultCountry()Gets the ID of the default country
• DeleteCity()Deletes a city from the world database
• DeleteCountry()Deletes a country from the world database
• DistanceUnits()Gets the distance units used by the session
• Find()Finds the ID of the city which precisely matches the specified city and country names
• FindCity()Finds the ID of the first city that has a name which starts with the specified search string
• FindCountry()Finds the ID of the first country whose name starts with the specified search string
• FirstCity()Gets the ID of the first city found, either in the current country or the whole world database
• FirstCountry()Gets the ID of the first country in the world database
• GetCountryNameByISOCode()Gets the country name for the given 2 character ISO country code
• Home()Gets the ID of the home city
• IsCityDeletable()Tests whether a specified city can be deleted
• IsCountryDeletable()Tests whether a specified country can be deleted
• LastCity()Gets the ID of the last city found, either in the current country or the whole world database
• LastCountry()Gets the ID of the last country in the world database
• NearestCity()Initialises the parameters for a next city search
• NextCity()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
• NextCountry()Gets the ID of the next country in the world database
• NextNearestCity()Gets the results of a search for the city nearest to a map co-ordinate
• NotifyOnChange()Provides notification of changes to the home city, default country, system time, or database files, asynchronously
• NotifyOnChangeCancel()Cancels an outstanding notification request made using NotifyOnChange()
• NumberCities()Gets the number of cities in the world database
• NumberCountries()Gets the number of countries in the world database
• PrevCity()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
• PrevCountry()Gets the ID of the previous country in the world database
• ResetAllData()Resets the database to the state it had when first opened, and notifies the clients
• RomTitle()Gets the title of the currently loaded world database, which is defined in the read-only file
• SetCollationLevelForFind()Set the collation level used by the RWorldServer::Find* functions
• SetDefaultCountry()Sets the default country
• SetDistanceUnits()Sets the distance units used by the session
• SetHome()Sets the home city
• UpdateCity()Updates the information for a city
• UpdateCountry()Updates the data for a country
• Version()Gets the version number of the world server

Inherited from RHandleBase:

• Attributes()
• BTraceId()Returns a unique object identifier for use with BTrace
• Close()Closes the handle
• Duplicate()Creates a valid handle to the kernel object for which the specified thread already has a handle
• FullName()Gets the full name of the handle
• Handle()Retrieves the handle-number of the object associated with this handle
• HandleInfo()Gets information about the handle
• Name()Gets the name of the handle
• SetHandle()Sets the handle-number of this handle to the specified value
• SetHandleNC()Sets the handle-number of this handle to the specified value, and marks it as not closable
• iHandle

Inherited from RSessionBase:

• CreateSession()Creates a session with a server, specifying no message slots
• EAutoAttach
• EExplicitAttach
• Open()Opens a handle to a session using a handle number sent by a client to a server
• Send()Issues a blind request to the server with the specified function number, and arguments
• SendReceive()Issues an asynchronous request to the server with the specified function number and arguments
• SetReturnedHandle()Sets the handle-number of this handle to the specified value
• ShareAuto()Creates a session that can be shared by other threads in the current process
• ShareProtected()Creates a session handle that can be be passed via IPC to another process as well as being shared by other threads in the current process
• TAttachModeIndicates whether or not threads in the process are automatically attached to the session when passed as a parameter to the Share() function

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

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

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

IMPORT_C TInt NumberCities() const;

Description

Gets the number of cities in the world database.

Return value

IMPORT_C TInt NumberCountries() const;

Description

Gets the number of countries in the world database.

Return value

IMPORT_C void NotifyOnChange(TRequestStatus &aStatus);

Description

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

Parameters

IMPORT_C void NotifyOnChangeCancel();

Description

Cancels an outstanding notification request made using NotifyOnChange().

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

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

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

IMPORT_C TInt DefaultCountry(TWorldId &aCountry) const;

Description

Gets the ID of the default country.

Parameters

Return value

IMPORT_C TInt SetDefaultCountry(const TWorldId &aId);

Description

Sets the default country.

Parameters

Return value

IMPORT_C TInt Home(TWorldId &aHome) const;

Description

Gets the ID of the home city.

Parameters

Return value

IMPORT_C TInt SetHome(const TWorldId &aId);

Description

Sets the home city.

Parameters

Return value

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

Return value

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

Return value

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

Description

Gets the city data associated with the specified ID.

Parameters

Return value

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

Description

Gets the country data associated with the specified ID.

Parameters

Return value

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

Return value

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

Return value

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

Return value

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

Return value

IMPORT_C TInt DistanceUnits(TWldDistanceUnits &aDistanceUnit) const;

Description

Gets the distance units used by the session.

Parameters

Return value

IMPORT_C TInt SetDistanceUnits(TWldDistanceUnits aUnit);

Description

Sets the distance units used by the session.

Parameters

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Return value

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

Description

Updates the data for a country.

Updated country names must be unique.

Parameters

Return value

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

Return value

IMPORT_C TInt SetCollationLevelForFind(TInt aCollationLevel);

Description

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

Parameters

Return value