Extension proposed to handle advanced alarms

[Kevin Ottens]

Hello,

In order to be able to support advanced alarm in Kontact over Kolab storage, I 
had to extend the kolab format to store more information. For now this 
extension is only implemented in the enterprise4 branch, but I think it'll 
probably hit trunk at one point.

The extension basically adds a new element named "advanced-alarms" which 
contains a list of "alarm" elements. Each "alarm" element has a mandatory 
"type" property whose value can be "display", "audio", "procedure" or "email".

So for instance it'll have the following form:
-------------------------------------
<advanced-alarms>
  <alarm type="display">
  ...
  </alarm>
  <alarm type="audio">
  ...
  </alarm>
</advanced-alarms>
-------------------------------------

Each alarm type has a different role:
 - "display" displays a message to the user when the alarm is triggered;
 - "audio" plays an audio file when the alarm is triggered;
 - "procedure" executes a program when the alarm is triggered;
 - "email" sends an email when the alarm is triggered.

Then each alarm can have the following sub elements to specify when it is 
triggered:
 - "start-offset", to set how many minutes from the event beginning the alarm 
should trigger, it's relative so negative values are allowed;
 - "end-offset", to set how many minutes from the event end the alarm should 
trigger, it's relative so negative values are allowed;
 - "repeat-count", to set how many times an alarm should be repeated after the 
first time it got triggered;
 - "repeat-interval", to set the amount of time between to repetition of the 
alarm.

So for instance, for an alarm first triggered ten minutes before the event, 
and then triggered again five times every two minutes, it'll have the 
following form:
-------------------------------------
<alarm type="...">
  <start-offset>-10</start-offset>
  <repeat-count>5</repeat-count>
  <repeat-interval>2</repeat-interval>
  ...
</alarm>
-------------------------------------

Each alarms will also have sub elements depending on their type:
 - "display" type, has a "text" sub-element to specify the text displayed to 
the user when the alarm is triggered:
-------------------------------------
<alarm type="display">
  ...
  <text>Time to leave!</text>
</alarm>
-------------------------------------

 - "audio" type, has a "file" sub-element to specify the audio file to be 
played when the alarm is triggered;
-------------------------------------
<alarm type="display">
  ...
  <file>/path/to/some/music.ogg</file>
</alarm>
-------------------------------------

 - "procedure" type, has a "program" sub-element to specify the program to be 
launched when the alarm is triggered, it also has an "arguments" sub-element 
to specify arguments to be passed to the program when invoked;
-------------------------------------
<alarm type="procedure">
  ...
  <program>/usr/bin/xmessage</program>
  <arguments>Time to leave</arguments>
</alarm>
-------------------------------------

 - "email" type is the most complex and has the following sub-elements:
    * "addresses" which contains a set of "address" sub-elements describing 
who will receive the mail (in name+email format);
    * "subject" which gives the subject of the mail;
    * "mail-text" which gives the pure text content of the mail;
    * "attachments" which contains a set of "attachment" sub-elements giving 
the path to a file to attach to the mail.
-------------------------------------
<alarm type="email">
  ...
  <addresses>
    <address>First User <user1 at foo.com></address>
    <address>Second User <user2 at foo.com></address>
  </addresses>
  <subject>We're about to be late</subject>
  <mail-text>It's really about time we leave!</mail-text>
  <attachments>
    <attachment>/path/to/a/scary-picture.jpg</attachment>
    <attachment>/path/to/another/scary-picture.png</attachment>
  </attachment>
</alarm>
-------------------------------------

It should be about it for this Kontact extension. Comments are welcome.

Thanks for your attention.

Regards.
-- 
Kevin Ottens, kevin at kdab.net
Klarälvdalens Datakonsult AB, Platform-independent software solutions
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part.
URL: <http://lists.kolab.org/pipermail/format/attachments/20080917/675a6729/attachment.sig>