libalarm.h File Reference

C API to alarm data. More...

Go to the source code of this file.

Data Structures

struct  alarm_attr_t
 Extra alarm attributes. More...
struct  alarm_action_t
 When and whether to send D-Bus messages, Execute commands or Snooze. More...
struct  alarm_recur_t
 Date and time based recurrence defination. More...
struct  alarm_event_t
 Alarm time control + actions to take. More...

Defines

#define ALARM_RECURRING_SECONDS(n)   (n)
 Calculate value for alarm_event::recur_secs specified in seconds.
#define ALARM_RECURRING_MINUTES(n)   ((n)*60)
 Calculate value for alarm_event::recur_secs specified in minutes.
#define ALARM_RECURRING_HOURS(n)   ((n)*60*60)
 Calculate value for alarm_event::recur_secs specified in hours.

Typedefs

typedef long cookie_t
 Unique identifier type for the alarm events.

Enumerations

enum  alarmattrtype { ALARM_ATTR_NULL, ALARM_ATTR_INT, ALARM_ATTR_TIME, ALARM_ATTR_STRING }
 supported types for alarm_attr_t objects
enum  alarmactionflags {
  ALARM_ACTION_TYPE_NOP = 0, ALARM_ACTION_TYPE_SNOOZE = 1 << 0, ALARM_ACTION_TYPE_DBUS = 1 << 1, ALARM_ACTION_TYPE_EXEC = 1 << 2,
  ALARM_ACTION_TYPE_DESKTOP = 1 << 3, ALARM_ACTION_TYPE_ACTDEAD = 1 << 8, ALARM_ACTION_TYPE_DISABLE = 1 << 10, ALARM_ACTION_WHEN_QUEUED = 1 << 4,
  ALARM_ACTION_WHEN_DELAYED = 1 << 11, ALARM_ACTION_WHEN_TRIGGERED = 1 << 5, ALARM_ACTION_WHEN_DISABLED = 1 << 9, ALARM_ACTION_WHEN_RESPONDED = 1 << 6,
  ALARM_ACTION_WHEN_DELETED = 1 << 7, ALARM_ACTION_DBUS_USE_ACTIVATION = 1 << 12, ALARM_ACTION_DBUS_USE_SYSTEMBUS = 1 << 13, ALARM_ACTION_DBUS_ADD_COOKIE = 1 << 14,
  ALARM_ACTION_TYPE_MASK, ALARM_ACTION_WHEN_MASK
}
 Options for alarm_action_t items. More...
enum  alarmrecurflags {
  ALARM_RECUR_MIN_DONTCARE = 0, ALARM_RECUR_MIN_ALL = (1ull << 60) - 1, ALARM_RECUR_HOUR_DONTCARE = 0, ALARM_RECUR_HOUR_ALL = (1u << 24) - 1,
  ALARM_RECUR_MDAY_DONTCARE = 0, ALARM_RECUR_MDAY_ALL = ~1u, ALARM_RECUR_MDAY_EOM = 1u, ALARM_RECUR_WDAY_DONTCARE = 0,
  ALARM_RECUR_WDAY_ALL = (1u << 7) - 1, ALARM_RECUR_WDAY_SUN = (1u << 0), ALARM_RECUR_WDAY_MON = (1u << 1), ALARM_RECUR_WDAY_TUE = (1u << 2),
  ALARM_RECUR_WDAY_WED = (1u << 3), ALARM_RECUR_WDAY_THU = (1u << 4), ALARM_RECUR_WDAY_FRI = (1u << 5), ALARM_RECUR_WDAY_SAT = (1u << 6),
  ALARM_RECUR_WDAY_MONFRI = ALARM_RECUR_WDAY_SAT - ALARM_RECUR_WDAY_MON, ALARM_RECUR_WDAY_SATSUN = ALARM_RECUR_WDAY_SAT | ALARM_RECUR_WDAY_SUN, ALARM_RECUR_MON_DONTCARE = 0, ALARM_RECUR_MON_ALL = (1u << 12) - 1,
  ALARM_RECUR_MON_JAN = (1u << 0), ALARM_RECUR_MON_FEB = (1u << 1), ALARM_RECUR_MON_MAR = (1u << 2), ALARM_RECUR_MON_APR = (1u << 3),
  ALARM_RECUR_MON_MAY = (1u << 4), ALARM_RECUR_MON_JUN = (1u << 5), ALARM_RECUR_MON_JUL = (1u << 6), ALARM_RECUR_MON_AUG = (1u << 7),
  ALARM_RECUR_MON_SEP = (1u << 8), ALARM_RECUR_MON_OCT = (1u << 9), ALARM_RECUR_MON_NOW = (1u << 10), ALARM_RECUR_MON_DEC = (1u << 11),
  ALARM_RECUR_SPECIAL_NONE = 0, ALARM_RECUR_SPECIAL_BIWEEKLY = 1, ALARM_RECUR_SPECIAL_MONTHLY = 2, ALARM_RECUR_SPECIAL_YEARLY = 3
}
 Constants for use with alarm_recur_t items. More...
enum  alarmeventflags {
  ALARM_EVENT_BOOT = 1 << 3, ALARM_EVENT_ACTDEAD = 1 << 4, ALARM_EVENT_SHOW_ICON = 1 << 5, ALARM_EVENT_CONNECTED = 1 << 7,
  ALARM_EVENT_RUN_DELAYED = 1 << 6, ALARM_EVENT_POSTPONE_DELAYED = 1 << 9, ALARM_EVENT_DISABLE_DELAYED = 1 << 12, ALARM_EVENT_BACK_RESCHEDULE = 1 << 10,
  ALARM_EVENT_DISABLED = 1 << 11, ALARM_EVENT_CLIENT_BITS = 16, ALARM_EVENT_CLIENT_MASK = (1 << ALARM_EVENT_CLIENT_BITS) - 1
}
 Options for alarm_event_t items. More...

Functions

alarm_attr_t methods
void alarm_attr_ctor (alarm_attr_t *self)
 alarm attr constructor
void alarm_attr_dtor (alarm_attr_t *self)
 alarm attr destructor
