NAME

Net::ICal::Alarm -- represents an alarm (a VALARM object).

SYNOPSIS

  use Net::ICal;

  # simple syntax
  $a = new Net::ICal::Alarm(action => 'DISPLAY',
                            trigger => "20000101T073000",
                            description => "Wake Up!");

  # elaborate
  $a = new Net::ICal::Alarm (action => 'EMAIL',
                             trigger => new Net::ICal::Trigger (
                                  type => 'DURATION',
                                  content => new Net::ICal::Duration ("-PT5M"),
                                  related => 'END
                             ),
                             attendee => [new Net::ICal::Attendee('mailto:alice@wonderland.com')],
                             summary => "mail subject",
                             description => "mail contents");

DESCRIPTION

This class handles reminders for Net::ICal Events and Todos. You can get a reminder in several different ways (a sound played, a message displayed on your screen, an email or a script/application run for you) at a certain time, either relative to the Event or Todo the Alarm is part of, or at a fixed date/time.

CONSTRUCTOR

new (optionhash)

Create a new Alarm. The minimum options are an action, a trigger and either an attach or a description.

The action describes what type of Alarm this is going to be. See "action" below for possible actions. The trigger describes when the alarm will be triggered. See "trigger" below for an explanation.

my $a = Net::ICal::Alarm->new();

ok(!(defined($a)), 'new Alarm with no events should fail');

$a = Net::ICal::Alarm->new( action => 'DISPLAY', trigger => '-5M', description => 'time for meeting');

ok(defined($a), 'new Alarm with DISPLAY, trigger, and desc is created');

$a = Net::ICal::Alarm->new( action => 'EMAIL', trigger => '-5M', description => 'time for meeting');

ok(defined($a), 'new Alarm with EMAIL, trigger, and desc is created');

# TODO: we need as_ical tests and such. These tests are only # barely adequate.

METHODS

action

What the Alarm does when fired. The default type is EMAIL.

AUDIO - play an audio file. Requires an "attach" property (a soundfile).
DISPLAY - pop up a note on the screen. Requires a "description" containing the text of the note.
EMAIL - send an email. Requires a "description" containing the email body and one or more "attendee"s for the email address(es).
PROCEDURE - trigger a procedure described by an "attach" which is the command to execute (required).

trigger

The time at which to fire off the reminder. This can either be relative to the Event/Todo (a Net::ICal::Duration or at a fixed date/time (a Net::ICal::Time).

summary

If the Alarm has an EMAIL "action", the text of the summary string will be the Subject header of the email.

description

If the Alarm has an EMAIL "action", the text of the description string will be the body of the email. If the Alarm has a PROCEDURE "action", this is the argument string to be passed to the program.

attach

If the Alarm has an AUDIO "action", this contains the sound to be played, either as an URL or inline. If the Alarm has an EMAIL "action", this will be attached to the email. If the Alarm has a PROCEDURE "action", it contains the application to be executed.

CPAN RT