Net-ICal
view release on metacpan or search on metacpan
lib/Net/ICal/Freebusy.pm view on Meta::CPAN
#!/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: Freebusy.pm,v 1.16 2001/08/04 04:59:36 srl Exp $
#
# (C) COPYRIGHT 2000-2001, Reefknot developers.
#
# See the AUTHORS file included in the distribution for a full list.
#======================================================================
=head1 NAME
Net::ICal::Freebusy -- Freebusy class
=cut
package Net::ICal::Freebusy;
use strict;
use base qw(Net::ICal::Component);
use Carp;
use Net::ICal::Period;
use Net::ICal::Property;
use Net::ICal::Util qw(:all);
# TODO, BUG 424142: this documentation needs expanding.
=head1 DESCRIPTION
Net::ICal::Freebusy represents a list of time when someone's
free or busy. Freebusy elements can be used in three ways:
=over 4
=item * To request information about a user's open schedule slots
=item * To reply to a request for free/busy information
=item * To publish a user's list of free/busy information.
=back
=head1 SYNOPSIS
use Net::ICal::Freebusy;
my $p = new Net::ICal::Period("19970101T120000","19970101T123000");
my $q = new Net::ICal::Period("19970101T124500","19970101T130000");
# syntax which works now
my $f = new Net::ICal::Freebusy(freebusy => [$p],
organizer => 'alice@wonderland.com');
# FIXME, BUG 424144:
# you should be able to say this, but it doesn't work now
my $f = new Net::ICal::Freebusy(freebusy => [$p, $q],
organizer => 'alice@wonderland.com');
=head1 BASIC METHODS
=head2 new (options_hash)
Creates a new Freebusy element. Arguments should be specified
as elements in a hash.
When making a request for information about a user's free/busy time,
arguments can be any of the following:
=over 4
=item * contact - who to contact about this
=item * dtstart - beginning of the window of time we want info about
=item * dtend - end of the window of time we want info about.
=item * duration - how large a block of time we want to know about.
=item * dtstamp - when this request was created
=item * organizer - user who wants information about free/busy times
=item * uid - a unique identifier for this request.
=item * url - a URL with more information about this request
=item * attendee - which users' schedules we want info about; an array of Attendee objects
=item * comment - a comment about this request.
=item * freebusy - allowed but meaningless.
=item * request_status - allowed but not relevant.
=back
When responding to a request for free/busy information, the arguments mean
different things:
=over 4
=item * contact - who to contact about this list
=item * dtstart - allowed but irrelevant
=item * dtend - allowed but irrelevant
=item * duration - allowed but irrelevant
=item * dtstamp - when this response was created
=item * organizer - allowed but irrelevant
=item * uid - a unique identifier for this response.
=item * url - a URL with more information about this response.
=item * attendee - the user responding to the request
=item * comment - a comment about this response.
=item * freebusy - an array of Durations that are free. Right now, only one Duration is allowed, This will be fixed.
=item * request_status - a number representing the success or failure of the request. See RFC2445 4.8.8.2.
=back
When publishing information about busy time to other users, the
parameters have the following meanings:
=over 4
=item * contact - who to contact about this list
=item * dtstart - Beginning date of this range of published free/busy time
=item * dtend - End date of this range of published free/busy time
=item * duration - allowed but irrelevant (?)
=item * dtstamp - when this information was published
=item * organizer - The calendar user associated with this free/busy info
=item * uid - a unique identifier for this publication of free/busy info.
=item * url - a URL with more information about this published free/busy.
=item * attendee - allowed but irrelevant.
=item * comment - a comment about this publication.
=item * freebusy - an array of Durations that are free. Right now, only one Duration is allowed, This will be fixed.
=item * request_status - allowed but irrelevant.
=back
=begin testing
use Net::ICal::Attendee;
use Net::ICal::Freebusy;
my $f = Net::ICal::Freebusy->new();
ok(!defined($f), "new() with no arguments fails");
# TODO: add tests and make the first test pass.
# That probably means adding in some real validation in the code.
my $p = new Net::ICal::Period("19970101T120000","19970101T123000");
# NOTE: this test should be compared to FreebusyItem to make sure it's sane.
# I'm not at all sure it is. --srl
$f = Net::ICal::Freebusy->new(freebusy => [$p],
organizer => Net::ICal::Attendee->new('mailto:alice@wonderland.com'));
ok(defined($f), "new() with 1 fbitem and an organizer succeeds");
my $f_ical = $f->as_ical;
my $f2 = Net::ICal::Freebusy->new_from_ical($f_ical);
ok($f2->as_ical eq $f->as_ical,
'reading in our output results in an identical object');
=end testing
=cut
#============================================================================
sub new {
my ($class, %args) = @_;
# set FBTYPE to the default, BUSY, if not otherwise specified.
# commented out because this property is supposed to show up on
# FREEBUSY lines
#unless (defined $args{fbtype}) {
# $args{fbtype} = 'BUSY';
#}
return undef unless (%args);
my $self = &_create ($class, %args);
return undef unless (defined $self);
unless ($self->uid) {
$self->uid (create_uuid);
}
return undef unless ($self->validate);
return $self;
}
#=================================================================================
=head2 new_from_ical ($text)
Takes iCalendar text as a parameter; returns a Net::ICal::Freebusy object.
=cut
# new_from_ical is inherited from Net::ICal::Component.
# TODO, BUG 424143: this needs a test case done to prove that it works.
#==================================================================================
# make sure that this object has the bare minimum requirements specified by the RFC,
my $count = 0;
sub validate {
my ($self) = @_;
#TODO: fill in validation checks
#BUG: 424137
return $self->SUPER::validate ($self);
}
# an internal function that sets up the object.
sub _create {
my ($class, %args) = @_;
my $map = { # RFC2445 4.6.4 describes VFREEBUSY
attendee => { # RFC2445 4.8.4.1 says this is PROHIBITED in VFREEBUSY;
# 4.6.4 says it's optional.
type => 'parameter',
doc => 'who is coming to this meeting',
domain => 'ref',
options => 'ARRAY',
value => undef,
},
comment => { # RFC2445 4.8.1.4 - optional in VFREEBUSY
type => 'parameter',
doc => '',
domain => 'param',
options => [qw(altrep param)],
# FIXME, BUG 424124:
# there can be more than one of these in an event/todo/journal.
# do they need to be ordered in an array?
value => undef,
},
contact => { # RFC2445 4.8.4.2 - optional in VFREEBUSY
type => 'parameter',
doc => 'who to contact about this event',
# i'm really surprised this isn't an Attendee type. but i guess
# it makes sense.
value => undef,
},
dtstart => { # RFC2445 4.8.2.4 - optional in VFREEBUSY,
type => 'parameter',
doc => '',
domain => 'ref',
# TODO, BUG 424114: needs to be in UTC. how to enforce?
options => 'Net::ICal::Time',
value => undef,
},
dtend => { # RFC2445 4.8.2.2 - optional in VFREEBUSY
type => 'parameter',
doc => 'when this event ends',
domain => 'ref',
options => 'Net::ICal::Time',
value => undef,
},
duration => { # XXX: RFC2445 4.8.2.5 says nothing about this;
# 4.6.4's ABNF says that duration is relevant in VFREEBUSY. Who's right?
type => 'parameter',
doc => 'how long this task lasts',
domain => 'ref',
options => 'Net::ICal::Duration',
value => undef,
},
dtstamp => { # RFC2445 4.8.7.2 - REQUIRED in VFREEBUSY
# XXX: 4.6.4's ABNF says this is optional. hm?
type => 'parameter',
doc => '',
domain => 'ref',
options => 'Net::ICal::Time',
value => undef,
# TODO, BUG 424118:
# This is the date/time this object was created; should we
# set it by default if the user doesn't set it?
# Does this have to be in UTC?
},
freebusy => {
type => 'parameter',
doc => 'one or more Net::ICal::Periods',
domain => 'ref',
options => 'ARRAY',
# TODO, BUG 424144:
# we need to support multiple FREEBUSY lines, as well as multiple
# Periods inside each FREEBUSY line. This very well might be an array
# of Net::ICal::FreebusyItem objects or something. Thoughts?
# TODO, BUG 424145: we need to be able to output lines like:
# FREEBUSY;VALUE=PERIOD:19971015T050000Z/PT8H30M,19971015T160000Z/PT5H30M
},
organizer => { # RFC2445 4.8.4.3 - REQUIRED in VFREEBUSY
# XXX: 4.6.4's ABNF says this is OPTIONAL. hm?
type => 'parameter',
doc => '',
domain => 'ref',
options => 'Net::ICal::Attendee',
value => undef,
},
request_status => { # RFC2445 4.8.8.2 - optional in VFREEBUSY
type => 'parameter',
doc => 'how successful have we been at scheduling this',
value => undef,
# This is a varying-granularity field; read the RFC.
# 1.x = preliminary success, pending completion
# 2.x = request completed successfully, possibly with a fallback.
# 3.x = request failed, syntax or semantic error in client req format
# 4.x = scheduling error; some kind of failure in the scheduling system.
# Values can look like "x.y.z" to give even more granularity.
# TODO, BUG 424125: I think we have to define our own error subcodes. --srl
},
uid => { # RFC2445 4.8.4.7 - REQUIRED in VFREEBUSY
# XXX: 4.6.4 claims this is optional. ????
type => 'parameter',
doc => 'global-unique identifier for a generated event',
value => undef,
},
url => { # RFC2445 4.8.4.6 - optional 1x in VFREEBUSY.
type => 'parameter',
doc => 'a url associated with this event',
value => undef,
},
};
my $self = $class->SUPER::new ('VFREEBUSY', $map, %args);
return $self;
}
# TODO, BUG 424148:
# Food for thought, from RFC2445 4.6.4:
# When present in a "VFREEBUSY" calendar component, the "DTSTART" and
# "DTEND" properties SHOULD be specified prior to any "FREEBUSY"
# properties. In a free time request, these properties can be used in
# combination with the "DURATION" property to represent a request for a
# duration of free time within a specified window of time.
#
# as_ical methods currently don't let us specify the output order. They'll
# need to in order for us to be RFC-compliant here.
1;
=head1 SEE ALSO
More documentation pointers can be found in L<Net::ICal>.
=cut
( run in 0.418 second using v1.01-cache-2.11-cpan-600a1bdf6e4 )