void alarm_attr_set_null (alarm_attr_t *self)
 sets alarm_attr_t object to state that does not have a value
void alarm_attr_set_string (alarm_attr_t *self, const char *val)
 sets alarm_attr_t object to contain a string value
void alarm_attr_set_int (alarm_attr_t *self, int val)
 sets alarm_attr_t object to contain a integer value
void alarm_attr_set_time (alarm_attr_t *self, time_t val)
 sets alarm_attr_t object to contain a time_t value
const char * alarm_attr_get_string (alarm_attr_t *self)
 gets string value of an alarm_attr_t
int alarm_attr_get_int (alarm_attr_t *self)
 gets integer value of an alarm_attr_t
time_t alarm_attr_get_time (alarm_attr_t *self)
 gets time_t value of an alarm_attr_t
alarm_attr_t * alarm_attr_create (const char *name)
 create a new alarm_attr_t object with name
void alarm_attr_delete (alarm_attr_t *self)
 delete an alarm_attr_t object
void alarm_attr_delete_cb (void *self)
 normalized delete callback
alarm_action_t methods
void alarm_action_ctor (alarm_action_t *self)
 Constructor.
void alarm_action_dtor (alarm_action_t *self)
 Destructor.
alarm_action_t * alarm_action_create (void)
 New operator.
void alarm_action_delete (alarm_action_t *self)
 Delete operator.
void alarm_action_delete_cb (void *self)
 Normalized delete callback.
int alarm_action_is_button (const alarm_action_t *self)
 Check if action is button for system ui dialog.
int alarm_action_set_dbus_args (alarm_action_t *self, int type,...)
 Add dbus arguments to alarm_action_t.
void alarm_action_del_dbus_args (alarm_action_t *self)
 Removes dbus arguments from alarm_action_t.
int alarm_action_set_dbus_args_valist (alarm_action_t *self, int type, va_list va)
 Add dbus arguments to alarm_action_t.
const char * alarm_action_get_label (const alarm_action_t *self)
 Gets label string from alarm_action_t.
const char * alarm_action_get_exec_command (const alarm_action_t *self)
 Gets exec_command string from alarm_action_t.
const char * alarm_action_get_dbus_interface (const alarm_action_t *self)
 Gets dbus_interface string from alarm_action_t.
const char * alarm_action_get_dbus_service (const alarm_action_t *self)
 Gets dbus_service string from alarm_action_t.
const char * alarm_action_get_dbus_path (const alarm_action_t *self)
 Gets dbus_path string from alarm_action_t.
const char * alarm_action_get_dbus_name (const alarm_action_t *self)
 Gets dbus_name string from alarm_action_t.
void alarm_action_set_label (alarm_action_t *self, const char *label)
 Sets label string in alarm_action_t.
void alarm_action_set_exec_command (alarm_action_t *self, const char *exec_command)
 Sets exec_command string in alarm_action_t.
void alarm_action_set_dbus_interface (alarm_action_t *self, const char *dbus_interface)
 Sets dbus_interface string in alarm_action_t.
void alarm_action_set_dbus_service (alarm_action_t *self, const char *dbus_service)
 Sets dbus_service string in alarm_action_t.
void alarm_action_set_dbus_path (alarm_action_t *self, const char *dbus_path)
 Sets dbus_path string in alarm_action_t.
void alarm_action_set_dbus_name (alarm_action_t *self, const char *dbus_name)
 Sets dbus_name string in alarm_action_t.
alarm_recur_t methods
void alarm_recur_ctor (alarm_recur_t *self)
 Constructor.
void alarm_recur_dtor (alarm_recur_t *self)
 Destructor.
alarm_recur_t * alarm_recur_create (void)
 Create new initialized alarm_recur_t object.
void alarm_recur_delete (alarm_recur_t *self)
 Cleanp and delete alarm_recur_t object.
void alarm_recur_init_from_tm (alarm_recur_t *self, const struct tm *tm)
 Setup alarm_recur_t object from struct tm data.
void alarm_recur_delete_cb (void *self)
 Normalized delete callback.
time_t alarm_recur_align (const alarm_recur_t *self, struct tm *trg, const char *tz)
 Align broken down time to recurrence rules, try not to advance time.
time_t alarm_recur_next (const alarm_recur_t *self, struct tm *trg, const char *tz)
 Align broken down time to recurrence rules, always advance time.
alarm_event_t methods
void alarm_event_delete (alarm_event_t *self)
 Will free all memory associated with the alarm event.
alarm_event_t * alarm_event_create (void)
 Create a new alarm event.
alarm_event_t * alarm_event_create_ex (size_t actions)
 Create a new alarm event with actions.
void alarm_event_delete_cb (void *self)
 Normalized delete callback.
void alarm_event_ctor (alarm_event_t *self)
 Constructor.
void alarm_event_dtor (alarm_event_t *self)
 Destructor.
const char * alarm_event_get_title (const alarm_event_t *self)
 Gets title string from alarm_event_t.
void alarm_event_set_title (alarm_event_t *self, const char *title)
 Sets title string in alarm_event_t.
const char * alarm_event_get_message (const alarm_event_t *self)
 Gets message string from alarm_event_t.
void alarm_event_set_message (alarm_event_t *self, const char *message)
 Sets message string in alarm_event_t.
const char * alarm_event_get_sound (const alarm_event_t *self)
 Gets sound string from alarm_event_t.
void alarm_event_set_sound (alarm_event_t *self, const char *sound)
 Sets sound string in alarm_event_t.
const char * alarm_event_get_icon (const alarm_event_t *self)
 Gets icon string from alarm_event_t.
void alarm_event_set_icon (alarm_event_t *self, const char *icon)
 Sets icon string in alarm_event_t.
const char * alarm_event_get_alarm_appid (const alarm_event_t *self)
 Gets alarm_appid string from alarm_event_t.
void alarm_event_set_alarm_appid (alarm_event_t *self, const char *alarm_appid)
 Sets alarm_appid string in alarm_event_t.
const char * alarm_event_get_alarm_tz (const alarm_event_t *self)
 Gets alarm_tz string from alarm_event_t.
void alarm_event_set_alarm_tz (alarm_event_t *self, const char *alarm_tz)
 Sets alarm_tz string in alarm_event_t.
