You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
356 lines
25 KiB
356 lines
25 KiB
/*
|
|
* 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 <tqstringlist.h>
|
|
class TQString;
|
|
|
|
/** 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 TQString& url, const TQString& 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 TQString& url, const TQString& 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 TQString() for the
|
|
* current default background colour. The string may be in any of the formats
|
|
* accepted by TQColor::TQColor(const TQString&).
|
|
* @param fgColor The foreground colour for the alarm message, or TQString() 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 TQString() for the default message font
|
|
* current at the time the message is displayed. The string should be in format
|
|
* returned by TQFont::toString().
|
|
* @param audioFile The audio file to play when the alarm is displayed, or TQString() 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 TQString& message, const TQString& startDateTime, int lateCancel, unsigned flags,
|
|
const TQString& bgColor, const TQString& fgColor, const TQString& font,
|
|
const KURL& audioFile, int reminderMins, const TQString& 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 TQString() for the
|
|
* current default background colour. The string may be in any of the formats
|
|
* accepted by TQColor::TQColor(const TQString&).
|
|
* @param fgColor The foreground colour for the alarm message, or TQString() 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 TQString() for the default message font
|
|
* current at the time the message is displayed. The string should be in format
|
|
* returned by TQFont::toString().
|
|
* @param audioFile The audio file to play when the alarm is displayed, or TQString() 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 TQString& message, const TQString& startDateTime, int lateCancel, unsigned flags,
|
|
const TQString& bgColor, const TQString& fgColor, const TQString& 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 TQString() for the
|
|
* current default background colour. The string may be in any of the formats
|
|
* accepted by TQColor::TQColor(const TQString&).
|
|
* @param fgColor The foreground colour for the alarm message, or TQString() 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 TQString() for the default message font
|
|
* current at the time the message is displayed. The string should be in format
|
|
* returned by TQFont::toString().
|
|
* @param audioFile The audio file to play when the alarm is displayed, or TQString() 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 TQString& message, const TQString& startDateTime, int lateCancel, unsigned flags,
|
|
const TQString& bgColor, const TQString& fgColor, const TQString& font,
|
|
const KURL& audioFile, int reminderMins,
|
|
int repeatType, int repeatInterval, const TQString& 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 TQString() for the
|
|
* current default background colour. The string may be in any of the formats
|
|
* accepted by TQColor::TQColor(const TQString&).
|
|
* @param audioFile The audio file to play when the alarm is displayed, or TQString() 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 TQString& startDateTime, int lateCancel, unsigned flags, const TQString& bgColor,
|
|
const KURL& audioFile, int reminderMins, const TQString& 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 TQString() for the
|
|
* current default background colour. The string may be in any of the formats
|
|
* accepted by TQColor::TQColor(const TQString&).
|
|
* @param audioFile The audio file to play when the alarm is displayed, or TQString() 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 TQString& startDateTime, int lateCancel, unsigned flags, const TQString& 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 TQString() for the
|
|
* current default background colour. The string may be in any of the formats
|
|
* accepted by TQColor::TQColor(const TQString&).
|
|
* @param audioFile The audio file to play when the alarm is displayed, or TQString() 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 TQString& startDateTime, int lateCancel, unsigned flags, const TQString& bgColor,
|
|
const KURL& audioFile, int reminderMins,
|
|
int repeatType, int repeatInterval, const TQString& 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 TQString& commandLine, const TQString& startDateTime, int lateCancel, unsigned flags,
|
|
const TQString& 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 TQString& commandLine, const TQString& 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 TQString& commandLine, const TQString& startDateTime, int lateCancel, unsigned flags,
|
|
int repeatType, int repeatInterval, const TQString& endDateTime) = 0;
|
|
|
|
/** Schedule an email alarm.
|
|
* @param fromID The KMail identity to use as the sender of the email, or TQString() 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 TQString& fromID, const TQString& addresses, const TQString& subject, const TQString& message,
|
|
const TQString& attachments, const TQString& startDateTime, int lateCancel, unsigned flags,
|
|
const TQString& recurrence, int repeatInterval, int repeatCount) = 0;
|
|
/** Schedule an email alarm.
|
|
* @param fromID The KMail identity to use as the sender of the email, or TQString() 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 TQString& fromID, const TQString& addresses, const TQString& subject, const TQString& message,
|
|
const TQString& attachments, const TQString& 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 TQString() 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 TQString& fromID, const TQString& addresses, const TQString& subject, const TQString& message,
|
|
const TQString& attachments, const TQString& startDateTime, int lateCancel, unsigned flags,
|
|
int repeatType, int repeatInterval, const TQString& endDateTime) = 0;
|
|
/** Open the alarm edit dialog to edit an existing alarm.
|
|
* @param eventId The unique ID of the event to be edited, or TQString() to create a new alarm.
|
|
* @return false if the alarm could not be found or is read-only, true otherwise.
|
|
*/
|
|
virtual bool edit(const TQString& 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 TQString() 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 TQString& templateName) = 0;
|
|
};
|
|
|
|
#endif // KALARMIFACE_H
|