Provides interface for interacting with system clock. More...

Inheritance diagram for MeeGo::QmTime:

Collaboration diagram for MeeGo::QmTime:

Public Types
enum	WhatChanged { TimeChanged, OnlySettingsChanged }
enum	DisconnectionPolicy { DisconnectWhenPossible, KeepConnected }
enum	SettingsSynchronizationPolicy { SynchronizeOnWrite, WaitForSignal }
enum	AutoSystemTimeStatus { AutoSystemTimeOff, AutoSystemTimeOn, AutoSystemTimeUnknown }
enum	AutoTimeZoneStatus { AutoTimeZoneOff, AutoTimeZoneOn, AutoTimeZoneUnknown }
Signals
void	timeOrSettingsChanged (MeeGo::QmTime::WhatChanged what)
void	timeOrSettingsChanged (MeeGo::QmTimeWhatChanged what)
Public Member Functions
	QmTime (QObject *parent=NULL)
virtual	~QmTime ()
bool	synchronize ()
enum AutoSystemTimeStatus	autoSystemTime ()
bool	setAutoSystemTime (enum AutoSystemTimeStatus new_status)
enum AutoTimeZoneStatus	autoTimeZone ()
bool	setAutoTimeZone (enum AutoTimeZoneStatus new_status)
bool	setTime (time_t time)
	Set current system and RTC date and time.
bool	setTimezone (const QString tz)
bool	getTimezone (QString &tz)
bool	getAutoTimezone (QString &tz)
time_t	getAutoTime ()
bool	isOperatorTimeAccessible (bool &result)
bool	deviceDefaultTimezone (QString &default_timezone)
int	getTimeDiff (time_t t, const QString &location1, const QString &location2)
bool	setTime (const QDateTime &time)
	Deprecated, use setTime(time_t) instead.
Static Public Member Functions
static bool	setDisconnectionPolicy (DisconnectionPolicy p)
static bool	setSynchronizationPolicy (SettingsSynchronizationPolicy p)
static bool	remoteTime (const QString &tz, time_t t, QDateTime &dt, struct tm *p=NULL)
static bool	localTime (time_t t, QDateTime &dt, struct tm *p=NULL)

Detailed Description

Provides interface for interacting with system clock.

Scope:: Nokia Meego

Setting the time should always be done through QmTime to ensure proper signalling to other applications.

Member Enumeration Documentation

enum MeeGo::QmTime::AutoSystemTimeStatus

Status of the automatic system time setting

Enumerator:

AutoSystemTimeOff	System time is set manually by a user
AutoSystemTimeOn	System time is set automatically
AutoSystemTimeUnknown	Status unknown

enum MeeGo::QmTime::AutoTimeZoneStatus

Status of the automatic time zone guess

Enumerator:

AutoTimeZoneOff	Time zone of the device guessed automatically
AutoTimeZoneOn	Time zone of the device is set manually by a user
AutoTimeZoneUnknown	Status unknown

enum MeeGo::QmTime::DisconnectionPolicy

Policy regarding disconnection from time daemon

Enumerator:

DisconnectWhenPossible	Time/settings change notification will be dropped if no QmTime object exists (default)
KeepConnected	The connection will be kept until policy change or process exit

enum MeeGo::QmTime::SettingsSynchronizationPolicy

Policy regarding disconnection from time and gconf daemons

Enumerator:

SynchronizeOnWrite	Every call changing time settings will be followed by settings synchronization D-Bus call
WaitForSignal	Settings will be retrieved only after arrival of the D-Bus signal

enum MeeGo::QmTime::WhatChanged

Enumeration for change events for QmTime.

Enumerator:

TimeChanged	System time (and possibly settings) changed
OnlySettingsChanged	Settings changed, system time is not changed

Constructor & Destructor Documentation

MeeGo::QmTime::QmTime ( QObject * parent = NULL )

virtual MeeGo::QmTime::~QmTime ( ) [virtual]