int alarm_event_is_recurring (const alarm_event_t *self)
 Check if alarm event is recurring.
alarm_action_t * alarm_event_add_actions (alarm_event_t *self, size_t count)
 Add & initialize actions to event.
alarm_action_t * alarm_event_get_action (const alarm_event_t *self, int index)
 Get pointer to alarm event action by index.
void alarm_event_del_actions (alarm_event_t *self)
 Delete all actions from event and release all dynamic memory related to them.
int alarm_event_set_action_dbus_args (const alarm_event_t *self, int index, int type,...)
 Helper method for manipulating alarm action dbus arguments.
const char * alarm_event_get_action_dbus_args (const alarm_event_t *self, int index)
 Helper method for manipulating alarm action dbus arguments.
void alarm_event_del_action_dbus_args (const alarm_event_t *self, int index)
 Helper method for manipulating alarm action dbus arguments.
alarm_recur_t * alarm_event_add_recurrences (alarm_event_t *self, size_t count)
 Add & initialize recurrence templates to event.
alarm_recur_t * alarm_event_get_recurrence (const alarm_event_t *self, int index)
 Get pointer to recurrence template in event.
void alarm_event_del_recurrences (alarm_event_t *self)
 Delete all recurrence templates from event and release all dynamic memory related to them.
void alarm_event_set_time (alarm_event_t *self, const struct tm *tm)
 Set alarm time from broken down time.
void alarm_event_get_time (const alarm_event_t *self, struct tm *tm)
 Get alarm time as broken down time.
int alarm_event_is_sane (const alarm_event_t *self)
 Check that alarm event content makes sense.
void alarm_event_del_attrs (alarm_event_t *self)
 Remove all attributes from alarm event object.
void alarm_event_rem_attr (alarm_event_t *self, const char *name)
 Remove named attribute from alarm event object.
alarm_attr_t * alarm_event_get_attr (alarm_event_t *self, const char *name)
 Locate named attribute from alarm event object.
int alarm_event_has_attr (alarm_event_t *self, const char *name)
 Check if alarm event object has named attribute.
alarm_attr_t * alarm_event_add_attr (alarm_event_t *self, const char *name)
 Adds named attribute to alarm event object.
void alarm_event_set_attr_int (alarm_event_t *self, const char *name, int val)
 Adds named integer attribute to alarm event object.
void alarm_event_set_attr_time (alarm_event_t *self, const char *name, time_t val)
 Adds named time_t attribute to alarm event object.
void alarm_event_set_attr_string (alarm_event_t *self, const char *name, const char *val)
 Adds named string attribute to alarm event object.
int alarm_event_get_attr_int (alarm_event_t *self, const char *name, int def)
 Gets integer value of named attribute in alarm event object.
time_t alarm_event_get_attr_time (alarm_event_t *self, const char *name, time_t def)
 Gets time_t value of named attribute in alarm event object.
const char * alarm_event_get_attr_string (alarm_event_t *self, const char *name, const char *def)
 Gets string value of named attribute in alarm event object.
alarmd functions for all clients
cookie_t alarmd_event_add (const alarm_event_t *event)
 Adds an event to the alarm queue.
cookie_t alarmd_event_add_with_dbus_params (const alarm_event_t *event, int type,...)
 Adds an event with dbus parameters to the alarm queue.
int alarmd_event_del (cookie_t cookie)
 Deletes alarm from the alarm queue.
cookie_t alarmd_event_update (const alarm_event_t *event)
 Updates an event already in the alarm queue.
cookie_t * alarmd_event_query (const time_t first, const time_t last, int32_t flag_mask, int32_t flags, const char *appid)
 Queries alarms in given time span.
alarm_event_t * alarmd_event_get (cookie_t cookie)
 Fetches alarm defails.
int alarmd_set_default_snooze (unsigned int snooze)
 Sets the amount events will be snoozed by default.
unsigned int alarmd_get_default_snooze (void)
 Gets the amount events will be snoozed by default.
cookie_t alarmd_event_add_valist (const alarm_event_t *event, int type, va_list va)
 va_list version of alarmd_event_add_with_dbus_params()
Alarmd functions for System UI usage only
int alarmd_ack_dialog (cookie_t cookie, int button)
 SystemUI: acknowledge user action on dialog.
int alarmd_ack_queue (cookie_t *cookies, int count)
 SystemUI: acknowledge having queued alarm events for dialogs.
Alarmd functions for development usage only
int alarmd_set_debug (unsigned mask_set, unsigned mask_clr, unsigned flag_set, unsigned flag_clr)
 Debug state manipulation, undocumented.

Detailed Description

C API to alarm data.

This is the API for accessing data on alarm daemon.

Copyright (C) 2008 Nokia. All rights reserved.

Author:
Simo Piiroinen <simo.piiroinen@nokia.com>

Enumeration Type Documentation

enum alarmactionflags

Options for alarm_action_t items.

Bits that define when action is to be taken:

Normally one would use WHEN_RESPONDED for dialog buttons, and WHEN_TRIGGERED for non-interactive alarms. The other WHEN bits can be used for debugging or tracing alarm state changes. For example if application UI sets up recurring alarm and wants to know when the trigger time is changed, a dbus call on WHEN_QUEUED can be requested.

Note that ALARM_ACTION_WHEN_TRIGGERED is effective only if the action label is also non-null, non-empty string (see alarm_action_is_button).

The ALARM_ACTION_WHEN_DELAYED bit can be used to get notifications if alarm gets handled beyond the orginal trigger time due to power outage for example.

Bits that define what is to be done:

More than one ACTION_TYPE bit can be set, all will be acted on.

Bits used for fine tuning D-Bus actions:

