alarm_event

alarm_event — The C client API

Synopsis



typedef     cookie_t;
enum        alarmeventflags;
enum        alarm_error_t;
            alarm_event_t;
cookie_t    alarm_event_add                 (alarm_event_t *event);
cookie_t    alarm_event_add_with_dbus_params
                                            (alarm_event_t *event,
                                             int first_arg_type,
                                             ...);
int         alarm_event_del                 (cookie_t event_cookie);
cookie_t*   alarm_event_query               (const time_t first,
                                             const time_t last,
                                             int32_t flag_mask,
                                             int32_t flags);
alarm_event_t* alarm_event_get              (cookie_t event_cookie);
void        alarm_event_free                (alarm_event_t *event);
char*       alarm_escape_string             (const char *string);
char*       alarm_unescape_string           (const char *string);
char*       alarm_unescape_string_noalloc   (char *string);
alarm_error_t alarmd_get_error              (void);
int         alarmd_set_default_snooze       (unsigned int snooze);
unsigned int alarmd_get_default_snooze      (void);

Description

Includes functions to communicate with the alarm daemon from another program.

Details

cookie_t

typedef long cookie_t;

Unique identifier type for the alarm events.

enum alarmeventflags

typedef enum {
	ALARM_EVENT_NO_DIALOG = 1 << 0,	/* Do not show the alarm dialog */
	ALARM_EVENT_NO_SNOOZE = 1 << 1,	/* Disable the snooze button */
	ALARM_EVENT_SYSTEM = 1 << 2,	/* Use the DBus system bus */
	ALARM_EVENT_BOOT = 1 << 3,	/* Boot up the system */
	ALARM_EVENT_ACTDEAD = 1 << 4,	/* Boot into alarm mode */
	ALARM_EVENT_SHOW_ICON = 1 << 5, /* Show alarm icon on statusbar */
	ALARM_EVENT_RUN_DELAYED = 1 << 6, /* Should the alarm be run on
					     startup if missed. */
	ALARM_EVENT_CONNECTED = 1 << 7, /* Run only when connected. */
	ALARM_EVENT_ACTIVATION = 1 << 8, /* Should DBus call use activation. */
	ALARM_EVENT_POSTPONE_DELAYED = 1 << 9, /* Should the alarm be postponed
						  if missed. */
	ALARM_EVENT_BACK_RESCHEDULE = 1 << 10, /* Should the alarm be moved
						  backwards, if time is changed
						  backwards. */
} alarmeventflags;

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

ALARM_EVENT_NO_DIALOG The alarm event should not show a dialog.
ALARM_EVENT_NO_SNOOZE The alarm dialog shoud not have snooze enabled.
ALARM_EVENT_SYSTEM The dbus call should be done on system bus.
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 The event should show a icon in the status bar.
ALARM_EVENT_RUN_DELAYED The event should be launched on next startup, if missed or immediately if jumped over.
ALARM_EVENT_CONNECTED The event should be launched only when connected to the internet.
ALARM_EVENT_ACTIVATION The dbus action should use DBus activation.
ALARM_EVENT_POSTPONE_DELAYED The event should be postponed to next day if miesed or jumped over.
ALARM_EVENT_BACK_RESCHEDULE The event should be moved backwards, if the time is moved backwards. Applies only to recurring events.

enum alarm_error_t

typedef enum {
	ALARMD_SUCCESS,
	ALARMD_ERROR_DBUS,
	ALARMD_ERROR_CONNECTION,
	ALARMD_ERROR_INTERNAL,
	ALARMD_ERROR_MEMORY,
	ALARMD_ERROR_ARGUMENT,
	ALARMD_ERROR_NOT_RUNNING
} alarm_error_t;

Error codes for an alarmd operation.

ALARMD_SUCCESS No error occurred during the operation.
ALARMD_ERROR_DBUS An error with DBus occurred, probably couldn't get a DBus connection.
ALARMD_ERROR_CONNECTION An error occurred while trying to connect to alarmd.
ALARMD_ERROR_INTERNAL An libalarm internal error occurred, possibly a version mismatch.
ALARMD_ERROR_MEMORY Memory exhausted while running operation.
ALARMD_ERROR_ARGUMENT An argument given by caller was invalid.
ALARMD_ERROR_NOT_RUNNING Alarmd was not running.

alarm_event_t

typedef struct {
	time_t alarm_time;		/* Time of alarm; UTC */
	uint32_t recurrence;		/* Number of minutes between
					 * each recurrence;
					 * 0 for one-shot alarms
					 */
	int32_t recurrence_count;	/* Number of recurrences, use -1 for
       					   infinite. */
	uint32_t snooze;		/* Number of minutes an alarm is
					 * potstponed on snooze. 0 for
					 * default */
	char *title;			/* Title of the alarm */
	char *message;			/* Alarm message to display */
	char *sound;			/* Alarm sound to play */
	char *icon;			/* Alarm icon to use */
	char *dbus_interface;		/* DBus callback: interface */
	char *dbus_service;		/* DBus callback: service
					 * set to NULL to send a signal
					 */
	char *dbus_path;		/* DBus callback: path */
	char *dbus_name;		/* DBus callback: method_call/signal */
	char *exec_name;		/* File callback: file to execute */
	int32_t flags;			/* Event specific behaviour */

	uint32_t snoozed;		/* How much the event has been
					   snoozed. */
} alarm_event_t;

