Class CTzLocalizer

class CTzLocalizer : public CBase;

Description

Retrieves localized time zone information based on a time zone ID.

Time zone information is available in the following forms:

• Standard Name, for instance Greenwich Mean Time,

• Short Standard Name, for instance GMT,

• Daylight Savings Name, for instance British Summer Time,

• Short Daylight Savings Name, for instance BST.

This information is encapsulated in a CTzLocalizedTimeZone object.

A collection of localizable cities for a specific time zone can also be returned. New cities can be added to a time zone. Cities may also be added to groups, but a city may only be a member of one group.

Derivation

• CBase - Base class for all classes to be instantiated on the heap

• CTzLocalizer - Retrieves localized time zone information based on a time zone ID

Members

Defined in CTzLocalizer:
AddCityL(), CheckLanguage(), ETzAlphaDaylightNameAscending, ETzAlphaDaylightNameDescending, ETzAlphaNameAscending, ETzAlphaNameDescending, ETzAlphaShortDaylightNameAscending, ETzAlphaShortDaylightNameDescending, ETzAlphaShortStandardNameAscending, ETzAlphaShortStandardNameDescending, ETzAlphaStandardNameAscending, ETzAlphaStandardNameDescending, ETzLocalizerPanicResourceFileNotFound, ETzLocalizerPanicTimeZoneServerNotFound, ETzUTCAscending, ETzUTCDescending, ETzUnsorted, FindCityByNameL(), FindCityGroupByNameL(), FindTimeZoneByNameL(), GetAllCityGroupsL(), GetAllTimeZonesL(), GetCitiesInGroupL(), GetCitiesInGroupL(), GetCitiesInGroupL(), GetCitiesL(), GetCitiesL(), GetCitiesL(), GetCitiesL(), GetCitiesWithUTCOffsetL(), GetCityGroupL(), GetCityGroupL(), GetDefaultCityL(), GetDefaultCityL(), GetDefaultCityL(), GetFrequentlyUsedZoneCityL(), GetFrequentlyUsedZoneL(), GetLocalizedTimeZoneL(), GetLocalizedTimeZoneL(), GetTimeZonesWithUTCOffsetL(), NewL(), NewLC(), RemoveCityL(), SetFrequentlyUsedZoneL(), SetFrequentlyUsedZoneL(), SetFrequentlyUsedZoneL(), SetTimeZoneL(), TTzLocalizerPanics, TTzSortOrder, ~CTzLocalizer()

Inherited from CBase:
Delete(), Extension_(), operator new()

See also

• timezonelocalization: Using Time Zone Localization

static IMPORT_C CTzLocalizer *NewL();

Description

Allocates and constructs a new CTzLocalizer object.

Return value

CTzLocalizer * The newly created CTzLocalizer object.

static IMPORT_C CTzLocalizer *NewLC();

Description

Allocates and constructs a new CTzLocalizer object. The pointer to the new object is left on the cleanup stack.

Return value

CTzLocalizer * The newly created CTzLocalizer object.

IMPORT_C ~CTzLocalizer();

Description

Destructor.

IMPORT_C CTzLocalizedTimeZone *GetLocalizedTimeZoneL(TInt aTimeZoneId) const;

Description

Gets the localized time zone that matches the time zone ID specified. The calling function takes ownership of the returned localized time zone.

Parameters

TInt aTimeZoneId A positive time zone ID of the localized time zone to return.

Return value

CTzLocalizedTimeZone * The localized time zone.

IMPORT_C CTzLocalizedTimeZone *GetLocalizedTimeZoneL(const CTzLocalizedCity &aCity) const;

Description

Gets the localized time zone that aCity is a member of. The calling function takes ownership of the returned localized time zone.

Parameters

const CTzLocalizedCity &aCity Any city in the time zone to return.

Return value

CTzLocalizedTimeZone * The localized time zone.

IMPORT_C CTzLocalizedTimeZoneArray *GetAllTimeZonesL(const TTzSortOrder aSortOrder=ETzUnsorted);

Description

Gets an array of all available localizable time zones, sorted according to aSortOrder. The calling function takes ownership of the returned array.

Parameters

const TTzSortOrder aSortOrder Specifies the sort order of the returned array.

Return value

CTzLocalizedTimeZoneArray * Array of all available localizable time zones.

IMPORT_C void SetTimeZoneL(TInt aTimeZoneId);

Description

Sets the time zone in the time zone server to be that of the supplied time zone id. The current cached zone is also updated.

Parameters

TInt aTimeZoneId A positive time zone ID of the new time zone.

IMPORT_C CTzLocalizedCity *GetDefaultCityL(TInt aTimeZoneId) const;

Description

Gets the default city for the specified time zone. The calling function takes ownership of the returned city.

Parameters

TInt aTimeZoneId A positive time zone ID of the default city to return.

Return value

CTzLocalizedCity * The default city for the specified time zone.

IMPORT_C CTzLocalizedCity *GetDefaultCityL(const CTzLocalizedCity &aCity) const;

Description

Gets the default city for the time zone the specified city is a member of. The calling function takes ownership of the returned city.

Parameters

const CTzLocalizedCity &aCity Any city in the required time zone.

Return value

CTzLocalizedCity * The default city.

IMPORT_C CTzLocalizedCity *GetDefaultCityL(const CTzLocalizedTimeZone &aTimeZone) const;

Description

Gets the default city for the specified time zone. The calling function takes ownership of the returned city.

Parameters

const CTzLocalizedTimeZone &aTimeZone A time zone.

Return value

CTzLocalizedCity * The default city for the specified time zone.

IMPORT_C CTzLocalizedCityArray *GetCitiesL(const TTzSortOrder aSortOrder=ETzUnsorted);

Description

Returns all cities defined in the static and persisted data. The calling function takes ownership of the returned array.

Parameters

const TTzSortOrder aSortOrder Specifies the order in which the returned array will be sorted. It can have one of the following values: ETzUnsorted, ETzUTCAscending, ETzUTCDescending, ETzAlphaNameAscending, or ETzAlphaNameDescending.

Return value

CTzLocalizedCityArray * Pointer to the array of cities.

IMPORT_C CTzLocalizedCityArray *GetCitiesL(TInt aTimeZoneId, const TTzSortOrder aSortOrder=ETzUnsorted);

Description

Gets all the cities defined in the static and persisted data that belong to the time zone identified by aTimeZoneId. The calling function takes ownership of the returned array.

Parameters

TInt aTimeZoneId A positive time zone ID that identifies the time zone of the cities to return. const TTzSortOrder aSortOrder Defines the order in which the returned array will be sorted. It can have one of the following values: ETzUnsorted, ETzAlphaNameAscending, ETzAlphaNameDescending.

Return value

CTzLocalizedCityArray * A pointer to the array of cities.

Leave codes

KErrArgument An invalid sort order is specified.

IMPORT_C CTzLocalizedCityArray *GetCitiesL(const CTzLocalizedTimeZone &aTimeZone, const TTzSortOrder aSortOrder=ETzUnsorted);

Description

Gets all the cities defined in the static and persisted data that belong to aTimeZone. The calling function takes ownership of the array.

Parameters

const CTzLocalizedTimeZone &aTimeZone The required time zone const TTzSortOrder aSortOrder Specifies the order in which the returned array will be sorted

Return value

CTzLocalizedCityArray * A pointer to the array of cities.

IMPORT_C CTzLocalizedCityArray *GetCitiesL(const CTzLocalizedCity &aCity, const TTzSortOrder aSortOrder=ETzUnsorted);

Description

Gets all the cities defined in the static and persisted data that belong to the same time zone as aCity. The calling function takes ownership of the returned array.

Parameters

const CTzLocalizedCity &aCity Any city in the desired time zone. const TTzSortOrder aSortOrder Specifies the order in which the returned array will be sorted.

Return value

CTzLocalizedCityArray * A pointer to the array of cities.

IMPORT_C CTzLocalizedCity *AddCityL(TInt aTimeZoneId, const TDesC &aCityName, TInt aGroupId=0);

Description

Creates a user defined city, specifying the time zone and optionally the group to which it belongs.

Parameters

TInt aTimeZoneId A positive time zone ID of the city to add. const TDesC &aCityName The name of the city to add. TInt aGroupId The ID of the city group to add the city to. Zero if the city doesn't belong to a group. Currently supports up to 255 groups

Return value

CTzLocalizedCity * The newly created city. The calling function takes ownership.

Leave codes

KErrAlreadyExists The specified city already exists in the time zone. KErrNotFound aTimeZoneId or aGroupId is not found. KErrArgument aGroupId is invalid

IMPORT_C void RemoveCityL(CTzLocalizedCity *aCity);

Description

Removes a city from the user defined city collection. The calling function loses ownership of aCity.

Parameters

CTzLocalizedCity *aCity The city to remove.

IMPORT_C CTzLocalizedCityGroupArray *GetAllCityGroupsL(const TTzSortOrder aSortOrder=ETzUnsorted) const;

Description

Gets a list of all the existing city groups. The calling function takes ownership of the returned array.

Parameters

const TTzSortOrder aSortOrder Specifies the order in which the returned array will be sorted. Possible values are ETzAlphaNameAscending or ETzAlphaNameDescending.

Return value

CTzLocalizedCityGroupArray * Array of all existing city groups.

IMPORT_C CTzLocalizedCityGroup *GetCityGroupL(TInt aGroupId) const;

Description

Gets the city group with the specified ID. The calling function takes ownership of the returned CTzLocalizedCityGroup.

Parameters

TInt aGroupId The ID of the city group to get.

Return value

CTzLocalizedCityGroup * The matching city group.

Leave codes

KErrArgument aGroupId is invalid

IMPORT_C CTzLocalizedCityGroup *GetCityGroupL(const CTzLocalizedCity &aCity) const;

Description

Gets the city group to which the specified city belongs. The calling function takes ownership of the returned CTzLocalizedCityGroup.

Parameters

const CTzLocalizedCity &aCity Any city in the required city group.

Return value

CTzLocalizedCityGroup * The city group.

IMPORT_C CTzLocalizedCityArray *GetCitiesInGroupL(TInt aGroupId, const TTzSortOrder aSortOrder=ETzUnsorted);

Description

Returns all cities defined in the static and persisted data that are members of the group with the specified group ID. The calling function takes ownership of the array.

Parameters

TInt aGroupId The group ID. const TTzSortOrder aSortOrder Specifies the order in which the returned array will be sorted. The following sort orders are supported: ETzUnsorted, ETzUTCAscending, ETzUTCDescending, ETzAlphaNameAscending, ETzAlphaNameDescending.

Return value

CTzLocalizedCityArray * Pointer to the array of cities.

Leave codes

KErrArgument aGroupId is invalid

IMPORT_C CTzLocalizedCityArray *GetCitiesInGroupL(const CTzLocalizedCity &aCity, const TTzSortOrder aSortOrder=ETzUnsorted);

Description

Returns all cities defined in the static and persisted data that are members of the same group as the specified city. The calling function takes ownership of the array.

Parameters

const CTzLocalizedCity &aCity Any city in the desired city group. const TTzSortOrder aSortOrder Specifies the order in which the returned array will be sorted. The following sort orders are supported: ETzUnsorted, ETzUTCAscending, ETzUTCDescending, ETzAlphaNameAscending, ETzAlphaNameDescending.

Return value

CTzLocalizedCityArray * Pointer to an array of cities.

IMPORT_C CTzLocalizedCityArray *GetCitiesInGroupL(const CTzLocalizedCityGroup &aCityGroup, const TTzSortOrder aSortOrder=ETzUnsorted);

Description

Returns all cities defined in the static and persisted data that are members of the specified city group. The calling function takes ownership of the array.

Parameters