Enumerator:
ALARM_ACTION_TYPE_NOP  Action is: Waiting for the user is enough (default)
ALARM_ACTION_TYPE_SNOOZE  Action is: Snooze the alarm
ALARM_ACTION_TYPE_DBUS  Action is: Make a dbus method call / send a signal
ALARM_ACTION_TYPE_EXEC  Action is: Execute a command
ALARM_ACTION_TYPE_DESKTOP  Action is: power up to desktop
ALARM_ACTION_TYPE_ACTDEAD  Action is: power up to actdead
ALARM_ACTION_TYPE_DISABLE  Action is: disable the alarm. Note that disabling an alarm with this action will not trigger ALARM_ACTION_WHEN_DISABLED type actions.
ALARM_ACTION_WHEN_QUEUED  Act when: the alarm is added in the queue. This will happen when new alarms are added to the queue, or the trigger time of existing alarms is changed due to: snooze, recurrence or timezone changes.
ALARM_ACTION_WHEN_DELAYED  Act when: the alarm trigger time is missed. Note that this does not change how the delayed control bits behave.

Since:
v1.0.9
See also: ALARM_EVENT_RUN_DELAYED, ALARM_EVENT_POSTPONE_DELAYED, ALARM_EVENT_DISABLE_DELAYED
ALARM_ACTION_WHEN_TRIGGERED  Act when: the alarm is triggered. The action will be done before setting up system ui dialog.
ALARM_ACTION_WHEN_DISABLED  Act when: the alarm is auto-disbled. This will occur if the trigger time is missed for example due to power outage and the alarm event itself has ALARM_EVENT_DISABLE_DELAYED flag set.

Specifically the auto-disable actions will not be triggered if client application directly manipulates ALARM_EVENT_DISABLED bit (via alarmd_event_update() for example), or if the event is disable due to user pressing a button with ALARM_ACTION_TYPE_DISABLE bit set.

ALARM_ACTION_WHEN_RESPONDED  Act when: user has clicked a button on system ui alarm dialog
ALARM_ACTION_WHEN_DELETED  Act when: the alarm is about to be deleted from the event queue
ALARM_ACTION_DBUS_USE_ACTIVATION  Calls dbus_message_set_auto_start() before sending the message
ALARM_ACTION_DBUS_USE_SYSTEMBUS  Sends message to systembus instead of session bus
ALARM_ACTION_DBUS_ADD_COOKIE  Appends alarm cookie as INT32 after user supplied dbus parameters

enum alarmrecurflags

Constants for use with alarm_recur_t items.

Constants for setting up alarm recurrence masks and special recurres

Enumerator:
ALARM_RECUR_MIN_DONTCARE  Do not adjust minute value
ALARM_RECUR_MIN_ALL  Allow any minute value
ALARM_RECUR_HOUR_DONTCARE  Do not adjust hour value
ALARM_RECUR_HOUR_ALL  Allow any hour value
ALARM_RECUR_MDAY_DONTCARE  Do not adjust day of month value
ALARM_RECUR_MDAY_ALL  Allow any day of month value
ALARM_RECUR_MDAY_EOM  Allow last day of month value, regardless of number of days in month
ALARM_RECUR_WDAY_DONTCARE  Do not adjust day of week value
ALARM_RECUR_WDAY_ALL  Allow any day of week value
ALARM_RECUR_WDAY_SUN  Allow Sundays
ALARM_RECUR_WDAY_MON  Allow Mondays
ALARM_RECUR_WDAY_TUE  Allow Tuesdays
ALARM_RECUR_WDAY_WED  Allow Wednesdays
ALARM_RECUR_WDAY_THU  Allow Thursdays
ALARM_RECUR_WDAY_FRI  Allow Fridays
ALARM_RECUR_WDAY_SAT  Allow Saturdays
ALARM_RECUR_WDAY_MONFRI  Allow Mon,Tue,Wed,Thu and Fri
ALARM_RECUR_WDAY_SATSUN  Allow Saturday and Sunday
ALARM_RECUR_MON_DONTCARE  Do not adjust month value
ALARM_RECUR_MON_ALL  Allow any month value
ALARM_RECUR_MON_JAN  Allow January
ALARM_RECUR_MON_FEB  Allow Fenruary
ALARM_RECUR_MON_MAR  Allow March
ALARM_RECUR_MON_APR  Allow April
ALARM_RECUR_MON_MAY  Allow May
ALARM_RECUR_MON_JUN  Allow June
ALARM_RECUR_MON_JUL  Allow July
ALARM_RECUR_MON_AUG  Allow August
ALARM_RECUR_MON_SEP  Allow September
ALARM_RECUR_MON_OCT  Allow October
ALARM_RECUR_MON_NOW  Allow November
ALARM_RECUR_MON_DEC  Allow December
ALARM_RECUR_SPECIAL_NONE  No special rule
ALARM_RECUR_SPECIAL_BIWEEKLY  Special rule: every 14 days
ALARM_RECUR_SPECIAL_MONTHLY  Special rule: every month
ALARM_RECUR_SPECIAL_YEARLY  Special rule: every year

enum alarmeventflags

Options for alarm_event_t items.

Describes alarm event. These should be bitwise orred to the flags field in alarm_event_t

Enumerator:
ALARM_EVENT_BOOT  The event should boot up the system, if powered off.
ALARM_EVENT_ACTDEAD  The device should only be powered to acting dead mode.
ALARM_EVENT_SHOW_ICON  Icon is shown in the statusbar when alarms with this flag set are in alarmd queue waiting to be triggered.
ALARM_EVENT_CONNECTED  Run only when internet connection is available.

See also: ALARM_EVENT_RUN_DELAYED, ALARM_EVENT_POSTPONE_DELAYED.

ALARM_EVENT_RUN_DELAYED  If the trigger time is missed (due to the device being off or system time being adjusted beyond the trigger point) the alarm should be run anyway.

See also: ALARM_EVENT_POSTPONE_DELAYED.

ALARM_EVENT_POSTPONE_DELAYED  If the trigger time is missed (due to the device being off or system time being adjusted beyond the trigger point) the alarm should be postponed for the next day.

See also: ALARM_EVENT_RUN_DELAYED.

ALARM_EVENT_DISABLE_DELAYED  If the trigger time is missed (due to the device being off or system time being adjusted beyond the trigger point) the alarm should be disabled, but not deleted.

See also: ALARM_EVENT_RUN_DELAYED, ALARM_EVENT_DISABLED, ALARM_ACTION_WHEN_DISABLED, ALARM_ACTION_TYPE_DISABLE.

