Developer's Guide to
provides an interface to allow other applications to request the following functions:
schedule a new alarm message
display or cancel an already scheduled alarm message
cancel an already scheduled alarm message
display an already scheduled alarm message
Each of the above functions is implemented both by a call and by the command line. calls should be used in preference if is already running.

interface
cancelMessage
cancel an already scheduled alarm message.

void cancelMessage(const QString& calendarFile, const QString& eventID)

Parameters
calendarFile 	 Specifies the of the calendar file containing the event to be cancelled.
eventID 	 Specifies the unique ID of the event to be cancelled, as stored in calendarFile.

Description
cancelMessage() is a call to cancel the specified alarm message. deletes the alarm message from the calendar file without displaying it.
The calendarFile parameter is only used for integrity checking: if the does not specify 's current default calendar file, the request will be ignored.
displayMessage
display an already scheduled alarm message.

void displayMessage(const QString& calendarFile, const QString& eventID)

Parameters
calendarFile 	 Specifies the of the calendar file containing the event to be displayed.
eventID 	 Specifies the unique ID of the event to be displayed, as stored in calendarFile.

Description
displayMessage() is a call to display the specified alarm message. retrieves the alarm message from the calendar file and then displays it.
If no repetitions of the alarm are still scheduled, then deletes the alarm message from the calendar file.
The calendarFile parameter is only used for integrity checking: if the does not specify 's current default calendar file, the request will be ignored.
handleEvent
display or cancel an already scheduled alarm message.

void handleEvent(const QString& calendarFile, const QString& eventID)

Parameters
calendarFile 	 Specifies the of the calendar file containing the event to be displayed or cancelled.
eventID 	 Specifies the unique ID of the event to be displayed or cancelled, as stored in calendarFile.

Description
handleEvent() is a call to display or cancel the specified alarm message. retrieves the alarm message from the calendar file and then determines what action to take. If the late-cancel flag is set and the alarm is late, the scheduled time of display was more than a minute ago, does not display the message; otherwise, displays the alarm message. If no repetitions of the alarm are still scheduled, then deletes the alarm message from the calendar file.
The calendarFile parameter is only used for integrity checking: if the does not specify 's current default calendar file, the request will be ignored.
scheduleMessage
schedule a new alarm message.

bool scheduleMessage(const QString& message, const QDateTime* dateTime, const QColor& bg, int flags)

bool scheduleMessage(const QString& message, const QDateTime* dateTime, const QColor& bg, int flags, int repeat_count, int interval)

Parameters
message 	 Specifies the text of the message to be scheduled.
dateTime 	 Specifies the scheduled date and time at which the message should be displayed.
bg 	 Specifies the background colour for displaying the message.
flags 	 Specifies the logical OR of the desired alarm message flags. The flag bits are those defined in msgevent.h
repeatCount 	 Specifies the number of times that the alarm message should be repeated, after its initial display.
interval 	 Specifies the interval in minutes between repetitions of the alarm message.

Description
scheduleMessage() is a call to schedule the specified alarm message for display at the specified date and time. It has two forms: one for a non-repeating alarm, and another for a repeating alarm.
If the scheduled time (including any repetitions) has already passed, immediately displays the message or, if the LATE_CANCEL flag bit is set, ignores the request. If the scheduled time is in the future, adds the alarm message to the calendar file for later display.
Use a code sequence similar to the following to set up the parameter data for the call to scheduleMessage() for a non-repeating alarm:

QString message;
QDateTime dateTime;
QColor bgColour;
Q_UINT32 flags;
. . .
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg <<  message;
arg.writeRawBytes((char*)&dateTime, sizeof(QDateTime));
arg.writeRawBytes((char*)&bgColour, sizeof(QColor));
arg << flags;

Use a code sequence similar to the following to set up the parameter data for the call to scheduleMessage() for a repeating alarm:

QString message;
QDateTime dateTime;
QColor bgColour;
Q_UINT32 flags;
Q_INT32 repeatCount, repeatInterval;
. . .
QByteArray data;
QDataStream arg(data, IO_WriteOnly);
arg << message;
arg.writeRawBytes((char*)&dateTime, sizeof(QDateTime));
arg.writeRawBytes((char*)&bgColour, sizeof(QColor));
arg << flags << repeatCount << repeatInterval;

scheduleFile
schedule a new alarm message which displays the contents of a text file.

bool scheduleFile(const QString& URL, const QDateTime* dateTime, const QColor& bg, int flags)

bool scheduleFile(const QString& URL, const QDateTime* dateTime, const QColor& bg, int flags, int repeat_count, int interval)

Parameters
URL 	 Specifies the name or of a text file whose contents are to be displayed in the message to be scheduled.
dateTime 	 Specifies the scheduled date and time at which the message should be displayed.
bg 	 Specifies the background colour for displaying the message.
flags 	 Specifies the logical OR of the desired alarm message flags. The flag bits are those defined in msgevent.h
repeatCount 	 Specifies the number of times that the alarm message should be repeated, after its initial display.
interval 	 Specifies the interval in minutes between repetitions of the alarm message.

Description
scheduleFile() is a call to schedule the specified text file for display at the specified date and time. Apart from specifying a file name or , its usage is identical to the scheduleMessage - see the description of that function for further details.

Command line interface
Command line options are provided to enable other programs (such as the alarm daemon) to start up if it is not already running, in order to display or cancel scheduled messages, or schedule new messages. The reason for using command line options for this purpose is that if were started without any command line parameters and then sent requests, it would start in its default graphical mode, which is clearly undesirable for an inter-program request.
Programs should first check whether is already running; if it is, they should instead use calls to request these operations.
The command line options for scheduling a new alarm message are as described in the chapter Using . The options for displaying and cancelling scheduled messages are as follows:
Normal users may also if they wish use these command line options (assuming that they can supply the necessary parameter information).
Option	Description
--calendarURL url	Use the calendar file with the specified . This option is only used for integrity checking: if the doesn't specify 's current default calendar file, the request will be ignored.
--cancelEvent eventID	Cancel the event with the specified event ID.
--displayEvent eventID	Display the event with the specified event ID.
--handleEvent eventID	Display or cancel the event with the specified event ID. determines which action to take in the same way as for the handleEvent() call.
--cancelEvent, --displayEvent and --handleEvent are mutually exclusive. --calendarURL is optional, but can only be used with one of the other three options.
Examples are:

% kalarm --displayEvent -387486299.702 --calendarURL file:/home/zaphod/hydra.ics
% kalarm --cancelEvent -388886299.793