CalAlarm Type

An alarm related to a calendar event.

Remarks

An Alarm calendar component is a grouping of properties 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 propertys. The Action property further constrains the CalAlarm in the following ways:

When the Action is aAudio, the alarm can optionally include an Attachment property, 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 property, which contains the text to be displayed when the alarm is triggered.

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

Fields

action
Actions

This property 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 property.
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 property with the message to be displayed.
aEmail (2) Instructs the CalDAV sever to email a specified Recipient. In this case, the Message property will contain the message body of the email and the Subject property should contain the subject line.

attachment
String

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

attachmentType
String

This property 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 property is used to tell the CalDAV server what type of binary file it is receiving. This property 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, aifcMacintosh 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 property. 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 property contains the interval between repeating alarms. This property 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 property contains a message used to alert the user when this alarm is triggered. If the Action is set to aDisplay, this property must contain the message that is to be displayed to the user. If Action is set to aEmail this property 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.";
or
  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 property contains the email address of the person to be alerted when this alarm is triggered. If Action is set to aEmail this property 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_
Int32

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

This property 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 property.

subject
String

This property contains the subject of the message used to alert the user when this alarm is triggered. If Action is set to aEmail this property 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 property 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 property. 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 init()
public init(trigger: String, action: Actions)

Copyright (c) 2022 /n software inc. - All rights reserved.
IPWorks 2020 macOS Edition - Version 20.0 [Build 8307]