Member Function Documentation

enum AutoSystemTimeStatus MeeGo::QmTime::autoSystemTime ( )

Get the state of automatic system time setting

Note:: Currently only automatic time setting based on network operator NITZ signal is supported, more time sources may be added in the future

Returns:: AutoSystemTimeOn if enabled, AutoSystemTimeOff if disabled, AutoSystemTimeUnknown on errors

enum AutoTimeZoneStatus MeeGo::QmTime::autoTimeZone ( )

Get the state of automatic time zone guessing

Note:: Currently only automatic time zone setting based on cellular network information is supported, more time zone sources may be added in the future

Returns:: AutoTimeZoneOn if enabled, AutoTimeZoneOff if disabled, AutoTimeZoneUnknown on errors

bool MeeGo::QmTime::deviceDefaultTimezone ( QString & default_timezone )

Get default time zone defined during device manufacture

Parameters:

default_timezone

a reference to a string variable to store the result

Returns:: True if information successfully retrieved

time_t MeeGo::QmTime::getAutoTime ( )

Get time received from automatic time source

Returns:: time_t value: amount of seconds after unix epoch begin (time_t)(-1) if automatic time is not available

bool MeeGo::QmTime::getAutoTimezone ( QString & tz )

Get automatically guessed time zone

Parameters:

tz

a reference to a string variable to store the result

Note:: Currently only automatic time zone guess based on cellular network information is supported, more time zone sources may be added in the future

Returns:: true if information succesfully retrieved and stored in the variable

int MeeGo::QmTime::getTimeDiff	(	time_t	t,
		const QString &	location1,
		const QString &	location2
	)

Get time difference between two locations at given moment of time

Parameters:

	t	The moment at which the difference should be calculated.
	location1	The time zone representing the first remote location
	location2	The time zone representing the second remote location

If either first or second location is empty, the current device timezone is used

Returns:: Local time difference between the locations in seconds, positive if the location1 is to the east of location2 -1 is returned on errors

bool MeeGo::QmTime::getTimezone ( QString & tz )

Get current time zone.

Parameters:

tz

a reference to a string variable to store the result

Returnes a current time zone. See the description of setTimezone() method above.

Returns:: True if time zone is set

bool MeeGo::QmTime::isOperatorTimeAccessible ( bool & result )

Get info if the device supports time updates from cellular network operator.

Parameters:

result

a reference to a boolean variable to store the result

Returns:: True if information successfully retrieved

static bool MeeGo::QmTime::localTime	(	time_t	t,
		QDateTime &	dt,
		struct tm *	p = `NULL`
	)			`[static]`

Calculate local time (in current timezone)

Parameters:

	t	time in seconds from the Unix epoch begin
	dt	a reference to variable to save broken down time representation
	p	pointer to save struct tm providing low level details, NULL if not needed

Returns:: True if information successfully retrieved

static bool MeeGo::QmTime::remoteTime	(	const QString &	tz,
		time_t	t,
		QDateTime &	dt,
		struct tm *	p = `NULL`
	)			`[static]`

Calculate local time in given timezone

Parameters:

	tz	the time zone
	t	time in seconds from the Unix epoch begin
	dt	a reference to variable to save broken down time representation
	p	pointer to save struct tm providing low level details, NULL if not needed

Returns:: True if information successfully retrieved

bool MeeGo::QmTime::setAutoSystemTime ( enum AutoSystemTimeStatus new_status )

Set the state of automatic system time setting

Credential:: timed::TimeControl Resource token required to set the network time autosync mode.

Note:: This method doesn't affect automatic setting of time zones; Currently only automatic time setting based on network operator NITZ signal is supported, more time sources may be added in the future; Switching off the automatic time setting doesn't affect current system time

Parameters:

new_status

AutoSystemTimeOn to enable, AutoSystemTimeOff to disable

Returns:: True if successfully set

bool MeeGo::QmTime::setAutoTimeZone ( enum AutoTimeZoneStatus new_status )