ALARM_EVENT_BACK_RESCHEDULE  If the system time is moved backwards, the alarm should be rescheduled.

Note: this only applies to recurring alarms.

ALARM_EVENT_DISABLED  Alarm is temporarily disabled, ignored by alarmd

See also: ALARM_EVENT_DISABLE_DELAYED

ALARM_EVENT_CLIENT_BITS  Higher bits are internal to alarmd and ignored when transferred over the dbus from client side.
ALARM_EVENT_CLIENT_MASK  Mask: bits accessable both to server and client.

Function Documentation

void alarm_attr_ctor ( alarm_attr_t *  self  ) 

alarm attr constructor

Initializes alarm_attr_t object to sane values

Since:
v1.0.4
Parameters:
self : alarm_attr_t pointer

void alarm_attr_dtor ( alarm_attr_t *  self  ) 

alarm attr destructor

Releases any dynamic resources bound to an alarm_attr_t object

Since:
v1.0.4
Parameters:
self : alarm_attr_t pointer

void alarm_attr_set_null ( alarm_attr_t *  self  ) 

sets alarm_attr_t object to state that does not have a value

Any value related dynamic resources are released

Since:
v1.0.4
Parameters:
self : alarm_attr_t pointer

void alarm_attr_set_string ( alarm_attr_t *  self,
const char *  val 
)

sets alarm_attr_t object to contain a string value

Type of alarm_attr_t is set to string and copy of the value is bound to the alarm_attr_t object.

Since:
v1.0.4
Parameters:
self : alarm_attr_t pointer
val : string to set as attr value

void alarm_attr_set_int ( alarm_attr_t *  self,
int  val 
)

sets alarm_attr_t object to contain a integer value

Type of alarm_attr_t is set to integer and value is set to given value.

Since:
v1.0.4
Parameters:
self : alarm_attr_t pointer
val : integer to set as attr value

void alarm_attr_set_time ( alarm_attr_t *  self,
time_t  val 
)

sets alarm_attr_t object to contain a time_t value

Type of alarm_attr_t is set to time and value is set to given value.

Since:
v1.0.4
Parameters:
self : alarm_attr_t pointer
val : time_t to set as attr value

const char* alarm_attr_get_string ( alarm_attr_t *  self  ) 

gets string value of an alarm_attr_t

Returns the value held in attr or NULL if the type of the attr is not string.

Since:
v1.0.4
Parameters:
self : alarm_attr_t pointer
Returns:
string value, or NULL if attr type is not string

int alarm_attr_get_int ( alarm_attr_t *  self  ) 

gets integer value of an alarm_attr_t

Returns the value held in attr. If the type of the attr is not integer, an attempt is made to convert other types to integer value.

Since:
v1.0.4
Parameters:
self : alarm_attr_t pointer
Returns:
integer value, or -1 if conversion is not possible

time_t alarm_attr_get_time ( alarm_attr_t *  self  ) 

gets time_t value of an alarm_attr_t

Returns the value held in attr. If the type of the attr is not time_t, an attempt is made to convert other types to time_t value.

Since:
v1.0.4
Parameters:
self : alarm_attr_t pointer
Returns:
integer value, or -1 if conversion is not possible

alarm_attr_t* alarm_attr_create ( const char *  name  ) 

create a new alarm_attr_t object with name

Allocates memory from heap and initializes the attribute to NULL value.

Since:
v1.0.4
Parameters:
name : name of the attr as string
Returns:
alarm_attr_t pointer

void alarm_attr_delete ( alarm_attr_t *  self  ) 

delete an alarm_attr_t object

Releases all dynamic resources bound to the attr object and the object itself.

Passing NULL object is permitted.

Since:
v1.0.4
Parameters:
self : alarm_attr_t pointer

void alarm_attr_delete_cb ( void *  self  ) 

normalized delete callback

Alias for alarm_attr_delete for use as callback.

Since:
v1.0.4
Parameters:
self : alarm_attr_t pointer

int alarm_action_is_button ( const alarm_action_t *  self  ) 

Check if action is button for system ui dialog.

Action is a button if:

Parameters:
self : alarm_action_t pointer
Returns:
0=not a button, 1=is a button

int alarm_action_set_dbus_args ( alarm_action_t *  self,
int  type,
  ... 
)

Add dbus arguments to alarm_action_t.

Duplicates behavior of dbus_message_append_args(), but encodes to asciz string suitable for storage at alarm daemon end.

Parameters:
self : alarm_action_t pointer
type : dbus type of first argument
... : terminated with DBUS_TYPE_INVALID
Returns:
error : 0=success, -1=errors

void alarm_action_del_dbus_args ( alarm_action_t *  self  ) 

Removes dbus arguments from alarm_action_t.

Parameters:
self : alarm_action_t pointer

int alarm_action_set_dbus_args_valist ( alarm_action_t *  self,
int  type,
va_list  va 
)

Add dbus arguments to alarm_action_t.

A va_list version of alarm_action_set_dbus_args()

Parameters:
self : alarm_action_t pointer
type : dbus type of first argument
va : variable argument list obtained via va_start()
Returns:
error : 0=success, -1=errors

const char* alarm_action_get_label ( const alarm_action_t *  self  ) 

Gets label string from alarm_action_t.

Parameters:
self : alarm_action_t pointer
Returns:
label, or empty string if not set

const char* alarm_action_get_exec_command ( const alarm_action_t *  self  ) 

Gets exec_command string from alarm_action_t.

Parameters:
self : alarm_action_t pointer
Returns:
exec_command, or empty string if not set

const char* alarm_action_get_dbus_interface ( const alarm_action_t *  self  ) 

Gets dbus_interface string from alarm_action_t.

Parameters:
self : alarm_action_t pointer
Returns:
dbus_interface, or empty string if not set

const char* alarm_action_get_dbus_service ( const alarm_action_t *  self  ) 

Gets dbus_service string from alarm_action_t.

Parameters:
self : alarm_action_t pointer
Returns:
dbus_service, or empty string if not set

const char* alarm_action_get_dbus_path ( const alarm_action_t *  self  ) 

Gets dbus_path string from alarm_action_t.

