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

  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");

#!/usr/bin/perl -w
# vi:sts=4:shiftwidth=4
# -*- Mode: perl -*-
#======================================================================
#
# This package is free software and is provided "as is" without
# express or implied warranty.  It may be used, redistributed and/or
# modified under the same terms as perl itself. ( Either the Artistic
# License or the GPL. )
#
# $Id: Alarm.pm,v 1.19 2001/07/19 03:32:32 srl Exp $
#
# (C) COPYRIGHT 2000-2001, Reefknot developers.
#
# See the AUTHORS file included in the distribution for a full list.
#======================================================================

package Net::ICal::Alarm;
use strict;

use base qw(Net::ICal::Component);
use Net::ICal::Trigger;

sub new {
    my ($class, %args) = @_;
   
    # this implements the heart of RFC2445 4.6.6, which says what
    # elements in an Alarm are required to be used.
    # Anything that's "return undef" is requred.
    
    # action and trigger are required.
    return undef unless defined $args{'action'};
    return undef unless defined $args{'trigger'};

    # display and email alarms must have descriptions.
    if ($args{'action'} eq 'DISPLAY' or $args{'action'} eq 'EMAIL') {
	return undef unless defined $args{'description'};
    }
    if (($args{'action'} ne 'EMAIL') and (defined $args{'attendee'})) {
        return undef;
    }

    # procedure alarms must invoke an attachment.
    # TODO: Attachments? This could be (is) implemented very poorly in some
    # of MS's software. eek.
    #BUG: 404132
    if ($args{'action'} eq 'PROCEDURE') {
	return undef unless defined $args{'attach'};
    }

    # duration and repeat must be used together or not at all.
    if (defined $args{'duration'} xor defined $args{'repeat'}) {
    	return undef;
    }

    #FIXME: it sucks we have to do this in every component. better
    #       try to get this into Component
    #BUG: 233771
    my $t = $args{'trigger'};
    unless (ref ($t)) {
	$args{'trigger'} = new Net::ICal::Trigger ($t);
    }

    return &_create ($class, %args);
}

#============================================================================
# create ($class, %args)
#
# sets up a map of the properties that N::I::Alarm objects share.
# See Net::ICal::Component and Class::MethodMapper if you want to know
# how this works. Takes a class name and a hash of arguments, returns a new
# Net::ICal::Alarm object. 
#============================================================================
sub _create {
  my ($class, %args) = @_;
   

   #TODO: validation of the parameters is performed by the new method.
   #      <LotR> actually, validation needs to be consistantly put in
   #      a seperate sub 

   my $map = {		# RFC2445 4.6.6
      action => { # 4.8.6.1
	 type => 'parameter',
	 doc => 'the action type of this alarm',
	 domain => 'enum',
	 options => [qw(AUDIO DISPLAY EMAIL PROCEDURE)],
	 value => 'EMAIL', # default
      },
      trigger => { # 4.8.6.3
	 type => 'parameter',
	 doc => 'when the alarm will be triggered',
	 domain => 'ref',
	 options => 'Net::ICal::Trigger',
	 value => undef,
      },
      description => { # 4.8.1.5
	 type => 'parameter',
	 doc => 'description of this alarm',
	 domain => 'param',
	 options => [qw(altrep language)],
	 value => undef,
      },
    # this might be better off as a class
      attach => { #4.8.1.1
	 type => 'parameter',
	 doc => 'an attachment',
	 domain => 'param',
	 options => [qw(encoding value fmttype)],
	 value => undef,
      },
      summary => { # 4.8.1.12
	 type => 'parameter',
	 doc => 'the summary (subject) if this is an EMAIL alarm',
	 domain => 'param',
	 options => [qw(altrep language)],
	 value => undef,
      },
      attendee => { # 4.8.4.1
	 type => 'parameter',
	 doc => 'the attendees (receivers of the email) for this EMAIL alarm',
	 domain => 'ref',
	 options => 'ARRAY',
	 value => undef,
      },
      duration => { # 4.8.2.5
	 type => 'parameter',
	 doc => 'the delay period between alarm repetitions',
	 value => 0,
      },
      repeat => { # 4.8.6.2
	 type => 'parameter',
	 doc => 'the amount of times the alarm is repeated',
	 value => 0,
      },
   };
   my $self = $class->SUPER::new ('VALARM', $map, %args);

   return $self;
}

1;