#!/usr/bin/perl -w
# -*- 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: Attendee.pm,v 1.20 2001/08/04 04:59:36 srl Exp $
#
# (C) COPYRIGHT 2000, Reefknot developers, including:
# Eric Busboom, http://www.softwarestudio.org
#
# See the AUTHORS file included in the distribution for a full list.
#======================================================================
=head1 NAME
Net::ICal::Attendee -- represents an attendee or organizer of a meeting
=cut
package Net::ICal::Attendee;
use strict;
use Net::ICal::Util qw(:all);
use UNIVERSAL;
use base qw(Net::ICal::Property);
=head1 SYNOPSIS
use Net::ICal;
$a = new Net::ICal::Attendee('mailto:alice@example.com');
$a = new Net::ICal::Attendee('mailto:alice@example.com',
cn => 'Alice Anders',
role => 'REQ-PARTICIPANT');
=head1 DESCRIPTION
Net::ICal::Attendee provides an interface to manipulate attendee data
in iCalendar (RFC2445) format.
=head1 METHODS
=head2 new($calid, $hash)
New will take a string and optional key-value pairs. The string is the
calender user address of the Attendee (usually a mailto uri).
$a = new Net::ICal::Attendee('mailto:alice@example.com');
$a = new Net::ICal::Attendee('mailto:alice@example.com',
cn => 'Alice Anders',
role => 'REQ-PARTICIPANT');
Meaningful hash keys are:
=over 4
=item * cn - common name - the name most people use for this attendee.
=item * cutype - type of user this attendee represents. Meaningful
values are INDIVIDUAL, GROUP, ROOM, RESOURCE, UNKNOWN.
=item * delegated_from - the user who delegated a meeting request to this
attendee.
=item * delegated_to - the user who's been delegated to handle meeting
requests for this attendee.
=item * dir - a URI that gives a directory entry associated with the user.
=item * partstat - whether this attendee will actually be at a meeting.
Meaningful values are NEEDS-ACTION, ACCEPTED, DECLINED, TENTATIVE,
DELEGATED, COMPLETED, or IN-PROCESS.
=item * role - how this attendee will participate in a meeting.
Meaningful values are REQ-PARTICIPANT, OPT-PARTICIPANT, NON-PARTICIPANT,
and CHAIR.
=item * rsvp - should the user send back a response to this request?
Valid values are TRUE and FALSE. FALSE is the default.
=item * sent_by - specifies a user who is acting on behalf of this
attendee; for example, a secretary for his/her boss, or a parent for his/her
10-year-old.
=back
To understand more about the uses for each of these properties,
read the source for this module and and look at RFC2445.
=begin testing
#generic stuff
use lib "./lib";
use Net::ICal::Attendee;
$mail = 'mailto:alice@example.com';
#start of tests
ok(my $a = Net::ICal::Attendee->new ($mail), "Simple attendee creation");
ok(not(Net::ICal::Attendee->new ("xyzzy")), "Nonsense email address");
=end testing
=cut
sub new {
my ($class, $value, %args) = @_;
$args{content} = $value;
#TODO: rsvp should default to false; see rfc2445 4.2.17 and SF bug 424101
my $self = _create ($class, %args);
return undef unless $self;
return undef unless $self->validate;
return $self;
}
=pod
=head2 validate
Returns 1 for valid attendee data, undef for invalid.
=for testing
ok($a->validate, "Simple validation");
=cut
sub validate {
my ($self) = @_;
# TODO: write this routine! SF bug 435998
unless ($self->content =~ /^mailto:.*\@/i) {
# TODO: make this work
#add_validation_error($self, "Attendee must begin with 'mailto:'");
return undef;
}
return 1;
}
sub _create {
my ($class, %args) = @_;
my $map = {
content => { # RFC2445 4.8.4.1
type =>'volatile',
doc => 'the email address of this attendee',
value => undef,
},
cn => { # RFC2445 4.2.2
type => 'parameter',
doc => "'Common Name', the name most people use to address the user",
value => undef,
},
cutype => { # RFC2445 4.2.3
type => 'parameter',
doc => 'type of user this calid represents',
domain => 'enum',
options => [qw(INDIVIDUAL GROUP ROOM RESOURCE UNKNOWN)],
# This attendee may be a person, or it may be a group, or a place,
# or a resource (overhead projector, for example) or something else.
value => undef,
},
delegated_from => { # RFC2445 4.2.4
type => 'parameter',
doc => 'the user this request was delegated from',
value => undef,
# Someone's passing the buck to Attendee.
},
delegated_to => { # RFC2445 4.2.5
type => 'parameter',
doc => 'who Attendee is delegating this request to',
value => undef,
# Mmm, passing the buck to someone else.
},
dir => { # RFC2445 4.2.6
type => 'parameter',
doc => 'Directory entry associated with the user',
value => undef,
},
partstat => { # RFC2445 4.2.12
type => 'parameter',
doc => 'status of user-participation',
domain => 'enum',
options => [qw(NEEDS-ACTION ACCEPTED DECLINED TENTATIVE DELEGATED COMPLETED IN-PROCESS)],
value => undef,
# whether the user's actually going to be there.
},
role => { # RFC2445 4.2.16
type => 'parameter',
doc => 'how the user will participate in the meeting',
domain => 'enum',
options => [qw(REQ-PARTICIPANT OPT-PARTICIPANT NON-PARTICIPANT CHAIR)],
# is the Attendee required, requested, not-participating, or running
# the event?
value => undef,
},
rsvp => { # RFC2445 4.2.17
type => 'parameter',
doc => 'User needs to send back a reply to this',
domain => 'enum',
options => [qw(FALSE TRUE)],
value => undef,
},
sent_by => { # RFC2445 4.2.18
type => 'parameter',
doc => 'who responds on behalf of this Attendee',
# a secretary, for example.
value => undef,
},
};
return $class->SUPER::new ('ATTENDEE', $map, %args);
}
1;
=head1 SEE ALSO
More documentation pointers can be found in L<Net::ICal>.
=cut