Parameters:
self : alarm_action_t pointer
Returns:
dbus_path, or empty string if not set

const char* alarm_action_get_dbus_name ( const alarm_action_t *  self  ) 

Gets dbus_name string from alarm_action_t.

Parameters:
self : alarm_action_t pointer
Returns:
dbus_name, or empty string if not set

void alarm_action_set_label ( alarm_action_t *  self,
const char *  label 
)

Sets label string in alarm_action_t.

Parameters:
self : alarm_action_t pointer
label : string, or NULL to unset

void alarm_action_set_exec_command ( alarm_action_t *  self,
const char *  exec_command 
)

Sets exec_command string in alarm_action_t.

Parameters:
self : alarm_action_t pointer
exec_command : string, or NULL to unset

void alarm_action_set_dbus_interface ( alarm_action_t *  self,
const char *  dbus_interface 
)

Sets dbus_interface string in alarm_action_t.

Parameters:
self : alarm_action_t pointer
dbus_interface : string, or NULL to unset

void alarm_action_set_dbus_service ( alarm_action_t *  self,
const char *  dbus_service 
)

Sets dbus_service string in alarm_action_t.

Parameters:
self : alarm_action_t pointer
dbus_service : string, or NULL to unset

void alarm_action_set_dbus_path ( alarm_action_t *  self,
const char *  dbus_path 
)

Sets dbus_path string in alarm_action_t.

Parameters:
self : alarm_action_t pointer
dbus_path : string, or NULL to unset

void alarm_action_set_dbus_name ( alarm_action_t *  self,
const char *  dbus_name 
)

Sets dbus_name string in alarm_action_t.

Parameters:
self : alarm_action_t pointer
dbus_name : string, or NULL to unset

void alarm_recur_ctor ( alarm_recur_t *  self  ) 

Constructor.

Parameters:
self : alarm_recur_t pointer

void alarm_recur_dtor ( alarm_recur_t *  self  ) 

Destructor.

Parameters:
self : alarm_recur_t pointer

alarm_recur_t* alarm_recur_create ( void   ) 

Create new initialized alarm_recur_t object.

Returns:
pointer to initialized alarm_recur_t object

void alarm_recur_delete ( alarm_recur_t *  self  ) 

Cleanp and delete alarm_recur_t object.

Parameters:
self : alarm_recur_t pointer

void alarm_recur_init_from_tm ( alarm_recur_t *  self,
const struct tm *  tm 
)

Setup alarm_recur_t object from struct tm data.

Parameters:
self : alarm_recur_t pointer
tm : broken down time as struct tm

void alarm_recur_delete_cb ( void *  self  ) 

Normalized delete callback.

Parameters:
self : alarm recurrence object to free

time_t alarm_recur_align ( const alarm_recur_t *  self,
struct tm *  trg,
const char *  tz 
)

Align broken down time to recurrence rules, try not to advance time.

Special rules are ignored.

Parameters:
self : alarm recurrence object to free
trg : current trigger time as struct tm
tz : timezone to use for evaluation

time_t alarm_recur_next ( const alarm_recur_t *  self,
struct tm *  trg,
const char *  tz 
)

Align broken down time to recurrence rules, always advance time.

Special rules are applied before aligning to time / date masks.

Parameters:
self : alarm recurrence object to free
trg : current trigger time as struct tm
tz : timezone to use for evaluation

void alarm_event_delete ( alarm_event_t *  self  ) 

Will free all memory associated with the alarm event.

The alarm_event_t should be obtained via:

Parameters:
self : alarm event to free

alarm_event_t* alarm_event_create ( void   ) 

Create a new alarm event.

Allocates dynamic memory for alarm_event_t and initializes all values to sane defaults using alarm_event_ctor().

Use alarm_event_delete() to release the event structure.

Returns:
event : alarm_event_t pointer

alarm_event_t* alarm_event_create_ex ( size_t  actions  ) 

Create a new alarm event with actions.

Use alarm_event_delete() to release the event structure.

Returns:
event : alarm_event_t pointer

void alarm_event_delete_cb ( void *  self  ) 

Normalized delete callback.

Parameters:
self : alarm event to free

void alarm_event_ctor ( alarm_event_t *  self  ) 

Constructor.

Parameters:
self : alarm_event_t pointer

void alarm_event_dtor ( alarm_event_t *  self  ) 

Destructor.

Parameters:
self : alarm_event_t pointer

const char* alarm_event_get_title ( const alarm_event_t *  self  ) 

Gets title string from alarm_event_t.

Parameters:
self : alarm_event_t pointer
Returns:
title, or empty string if not set

void alarm_event_set_title ( alarm_event_t *  self,
const char *  title 
)

Sets title string in alarm_event_t.

Parameters:
self : alarm_event_t pointer
title : string, or NULL to unset

const char* alarm_event_get_message ( const alarm_event_t *  self  ) 

Gets message string from alarm_event_t.

Parameters:
self : alarm_event_t pointer
Returns:
message, or empty string if not set

void alarm_event_set_message ( alarm_event_t *  self,
const char *  message 
)

Sets message string in alarm_event_t.

Parameters:
self : alarm_event_t pointer
message : string, or NULL to unset

const char* alarm_event_get_sound ( const alarm_event_t *  self  ) 

Gets sound string from alarm_event_t.

Parameters:
self : alarm_event_t pointer
Returns:
sound, or empty string if not set

void alarm_event_set_sound ( alarm_event_t *  self,
const char *  sound 
)

Sets sound string in alarm_event_t.

Parameters:
self : alarm_event_t pointer
sound : string, or NULL to unset

const char* alarm_event_get_icon ( const alarm_event_t *  self  ) 

Gets icon string from alarm_event_t.

Parameters:
self : alarm_event_t pointer
Returns:
icon, or empty string if not set

void alarm_event_set_icon ( alarm_event_t *  self,
const char *  icon 
)

Sets icon string in alarm_event_t.

Parameters:
self : alarm_event_t pointer
icon : string, or NULL to unset

const char* alarm_event_get_alarm_appid ( const alarm_event_t *  self  ) 

Gets alarm_appid string from alarm_event_t.

