Public Types | Signals | Public Member Functions | Static Public Member Functions

MeeGo::QmTime Class Reference

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

#include <qmtime.h>

List of all members.

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.

Definition at line 77 of file qmtime.h.


Member Enumeration Documentation

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

Definition at line 112 of file qmtime.h.

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

Definition at line 120 of file qmtime.h.

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

Definition at line 98 of file qmtime.h.

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

Definition at line 105 of file qmtime.h.

Enumeration for change events for QmTime.

Enumerator:
TimeChanged 

System time (and possibly settings) changed

OnlySettingsChanged 

Settings changed, system time is not changed

Definition at line 91 of file qmtime.h.


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

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]

The documentation for this class was generated from the following file: