Net::ICal::Freebusy - Freebusy class

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

#!/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.
#======================================================================

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. 

#============================================================================
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;
}

#=================================================================================

# 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;