CalAlarm Type

An alarm related to a calendar event.

Remarks

An Alarm calendar component is a grouping of fields that set up a reminder or an alarm for an event or to-do. For example, it may be used to define a reminder for a pending event or an overdue to-do.

The CalAlarm calendar component MUST include the Action and Trigger fields. The Action field further constrains the CalAlarm in the following ways:

When the Action is aAudio, the alarm can optionally include an Attachment field, containing a base-64 encoded binary audio file to be played when the alarm is triggered.

When the Action is aDisplay, the alarm MUST also include the Message field, which contains the text to be displayed when the alarm is triggered.

When the Action is aEmail, the alarm MUST include the Message field, which contains the text to be used as the message body, the Subject field, which contains the text to be used as the message subject, and the Recipient field, which contains the email address of the person intended to receive the message.

Fields

Action
int

This field determines what the CalDAV server will do when the alarm Trigger is reached. The following table explains the possible alarm actions:


aAudio (0)	Specifies an alarm that causes a sound to be played to alert the user. You may attach a custom sound file using the Attachment field.
aDisplay (1)	Specifies an alarm that causes a visual alert to be displayed to the user. If Action is set to this value, you must also set the Message field with the message to be displayed.
aEmail (2)	Instructs the CalDAV sever to email a specified Recipient. In this case, the Message field will contain the message body of the email and the Subject field should contain the subject line.

Attachment
String

This field contains a sound file attached to the alarm. If the Action is set to aAudio, this field may optionally contain a base-64 encoded binary sound file to be played. The AttachmentType field indicates the data type of the attached file.

AttachmentType
String

This field contains the MIME-Type of the attachment. If the Action is set to aAudio or aEmail the Attachment property may optionally contain a base-64 binary encoded attachment. The AttachmentType field is used to tell the CalDAV server what type of binary file it is receiving. This field is a standard MIME content type, in the format "type/sub-type". The most common audio types are shown in the table below:


AttachmentType	File Extension	Description
audio/basic	au, snd	basic audio, 8-bit u-law PCM.
audio/mid	mid, rmi	MIDI music data
audio/mpeg	mp2, mp3	MPEG-1 Audio Layer II and III.
audio/x-aiff	aiff, aif, aifc	Macintosh audio format
audio/x-mp4a-latm	m4a	MPEG-4 Audio
audio/x-pn-realaudio	ra, ram	Realaudio
audio/x-wav	wav	Microsoft waveform audio
audio/x-ms-wma	wma	Windows Media Audio (Microsoft)

You may use standard MIME content-types for any other file type you wish to submit in the Attachment field. If Attachment is specified but AttachmentType is left blank, no format type will be submitted with the Attachment and the CalDAV server may (or may not) attempt to determine the data type itself.

Duration
String

This field contains the interval between repeating alarms. This field is only used when an alarm is set to Repeat multiple times. It is specified in the form of a Duration data type. Durations are represented by the format P<date>T<time>. The date component may contain a number of days or weeks (but not months or years), and the time component may consist of hours, minutes, and seconds. These are represented by an integer value followed by a letter representing the units, as specified by the table below:


P	is the duration designator (historically called "period") placed at the start of the duration representation.
W	is the week designator that follows the value for the number of weeks.
D	is the day designator that follows the value for the number of days.
T	is the time designator that precedes the time components of the representation.
H	is the hour designator that follows the value for the number of hours.
M	is the minute designator that follows the value for the number of minutes.
S	is the second designator that follows the value for the number of seconds.

For example, "P4DT12H30M5S" represents a duration of four days, twelve hours, thirty minutes, and five seconds. Unused date/time designators may be left out completely. (A five-minute duration may be represented as simply "PT5M"). Also note that "PT36H" and "P1DT12H" represent the same duration.

This format is based on ISO-8601, but unlike the ISO specification this duration property does not support durations measured in years or months.

The following is an example of an alarm that repeats 4 additional times after the initial Trigger, with a 5-minute delay between each alarm:

  CalDav.Trigger = "-PT10M";
  CalDAV.Alarm.Repeat = 4;
  CalDAV.Duration = "PT5M"
  CalDAV.Action = aDisplay;

If Duration is specified, Repeat MUST also be specified.

Message
String

This field contains a message used to alert the user when this alarm is triggered. If the Action is set to aDisplay, this field must contain the message that is to be displayed to the user. If Action is set to aEmail this field will contain the message body of the email that is sent to the Recipient. For instance:

  CalDAV.Alarm.Action = aEmail;
  CalDAV.Alarm.Recipient = "mailto:john_doe@example.com";
  CalDAV.Alarm.Message = "A draft agenda needs to be sent out to the attendees to the weekly managers meeting (MGR-LIST).";
  CalDAV.Alarm.Subject = "REMINDER: Send agenda for weekly staff meeting.";

  CalDAV.Alarm.Action = aDisplay;
  CalDAV.Alarm.Message = "REMINDER: Send agenda for weekly staff meeting.";

Message is not used for the aAudio alarm Action.

Recipient
String

This field contains the email address of the person to be alerted when this alarm is triggered. If Action is set to aEmail this field must contain one or more comma-separated email addresses to which the email alarm is to be sent. For instance:

  CalDAV.Alarm.Action = aEmail;
  CalDAV.Alarm.Recipient = "mailto:john_doe@example.com";
  CalDAV.Alarm.Message = "A draft agenda needs to be sent out to the attendees to the weekly managers meeting (MGR-LIST).";
  CalDAV.Alarm.Subject = "REMINDER: Send agenda for weekly staff meeting.";

Recipient is not used for the aAudio or aDisplay alarm Actions.

Repeat
int

This field contains the number of times the alarm is to be repeated after the initial trigger.

This field defines the number of times an alarm should be repeated after its initial Trigger. If the alarm triggers more than once, then this property MUST be specified along with the Duration field.

Subject
String

This field contains the subject of the message used to alert the user when this alarm is triggered. If Action is set to aEmail this field will contain the subject the email that is sent to the Recipient. For instance:

  CalDAV.Alarm.Action = aEmail;
  CalDAV.Alarm.Recipient = "mailto:john_doe@example.com";
  CalDAV.Alarm.Message = "A draft agenda needs to be sent out to the attendees to the weekly managers meeting (MGR-LIST).";
  CalDAV.Alarm.Subject = "REMINDER: Send agenda for weekly staff meeting.";

Subject is not used for the aAudio or aDisplay alarm Actions.

Trigger
String

This field contains the time when the alarm is triggered.

The Trigger is represented as a duration relative to the start of an event. The format is (+/-)P<date>T<time>. The date component may contain a number of days or weeks (but not months or years), and the time component may consist of hours, minutes, and seconds. These are represented by an integer value followed by a letter representing the units, as specified by the table below:


P	is the duration designator (historically called "period") placed at the start of the duration representation.
W	is the week designator that follows the value for the number of weeks.
D	is the day designator that follows the value for the number of days.
T	is the time designator that precedes the time components of the representation.
H	is the hour designator that follows the value for the number of hours.
M	is the minute designator that follows the value for the number of minutes.
S	is the second designator that follows the value for the number of seconds.

Either a positive or negative duration may be specified for the Trigger field. An alarm with a positive duration is triggered after the associated start of the event (or to-do). An alarm with a negative duration is triggered before the start of the event. For instance, the following code instructs an alarm to fire 10 minutes before the event starts:

  CalDAV.Alarm.Trigger = "-PT10M"

Constructors

public CalAlarm();

public CalAlarm(String trigger, int action);