LIBTIMED(3)
===========


NAME
----
libtimed - library to communicate with the time daemon


SYNOPSIS
--------
[verse]
*#include <timed/interface>*

[verse]
*class Maemo::Timed::Interface ;*

[verse]
*#include <timed/wallclock>*

[verse]
*class Maemo::Timed::WallClock ;*
*class Maemo::Timed::WallClock::Info ;*
*class Maemo::Timed::WallClock::Settings ;*

[verse]
*#include <timed/event>*

[verse]
*class Maemo::Timed::Event ;*
*class Maemo::Timed::Event::Action ;*
*class Maemo::Timed::Event::Button ;*
*class Maemo::Timed::Event::Recurrence ;*
*class Maemo::Timed::Event::List ;*
*class Maemo::Timed::Event::Triggers ;*

[verse]
*class Maemo::Timed::Event::DBusReply ;*
*class Maemo::Timed::Event::DBusPendingReply ;*
*class Maemo::Timed::Event::List::DBusReply ;*
*class Maemo::Timed::Event::List::DBusPendingReply ;*

[verse]
*#include <timed/exception>*

[verse]
*class Maemo::Timed::Exception ;*


DAEMON INTERFACE
----------------

*class Maemo::Timed::Interface*::
  The class is a child class of QDBusAbstractInterface,
  representing the D-Bus interface to the time daemon.
  +
  bool *settings_changed_connect*(QObject &ast; object, const char &ast; slot) -
  connects the given object/slot pair to the D-Bus signal sent by the daemon
  in case of time setting change. Return value indicates if the connection was
  performed.
  +
  bool *settings_changed_disconnect*(QObject &ast; object, const char &ast; slot) -
  disconnects the given object/slot pair from the D-Bus signal sent by the daemon
  in case of time setting change. Returns true if the disconnection was
  successful.
  +
  The 'slot' must have the signature
  'void settings_changed(const Maemo::Timed::WallClock::Info &info, bool
  time_changed)'. If not, then the call will fail, no signal will be delivered, and a
  warning
  will be printed by Qt library (which is nowhere documented through).
  The meaning of the slot parameters: the Info structure is described below in
  'WALL CLOCK HANDLING'. The 'time_changed' flas is set iff the system time
  was changed (not only the settings).
  +
  bool *alarm_triggers_changed_connect*(QObject &ast; object, const char &ast; slot) -
  connects the given object/slot pair to the D-Bus signal sent by the daemon
  when alarm queue changes. Return value indicates if the connection was
  performed.
  +
  bool *alarm_triggers_changed_disconnect*(QObject &ast; object, const char &ast; slot) -
  disconnects the given object/slot pair from the D-Bus signal sent by the daemon
  when the alarm queue changes. Returns true if the disconnection was
  successful.
  +
  The 'slot' must have the signature
  'void alarm_triggers_changed(const Maemo::Timed::Event::Triggers)'.
  If not, then the call will fail, no signal will be delivered, and a
  warning
  will be printed by Qt library (which is nowhere documented through).
  The parameter 'Maemo::Timed::Event::Triggers' is a QMap<quint32,quint32>,
  where the keys are cookies and values trigger times as seconds since Unix epoch.
//  +
//  Qt signals provided by the class and mirroring the D-Bus signals sent by the
//  daemon:
//  +
//  daylight_saving_switched() - sent as the time in the current timezone was
//  switched from summer time to winter time or vice versa.
//  +
//  settings_changed(Maemo::Timed::WallClock::Info) - some of the settings are
//  changed. The Info class is a read only structure describing the setting of
//  the daemon concerning wall clock and timezone handling. See below for the
//  description of this structure.
  +
  For every method 'xxx' of the D-Bus interface
  described in 'timed(8)'
  the class has
  two member functions with the same parameter set:
  +
  QDBusMessage *xxx_sync*(...input parameters...) ;
  +
  QDBusPengingCall *xxx_async*(...input parameters...) ;
  +
  The former function is performing a synchronous D-Bus call and is returning the reply
  message. The method call return parameters can be retrieved by casting the
  returned message value to
  *QDBusReply<output_params>*,
  where 'output_params' is the list representing the output
  parameter types of the given D-Bus call.
  There is special case for get_event_sync and get_events_sync. The return for
  these methods can be retrieved by casting the returned message value to
  *Maemo::Timed::Event::DBusReply* and to
  *Maemo::Timed::Event::List::DBusReply* respectively. These are adapters
  above *QDBusReply* and behave very similar (see examples).
  +
  The latter function is starting an asynchronous D-Bus call and returning a Qt
  object needed to watch the call execution and to retrieve the return
  value (see the Qt documentation for class QDBusPendingCall for details).
  There is special case for get_event_async and get_events_async. The return for
  these methods can be retrieved by casting the returned pending call value to
  *Maemo::Timed::Event::DBusPendingReply* and to
  *Maemo::Timed::Event::List::DBusPendingReply* respectively. These are adapters
  above *QDBusPendingReply* and behave very similar (see examples).
  +
  For the detailed description of time daemon D-Bus interface methods and their parameters
  see the section DBUS in 'timed(8)' manual page.
  +
  The following list shows the usage of the synchronous interface functions.
  The type on the left side is _not_ the type of the returning value (which is
  always QDBusMessage), but more the suggested template parameters
  for the class QDBusReply<> needed to define the
  type for the return value to be casted to.
  The usage of the asynchronous equivalents is similar.
  +
  <Maemo::Timed::WallClock::Info> 'get_wall_clock_info_sync'() ;
  +
  <bool> 'wall_clock_settings_sync'(Maemo::Timed::WallClock::Settings) ;
  +
  <uint> 'add_event_sync'(Maemo::Timed::Event) ;
  +
  <bool> 'cancel_sync'(uint) ;
  +
  <Maemo::Timed::Event&> 'get_event_sync'(uint) ;
  +
  <Maemo::Timed::Event::List&> 'get_events_sync'(const QList<uint>&) ;
  +
  <uint> 'replace_event_sync'(Maemo::Timed::Event, uint) ;
  +
  <QList<QVariant>> 'query_sync'(QMap<QString,QVariant>) ;
  +
  <QMap<QString,QVariant>> 'query_attributes_sync'(uint) ;
  +
  <void> 'enable_alarms_sync'(bool) ;
  +
  <bool> 'alarms_enabled_sync'() ;
  +
  <bool> 'set_default_snooze_sync'(int) ;
  +
  <int> 'get_default_snooze_sync'() ;
  +
  <bool> 'dialog_response_sync'(uint, int) ;

    Example: ::
-----------------------
/* Perform synchronous call to 'pid' method */
Maemo::Timed::Interface ifc ;
QDBusReply<int> res = ifc.pid_sync() ;
if(res.isValid())
  cerr << "D-Bus call failed" << endl ;
else
  cout << "Time daemon pid is " << res.value() << endl ;
-----------------------


WALL CLOCK HANDLING
-------------------