Set the state of automatic time zone guessing

Credential:: timed::TimeControl Resource token required to set the network time autosync mode.

Note:: This method doesn't affect automatic setting of system time; Currently only automatic time zone setting based on cellular network information is supported, more time zone sources may be added in the future; Switching off the automatic time zone setting could cause change of current time zone. Currently the time zone value is set to the last manual set time zone, if known and to device's default time zone otherwise. This behaviour could chagnge in the future.

Parameters:

new_status

AutoTimeZoneOn to enable, AutoTimeZoneOff to disable

Returns:: True if successfully set

static bool MeeGo::QmTime::setDisconnectionPolicy ( DisconnectionPolicy p ) [static]

Set the policy of disconnection from daemon signals

Note:: Disconnection policy is defined application-wide; Default policy is QmTime::KeepConnected

Parameters:

p QmTime::DisconnectWhenPossible if the application is not interested in status updates during its life time QmTime::KeepConnected to reduce amount of D-Bus traffic during QmTime object construction

Returns:: true if successfully set

static bool MeeGo::QmTime::setSynchronizationPolicy ( SettingsSynchronizationPolicy p ) [static]

Set settings synchronization policy

Note:: Synchronization policy is defined application-wide; Default policy is QmTime::WaitForSignal

Parameters:

p QmTime::SynchronizeOnWrite to execute synchronize() after every call changing settings QmTime::WaitForSignal to avoid it

Returns:: true if successfully set

bool MeeGo::QmTime::setTime ( const QDateTime & time )

Deprecated, use setTime(time_t) instead.

Deprecated:

bool MeeGo::QmTime::setTime ( time_t time )

Set current system and RTC date and time.

Credential:: timed::TimeControl Resource token required to set the device time.

Note:: This method (if successful) will switch off the automatic time update

Parameters:

time

The new system time.

Returns:: True if time is successfully set.

bool MeeGo::QmTime::setTimezone ( const QString tz )

Set current time zone.

Credential:: timed::TimeControl Resource token required to set the device time zone.

Parameters:

tz

Time zone

The following two formats are accepted:

1) Geographical entry in the Olson database (almost all of them). 2) Zones with a fixed GMT offset as described by ISO 8601

The full list of all valid time zones can be found in /usr/share/tzdata-timed/zone.alias file (binary package 'tzdata-timed', source package 'tzdata')

Even if a string is accepted as input for this method, it doesn't mean that the timezone will be set accordingly: If a string is just an alias (listed as a non-first word of line in the above file), then the time zone will be set to the main name of the time zone (listed as the first word in the same line).

Examples: setTimezone('Europe/Helsinki') sets the time zone to 'Europe/Helsinki' setTimezone('Asia/Calcutta') sets the time zone to 'Asia/Kolkata' setTimezone('Israel') sets the time zone to 'Asia/Jerusalem' setTimezone('Universal') sets the time zone to 'Iso8601/+0000' setTimezone('Etc/GMT-3') sets the time zone to 'Iso8601/+0300' setTimezone('Iso8601/-03:45') sets the time zone to 'Iso8601/-0345'

The above examples are purely informative. The content of the zone.alias reflects the set of supported time zones, and can be changed with a new tzdata version.

Note:: This method (if successful) will switch off the automatic timezone update

Returns:: True if zone was succesfully set, or false if not.

bool MeeGo::QmTime::synchronize ( )

Requests settings from time daemon

Note:: Usually you don't have to call this function

Returns:: true if successfully done

void MeeGo::QmTime::timeOrSettingsChanged ( MeeGo::QmTime::WhatChanged what ) [signal]

Sent when system time or settings have changed.

Parameters:

what

What has changed

void MeeGo::QmTime::timeOrSettingsChanged ( MeeGo::QmTimeWhatChanged what ) [signal]

MeeGo::QmTime Class Reference

Public Types

Signals

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation