Main Page | Data Structures | File List | Data Fields | Globals

include/alarm_event.h

Go to the documentation of this file.
00001 /**
00002  * This file is part of alarmd
00003  *
00004  * Contact Person: David Weinehall <david.weinehall@nokia.com>
00005  *
00006  * Copyright (C) 2006 Nokia Corporation
00007  * alarmd and libalarm are free software; you can redistribute them
00008  * and/or modify them under the terms of the GNU Lesser General Public
00009  * License version 2.1 as published by the Free Software Foundation.
00010  *
00011  * alarmd and libalarm are distributed in the hope that they will be useful,
00012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00014  * Lesser General Public License for more details.
00015  *
00016  * You should have received a copy of the GNU Lesser General Public
00017  * License along with this software; if not, write to the Free
00018  * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
00019  * 02110-1301 USA
00020  */
00021 
00022 #ifndef _ALARM_EVENT_H_
00023 #define _ALARM_EVENT_H_
00024 
00025 #include <stdint.h>
00026 #include <time.h>
00027 
00028 /**
00029  * SECTION:alarm_event
00030  * @short_description: The C client API
00031  * 
00032  * Includes functions to communicate with the alarm daemon from another
00033  * program.
00034  **/
00035 
00036 /**
00037  * cookie_t:
00038  *
00039  * Unique identifier type for the alarm events.
00040  **/
00041 typedef long cookie_t;
00042 
00043 /**
00044  * alarmeventflags:
00045  * @ALARM_EVENT_NO_DIALOG: The alarm event should not show a dialog.
00046  * @ALARM_EVENT_NO_SNOOZE: The alarm dialog shoud not have snooze enabled.
00047  * @ALARM_EVENT_SYSTEM: The dbus call should be done on system bus.
00048  * @ALARM_EVENT_BOOT: The event should boot up the system, if powered off.
00049  * @ALARM_EVENT_ACTDEAD: The device should only be powered to acting dead mode.
00050  * @ALARM_EVENT_SHOW_ICON: The event should show a icon in the status bar.
00051  * @ALARM_EVENT_RUN_DELAYED: The event should be launched on next startup,
00052  * if missed or immediately if jumped over.
00053  * @ALARM_EVENT_CONNECTED: The event should be launched only when connected to
00054  * the internet.
00055  * @ALARM_EVENT_ACTIVATION: The dbus action should use DBus activation.
00056  * @ALARM_EVENT_POSTPONE_DELAYED: The event should be postponed to next day
00057  * if miesed or jumped over.
00058  * @ALARM_EVENT_BACK_RESCHEDULE: The event should be moved backwards, if the
00059  * time is moved backwards. Applies only to recurring events.
00060  *
00061  * Describes alarm event. These should be bitwise orred to the flags field in
00062  * #alarm_event_t.
00063  **/
00064 typedef enum {
00065         ALARM_EVENT_NO_DIALOG = 1 << 0, /* Do not show the alarm dialog */
00066         ALARM_EVENT_NO_SNOOZE = 1 << 1, /* Disable the snooze button */
00067         ALARM_EVENT_SYSTEM = 1 << 2,    /* Use the DBus system bus */
00068         ALARM_EVENT_BOOT = 1 << 3,      /* Boot up the system */
00069         ALARM_EVENT_ACTDEAD = 1 << 4,   /* Boot into alarm mode */
00070         ALARM_EVENT_SHOW_ICON = 1 << 5, /* Show alarm icon on statusbar */
00071         ALARM_EVENT_RUN_DELAYED = 1 << 6, /* Should the alarm be run on
00072                                              startup if missed. */
00073         ALARM_EVENT_CONNECTED = 1 << 7, /* Run only when connected. */
00074         ALARM_EVENT_ACTIVATION = 1 << 8, /* Should DBus call use activation. */
00075         ALARM_EVENT_POSTPONE_DELAYED = 1 << 9, /* Should the alarm be postponed
00076                                                   if missed. */
00077         ALARM_EVENT_BACK_RESCHEDULE = 1 << 10, /* Should the alarm be moved
00078                                                   backwards, if time is changed
00079                                                   backwards. */
00080 } alarmeventflags;
00081 
00082 typedef enum {
00083         ALARMD_SUCCESS,
00084         ALARMD_ERROR_DBUS,
00085         ALARMD_ERROR_CONNECTION,
00086         ALARMD_ERROR_INTERNAL,
00087         ALARMD_ERROR_MEMORY,
00088         ALARMD_ERROR_ARGUMENT
00089 } alarm_error_t;
00090         
00091 /**
00092  * alarm_event_t:
00093  * @alarm_time: Time of alarm.
00094  * @recurrence: Number of minutes between each recurrence.
00095  * @recurrence_count: Number of recurrences, -1 for infinite.
00096  * @snooze: Number of minutes an event is postponed on snooze.
00097  * @title: The title of the alarm dialog.
00098  * @message: The message in the alarm dialog.
00099  * @sound: The sound played while showin the alarm dialog.
00100  * @icon: The icon shown in the alarm dialog.
00101  * @dbus_interface: The interface for the dbus call.
00102  * @dbus_service: The service for the dbus call.
00103  * @dbus_path: The path for the dbus call.
00104  * @dbus_name: The name of the dbus call.
00105  * @exec_name: The command to be run.
00106  * @flags: Bitfield describing the event, see #alarmeventflags.
00107  *
00108  * Describes an alarm event.
00109  **/
00110 typedef struct {
00111         time_t alarm_time;              /* Time of alarm; UTC */
00112         uint32_t recurrence;            /* Number of minutes between
00113                                          * each recurrence;
00114                                          * 0 for one-shot alarms
00115                                          */
00116         int32_t recurrence_count;       /* Number of recurrences, use -1 for
00117                                            infinite. */
00118         uint32_t snooze;                /* Number of minutes an alarm is
00119                                          * potstponed on snooze. 0 for
00120                                          * default */
00121         char *title;                    /* Title of the alarm */
00122         char *message;                  /* Alarm message to display */
00123         char *sound;                    /* Alarm sound to play */
00124         char *icon;                     /* Alarm icon to use */
00125         char *dbus_interface;           /* DBus callback: interface */
00126         char *dbus_service;             /* DBus callback: service
00127                                          * set to NULL to send a signal
00128                                          */
00129         char *dbus_path;                /* DBus callback: path */
00130         char *dbus_name;                /* DBus callback: method_call/signal */
00131         char *exec_name;                /* File callback: file to execute */
00132         int32_t flags;                  /* Event specific behaviour */
00133 
00134         uint32_t snoozed;               /* How much the event has been
00135                                            snoozed. */
00136 } alarm_event_t;
00137 
00138 /**
00139  * alarm_event_add:
00140  * @event: #alarm_event_t struct describing the event to be added.
00141  *
00142  * Adds an event to the alarm queue.
00143  * If event->exec_name and event->dbus_path are NULL, the alarm will be only
00144  * show a dialog (unless #ALARM_EVENT_NO_DIALOG is set in flags, in which case,
00145  * the event does nothing). If only event->dbus_path is NULL, the alarm will
00146  * run a program at given time (and show a dialog unless otherwise
00147  * instructed). If recurrence > 0, the alarm will repeat recurrence_count
00148  * times. If snooze_time is zero, default of 10 minutes is used.
00149  * Returns: Unique identifier for the alarm, or 0 on failure.
00150  **/
00151 cookie_t alarm_event_add(alarm_event_t *event);
00152 
00153 /**
00154  * alarm_event_del:
00155  * @event_cookie: Unique identifier of the alarm to be removed.
00156  *
00157  * Deletes alarm from the alarm queue.
00158  * The alarm with the event_cookie identifier will be removed from the
00159  * alarm queue, if it exists.
00160  * Returns: 1 If alarm was on the queue, 0 otherwise.
00161  **/
00162 int alarm_event_del(cookie_t event_cookie);
00163 
00164 /**
00165  * alarm_event_query:
00166  * @first: Alarms happening after this time will be returned.
00167  * @last: Alarms: happening before this time will be returned.
00168  * @flag_mask: A mask describing which flags you're interested in.
00169  *              Pass 0 to get all events.
00170  * @flags: Values for the flags you're querying.
00171  *
00172  * Queries alarms in given time span.
00173  * Finds every alarm whose _next_ occurence time is between first and last.
00174  * Returns: Newly allocated, zero-terminated list of alarm id's, should be
00175  *         free()'d.
00176  **/
00177 cookie_t *alarm_event_query(const time_t first, const time_t last,
00178                 int32_t flag_mask, int32_t flags);
00179 
00180 /**
00181  * alarm_event_get:
00182  * @event_cookie: Unique identifier of the alarm.
00183  *
00184  * Fetches alarm defails.
00185  * Finds an alarm with given identifier and returns alarm_event struct
00186  * describing it.
00187  * Returns: Newly allocated alarm_event struct, should be free'd with
00188  *         alarm_event_free().
00189  **/
00190 alarm_event_t *alarm_event_get(cookie_t event_cookie);
00191 
00192 /**
00193  * alarm_event_free:
00194  * @event: The alarm_event struct to be free'd.
00195  *
00196  * Frees given alarm_event struct.
00197  * Will free all memory associated with the alarm_event struct.
00198  **/
00199 void alarm_event_free(alarm_event_t *event);
00200 
00201 /**
00202  * alarm_escape_string:
00203  * @string: The string that should be escaped.
00204  *
00205  * Escapes a string to be used as alarm dialog message or title. All { and }
00206  * characters will be escaped with backslash and all backslashes will be
00207  * duplicated.
00208  * Returns: Newly allocated string, should be freed with free().
00209  **/
00210 char *alarm_escape_string(const char *string);
00211 
00212 /**
00213  * alarm_unescape_string:
00214  * @string: The string that should be unescaped.
00215  *
00216  * Unescapes a string escaped with alarm_escape_string.
00217  * Returns: Newly allocated string, should be freed with free().
00218  **/
00219 char *alarm_unescape_string(const char *string);
00220 
00221 /**
00222  * alarm_unescape_string_noalloc:
00223  * @string: The string that should be unescaped.
00224  *
00225  * Unescapes a string escaped with alarm_escape_string. Note, @string is
00226  * modified.
00227  * Returns: @string.
00228  **/
00229 char *alarm_unescape_string_noalloc(char *string);
00230 
00231 /**
00232  * alarmd_get_error:
00233  * 
00234  * Gets the error code for previous action.
00235  **/
00236 alarm_error_t alarmd_get_error(void);
00237 
00238 /**
00239  * alarmd_set_default_snooze:
00240  * @snooze: The preferred snooze time in minutes.
00241  *
00242  * Sets the amount events will be snoozed by default.
00243  * Returns: 1 on success, 0 on failure.
00244  **/
00245 int alarmd_set_default_snooze(unsigned int snooze);
00246 
00247 /**
00248  * alarmd_get_default_snooze:
00249  * 
00250  * Gets the amount events will be snoozed by default.
00251  * Returns: The preferred snooze time in minutes.
00252  **/
00253 unsigned int alarmd_get_default_snooze(void);
00254 
00255 #endif /* _ALARM_EVENT_H_ */

Generated on Thu Dec 21 18:23:30 2006 for Alarmd by  doxygen 1.4.2