const CTzLocalizedCityGroup &aCityGroup The city group of interest. const TTzSortOrder aSortOrder Specifies the order in which the returned array will be sorted. The following sort orders are supported: ETzUnsorted, ETzUTCAscending, ETzUTCDescending, ETzAlphaNameAscending, ETzAlphaNameDescending.

Return value

CTzLocalizedCityArray * Pointer to an array of cities.

IMPORT_C CTzLocalizedTimeZone *GetFrequentlyUsedZoneL(const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone);

Description

Gets the cached time zone identified by aFrequentlyUsedZone. The calling function takes ownership of the returned zone. When retrieving the current zone (CTzLocalizedTimeZone::ECurrentZone), the time zone server is queried to make sure that the system's current time zone has not been updated since the current zone was cached. If the system's time zone has been updated, the new localised zone is stored in the database.

Parameters

const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone Identifies the cached zone to return.

Return value

CTzLocalizedTimeZone * The cached zone.

IMPORT_C CTzLocalizedCity *GetFrequentlyUsedZoneCityL(const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone);

Description

Gets the city that was used to set the specified cached time zone. The calling function takes ownership of the returned city. If a city was not used to set the cached zone, the default city for the zone is returned.

Parameters

const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone Indicates one of the five cached zones.

Return value

CTzLocalizedCity * The city used to set the cached zone.

IMPORT_C void SetFrequentlyUsedZoneL(TInt aTimeZoneId, const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone);

Description

Sets the ID of the specified cached time zone.

Parameters

TInt aTimeZoneId A positive time zone ID to assign to aFrequentlyUsedZone. Must not be zero or the function leaves with KErrArgument. const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone Identifies the cached zone whose ID will be set. This must be either CTzLocalizedTimeZone::ECurrentZone, CTzLocalizedTimeZone::EHomeZone or CTzLocalizedTimeZone::EInterestZone, or the function leaves with KErrArgument. N.B. When the current zone is set, the time zone of the device is altered.

IMPORT_C void SetFrequentlyUsedZoneL(const CTzLocalizedTimeZone &aTimeZone, const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone);

Description

Sets the value of the specified cached time zone.

Parameters

const CTzLocalizedTimeZone &aTimeZone The value to assign to aFrequentlyUsedZone. It must have an ID greater than zero or the function leaves with KErrArgument. const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone Identifies the cached zone whose ID will be set. This must be either CTzLocalizedTimeZone::ECurrentZone, CTzLocalizedTimeZone::EHomeZone or CTzLocalizedTimeZone::EInterestZone, or the function leaves with KErrArgument. N.B. When the current zone is set, the time zone of the device is altered.

IMPORT_C void SetFrequentlyUsedZoneL(const CTzLocalizedCity &aCity, const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone);

Description

Sets the value of the specified cached zone to be the zone which aCity is located in. Setting a cached zone by city also stores the city used to select the time zone.

Parameters

const CTzLocalizedCity &aCity Any city in the time zone to set. It must have a time zone ID greater than zero or the function leaves with KErrArgument. const CTzLocalizedTimeZone::TTzFrequentlyUsedZone aFrequentlyUsedZone Indicates which of the cached zones to set. This must be either CTzLocalizedTimeZone::ECurrentZone, CTzLocalizedTimeZone::EHomeZone or CTzLocalizedTimeZone::EInterestZone, or the function leaves with KErrArgument. N.B. When the current zone is set, the time zone of the device is altered.

IMPORT_C CTzLocalizedCity *FindCityByNameL(const TDesC &aCityName, const TInt aTimeZoneId=0);

Description

Searches for a city with the specified name. If a time Zone ID is also specified, then the search only covers cities in that time zone. Otherwise, all time zones are searched. The first matching city is returned.

Parameters

const TDesC &aCityName Name of the city to search for. const TInt aTimeZoneId (Optional) A positive time zone ID of the city to search for. Specify zero to omit.

Return value

CTzLocalizedCity * If successful, a pointer to a CTzLocalizedCity. The calling function takes ownership of the returned pointer. If the search string is not found, NULL is returned.

