ipworksssl
Class CalAlarm

java.lang.Object
  ipworksssl.CalAlarm

public class CalAlarm
extends java.lang.Object

An alarm related to a calendar event.

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.

Action: 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: 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: 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:

AttachmentTypeFile Extension

Description

audio/basicau, snd

basic audio, 8-bit u-law PCM.

audio/midmid, rmi

MIDI music data

audio/mpegmp2, mp3

MPEG-1 Audio Layer II and III.

audio/x-aiffaiff, aif, aifc

Macintosh audio format

audio/x-mp4a-latmm4a

MPEG-4 Audio

audio/x-pn-realaudiora, ram

Realaudio

audio/x-wavwav

Microsoft waveform audio

audio/x-ms-wmawma

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: 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: 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."; 

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: 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 Action s.

Repeat: 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: 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 Action s.

Trigger: 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" 

See Also:

Atoms, Atoms.CalAlarm

Field Summary

static int	aAudio
static int	aDisplay
static int	aEmail
static int	aNoAlarm

Constructor Summary

CalAlarm()

CalAlarm(java.lang.String trigger, int action)

Method Summary

int	getAction()
java.lang.String	getAttachment()
java.lang.String	getAttachmentType()
java.lang.String	getDuration()
java.lang.String	getMessage()
java.lang.String	getRecipient()
int	getRepeat()
java.lang.String	getSubject()
java.lang.String	getTrigger()
void	setAction(int value)
void	setAttachment(java.lang.String value)
void	setAttachmentType(java.lang.String value)
void	setDuration(java.lang.String value)
void	setMessage(java.lang.String value)
void	setRecipient(java.lang.String value)
void	setRepeat(int value)
void	setSubject(java.lang.String value)
void	setTrigger(java.lang.String value)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

aNoAlarm

public static final int aNoAlarm

See Also:

Constant Field Values

aAudio

public static final int aAudio

See Also:

Constant Field Values

aDisplay

public static final int aDisplay

See Also:

Constant Field Values

aEmail

public static final int aEmail

See Also:

Constant Field Values

Constructor Detail

CalAlarm

public CalAlarm()

CalAlarm

public CalAlarm(java.lang.String trigger,
                int action)

Method Detail

getAction

public int getAction()

setAction

public void setAction(int value)

getAttachment

public java.lang.String getAttachment()

setAttachment

public void setAttachment(java.lang.String value)

getAttachmentType

public java.lang.String getAttachmentType()

setAttachmentType

public void setAttachmentType(java.lang.String value)

getDuration

public java.lang.String getDuration()

setDuration

public void setDuration(java.lang.String value)

getMessage

public java.lang.String getMessage()

setMessage

public void setMessage(java.lang.String value)

getRecipient

public java.lang.String getRecipient()

setRecipient

public void setRecipient(java.lang.String value)

getRepeat

public int getRepeat()

setRepeat

public void setRepeat(int value)

getSubject

public java.lang.String getSubject()

setSubject

public void setSubject(java.lang.String value)

getTrigger

public java.lang.String getTrigger()

setTrigger

public void setTrigger(java.lang.String value)