Describes an alarm event.

time_t alarm_time; Time of alarm.
uint32_t recurrence; Number of minutes between each recurrence.
int32_t recurrence_count; Number of recurrences, -1 for infinite.
uint32_t snooze; Number of minutes an event is postponed on snooze.
char *title; The title of the alarm dialog.
char *message; The message in the alarm dialog.
char *sound; The sound played while showin the alarm dialog.
char *icon; The icon shown in the alarm dialog.
char *dbus_interface; The interface for the dbus call.
char *dbus_service; The service for the dbus call.
char *dbus_path; The path for the dbus call.
char *dbus_name; The name of the dbus call.
char *exec_name; The command to be run.
int32_t flags; Bitfield describing the event, see alarmeventflags.
uint32_t snoozed; Amount of minutes the event has been snoozed.

alarm_event_add ()

cookie_t    alarm_event_add                 (alarm_event_t *event);

Adds an event to the alarm queue. If event->exec_name and event->dbus_path are NULL, the alarm will be only show a dialog (unless ALARM_EVENT_NO_DIALOG is set in flags, in which case, the event does nothing). If only event->dbus_path is NULL, the alarm will run a program at given time (and show a dialog unless otherwise instructed). If recurrence > 0, the alarm will repeat recurrence_count times. If snooze_time is zero, default of 10 minutes is used.

event : alarm_event_t struct describing the event to be added.
Returns : Unique identifier for the alarm, or 0 on failure.

alarm_event_add_with_dbus_params ()

cookie_t    alarm_event_add_with_dbus_params
                                            (alarm_event_t *event,
                                             int first_arg_type,
                                             ...);

Just like alarm_event_add, but with arguments for the DBus call. The DBus arguments should be passed as pointers, like for dbus_message_append_args. List should be terminated with DBUS_TYPE_INVALID. Note, you need dbus/dbus-protocol.h for the type macros.

event : alarm_event_t struct describing the event to be added.
first_arg_type : Type of first argument to the DBus actionn.
... : Type-value pairs of the arguments to the dbus call; end with DBUS_TYPE_INVALID.
Returns : Unique identifier for the alarm, or 0 on failure.

alarm_event_del ()

int         alarm_event_del                 (cookie_t event_cookie);

Deletes alarm from the alarm queue. The alarm with the event_cookie identifier will be removed from the alarm queue, if it exists. For more details on errors, use alarmd_get_eroror.

event_cookie : Unique identifier of the alarm to be removed.
Returns : 1 If alarm was on the queue, 0 if not and -1 on errors.

alarm_event_query ()

cookie_t*   alarm_event_query               (const time_t first,
                                             const time_t last,
                                             int32_t flag_mask,
                                             int32_t flags);

Queries alarms in given time span. Finds every alarm whose _next_ occurence time is between first and last.

first : Alarms happening after this time will be returned.
last : Alarms: happening before this time will be returned.
flag_mask : A mask describing which flags you're interested in. Pass 0 to get all events.
flags : Values for the flags you're querying.
Returns : Newly allocated, zero-terminated list of alarm id's, should be free()'d.

alarm_event_get ()

alarm_event_t* alarm_event_get              (cookie_t event_cookie);

Fetches alarm defails. Finds an alarm with given identifier and returns alarm_event struct describing it.

event_cookie : Unique identifier of the alarm.
Returns : Newly allocated alarm_event struct, should be free'd with alarm_event_free().

alarm_event_free ()

void        alarm_event_free                (alarm_event_t *event);

Frees given alarm_event struct. Will free all memory associated with the alarm_event struct.

event : The alarm_event struct to be free'd.

alarm_escape_string ()

char*       alarm_escape_string             (const char *string);

Escapes a string to be used as alarm dialog message or title. All { and } characters will be escaped with backslash and all backslashes will be duplicated.

string : The string that should be escaped.
Returns : Newly allocated string, should be freed with free().

alarm_unescape_string ()

char*       alarm_unescape_string           (const char *string);

Unescapes a string escaped with alarm_escape_string.

string : The string that should be unescaped.
Returns : Newly allocated string, should be freed with free().

alarm_unescape_string_noalloc ()

char*       alarm_unescape_string_noalloc   (char *string);

Unescapes a string escaped with alarm_escape_string. Note, string is modified.

string : The string that should be unescaped.
Returns : string.

alarmd_get_error ()

alarm_error_t alarmd_get_error              (void);

Gets the error code for previous action.

Returns : The error code.

alarmd_set_default_snooze ()

int         alarmd_set_default_snooze       (unsigned int snooze);

Sets the amount events will be snoozed by default.

snooze : The preferred snooze time in minutes.
Returns : 1 on success, 0 on failure.

alarmd_get_default_snooze ()

unsigned int alarmd_get_default_snooze      (void);

Gets the amount events will be snoozed by default.

Returns : The preferred snooze time in minutes.