<?php

/**
 * Abstract Calendaring Adapter class
 *
 * Implement this class to add support for new protocols.
 * 
 * @package Atmail
 * @subpackage Calendar 
 * @copyright Copyright (C) 2011 Atmail. All rights reserved.
 * @author Evert Pot (http://www.rooftopsolutions.nl/) 
 */
abstract class Atmail_Calendar_Adapter_Abstract {

    /**
     * Returns the list of calendars for this connection
     *
     * @return Atmail_Calendar_Calendar[] 
     */
    abstract public function getCalendars(); 

    /**
     * Returns a single calendar by it's url 
     * 
     * @param string $url 
     * @return Atmail_Calendar_Calendar 
     */
    abstract public function getCalendarByUrl($url);

    /**
     * Updates a calendars' properties
     *
     * @param Atmail_Calendar_Calendar $calendar
     * @return void
     */
    abstract public function updateCalendar(Atmail_Calendar_Calendar $calendar);
   
    /**
     * Creates a new calendar 
     * 
     * @param Atmail_Calendar_Calendar $calendar 
     * @return void
     */
    abstract public function createCalendar(Atmail_Calendar_Calendar $calendar);
   
    /**
     * Deletes an entire calendar 
     * 
     * @param Atmail_Calendar_Calendar $calendar 
     * @return void
     */
    abstract public function deleteCalendar(Atmail_Calendar_Calendar $calendar);
    
    /**
     * Returns true if the external server could be reached.
     * 
     * @return bool 
     */
    public function ping() {

        return true;
        
    }

    /**
     * Returns a list of events by a date range
     *
     * The dates must be specified as unix timestamps 
     * 
     * @param Atmail_Calendar_Calendar $calendar 
     * @param int $startDate 
     * @param int $endDate 
     * @return Atmail_Calendar_Event[] 
     */
    abstract public function getEventsByDateRange(Atmail_Calendar_Calendar $calendar, $startDate, $endDate); 

    /**
     * Returns a list of events with alarms triggering within the specified 
     * date range.
     *
     * The dates must be specified as unix timestamps
     * 
     * @param Atmail_Calendar_Calendar $calendar 
     * @param int $startDate 
     * @param int $endDate 
     * @return Atmail_Calendar_Event[] 
     */
    abstract public function getAlarmsByDateRange(Atmail_Calendar_Calendar $calendar, $startDate, $endDate);

    /**
     * Creates a new event in a calendar
     *
     * @param Atmail_Calendar_Calendar $calendar 
     * @param Atmail_Calendar_Event $event 
     * @return void
     */
    abstract public function createEvent(Atmail_Calendar_Calendar $calendar, Atmail_Calendar_Event $event);

    /**
     * Updates an existing event in a calendar
     *
     * If the oldETag argument is specified, we will instruct the server to 
     * only update the event the etag has not changed.
     *
     * @param Atmail_Calendar_Calendar $calendar 
     * @param Atmail_Calendar_Event $event
     * @param string $oldETag  
     * @return void
     */
    abstract public function updateEvent(Atmail_Calendar_Calendar $calendar, Atmail_Calendar_Event $event); 

    /**
     * Returns a single event, based on it's url. 
     * 
     * @param string $url 
     * @return Atmail_Calendar_Event 
     */
    abstract public function getEventByUrl($url);

    /**
     * Returns a single event, based on it's uid.
     *
     * Note that this is likely considerably slower than getEventByUrl 
     * 
     * @param Atmail_Calendar_Calendar $calendar
     * @param string $url
     * @return Atmail_Calendar_Event 
     */
    abstract public function getEventByUid(Atmail_Calendar_Calendar $calendar, $uid);

    /**
     * Deletes an event
     * 
     * @param Atmail_Calendar_Event $Atmail_Calendar_Event 
     * @return void
     */
    abstract public function deleteEvent(Atmail_Calendar_Event $event);

}