Parameters:
self : alarm_event_t pointer
Returns:
alarm_appid, or empty string if not set

void alarm_event_set_alarm_appid ( alarm_event_t *  self,
const char *  alarm_appid 
)

Sets alarm_appid string in alarm_event_t.

Parameters:
self : alarm_event_t pointer
alarm_appid : string, or NULL to unset

const char* alarm_event_get_alarm_tz ( const alarm_event_t *  self  ) 

Gets alarm_tz string from alarm_event_t.

Parameters:
self : alarm_event_t pointer
Returns:
alarm_tz, or empty string if not set

void alarm_event_set_alarm_tz ( alarm_event_t *  self,
const char *  alarm_tz 
)

Sets alarm_tz string in alarm_event_t.

Parameters:
self : alarm_event_t pointer
alarm_tz : string, or NULL to unset

int alarm_event_is_recurring ( const alarm_event_t *  self  ) 

Check if alarm event is recurring.

Alarm event is recurring if:

Since:
v1.0.4
Parameters:
self : alarm_event_t pointer
Returns:
non zero value if alarm event is recurring

alarm_action_t* alarm_event_add_actions ( alarm_event_t *  self,
size_t  count 
)

Add & initialize actions to event.

Note: the pointer returned is valid until next call to alarm_event_add_actions() or alarm_event_del_actions().

Parameters:
self : alarm_event_t pointer
count : number of actions to add
Returns:
pointer to initialized new actions

alarm_action_t* alarm_event_get_action ( const alarm_event_t *  self,
int  index 
)

Get pointer to alarm event action by index.

Parameters:
self : alarm_event_t pointer
index : index of alarm action
Returns:
pointer to alarm action or NULL

void alarm_event_del_actions ( alarm_event_t *  self  ) 

Delete all actions from event and release all dynamic memory related to them.

Parameters:
self : alarm_event_t pointer

int alarm_event_set_action_dbus_args ( const alarm_event_t *  self,
int  index,
int  type,
  ... 
)

Helper method for manipulating alarm action dbus arguments.

Set dbus args for alarm event action. See alarm_action_set_dbus_args() for reference.

Parameters:
self : alarm_event_t pointer
index : action index
type : dbus type of first argument
... : dbus arguments
Returns:
error : 0=success, -1=errors

const char* alarm_event_get_action_dbus_args ( const alarm_event_t *  self,
int  index 
)

Helper method for manipulating alarm action dbus arguments.

Get serialized dbus args for alarm event action.

Parameters:
self : alarm_event_t pointer
index : action index
Returns:
serialized dbus args or NULL on error

void alarm_event_del_action_dbus_args ( const alarm_event_t *  self,
int  index 
)

Helper method for manipulating alarm action dbus arguments.

Delete serialized dbus args from alarm event action.

Parameters:
self : alarm_event_t pointer
index : action index

alarm_recur_t* alarm_event_add_recurrences ( alarm_event_t *  self,
size_t  count 
)

Add & initialize recurrence templates to event.

Note: the pointer returned is valid until next call to alarm_event_add_recurrences() or alarm_event_del_arecurrences().

Parameters:
self : alarm_event_t pointer
count : number of recurrencies to add
Returns:
pointer to initialized new recurrencies

alarm_recur_t* alarm_event_get_recurrence ( const alarm_event_t *  self,
int  index 
)

Get pointer to recurrence template in event.

Since:
v1.0.3
Note: the pointer returned is valid until next call to alarm_event_add_recurrences() or alarm_event_del_arecurrences().

Parameters:
self : alarm_event_t pointer
index : index of recurrence to get
Returns:
pointer to initialized new recurrencies

void alarm_event_del_recurrences ( alarm_event_t *  self  ) 

Delete all recurrence templates from event and release all dynamic memory related to them.

Parameters:
self : alarm_event_t pointer

void alarm_event_set_time ( alarm_event_t *  self,
const struct tm *  tm 
)

Set alarm time from broken down time.

Broken down time supplied will be used to calculate trigger time.

See also alarm_event_set_alarm_tz().

Parameters:
self : alarm_event_t pointer
tm : pointer to struct tm

void alarm_event_get_time ( const alarm_event_t *  self,
struct tm *  tm 
)

Get alarm time as broken down time.

If alarm event is configured to use absolute time instead of broken down time, the absolute time will be evaluated in currently active local timezone.

Parameters:
self : alarm_event_t pointer
tm : pointer to struct tm

int alarm_event_is_sane ( const alarm_event_t *  self  ) 

Check that alarm event content makes sense.

Goes through all the flags and fields in an alarm event strucure, logs out things that do not make sense.

Returns 1 if everything is ok, 0 if there were minor issues and -1 if event configuration is broken enough not to be usable.

Note: adding and updating events that return -1 on this test will fail already on the client side, the events will not be sent over to alarmd.

Since:
v1.0.3
Parameters:
self : alarm_event_t pointer
Returns:
1=ok, 0=warnings, -1=failure

void alarm_event_del_attrs ( alarm_event_t *  self  ) 

Remove all attributes from alarm event object.

Removes all attributes from alarm event object and releases all dynamic resources bound to them.

Since:
v1.0.4
Parameters:
self : alarm_event_t pointer

void alarm_event_rem_attr ( alarm_event_t *  self,
const char *  name 
)

Remove named attribute from alarm event object.

Removes named attribute from alarm event object.

Since:
v1.0.4
Parameters:
self : alarm_event_t pointer
name : attribute name

alarm_attr_t* alarm_event_get_attr ( alarm_event_t *  self,
const char *  name 
)

Locate named attribute from alarm event object.

Locates named attribute from alarm event object.

Since:
v1.0.4
Parameters:
self : alarm_event_t pointer
name : attribute name
Returns:
alarm_attr_t pointer, or NULL if no attribute was found

int alarm_event_has_attr ( alarm_event_t *  self,
const char *  name 
)

Check if alarm event object has named attribute.

Check if alarm event object has named attribute.

Since:
v1.0.4
Parameters:
self : alarm_event_t pointer
name : attribute name
Returns:
1 if attribute is present, or 0 if not

