1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
|
/*
* kalarmiface.h - DCOP interface to KAlarm
* Program: kalarm
* Copyright © 2004-2006,2008 by David Jarvie <djarvie@kde.org>
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License along
* with this program; if not, write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
*/
#ifndef KALARMIFACE_H
#define KALARMIFACE_H
/** @file kalarmiface.h - DCOP interface to KAlarm */
// No forward declarations - dcopidl2cpp won't work
#include <dcopobject.h>
#include <kurl.h>
#include <qstringlist.h>
class QString;
/** KAlarmIface provides a DCOP interface for other applications to request
* KAlarm actions.
*/
class KAlarmIface : virtual public DCOPObject
{
K_DCOP
public:
/** Bit values for the @p flags parameter of "scheduleXxxx()" DCOP calls.
* The bit values may be OR'ed together.
* @li REPEAT_AT_LOGIN - repeat the alarm at every login.
* @li BEEP - sound an audible beep when the alarm is displayed.
* @li SPEAK - speak the alarm message when it is displayed.
* @li REPEAT_SOUND - repeat the sound file while the alarm is displayed.
* @li CONFIRM_ACK - closing the alarm message window requires a confirmation prompt.
* @li AUTO_CLOSE - auto-close the alarm window after the late-cancel period.
* @li SCRIPT - the command to execute is a script, not a shell command line.
* @li EXEC_IN_XTERM - execute the command alarm in a terminal window.
* @li EMAIL_BCC - send a blind copy the email to the user.
* @li SHOW_IN_KORG - show the alarm as an event in KOrganizer
* @li DISABLED - set the alarm status to disabled.
*/
enum Flags
{
REPEAT_AT_LOGIN = 0x01, // repeat alarm at every login
BEEP = 0x02, // sound audible beep when alarm is displayed
REPEAT_SOUND = 0x08, // repeat sound file while alarm is displayed
CONFIRM_ACK = 0x04, // closing the alarm message window requires confirmation prompt
AUTO_CLOSE = 0x10, // auto-close alarm window after late-cancel period
EMAIL_BCC = 0x20, // blind copy the email to the user
DISABLED = 0x40, // alarm is currently disabled
SCRIPT = 0x80, // command is a script, not a shell command line
EXEC_IN_XTERM = 0x100, // execute command alarm in terminal window
SPEAK = 0x200, // speak the alarm message when it is displayed
SHOW_IN_KORG = 0x400 // show the alarm as an event in KOrganizer
};
/** Values for the @p repeatType parameter of "scheduleXxxx()" DCOP calls.
* @li MINUTELY - the repeat interval is measured in minutes.
* @li DAILY - the repeat interval is measured in days.
* @li WEEKLY - the repeat interval is measured in weeks.
* @li MONTHLY - the repeat interval is measured in months.
* @li YEARLY - the repeat interval is measured in years.
*/
enum RecurType
{
MINUTELY = 1, // the repeat interval is measured in minutes
DAILY = 2, // the repeat interval is measured in days
WEEKLY = 3, // the repeat interval is measured in weeks
MONTHLY = 4, // the repeat interval is measured in months
YEARLY = 5 // the repeat interval is measured in years
};
k_dcop:
/** Cancel (delete) an already scheduled alarm.
* @param url - The URL (not path) of the calendar file containing the event to be cancelled.
* Used only for integrity checking: the call will fail if it is not KAlarm's
* current calendar file.
* @param eventId - The unique ID of the event to be cancelled, as stored in the calendar file @p url.
*/
virtual bool cancelEvent(const QString& url, const QString& eventId) = 0;
/** Trigger the immediate display or execution of an alarm, regardless of what time it is scheduled for.
* @param url - The URL (not path) of the calendar file containing the event to be triggered.
* Used only for integrity checking: the call will fail if it is not KAlarm's
* current calendar file.
* @param eventId - The unique ID of the event to be triggered, as stored in the calendar file @p url.
*/
virtual bool triggerEvent(const QString& url, const QString& eventId) = 0;
/** Schedule a message display alarm.
* @param message The text of the message to display.
* @param startDateTime Start date/time, in the format YYYY-MM-DD[THH:MM[:SS]] or [T]HH:MM[:SS]
* @param lateCancel Late-cancellation period in minutes, or 0 for no cancellation.
* @param flags OR of flag bits defined in Flags enum.
* @param bgColor The background colour for the alarm message window, or QString::null for the
* current default background colour. The string may be in any of the formats
* accepted by QColor::QColor(const QString&).
* @param fgColor The foreground colour for the alarm message, or QString::null for the current
* default foreground colour. The format of the string is the same as for @p bgColor.
* @param font The font for the alarm message, or QString::null for the default message font
* current at the time the message is displayed. The string should be in format
* returned by QFont::toString().
* @param audioFile The audio file to play when the alarm is displayed, or QString::null for none.
* @param reminderMins The number of minutes in advance of the main alarm and its recurrences to display
* a reminder alarm, or 0 for no reminder.
* @param recurrence Recurrence specification using iCalendar syntax (defined in RFC2445).
* @param repeatInterval Simple repetition repeat interval in minutes, or 0 for no sub-repetition.
* @param repeatCount Simple repetition repeat count (after the first occurrence), or 0 for no sub-repetition.
* @return true if alarm was scheduled successfully, false if configuration errors were found.
*/
virtual bool scheduleMessage(const QString& message, const QString& startDateTime, int lateCancel, unsigned flags,
const QString& bgColor, const QString& fgColor, const QString& font,
const KURL& audioFile, int reminderMins, const QString& recurrence,
int repeatInterval, int repeatCount) = 0;
/** Schedule a message display alarm.
* @param message The text of the message to display.
* @param startDateTime Start date/time, in the format YYYY-MM-DD[THH:MM[:SS]] or [T]HH:MM[:SS]
* @param lateCancel Late-cancellation period in minutes, or 0 for no cancellation.
* @param flags OR of flag bits defined in Flags enum.
* @param bgColor The background colour for the alarm message window, or QString::null for the
* current default background colour. The string may be in any of the formats
* accepted by QColor::QColor(const QString&).
* @param fgColor The foreground colour for the alarm message, or QString::null for the current
* default foreground colour. The format of the string is the same as for @p bgColor.
* @param font The font for the alarm message, or QString::null for the default message font
* current at the time the message is displayed. The string should be in format
* returned by QFont::toString().
* @param audioFile The audio file to play when the alarm is displayed, or QString::null for none.
* @param reminderMins The number of minutes in advance of the main alarm and its recurrences to display
* a reminder alarm, or 0 for no reminder.
* @param repeatType The time units to use for recurrence. The actual recurrence interval is equal to
* @p repeatType multiplied by @p repeatInterval.
* The value of @p repeatType must a value defined in the RecurType enum.
* @param repeatInterval Recurrence interval in units defined by @p repeatType, or 0 for no recurrence.
* @param repeatCount Recurrence count (after the first occurrence), or 0 for no recurrence.
* @return true if alarm was scheduled successfully, false if configuration errors were found.
*/
virtual bool scheduleMessage(const QString& message, const QString& startDateTime, int lateCancel, unsigned flags,
const QString& bgColor, const QString& fgColor, const QString& font,
const KURL& audioFile, int reminderMins,
int repeatType, int repeatInterval, int repeatCount) = 0;
/** Schedule a message display alarm.
* @param message The text of the message to display.
* @param startDateTime Start date/time, in the format YYYY-MM-DD[THH:MM[:SS]] or [T]HH:MM[:SS]
* @param lateCancel Late-cancellation period in minutes, or 0 for no cancellation.
* @param flags OR of flag bits defined in Flags enum.
* @param bgColor The background colour for the alarm message window, or QString::null for the
* current default background colour. The string may be in any of the formats
* accepted by QColor::QColor(const QString&).
* @param fgColor The foreground colour for the alarm message, or QString::null for the current
* default foreground colour. The format of the string is the same as for @p bgColor.
* @param font The font for the alarm message, or QString::null for the default message font
* current at the time the message is displayed. The string should be in format
* returned by QFont::toString().
* @param audioFile The audio file to play when the alarm is displayed, or QString::null for none.
* @param reminderMins The number of minutes in advance of the main alarm and its recurrences to display
* a reminder alarm, or 0 for no reminder.
* @param repeatType The time units to use for recurrence. The actual recurrence interval is equal to
* @p repeatType multiplied by @p repeatInterval.
* The value of @p repeatType must a value defined in the RecurType enum.
* @param repeatInterval Recurrence interval in units defined by @p repeatType, or 0 for no recurrence.
* @param endDateTime Date/time after which the recurrence will end.
* @return true if alarm was scheduled successfully, false if configuration errors were found.
*/
virtual bool scheduleMessage(const QString& message, const QString& startDateTime, int lateCancel, unsigned flags,
const QString& bgColor, const QString& fgColor, const QString& font,
const KURL& audioFile, int reminderMins,
int repeatType, int repeatInterval, const QString& endDateTime) = 0;
/** Schedule a file display alarm.
* @param file The text or image file to display.
* @param startDateTime Start date/time, in the format YYYY-MM-DD[THH:MM[:SS]] or [T]HH:MM[:SS]
* @param lateCancel Late-cancellation period in minutes, or 0 for no cancellation.
* @param flags OR of flag bits defined in Flags enum.
* @param bgColor The background colour for the alarm message window, or QString::null for the
* current default background colour. The string may be in any of the formats
* accepted by QColor::QColor(const QString&).
* @param audioFile The audio file to play when the alarm is displayed, or QString::null for none.
* @param reminderMins The number of minutes in advance of the main alarm and its recurrences to display
* a reminder alarm, or 0 for no reminder.
* @param recurrence Recurrence specification using iCalendar syntax (defined in RFC2445).
* @param repeatInterval Simple repetition repeat interval in minutes, or 0 for no sub-repetition.
* @param repeatCount Simple repetition repeat count (after the first occurrence), or 0 for no sub-repetition.
* @return true if alarm was scheduled successfully, false if configuration errors were found.
*/
virtual bool scheduleFile(const KURL& file, const QString& startDateTime, int lateCancel, unsigned flags, const QString& bgColor,
const KURL& audioFile, int reminderMins, const QString& recurrence,
int repeatInterval, int repeatCount) = 0;
/** Schedule a file display alarm.
* @param file The text or image file to display.
* @param startDateTime Start date/time, in the format YYYY-MM-DD[THH:MM[:SS]] or [T]HH:MM[:SS]
* @param lateCancel Late-cancellation period in minutes, or 0 for no cancellation.
* @param flags OR of flag bits defined in Flags enum.
* @param bgColor The background colour for the alarm message window, or QString::null for the
* current default background colour. The string may be in any of the formats
* accepted by QColor::QColor(const QString&).
* @param audioFile The audio file to play when the alarm is displayed, or QString::null for none.
* @param reminderMins The number of minutes in advance of the main alarm and its recurrences to display
* a reminder alarm, or 0 for no reminder.
* @param repeatType The time units to use for recurrence. The actual recurrence interval is equal to
* @p repeatType multiplied by @p repeatInterval.
* The value of @p repeatType must a value defined in the RecurType enum.
* @param repeatInterval Recurrence interval in units defined by @p repeatType, or 0 for no recurrence.
* @param repeatCount Recurrence count (after the first occurrence), or 0 for no recurrence.
* @return true if alarm was scheduled successfully, false if configuration errors were found.
*/
virtual bool scheduleFile(const KURL& file, const QString& startDateTime, int lateCancel, unsigned flags, const QString& bgColor,
const KURL& audioFile, int reminderMins, int repeatType, int repeatInterval, int repeatCount) = 0;
/** Schedule a file display alarm.
* @param file The text or image file to display.
* @param startDateTime Start date/time, in the format YYYY-MM-DD[THH:MM[:SS]] or [T]HH:MM[:SS]
* @param lateCancel Late-cancellation period in minutes, or 0 for no cancellation.
* @param flags OR of flag bits defined in Flags enum.
* @param bgColor The background colour for the alarm message window, or QString::null for the
* current default background colour. The string may be in any of the formats
* accepted by QColor::QColor(const QString&).
* @param audioFile The audio file to play when the alarm is displayed, or QString::null for none.
* @param reminderMins The number of minutes in advance of the main alarm and its recurrences to display
* a reminder alarm, or 0 for no reminder.
* @param repeatType The time units to use for recurrence. The actual recurrence interval is equal to
* @p repeatType multiplied by @p repeatInterval.
* The value of @p repeatType must a value defined in the RecurType enum.
* @param repeatInterval Recurrence interval in units defined by @p repeatType, or 0 for no recurrence.
* @param endDateTime Date/time after which the recurrence will end.
* @return true if alarm was scheduled successfully, false if configuration errors were found.
*/
virtual bool scheduleFile(const KURL& file, const QString& startDateTime, int lateCancel, unsigned flags, const QString& bgColor,
const KURL& audioFile, int reminderMins,
int repeatType, int repeatInterval, const QString& endDateTime) = 0;
/** Schedule a command execution alarm.
* @param commandLine The command line or command script to execute.
* @param startDateTime Start date/time, in the format YYYY-MM-DD[THH:MM[:SS]] or [T]HH:MM[:SS]
* @param lateCancel Late-cancellation period in minutes, or 0 for no cancellation.
* @param flags OR of flag bits defined in Flags enum.
* @param recurrence Recurrence specification using iCalendar syntax (defined in RFC2445).
* @param repeatInterval Simple repetition repeat interval in minutes, or 0 for no sub-repetition.
* @param repeatCount Simple repetition repeat count (after the first occurrence), or 0 for no sub-repetition.
* @return true if alarm was scheduled successfully, false if configuration errors were found.
*/
virtual bool scheduleCommand(const QString& commandLine, const QString& startDateTime, int lateCancel, unsigned flags,
const QString& recurrence, int repeatInterval, int repeatCount) = 0;
/** Schedule a command execution alarm.
* @param commandLine The command line or command script to execute.
* @param startDateTime Start date/time, in the format YYYY-MM-DD[THH:MM[:SS]] or [T]HH:MM[:SS]
* @param lateCancel Late-cancellation period in minutes, or 0 for no cancellation.
* @param flags OR of flag bits defined in Flags enum.
* @param repeatType The time units to use for recurrence. The actual recurrence interval is equal to
* @p repeatType multiplied by @p repeatInterval.
* The value of @p repeatType must a value defined in the RecurType enum.
* @param repeatInterval Recurrence interval in units defined by @p repeatType, or 0 for no recurrence.
* @param repeatCount Recurrence count (after the first occurrence), or 0 for no recurrence.
* @return true if alarm was scheduled successfully, false if configuration errors were found.
*/
virtual bool scheduleCommand(const QString& commandLine, const QString& startDateTime, int lateCancel, unsigned flags,
int repeatType, int repeatInterval, int repeatCount) = 0;
/** Schedule a command execution alarm.
* @param commandLine The command line or command script to execute.
* @param startDateTime Start date/time, in the format YYYY-MM-DD[THH:MM[:SS]] or [T]HH:MM[:SS]
* @param lateCancel Late-cancellation period in minutes, or 0 for no cancellation.
* @param flags OR of flag bits defined in Flags enum.
* @param repeatType The time units to use for recurrence. The actual recurrence interval is equal to
* @p repeatType multiplied by @p repeatInterval.
* The value of @p repeatType must a value defined in the RecurType enum.
* @param repeatInterval Recurrence interval in units defined by @p repeatType, or 0 for no recurrence.
* @param endDateTime Date/time after which the recurrence will end.
* @return true if alarm was scheduled successfully, false if configuration errors were found.
*/
virtual bool scheduleCommand(const QString& commandLine, const QString& startDateTime, int lateCancel, unsigned flags,
int repeatType, int repeatInterval, const QString& endDateTime) = 0;
/** Schedule an email alarm.
* @param fromID The KMail identity to use as the sender of the email, or QString::null to use KAlarm's default sender ID.
* @param addresses Comma-separated list of addresses to send the email to.
* @param subject Subject line of the email.
* @param message Email message's body text.
* @param attachments Comma- or semicolon-separated list of paths or URLs of files to send as
* attachments to the email.
* @param startDateTime Start date/time, in the format YYYY-MM-DD[THH:MM[:SS]] or [T]HH:MM[:SS]
* @param lateCancel Late-cancellation period in minutes, or 0 for no cancellation.
* @param flags OR of flag bits defined in Flags enum.
* @param recurrence Recurrence specification using iCalendar syntax (defined in RFC2445).
* @param repeatInterval Simple repetition repeat interval in minutes, or 0 for no sub-repetition.
* @param repeatCount Simple repetition repeat count (after the first occurrence), or 0 for no sub-repetition.
* @return true if alarm was scheduled successfully, false if configuration errors were found.
*/
virtual bool scheduleEmail(const QString& fromID, const QString& addresses, const QString& subject, const QString& message,
const QString& attachments, const QString& startDateTime, int lateCancel, unsigned flags,
const QString& recurrence, int repeatInterval, int repeatCount) = 0;
/** Schedule an email alarm.
* @param fromID The KMail identity to use as the sender of the email, or QString::null to use KAlarm's default sender ID.
* @param addresses Comma-separated list of addresses to send the email to.
* @param subject Subject line of the email.
* @param message Email message's body text.
* @param attachments Comma- or semicolon-separated list of paths or URLs of files to send as
* attachments to the email.
* @param startDateTime Start date/time, in the format YYYY-MM-DD[THH:MM[:SS]] or [T]HH:MM[:SS]
* @param lateCancel Late-cancellation period in minutes, or 0 for no cancellation.
* @param flags OR of flag bits defined in the Flags enum.
* @param repeatType The time units to use for recurrence. The actual recurrence interval is equal to
* @p repeatType multiplied by @p repeatInterval.
* The value of @p repeatType must a value defined in the RecurType enum.
* @param repeatInterval Recurrence interval in units defined by @p repeatType, or 0 for no recurrence.
* @param repeatCount Recurrence count (after the first occurrence), or 0 for no recurrence.
* @return true if alarm was scheduled successfully, false if configuration errors were found.
*/
virtual bool scheduleEmail(const QString& fromID, const QString& addresses, const QString& subject, const QString& message,
const QString& attachments, const QString& startDateTime, int lateCancel, unsigned flags,
int repeatType, int repeatInterval, int repeatCount) = 0;
/** Schedule an email alarm.
* @param fromID The KMail identity to use as the sender of the email, or QString::null to use KAlarm's default sender ID.
* @param addresses Comma-separated list of addresses to send the email to.
* @param subject Subject line of the email.
* @param message Email message's body text.
* @param attachments Comma- or semicolon-separated list of paths or URLs of files to send as
* attachments to the email.
* @param startDateTime Start date/time, in the format YYYY-MM-DD[THH:MM[:SS]] or [T]HH:MM[:SS]
* @param lateCancel Late-cancellation period in minutes, or 0 for no cancellation.
* @param flags OR of flag bits defined in the Flags enum.
* @param repeatType The time units to use for recurrence. The actual recurrence interval is equal to
* @p repeatType multiplied by @p repeatInterval.
* The value of @p repeatType must a value defined in the RecurType enum.
* @param repeatInterval Recurrence interval in units defined by @p repeatType, or 0 for no recurrence.
* @param endDateTime Date/time after which the recurrence will end.
* @return true if alarm was scheduled successfully, false if configuration errors were found.
*/
virtual bool scheduleEmail(const QString& fromID, const QString& addresses, const QString& subject, const QString& message,
const QString& attachments, const QString& startDateTime, int lateCancel, unsigned flags,
int repeatType, int repeatInterval, const QString& endDateTime) = 0;
/** Open the alarm edit dialog to edit an existing alarm.
* @param eventId The unique ID of the event to be edited, or QString::null to create a new alarm.
* @return false if the alarm could not be found or is read-only, true otherwise.
*/
virtual bool edit(const QString& eventID) = 0;
/** Open the alarm edit dialog to edit a new alarm.
* @param templateName Name of the alarm template to base the new alarm on, or QString::null if none.
* If a template is specified but cannot be found, the alarm edit dialog is still
* opened but is (obviously) not preset with the template.
* @return false if an alarm template was specified but could not be found, true otherwise.
*/
virtual bool editNew(const QString& templateName) = 0;
};
#endif // KALARMIFACE_H
|