Leave codes

KErrNotFound The specified time zone ID does not exist.

IMPORT_C CTzLocalizedTimeZone *FindTimeZoneByNameL(const TDesC &aTimeZoneName);

Description

Searches for a time zone with the specified name. All text fields of the time zone are searched.

Parameters

const TDesC &aTimeZoneName the name of the time zone to search for.

Return value

CTzLocalizedTimeZone * If successful, a pointer to a CTzLocalizedTimeZone. The calling function takes ownership of the returned pointer. If the search string is not found, NULL is returned.

IMPORT_C CTzLocalizedCityGroup *FindCityGroupByNameL(const TDesC &aCityGroupName);

Description

Searches for a city group with the specified name.

Parameters

const TDesC &aCityGroupName The name of the city group to search for.

Return value

CTzLocalizedCityGroup * If successful, a pointer to a CTzLocalizedCityGroup. The calling function takes ownership of the returned pointer. If the search string is not found, NULL is returned.

IMPORT_C TBool CheckLanguage();

Description

Tests whether the language of the loaded static data is still correct. If it is not, the static data is reloaded.

Return value

TBool ETrue if the system language (as returned by User::Language()) has changed, EFalse if it has not.

See also:

• User::Language()

IMPORT_C CTzLocalizedCityArray *GetCitiesWithUTCOffsetL(TInt aUTCOffsetInMinutes, const TTzSortOrder aSortOrder=ETzUnsorted);

Description

Returns all cities defined in the static and persisted data that have the specified UTC offset. The calling function takes ownership of the array.

Parameters

TInt aUTCOffsetInMinutes The offset in minutes. const TTzSortOrder aSortOrder Specifies the order in which the returned array will be sorted. Only ETzUnsorted, ETzAlphaNameAscending and ETzAlphaNameDescending will have any effect, as all elements in the returned array will have the same UTC offset.

Return value

CTzLocalizedCityArray * Pointer to the array of cities.

IMPORT_C CTzLocalizedTimeZoneArray *GetTimeZonesWithUTCOffsetL(TInt aUTCOffsetInMinutes, const TTzSortOrder aSortOrder=ETzUnsorted);

Description

Returns all the time zones defined in the static data that have the specified UTC offset. The calling function takes ownership of the array.

Parameters

TInt aUTCOffsetInMinutes The UTC offset in minutes. const TTzSortOrder aSortOrder Specifies the order in which the returned array will be sorted. Sort orders ETzUTCAscending and ETzUTCDescending will not have any effect as all elements in the returned array will have the same UTC offset.

Return value

CTzLocalizedTimeZoneArray * Pointer to the array of time zones.

TTzLocalizerPanics

Description

Panic reasons for the time zone localization component.

ETzLocalizerPanicTimeZoneServerNotFound The time zone server was not found. ETzLocalizerPanicResourceFileNotFound A resource file was not found.

TTzSortOrder

Description

Used to specify the sort order of localized time zone information.

ETzUnsorted Unsorted. This is the fastest way to get localized data. ETzUTCAscending Sort by UTC offset starting with the lowest. ETzUTCDescending Sort by UTC offset starting with the highest. ETzAlphaNameAscending Sort by name (city name/group name/standard time zone name), from A-Z. ETzAlphaNameDescending Sort by name (city name/group name/standard time zone name), from Z-A. ETzAlphaStandardNameAscending Sort by standard name from A-Z. ETzAlphaDaylightNameAscending Sort by daylight savings name from A-Z. ETzAlphaShortStandardNameAscending Sort by short standard name from A-Z. ETzAlphaShortDaylightNameAscending Sort by short daylight savings name from A-Z. ETzAlphaStandardNameDescending Sort by standard name from Z-A. ETzAlphaDaylightNameDescending Sort by daylight savings name from Z-A. ETzAlphaShortStandardNameDescending Sort by short standard name from Z-A. ETzAlphaShortDaylightNameDescending Sort by short daylight savings name from Z-A.