alarm_attr_t* alarm_event_add_attr ( alarm_event_t *  self,
const char *  name 
)

Adds named attribute to alarm event object.

Adds named attribute to alarm event object. If attribute by given name already exists that will be returned.

Since:
v1.0.4
Parameters:
self : alarm_event_t pointer
name : attribute name
Returns:
alarm_attr_t pointer

void alarm_event_set_attr_int ( alarm_event_t *  self,
const char *  name,
int  val 
)

Adds named integer attribute to alarm event object.

If attribute with the same name already exists, it will be converted to integer type with the given value.

Since:
v1.0.4
Parameters:
self : alarm_event_t pointer
name : attribute name
val : attribute value as integer

void alarm_event_set_attr_time ( alarm_event_t *  self,
const char *  name,
time_t  val 
)

Adds named time_t attribute to alarm event object.

If attribute with the same name already exists, it will be converted to time_t type with the given value.

Since:
v1.0.4
Parameters:
self : alarm_event_t pointer
name : attribute name
val : attribute value as time_t

void alarm_event_set_attr_string ( alarm_event_t *  self,
const char *  name,
const char *  val 
)

Adds named string attribute to alarm event object.

If attribute with the same name already exists, it will be converted to string type with the given value.

Since:
v1.0.4
Parameters:
self : alarm_event_t pointer
name : attribute name
val : attribute value as string

int alarm_event_get_attr_int ( alarm_event_t *  self,
const char *  name,
int  def 
)

Gets integer value of named attribute in alarm event object.

Gets integer value of named attribute in alarm event object. If the attribute does not exist, the given default value is returned.

Since:
v1.0.4
Parameters:
self : alarm_event_t pointer
name : attribute name
def : value to return if attribute is not found
Returns:
integer value or given default value

time_t alarm_event_get_attr_time ( alarm_event_t *  self,
const char *  name,
time_t  def 
)

Gets time_t value of named attribute in alarm event object.

Gets time_t value of named attribute in alarm event object. If the attribute does not exist, the given default value is returned.

Since:
v1.0.4
Parameters:
self : alarm_event_t pointer
name : attribute name
def : value to return if attribute is not found
Returns:
time_t value or given default value

const char* alarm_event_get_attr_string ( alarm_event_t *  self,
const char *  name,
const char *  def 
)

Gets string value of named attribute in alarm event object.

Gets string value of named attribute in alarm event object. If the attribute does not exist, the given default value is returned.

Since:
v1.0.4
Parameters:
self : alarm_event_t pointer
name : attribute name
def : value to return if attribute is not found
Returns:
string value or given default value

cookie_t alarmd_event_add ( const alarm_event_t *  event  ) 

Adds an event to the alarm queue.

No dialog will be shown unless the event has at least one action with non-empty label and ALARM_ACTION_WHEN_RESPONDED in flags.

Returns: Unique identifier for the alarm, or 0 on failure.

Parameters:
event : alarm_event_t pointer
Returns:
cookie : unique alarm event identifier

cookie_t alarmd_event_add_with_dbus_params ( const alarm_event_t *  event,
int  type,
  ... 
)

Adds an event with dbus parameters to the alarm queue.

Just like alarmd_event_add(), but with arguments for the D-Bus method call / signal.

The DBus arguments should be passed as pointers, like for dbus_message_append_args(). List should be terminated with DBUS_TYPE_INVALID.

The DBus arguments will be used for the first action that has null dbus_args and ALARM_ACTION_TYPE_DBUS set in flags. If such action is not found, error is returned and event is not sent to alarmd.

Note, you need dbus/dbus-protocol.h for the type macros.

Parameters:
event : alarm_event_t pointer
type : dbus type identifier of the the first element to add
Returns:
cookie : unique alarm event identifier, or 0 = failure

int alarmd_event_del ( cookie_t  cookie  ) 

Deletes alarm from the alarm queue.

The alarm with the event_cookie identifier will be removed from the alarm queue, if it exists.

Parameters:
cookie : unique alarm event identifier
Returns:
error : 0 = no error, -1 = error

cookie_t alarmd_event_update ( const alarm_event_t *  event  ) 

Updates an event already in the alarm queue.

Uses only one dbus transaction, acts bit like doing:

  1. alarmd_event_del(event->cookie);
  2. alarmd_event_add(event);

Notes:

Parameters:
event : alarm_event_t pointer with nonzero event->cookie
Returns:
cookie : unique alarm event identifier, or 0 on error

cookie_t* alarmd_event_query ( const time_t  first,
const time_t  last,
int32_t  flag_mask,
int32_t  flags,
const char *  appid 
)

Queries alarms in given time span.

Finds every alarm whose _next_ occurence time is between first and last.

Returns zero-terminated array of alarm cookies.

Use free() to release the returned array.

Special cases:

So alarmd_event_query(0,0, 0,0, appid) will return cookies of alarms for the given appid, and alarmd_event_query(0,0, 0,0, NULL) will return all cookies for all alarms for all apps.

Parameters:
first : start of time span (inclusive)
last : end of time span (inclusive)
flag_mask : Mask describing which flags you're interested in. Pass 0 to get all events.
flags : Values for the flags you're querying.
appid : Name of application, or NULL for all
Returns:
cookies : zero terminated array of cookies

alarm_event_t* alarmd_event_get ( cookie_t  cookie  ) 

Fetches alarm defails.

Finds an alarm with given identifier and returns alarm_event_t struct describing it.

Use alarm_event_delete() to release the event structure.

Parameters:
cookie : unique alarm event identifier
Returns:
event : alarm_event_t pointer

int alarmd_set_default_snooze ( unsigned int  snooze  ) 

Sets the amount events will be snoozed by default.

Sets the amount events will be snoozed by default.

Using value of zero will restore the builtin default value (10 minutes).

Parameters:
snooze : preferred snooze time in seconds
Returns:
error : 0=success, -1=errors

unsigned int alarmd_get_default_snooze ( void   ) 

Gets the amount events will be snoozed by default.

Gets the amount events will be snoozed by default.

Returns:
snooze : preferred snooze time in seconds

Generated on Tue Feb 24 16:21:30 2009 for libalarm by  doxygen 1.5.1