Wall clock and time zone information in the time daemon::
  +
  The wall clock is represented in the time daemon by three entities and
  several flags.
  +
  First entity, the Unix time (called 'system time'
  as well) represents the current time according to the Coordinated Universal Time
  (abbreviated as 'UTC'). This is the only time known by the Linux kernel and
  usually represented by a 31 bit integer value (in seconds) or a double
  precision integer value (in nano-seconds) as a time elapsed from the begining
  of the year 1970.
  +
  Second entity, the symbolic timezone description, representing an entry in the
  'Olson database'. A database entry describes the rules how the local time
  at given location has to be calculated for given UTC time value. That
  includes the rules for 'Daylight Saving Time' (abbreviated as 'DST', also
  informally known as summer/winter time switch) for
  given location based on local legislation. The examples of the database
  entries are 'Euprope/Helsinki' and 'Asia/Jerusalem'.
  The Olson data is used for localtime calculation and automatic DST switch.
  +
  Third entity, the numerical offset between the local time and the UTC time,
  which is a multiple of a 15 minutes unit, usually positive to the east of
  Greenwich and negative to the west.
  This value is only used for calculation of the local time,
  if the user has explicitely disabled the automatic DST switching.
  +
  All these entities can be obtained from different sources,
  depending on the flags described below and availability of data sources.
  +
  Flag *time_nitz* - indicates that the UTC time should be obtained from
  the cellular network operator if available
  (NITZ is an abbreviation for 'Network
  Identity and Time Zone'). If the flag is set, but the NITZ is not available,
  the daemon falls back to manual settings.
  +
  Flags *time_gps* and *time_ntp* - are reserved for future use.
  +
  Flag *local_cellular* - indicated that the local time information should be
  obtained by the information given by the cellular network operator. As the
  NITZ is only providing the numerical offset information, the MCC (Mobile
  Network Code) information is used to deduce the current symbolic timezone,
  if possible. If this flag is not set, the user application (usually the
  Clock UI based on human input) is selecting the offset or symbolic timezone.
  If the flag is set, but the cellular network provider information
  is not available,
  the daemon falls back to manual settings.
  +
  Flag *auto_dst* - indicates, if the symbolic
  timezone names are in use (allowing the automatical UTC offset adjustment in
  spring or autumn), or the numerical UTC offset is used.

*class Maemo::Timed::WallClock*::
  +
  The class is a namespace container for clock handling types.
  +
  enum *Maemo::Timed::WallClock::UtcSource* { 'UtcManual', 'UtcNitz', 'UtcGps', 'UtcNtp' }
  -
  enumerates the sources of the system time.
  'UtcManual' represents the time set by any client application, usually (but not
  exclusively) it's the Clock UI based on user input.
  'UtcNitz'
  represents time received from the cellular network operator.
  The values 'UtcGps' and 'UtcNtp' (representing the time information received from the
  Global Positioning System and by Network Time Protocol respectively) are
  reserved for future use.
  +
  enum *Maemo::Timed::WallClock::TimezoneSource* { 'TimezoneManual', 'TimezoneCellular' }
  -
  enumerates the sources of the time zone information.
  'TimezoneManual' represents the symbolic time zone set by a client application,
  usually (but not
  exclusively) it's the Clock UI based on user input.
  'TimezoneCellular' represents
  the timezone information deduced from NITZ and MCC
  information given by the cellular network operator.
  +
  enum *Maemo::Timed::WallClock::OffsetSource* { 'OffsetManual', 'OffsetNitz' }
  -
  enumerates the sources of the time offset to UTC.
  'OffsetManual' represents
  the offset set by any client application, usually (but not
  exclusively) it's the Clock UI based on user input.
  'OffsetNitz' represents the time offset given by the network operator.

class *Maemo::Timed::WallClock::Info*::
  +
  is representing a read only structure containing information about current
  time settings. It's being sent to the client application either wenn
  explicitly requested by the 'get_wall_clock_info' D-Bus method, or by receiving
  the 'settings_changed' D-Bus signal.
  +
  Member functions:
  +
  bool *flagTimeNitz*() const - the value of 'time_nitz' flag decribed above.
  +
  bool *flagLocalCellular*() const - the value of 'local_cellular' flag decribed above.
  +
  bool *flagAutoDst*() const - the value of 'auto_dst' flag decribed above.
  +
  bool *flagFormat24*() const - whether or not the 24 hour time formatting
  (like 21:34) is in use (if not, 12 hour like "9:34pm" is used).
//  +
//  This method is a shortcut for 'utc(UtcSource())' - see below.
  +
  QString *etcLocaltime*() const - returnes the path to the time zone
  description file. Usually the '/etc/localtime' is a symbolic link to this
  value.
  +
  QString *humanReadableTz*() const - depending on the value of 'auto_dst'
  flag returns either the current entry in Olson database (like
  'Europe/Berlin'), or
  the string representation of the numerical offset in the form 'GMT+2',
  'GMT+5:30' and so on. The plus sign is used for the locations to the East of
  Greenwitch. The zero offset is not explicitely shown.
  +
  int *secondsEastOfGmt()* const - shows current offset to GMT in seconds.
  Positive values are in the East.
  +
  QString *tzAbbreviation()* const - the symbolic name of current time zone
  like 'EEST', 'MSK' an so on. It depends on location as well as on 'auto_dst'
  flag and sometimes on the current season.
  +
  time_t *utc*() const - returns the current UTC time according to the data
  received. Two consequent calls may return different time, because the data
  structure doesn'n contain exact time stamp, internaly the difference between
  the time and Linux monotinoc clock is stored. The return value should
  coincide with the Linux system time (unless the latter is changed).
  +
  Maemo::Timed::WallClock::UtcSource *utcSource*() const - returns the current
  source of the UTC time information. Note: even if 'time_nitz' flag is set,
  this function will return 'UtcManual' if the operator time is not available
  currently. The similar is true for the next two methods.
  +
  Maemo::Timed::WallClock::TimezoneSource *timezoneSource*() const - returns the
  current source of the symbolic timezone information.
  +
  Maemo::Timed::WallClock::OffsetSource *offsetSource*() const - returns the
  current source of the UTC offset information.
  +
  bool *utcAvalable*(Maemo::Timed::WallClock::UtcSource) const - indicates if
  the given UTC time source is currently available. The current source is
  always available. The 'UtcManual' source is always available as well.
  +
  bool *timezoneAvailable*(Maemo::Timed::WallClock::TimezoneSource) const - indicates if the
  given source of the symbolic timezone informaion is available. If the
  'auto_dst' flag is set, the current source is available.
  +
  bool *offsetAvailable*(Maemo::Timed::WallClock::OffsetSource) const -
  indicates if the given source of the UTC offset informaion is available.
  The current source is always available.
  +
  time_t *utc*(Maemo::Timed::WallClock::UtcSource) const - returns the current
  UTC time from the given source. If the given source is not available,
  returns the invalid value (time_t)(-1).
  Two consequent calls may return different time values as described above
  (see the 'utc()' method).
  +
  QString *timezone*(Maemo::Timed::WallClock::TimezoneSource) const -
  returns the timezone from given source, if available. If not, the null
  string is returned.
  +
  int *offset*(Maemo::Timed::WallClock::OffsetSource) const -
  returns the offset of the local time according to the given source.
  The value is amount of seconds, divisible by 900 (which is equivalent
  to 15min steps). If the source is not available, the special invalid value
  -1 is returned. Note: the valid value could be negative (in the west).
//  +
//  static QString *offsetStr*(int value) - converts the offset value
//  to a string representation like 'GMT' or 'GMT+2' or even
//  'GMT+5:30'. If the value is not valid (XXX: the list of all valid values can be
//  obtained who knows how, but I think, it will be some context property)
//  the null string is returned.
  +
  struct timespec *clockDiffNano*() - after the system time change is signalled,
  this method returnes the time difference between the old and the new system time
  (which is positive, if the clock was moved back). The
  'timespec' structure contains the time difference in nano-seconds,
  its fields are described in the manual page 'clock_gettime(2)'
  +
  time_t *clockDiff*() - the same value as above, rounded to the whole seconds.
  +
  QString *str*() const -
  returns a human readable representation of the structure
  usable for printing on a single line and debugging.
  The client application should never depend on this method,
  as sometimes an empty string could be returned.

class *Maemo::Timed::WallClock::Settings*::
  +
  is representing a write only structure
  used to change the current time settings.
  It's being sent by the client application
  to the time daemon by the 'wall_clock_settings'
  D-Bus call.
  +
  If many settings are to be changed, the client application is encouraged
  to fill all of them to a single instance of this structure and submit to
  the time daemon in a single call.
  Beside of reducing D-Bus usage, that procedure helps to avoid race
  conditions.
  +
  If the D-Bus method call is failed or rejected by the daemon,
  not a single setting will be changed. The failure could be
  detected by the return value, the exact reason is
  currently have to be found in daemon's log file.
  +
  Member functions:
  +
  void *setFlag24*(bool format24) - depending on the parameter set 12 or 24
  hours time
  formatting. This setting is shared by all applications on the device.
  +
  void *setTimeNitz*() - sets the flag 'time_nitz'
  +
  void *setTimeManual*() - clears the flag 'time_nitz'. It it was set before,
  and the network operator time is available, the manual time is set to the
  current value of network time.
  +
  void *setTimeManual*(time_t value) - clears the flag 'time_nitz'. Sets
  the manual time source to the given value, which must be valid.
  +
  void *setOffsetCellular*() - [THIS METHOD IS DEPRECATED, NEVER USE IT] sets the flag 'local_cellular' and clears the flag
  'auto_dst'. This method could be called to enable the automatical time zone
  tracking without automatocal DST switch.
  +
  void *setOffsetManual*() - [THIS METHOD IS DEPRECATED, NEVER USE IT] clears both the flags 'local_cellular' and
  'auto_dst'. Depending on the value of those flags before the call,
  the manual offset value is set to something. XXX: what exactly?
  +
  void *setOffsetManual*(int value) - [THIS METHOD IS DEPRECATED, NEVER USE IT] clears both flags 'local_cellular' and
  'auto_dst', the manual offset value is set according to the parameter.
  +
  void *setTimezoneCellular*() - set both the flags 'local_cellular' and
  'auto_dst'. If neither the manual nor the cellular timezone source is
  available, the manual timezone is to be set by guessing. The guess quality
  could be very low, thus calling of this method should be avoided in such
  case. If the application knows more about the location, the following
  method should be used instead.
  +
  void *setTimezoneCellular*(QString fallback_zone) - set both the flags
  'local_cellular' and 'auto_dst', set the source of the manual zone (which
  will be used unltil the cellular timezome is available) to the value of
  'fallback_zone' parameter. No guessing is performed.
  +
  void *setTimezoneManual*(QString zone) - set the flag 'auto_dst' and clear
  the flag 'local_cellular'. Set the value of 'zone' as the manual time zone
  source.
  +
  bool *check*() const - simple validity check. If it fails, the structure
  can't be submitted to the daemon. It the application try to submit it,
  an exception will occur. Even if this function returnes the true value,
  it can't be guaranteed that the daemon will accept the request, but
  the structure will be submitted via D-Bus without any exception thrown.
  +
  QString *str*() const -
  returns a human readable representation of the structure
  usable for printing on a single line and debugging.
  The client application should never relay on the return value,
  which can be even empty.
  +
  Note: the API doesn't contain a parameter-less method setTimezoneManual().
  XXX:  need an explanation here, why not and what to do.
  +
  Note: all three 'setTime...' functions are mutually exclusive. If the client
  is making more than one call to them, the structure becomes invalid.
  All six 'set{Offset,Timezone}...' functions are mutually exclusive as well.


EVENT HANDLING
--------------

*class Maemo::Timed::Event*::
  +
  The class represents a new event to be inserted to the event queue of the
  time daemon by the D-Bus method.
  +
  Member functions:
  +
  void *setTicker(time_t ticker)* - sets the trigger time counted in seconds
  after the beginning of the year 1970 AD (UTC). Even if a timezone is given for
  the event, the timezone information will be only used for the recurrencies
  calculation.
  +
  time_t *ticker()* const - gets the trigger time counted in seconds
  after the beginning of the year 1970 AD (UTC). Even if a timezone is given for
  the event, the timezone information will be only used for the recurrencies
  calculation.
  +
  void *setTime(unsigned year, unsigned month, unsigned day, unsigned hour,
  unsigned minute)* - sets the trigger time in the broken down representation.
  The calculation of the trigger time is performed according to the timezone set
  for the given event. If no timezone is set, the device timezone will
  be used, it means the trigger time will be changed, if the device timezone is
  changed.
  The input values must
  satisfy 1971<=year<=2037, month<=12, day<=31, hour<24, minute<60 and it's
  not allowed to specify non-existing dates like April, 31 or 1973-02-29.
  +
  unsigned *year()* const - gets year, set by *setTime* (see *setTime* for
  details).
  +
  unsigned *month()* const - gets month, set by *setTime* (see *setTime* for
  details).
  +
  unsigned *day()* const - gets day, set by *setTime* (see *setTime* for
  details).
  +
  unsigned *hour()* const - gets hour, set by *setTime* (see *setTime* for
  details).
  +
  unsigned *minute()* const - gets minute, set by *setTime* (see *setTime* for
  details).
  +
  unsigned *year()* const - gets year, set by *setTime* (see *setTime* for
  details).
  +
  void *setTimezone(QString tz)* - sets the timezone for the event. The timezone
  info is used first for the calculation of the trigger time (if the trigger
  time was given in the broken down representation). Then it's used for the
  calculation of the recurrencies.
  +
  const QString & *timezone()* const -gets the timezone for the event.
  +
  Maemo::Timed::Event::Action &amp; *addAction*() - adds a new action for the
  event and returns a reference to the action object.
  +
  int *actionsCount()* const - gets count of actions attached to the event.
  +
  Action & *action(int index)* - gets the requested action attached to the event.
  +
  void *removeAction(int index)* - removes the requested action.
  +
  void *clearActions()* - removes all actions attached to the event.
  +
  Maemo::Timed::Event::Button &amp; *addButton*() - adds a new application
  specific button to the
  notification dialog shown for the event and returns a reference to the
  button object. A custom dialog for the event will be shown if and only if
  the event has at least one button defined by this method. To show a system
  default dialog use the setReminderFlag() method.
  The maximal amount of application specific buttons of an event dialog is
  equal to (FIXME: I don't know how many exactly, a dozen maybe? Who cares,
  whatever). This value
  can be changed in the future, use the method 'getMaximalButtonAmount()' to retrieve it.
  +
  int *buttonsCount()* const - gets count of buttons attached to the event.
  +
  Button & *button(int index)* - gets the requested button attached to the
  event.
  +
  void *removeButton(int index)* - removes the requested button.
  +
  void *clearButtons()* - removes all buttons attached to the event.
  +
  Maemo::Timed::Event::Recurrence &amp; *addRecurrence*() - adds a new recurrence
  rule for the event and returns a reference to the recurrence rule object.
  +
  int *recurrencesCount()* const - gets count of recurrences attached to the
  event.
  +
  Recurrence & *recurrence(int index)* - gets the requested recurrence attached to
  the event.
  +
  void *removeRecurrence(int index)* - removes the requested recurrence.
  +
  void *clearRecurrences()* - removes all recurrences attached to the event.
  +
  static unsigned *getMaximalButtonAmount*() - returns the maximal
  possible amount of application specific buttons in the reminder dialog.
  +
  static unsigned *getSysButtonAmount*() - returns the amount
  of platform wide buttons in the reminder dialog. Currently this method returned 2 (one 'cancel'
  button and one 'snooze' button).
  +
  void *setAlarmFlag*() - sets the 'alarm' flag. All the events with this flag can be
  enabled (or disabled) at once by calling the D-Bus method
  'enable_alarms'. Usually the clock UI application should use this flag
  for the user defined wake up alarms; an alarm symbol should be shown to the human
  end user if there are any events with this flag queued.
  +
  bool *alarmFlag()* const - gets the 'alarm' flag (see *setAlarmFlag* for
  details).
  +
  void *clearAlarmFlag()* - clears the 'alarm' flag (see *setAlarmFlag* for
  details).
  +
  void *setTriggerIfMissedFlag()* - sets the flag enabling the triggering of
  the event even if its triiger time was missed by more than 59 seconds.
  Ususally such an event is not triggered.
  +
  bool *triggerIfMissedFlag()* const - gets the 'trigger if missed' flag (see
  *setTriggerIfMissedFlag* for details).
  +
  void *clearTriggerIfMissedFlag()* - clears the 'trigger if missed' flag (see
  *setTriggerIfMissedFlag* for details).
  +
  bool *triggerWhenAdjustingFlag()* const - gets the 'trigger when adjusting' flag
  (see *setTriggerWhenAdjustingFlag* for details).
  +
  void *clearTriggerWhenAdjustingFlag()* - clears the 'trigger when adjusting' flag
  (see *setTriggerWhenAdjustingFlag* for details).
  +
  bool *triggerWhenSettingsChangedFlag()* const - gets the 'trigger when
  settings changed' flag (see *setTriggerWhenSettingsChangedFlag* for details).
  +
  void *clearTriggerWhenSettingsChangedFlag()* - clears the 'trigger when
  settings changed' flag (see *setTriggerWhenSettingsChangedFlag* for details).
  +
  void *setUserModeFlag()* - disables the triggering of the event in the
  acting dead mode of the device.
  +
  bool *userModeFlag()* const - gets the 'user mode' flag (see *setUserModeFlag*
  for details).
  +
  void *clearUserModeFlag()* - clears the 'user mode' flag (see *setUserModeFlag*
  for details).
  +
  void *setAlignedSnoozeFlag()* - usually an event snoozed by human end user
  for 'N' seconds
  is triggered after exactly 'N' seconds after the human interaction. With
  this flag set the difference between the new trigger time and the snoozed
  trigger time has to be a multiply of snoozing time period 'N'.
  +
  bool *alignedSnoozeFlag()* const - gets the 'aligned snooze' flag (see
  *setAlignedSnoozeFlag* for details).
  +
  void *clearAlignedSnoozeFlag()* - clears the 'aligned snooze' flag (see
  *setAlignedSnoozeFlag* for details).
  +
  void *setReminderFlag()* - the event requires an end user notification
  provided by the notification service. This function is called by addButton()
  function, thus it's only has to be called explicitly for the default
  notification dialog.
  +
  bool *reminderFlag()* const - gets the 'reminder' flag (see *setReminderFlag*
  for details).
  +
  void *clearReminderFlag()* - clear the 'reminder' flag (see *setReminderFlag*
  for details).
  +
  void *setBootFlag()* - the event requires the device to be powered on and
  booted into the acting dead state 60 seconds before the trigger time, if the
  device is powered off before that.
  +
  bool *bootFlag()* const - gets the 'boot' flag (see *setBootFlag* for
  details).
  +
  void *clearBootFlag()* - clears the 'boot' flag (see (setBootFlag* for
  details).
  +
  void *setKeepAliveFlag*() - the event will not be removed until explicit
  requested by the application. It's possible to have an event with this flag without
  any triggering information (like broken down trigger time, ticker, timezone or
  recurrence patterns).
  +
  bool *keepAliveFlag()* const - gets the 'keep alive' flag (see
  *setKeepAliveFlag* for details).
  +
  void *clearKeepAliveFlag()* - clears the 'keep alive' flag (see
  *setKeepAliveFlag* for details).
  +
  void *setFakeFlag()* - alias for 'setKeepAliveFlag', never use this method.
  +
  void *setSingleShotFlag*() - any recurrence information will be removed after the
  first trigger.
  +
  bool *singleShotFlag()* const - gets the 'single shot' flag (see
  *setSingleShotFlag* for details).
  +
  void *clearSingleShotFlag()* - clears the 'single shot' flag (see
  *setSingleShotFlag* for details).
  +
  bool *backupFlag()* const - gets the 'backup' flag (see *setBackupFlag* for
  details).
  +
  void *clearBackupFlag()* - clears the 'backup' flag (see *setBackupFlag* for
  details).
  +
  void *suppressTimeoutSnooze()* - the notification dialog will not be snoozed
  after a minute.
  +
  bool *doSuppressTimeoutSnooze()* const - gets if the notification dialog will
  not be snoozed after a minute or not.
  +
  void *allowTimeoutSnooze()* - the notification dialog will be snoozed
  after a minute (set by default).
  +
  void *hideSnoozeButton1()* - do not include the default snooze button into
  the reminder dialog.
  +
  bool *doHideSnoozeButton1()* const - gets if the default snooze button is
  included into the reminder dialog.
  +
  void *showSnoozeButton1()* - include the default snooze button into the
  reminder dialog (set by default).
  +
  void *hideCancelButton2()* - do not include the default cancel button into
  the reminder dialog.
  +
  bool *doHideCancelButton2()* const - gets if the default cancel button is
  included into the reminder dialog.
  +
  void *showCancelButton2()* - include the default cancel button into the
  reminder dialog (set by default).
  +
  void *setMaximalTimeoutSnoozeCounter(int tsz_max_counter)* - restricts snoozing
  by user's inactivity in the notification dialog to given repeat amount. The event
  will be marked as served and the counter reset in case of one more inactivity.
  The counter will also be reset by any manual snoooze or dismiss.
  +
  int *maximalTimeoutSnoozeCounter()* const - gets maximal timeout snoooze
  counter (see *setMaximalTimeoutSnoozeCounter* for details).
  +
  void *setTimeoutSnooze(int tsz_length)* - set the length of snooze caused by
  user inactivity in the notification dialog to givem length in seconds,
  instead of system wide default value. The length must be a least 10 seconds.
  +
  int *timeoutSnoozeLenght()* const - gets timeout snooze length (see
  *setTimeoutSnooze* for details). *1* means "the default length of snooze".
  +
  void *setAttribute(QString key, QString value)* - sets the text attribute
  with given key/value pair. Both the key and the value can be neither empty
  nor null. An event can have any amount of attributes, the same is true for the
  event actions and event buttons. Some attribute keys have a spetial meaning
  for the time daemon. Other are just transmitted to the notification daemon
  (button attributes)
  or other applications (during executing of actions).
  +
  Keys having a special meaning for the time daemon (the exact
  explanation of the meaning can be found somewhere in this manual page) are:
  "APPLICATION", "TITLE", "TEST",
  "COMMAND", "USER", "DBUS_SERVICE", "DBUS_PATH", "DBUS_INTERFACE",
  "DBUS_METHOD", "DBUS_SIGNAL", "PLUGIN", "BACKUP".
  +
  The usage of other upper case keys is deprecated, the client application can
  use low or mixed case keys for its own data.
  +
  Every client application must set an APPLICATION attribute to a string
  consisting of latin letters, digits and underscores and not beginning with a
  digit.
  +
  The value of the TEST attribute (if given) is printed by the daemon together with the
  event cookie after the event is inserted into the event queue, it could be used
  for debugging.
  +
  const QMap<QString, QString> & *attributes()* const - gets attributes (see
  *setAttribute* for details).
  +
  void *removeAttribute(const QString &key)* - removes the attribut with
  the given key.
  +
  void *clearAttributes()* - removes all attributes.
  +
  QStringList *droppedCredentials()* const - gets the list of the dropped
  credentials.
  +
  void *removeCredentialDrop(const QString &token)* - removes the dropped
  credential with geven token.
  +
  QStringList *accruedCredentials()* const - gets the list of the accrued
  credentials.
  +
  void *removeCredentialAccrue(const QString &token)* - removes the accrued
  credential with geven token.
  +
  void *clearCredentialModifiers()* - clear all credential modifications.
  +
  int *check(QString *s=NULL, bool exc=true)* - performes simple sanity checks for the event. This
  method does not throw an exception, unless requested. The return value is zero if the event
  seems to be sane and can be submitted to the time daemon (but this does not mean
  the event will be accepted). If the check fails and the a non null pointer to an
  existing QString instance is given as a parameter, the human readable
  description is written there. If the check fails, parameter 's' is NULL and
  the parameter 'exc' is true, an exception of the type
  Maemo::Timed::Exception will be thrown.
  The methods 'add_event' and 'replace_event' of
  the interface are calling check() without parameters, which will cause
  throwing of the exception,  if it fails.

*class Maemo::Timed::Event::Recurrence*::
  The class represents a pattern describing the event recurrence rules.
  +
  If an event has no recurrence pattern, it will be triggered only once and it
  can be repeated only by snoozing for a short period of time: after that it
  will be removed from the event queue. To make an event to be re-triggered on a
  regular basis, the application can set one or more recurrence pattern.
  +
  If an
  event has multiply patterns, the one producing the earliest recurrence is used
  during every re-calculation. The patterns are using broken down time, thus the
  event time zone is used for the calculation. If no time zone is given for the
  event, the device time zone is used.
  +
  Every pattern consists of five bit masks (one for months, one for days of month,
  one for days of week, one for hours and one for minutes), which are only accessible for adding
  bits via the member functions listed below. The quintuple
  (month, day\_of\_month, day\_of\_week, hour, minute) is said to be _matching_ the given
  pattern if the pattern has the bits corresponding to the quintuple values set.
  The last day of every month is a  special case: it can be matched not only by
  the bit in day\_of\_month corresponding to its ordinal, but by the special
  bit, which can be set with the appropriate method below.
  +
  A pattern is said to be 'empty' if it can't be matched at all, even in a leap
  year starting on appropriate day of week. A pattern
  without any bit is empty, but not vice versa.
  Even if a pattern is *not* empty, it can't be guarantied that it will be
  matched some day, see the example below producing an non-empty pattern,
  which will be never matched due to current local daylight saving time
  legislation. The example after that shows a non-empty pattern which is matched
  not very frequently.
  +
  Member functions:
  +
  bool *isEmpty()* const - returns true if the recurrence pattern can be
  _never_ satisfied. Such a pattern can't be used for an event. Initially every
  freshly created pattern is empty, because it doesn't contain any bits. It
  has to be filled before the event is submitted to the daemon.
  +
  void *addMonth(int x)* - makes the pattern match the month 'x' (counted from
  1=Jan to 12=Dec).
  +
  void *everyMonth()* - makes the pattern match every month.
  +
  int *months()* const- gets month bit mask (Jan is 0 bit, Feb is 1 bit ...
  Dec is 11 bit).
  void *removeMonth(int x)* - removes the month 'x' from the pattern.
  +
  void *removeEveryMonth()* - resets the month bit mask.
  +
  void *addDayOfMonth(int x)* - makes the pattern match the given day, 'x' is
  counted from 1.
  +
  void *addLastDayOfMonth()* - makes the pattern match the last day of month.
  +
  void *everyDayOfMonth()* - makes the pattern match every day of month.
  +
  int daysOfMonth() const - gets the day of month bit mask (the last day of
  month is 0 bit, 1st - 1 bit, 2nd - 2 bit ... 31st is 31 bit).
  +
  void *removeDayOfMonth(int x)* - removes the given day 'x' from the pattern.
  +
  void *removeLastDayOfMonth()* - removes the last day of month from the
  pattern.
  +
  void *removeEveryDayOfMonth()* - resets the day of month bit mask.
  +
  void *addDayOfWeek(int x)* - makes the pattern match the given week day, the
  days are encoded as follows: 0=Su, 1=Mo, 2=Tu, 3=We, 4=Th, 5=Fr, 6=Sa, 7=Su.
  +
  void *everyDayOfWeek()* - makes the pattern match the whole week.
  +
  int *daysOfWeek()* const - gets the day of week bit mask (Su is 0 bit, Mo is 1
  bit ... Sa is 6 bit).
  +
  void *removeDayOfWeek(int x)* - removes the given week day 'x' from the
  pattern.
  +
  void *removeEveryDayOfWeek()* - resets the day of week bit mask.
  +
  void *addHour(int x)* - makes the pattern match the given hour, counted from 0 to
  23.
  +
  int *hours()* const - gets the hour bit mask (0 is 0 bit ... 23 is 23 bit).
  +
  void *removeHour(int x)* - removes the given hour 'x' from the pattern.
  +
  void *removeEveryHour()* - resets the hour bit mask.
  +
  void *addMinute(int x)* - makes the pattern match the given minute, counted from
  0 to 59.
  +
  quint64 *minutes()* const - gets the minute bit mask (0 is 0 bit ... 59 is
  59 bit).
  +
  void *removeMinute(int x)* - removes the given minute 'x' from the pattern.
  +
  void *removeEveryMinute()* - resets the minute bit mask.
  +
  bool *fillingGapsFlag()* const - gets the 'filling gaps' flag.
  +
  void *clearFillingGapsFlag()* - clears the 'filling gaps' flag.

    Example, an event triggering every Monday at five pm: ::

-----------------------
Maemo::Timed::Event e ;
Maemo::Timed::Event::Recurrence &five_o_clock = e.addRecurrence() ;
five_o_clock.addDayOfWeek(1) ;
five_o_clock.addHour(17), five_o_clock.addMinute(00) ;
five_o_clock.everyDayOfMonth(), five_o_clock.everyMonth() ;
-----------------------

    Example, an event triggering every European working day at 11am: ::

-----------------------
Maemo::Timed::Event e ;
Maemo::Timed::Event::Recurrence &lunch = e.addRecurrence() ;
for(int i=1; i<=5; ++i) lunch.addDayOfWeek(i) ;
lunch.addHour(11), lunch.addMinute(00) ;
lunch.everyDayOfMonth(), lunch.everyMonth() ;
-----------------------

    Example, an event triggering every leap year on Feb 29 at 13:54, and every last May Sunday at noon: ::

-----------------------
Maemo::Timed::Event e ;
Maemo::Timed::Event::Recurrence &feb29 = e.addRecurrence() ;
Maemo::Timed::Event::Recurrence &maySu = e.addRecurrence() ;
feb29.everyDayOfWeek() ;
feb29.addHour(13), feb29.addMinute(54) ;
feb29.addMonth(2), feb29.addDay(29) ;
maySu.addMonth(5), maySu.addHour(12), maySu.addMinute(0) ;
maySu.addDayOfWeek(0 /* or 7, it doesn't matter  */) ;
for(int i=0; i<7; ++i) maySu.addDay(31-i) ;
-----------------------

    Example, a non empty pattern, which will not be matched unless the Finnish legislation will be changed: ::

-----------------------
Maemo::Timed::Event e ;
e.setTimezone(":Europe/Helsinki")
Maemo::Timed::Event::Recurrence &x = e.addRecurrence() ;
x.addDayOfWeek(7) ; /* It's Sunday */
for(int i=0; i<7; ++i) x.addDay(31-i) ; /* The last week */
x.addMonth(3) ; /* March */
   /* 3:15 is between 3:00 and 4:00 */
x.addHour(3), x.addMinute(15) ;
assert(!x.isEmpty()) ; /* not empty */
-----------------------

    Example, a pattern will be matched every 28 years, beginning 2036: ::

-----------------------
Maemo::Timed::Event e ;
Maemo::Timed::Event::Recurrence &x = e.addRecurrence() ;
x.addDayOfWeek(5) ; /* It is Friday */
x.addDay(29), x.addMonth(2) ; /* Feb, 29 */
x.addHour(12), x.addMinute(00) ;
/* see you in 28 years */
-----------------------


class *Maemo::Timed::Event::Button*::
  The class represents a dialog button corresponding to a possible human answer
  in the notification dialog. This information is transmitted to the
  notification service.
  +
  Member functions:
  +
  void *setAttribute(QString key, QString value)* - sets a button attribute.
  +
  const QMap<QString, QString> & *attributes()* const - gets attributes (see
  *setAttribute* for details).
  +
  void *removeAttribute(const QString &key)* - removes the attribut with
  the given key.
  +
  void *clearAttributes()* - removes all attributes.
  +
  void *setSnooze(int secs)* - sets the length of snooze caused by human
  selecting the given button. If the snooze value is not set, no snooze will
  be performed. The parameter can't be less than 10 seconds.
  +
  void *setSnoozeDefault()* - marks the button as having the system wide default
  snooze value. This value can be changed anytime by a D-Bus method call.
  +
  int *snooze()* const - gets the length of snooze caused by human selecting
  the given button. *1* means "the default length of snooze".

class *Maemo::Timed::Event::Action*::
  The class represents an action executed due to the processing of an event.
  The action can launch an external command (by calling '/bin/sh -c'), send a
  D-Bus message or do both of above.
  An event can have any amount of actions.
  An action can be connected to the arbitrary subset of the set
  of internal event states and it will be executed every time the event is
  entering one of those states.
  +
  Member functions:
  +
  void *setAttribute(QString key, QString value)* - sets an attribute, which is  specific
  for the given action. Every time an action is to be performed, all the needed
  attributes have to be found in the action attributes, set by this method.
  If an attribute is not found, the daemon will look for it in the event
  attributes, set by the method of the class Maemo::Timed::Event.
  +
  const QMap<QString, QString> & *attributes()* const - gets attributes (see
  *setAttribute* for details).
  +
  void removeAttribute(const QString &key) - removes the attribut with
  the given key.
  +
  void clearAttributes() - removes all attributes.
  +
  void *runCommand()* - the time daemon will execute an external command,
  given in COMMAND attribute. Before that the user will be change to
  the user ID given in the USER attribute (if no
  USER attribute is given, "user" is used) and the current working directory
  will be changed to the home directory of the given user, unless it's the
  "root" user.
  Only the superuser can add an event executing a command by another user but
  itself.
  +
  void *runCommand(QString cmd)* - is equivalent to
  setAttribute("COMMAND",cmd) ; runCommand() ;
  +
  void *runCommand(QString cmd, QString user)* - is equivalent to
  setAttribute("USER",user) ; runCommand(cmd) ;
  +
  bool *runCommandFlag()* const - gets the 'run command' flag.
  +
  const QString *runCommandLine()* const - gets an external command from
  COMMAND attribute. Returns an empty QString if the attribute or the 'run command'
  flag are not set.
  +
  const QString *runCommandUser()* const - gets the user from USER attribute.
  Returns an empty QString if the attribute or the 'run command' flag are not set.
  +
  void *removeCommand()* - clears the 'run command' flag and removes COMMAND and
  USER attributes.
  +
  void *dbusMethodCall()* - the time daemon will start an asynchronous method
  call on the session bus (unless the flag useSystemBus described below is set).
  The D-Bus call service name, object path, interface (optional) and method
  name will be taken from the attributes "DBUS_SERVICE", "DBUS_PATH",
  "DBUS_INTERFACE" and "DBUS_METHOD" respectively.
  The method call has the only parameter of the type string array.
  This array contains two strings (key and value) for every token to be sent.
  A token can be either an action attribute (only if the 'sendAttribute' flag
  is set for the action) or an event attribute (only if the 'sendEventAttributes'
  flag is set) or the event cookie (only if the 'sendCookie' flag
  is set).
  The following attributes will not be sent in the parameter list:
  "COMMAND", "USER", "DBUS_SERVICE", "DBUS_PATH", "DBUS_INTERFACE",
  "DBUS_METHOD", "DBUS_SIGNAL".
  +
  void *dbusMethodCall(QString srv, QString mtd, QString obj, QString ifc="")* -
  calls dbusMethodCall() method and
  sets the atributes DBUS_SERVICE, DBUS_METHOD, DBUS_PATH according to
  parameters 'srv', 'mtd', 'obj'. Sets the DBUS_INTERFACE attribute only if
  the last parameter is a non-empty string.
  +
  bool *dbusMethodCallFlag()* const - gets the 'dbus method call' flag.
  +
  const QString *dbusMethodCallService()* const - gets the dbus method call
  service from DBUS_SERVICE attribute. Returns an empty QString if the attribute
  or the 'dbus method call' flag are not set.
  +
  const QString *dbusMethodCallMethod()* const - gets the dbus method call
  method from DBUS_METHOD attribute. Returns an empty QString if the attribute or
  the 'dbus method call' flag are not set.
  +
  const QString *dbusMethodCallPath()* const - gets the dbus method call path
  from DBUS_PATH attribute. Returns an empty QString if the attribute or 'dbus
  method call' flag are not set.
  +
  const QString *dbusMethodCallInterface()* const - gets the dbus method call
  interface from DBUS_INTERFACE attribute. Returns an empty QString if the attribute
  or the 'dbus method call' flag are not set.
  +
  void *removeDbusMethodCall()* - clears the 'dbus method call' flag and removes
  DBUS_SERVICE, DBUS_METHOD, DBUS_PATH and DBUS_INTERFACE attributes.
  +
  void *dbusSignal()* - the time daemon will send a D-Bus signal. The D-Bus
  connection, object path, interface and message parameters are the same as for
  'dbusMethodCall' above. The interface parameter is obligatory. The signal name
  is set by the "DBUS_SIGNAL" attribute.
  +
  void *dbusSignal(QString obj, QString sig, QString ifc)* - is equivalent to
  dbusSignal() ;
  setAttribute("DBUS_PATH", obj) ;
  setAttribute("DBUS_SIGNAL", sig) ;
  setAttribute("DBUS_INTERFACE", ifc) ;
  +
  bool *dbusSignalFlag()* const - gets the 'dbus signal' flag.
  +
  const QString *dbusSignalPath()* const - gets the dbus signal path from
  DBUS_PATH attribute. Returns an empty QString if the attribute or 'dbus signal'
  flag are not set.
  +
  const QString *dbusSignalName()* const - gets the dbus signal from
  DBUS_SIGNAL attribute. Returns an empty QString if the attribute or 'dbus
  signal' flag are not set.
  +
  const QString *dbusSignalInterface()* const gets the dbus signal interface
  from DBUS_INTERFACE attribute. Returns an empty QString if the attribute or
  the 'dbus signal' flag are not set.
  +
  void *removeDbusSignal()* - clears the 'dbus signal' flag and removes DBUS_PATH,
  DBUS_SIGNAL and DBUS_INTERFACE attributes.
  +
  void *setSendCookieFlag()* - set the flag causing
  the daemon to send the
  event cookie during execution of the action.
  The command to be executed (given in the COMMAND attribute) will be modified:
  the upper case word COOKIE as well as a string "<COOKIE>" will be replaced by
  the decimal representation of the cookie value.
  The parameter list of the D-Bus call will include the string "COOKIE" followed
  by the string containing the decimal representation of the cookie.
  +
  bool *sendCookieFlag()* const - gets the 'send cookie' flag (see
  *setSendCookieFlag* for details).
  +
  void *clearSendCookieFlag()* - clears the 'send cookie' flag (see
  *setSendCookieFlag* for details).
  +
  void *setSendAttributesFlag()* - causes the action attributes to be sent via
  dbus as described above.
  +
  bool *sendAttributesFlag()* const - gets the 'send attributes' flag (see
  *setSendAttributesFlag* for details).
  +
  void *clearSendAttributesFlag()* - clears the 'send attributes' flag (see
  *setSendAttributesFlag* for details).
  +
  void *setSendEventAttributesFlag()* - causes the event attributes to be sent via
  dbus as described above.
  +
  bool *sendEventAttributesFlag()* const - gets the 'send event attributes' flag (see
  *setSendEventAttributesFlag* for details).
  +
  void *clearSendEventAttributesFlag()* - clears the 'send event attributes' flag
  (see *setSendEventAttributesFlag* for details).
  +
  void *setUseSystemBusFlag()* - causes time daemon to use the connection to the
  system bus (instead of session bus) for execution of the D-Bus action.
  +
  bool *useSystemBusFlag()* const - gets the 'use system bus' flag (see
  *setUseSystemBusFlag* for details).
  +
  void *clearUseSystemBusFlag()* - clears the 'use system bus' flag (see
  *setUseSystemBusFlag* for details).
  +
  The following methods are connecting the action to one one more internal
  states the event is going through during its lifetime. An event can go to
  a particular state more than once, but it can also never reach some states.
  +
  void *whenQueued()* - an event is waiting until the trigger time. Not every
  event ever achieves this state, for example events needing the device's User
  Mode, are waiting indifinetely if the device is in any oher mode.
  +
  bool *whenQueuedFlag()* const - gets the 'when queued' flag (see
  *whenQueued* for details).
  +
  void *clearWhenQueuedFlag()* - clears the 'when queued' flag (see *whenQueued*
  for details).
  +
  void *whenDue()* - the trigger time of the queued event is reached.
  +
  bool *whenDueFlag()* const - gets the 'when due' flag (see *whenDue* for
  details).
  +
  void *clearWhenDueFlag()* - clear the 'when due' flag (see *whenDue* for
  details).
  +
  void *whenMissed()* - if the trigger time of the event lies more than 59
  seconds back, the event is said to be 'missed'. It still can be triggered,
  but only if the triggerIfMissedFlag is set.
  +
  bool *whenMissedFlag()* const - gets the 'when missed' flag (see
  *whenMissed* for details).
  +
  void *clearWhenMissedFlag()* - clears the 'when missed' flag (see
  *whenMissed* for details).
  +
  void *whenTriggered()* - the event is to be triggered
  +
  bool *whenTriggeredFlag()* const - gets the 'when triggered' flag (see
  *whenTriggered* for details).
  +
  void *clearWhenTriggeredFlag()* - clears the 'when triggered' flag (see
  *whenTriggered* for details).
  +
  void *whenSnoozed()* - the user has decided to snooze the event
  +
  bool *whenSnoozedFlag()* const - gets the 'when snoozed' flag (see
  *whenSnoozed* for details).
  +
  void *clearWhenSnoozedFlag()* - clears the 'when snoozed' flag (see
  *whenSnoozed* for details).
  +
  void *whenServed()* - the event was either triggered or missed, and the
  whole trigger loop (if any) was completed.
  +
  bool *whenServedFlag()* const - gets the 'when served' flag (see
  *whenServed* for details).
  +
  void *clearWhenServedFlag()* - clears the 'when served' flag (see
  *whenServed* for details).
  +
  void *whenAborted()* - the event is cancelled by the application
  +
  bool *whenAbortedFlag()* const - gets the 'when aborted' flag (see
  *whenAborted* for details).
  +
  void *clearWhenAbortedFlag()* - clears the 'when aborted' flag (see
  *whenAborted* for details).
  +
  void *whenTranquil()* - the event reaches the 'tranqiol' state, which means
  it will be never triggered and just keeped there to be queried until
  the client application decides to remove it.
  +
  bool *whenTranquilFlag()* const - gets the 'when tranquil' flag (see
  *whenTranquil* for details).
  +
  void *clearWhenTranquilFlag()* - clears the 'when tranquil' flag (see
  *whenTranquil* for details).
  +
  void *whenFailed()* - the daemon was not able to schedule the event, usually
    it happens because of the data given by the application.
  +
  bool *whenFailedFlag()* const - gets the 'when failed' flag (see
  *whenFailed* for details).
  +
  void *clearWhenFailedFlag()* - clears the 'when failed' flag (see
  *whenFailed* for details).
  +
  void *whenFinalized()* - that is the last state for the event, before it's
  beeng discarded
  +
  bool *whenFinalizedFlag()* const - gets the 'when finalized' flag (see
  *whenFinalized* for details).
  +
  void *clearWhenFinalizedFlag()* - clears the 'when finalized' flag (see
  *whenFinalized* for details).
  +
  void *whenButton(const Maemo::Timed::Event::Button &amp; x)* - the user
  has selected the application specific
  button introduced by the call to Event::addButton() method.
  +
  QVector<int> *whenButtons()* const - gets the numbers of the user specific
  buttons which trigger the action. The button number can be passed as index
  into *button* function of the event to get the reference to the button.
  +
  void *clearWhenButton(const Event::Button &x)* - the user specific button
  won't trigger the action anymore.
  +
  void *whenSysButton(int x)* - the user has selected the x-th platform wide
  notification dialog button. The value of 'x' is a non-negative integer
  number not exceeding the value returning by Event::getSysButtonAmount() method
  (which is the amount of the platform wide
  buttons, currently it's 2, but it can change later). The value 'x=0' is a special value for the
  out-of-screen user actions.
  +
  QVector<int> *whenSysButtons()* const - gets the numbers of the platform
  wide notification dialog buttons which trigger the action (see
  *whenSysButton* for details).
  +
  void *clearWhenSysButton(int x)* - the paltform wide notification dialog
  buttons won't trigger the action anymore.
  +
  QStringList *droppedCredentials()* const - gets the list of the dropped
  credentials.
  +
  void *removeCredentialDrop(const QString &token)* - removes the dropped
  credential with geven token.
  +
  QStringList *accruedCredentials()* const - gets the list of the accrued
  credentials.
  +
  void *removeCredentialAccrue(const QString &token)* - removes the accrued
  credential with geven token.

*class Maemo::Timed::Event::Triggers*::
  This class represents the queue of currently active alarms. The class inherits
  QMap<quint32, quint32>, the keys of the map are are cookies and values trigger
  times as seconds since Unix epoch. A client application can obtain an instance
  of this class by subscribing to the 'alarm_triggers_changed' D-Bus signal, see
  'alarm_triggers_changed_connect' and 'alarm_triggers_changed_disconnect'

EXCEPTIONS
----------

class *Maemo::Timed::Exception*::
  An instance of this std::exception subclass will be thrown by one of the
  functions described above in case of inconsistent input.
  +
  Methods:
  +
  const char * *what()*- returns a human readable message
  describing the problem and function caused the exception.

DBUS REPLY WRAPPERS
-------------------
Due to timed internal implementation, QDBus reply classes are not work as
expected. One of dbus reply wrapper shall be used to extract data returned by
*get_event_sync*, *get_event_async*, *get_events_sync* and *get_events_async*.

class *Maemo::Timed::Event::DBusReply*::
class *Maemo::Timed::Event::List::DBusReply*::
  These classes are almost equal to *QDBusReply<T>* with
  T=*Maemo::Timed::Event* and T=*Maemo::Timed::Event::List* respectively
  except several things:
  1. Objects of these classes can be constructed from *QDBusMessage* object only;
  2. No *operator=* defined;
  3. *operator T ()* is non-const function and provides a reference to the
  object of type T inside;
  4. There are const and non-const *value()* functions which returns a reference
  to the object of type T inside;
  5. *operator T ()* and both *value()* functions throw
  *Maemo::Timed::Exception* if the reply is not valid.
  +
  The rest functions *isValid()* and *error()* are equal to *QDBusReply<T>*.
  +
  It is expected that these classes will be used in the same manner as
  *QDBusReply<T>* for *get_event_sync* and *get_events_sync* (see Qt Reference
  Documentation for details).

    Example: ::
-----------------------
Maemo::Timed::Interface ifc ;
Maemo::Timed::Event::DBusReply reply = ifc.get_event_sync(15) ;
assert(reply.isValid()) ;
Maemo::Timed::Event &event = reply.value() ;
//event can be used to examine or to modify the returned event
//ifc.replace_event_sync can be used after this to update the event on server
//side
-----------------------

class *Maemo::Timed::Event::DBusPendingReply*::
class *Maemo::Timed::Event::List::DBusPendingReply*::
  These classes are almost equal to *QDBusPendingReply<T>* with
  T=*Maemo::Timed::Event* and T=*Maemo::Timed::Event::List* respectively
  except several things:
  1. Objects of these classes can be constructed from *QDBusPendingCall* object
  only;
  2. No *operator=* defined;
  3. *operator T ()* is non-const function and provides a reference to the
  object of type T inside;
  4. There are const and non-const *value()* functions which returns a
  reference to the object of type T inside;
  5. *operator T ()* and both *value()* functions throw
  *Maemo::Timed::Exception* if the reply is not valid;
  6. No *argumentAt*, *count()*, *reply()* functions.
  +
  The rest functions *isValid()*, *isError()*, *isFinished()*,
  *waitForFinished()* and *error()* are equal to *QDBusPendingReply<T>*.
  +
  It is expected that these classes will be used in the same manner as
  *QDBusPendingReply<T>* for *get_event_async* and *get_events_async* (see Qt
  Reference Documentation for details).

    Example: ::
-----------------------
Maemo::Timed::Interface ifc ;
Maemo::Timed::Event::DBusPendingReply reply = ifc.get_event_async(15) ;
reply.waitForFinished() ;
assert(reply.isValid()) ;
Maemo::Timed::Event &event = reply.value() ;
//event can be used to examine or to modify the returned event
//ifc.replace_event_sync can be used after this to update the event on server
//side
//Also note that more common case is to create QDBusPendingCallWatcher from
//QDBusPendingCall, to connect finished signal to some slot and to use
//DBusPendingReply inside the solt to extract a returned event or list.
//It can be done in the same manner as with QDBusPendingReply<T> usage.
-----------------------

SEE ALSO
--------

'timed(8)', 'libtimed-voland(3)', voland(8)

WIKIPEDIA
---------

http://en.wikipedia.org/wiki/Coordinated_Universal_Time
http://en.wikipedia.org/wiki/Daylight_saving_time
http://en.wikipedia.org/wiki/Mobile_Country_Code
http://en.wikipedia.org/wiki/Mobile_Network_Code
http://en.wikipedia.org/wiki/NITZ
http://en.wikipedia.org/wiki/Olson_database

QT-DOCUMENTATION
----------------

QDBusAbstractInterface etc

COLOPHON
--------

This page is part of timed, the Maemo time daemon.
