calendar_driver.php

   1 <?php
   2
   3 /**
   4  * Driver interface for the Calendar plugin
   5  *
   6  * @version @package_version@
   7  * @author Lazlo Westerhof <hello@lazlo.me>
   8  * @author Thomas Bruederli <bruederli@kolabsys.com>
   9  *
  10  * Copyright (C) 2010, Lazlo Westerhof <hello@lazlo.me>
  11  * Copyright (C) 2012, Kolab Systems AG <contact@kolabsys.com>
  12  *
  13  * This program is free software: you can redistribute it and/or modify
  14  * it under the terms of the GNU Affero General Public License as
  15  * published by the Free Software Foundation, either version 3 of the
  16  * License, or (at your option) any later version.
  17  *
  18  * This program is distributed in the hope that it will be useful,
  19  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  20  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  21  * GNU Affero General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU Affero General Public License
  24  * along with this program. If not, see <http://www.gnu.org/licenses/>.
  25  */
  26
  27
  28 /**
  29  * Struct of an internal event object how it is passed from/to the driver classes:
  30  *
  31  *  $event = array(
  32  *            'id' => 'Event ID used for editing',
  33  *           'uid' => 'Unique identifier of this event',
  34  *      'calendar' => 'Calendar identifier to add event to or where the event is stored',
  35  *         'start' => DateTime,  // Event start date/time as DateTime object
  36  *           'end' => DateTime,  // Event end date/time as DateTime object
  37  *        'allday' => true|false,  // Boolean flag if this is an all-day event
  38  *       'changed' => DateTime,    // Last modification date of event
  39  *         'title' => 'Event title/summary',
  40  *      'location' => 'Location string',
  41  *   'description' => 'Event description',
  42  *           'url' => 'URL to more information',
  43  *    'recurrence' => array(   // Recurrence definition according to iCalendar (RFC 2445) specification as list of key-value pairs
  44  *            'FREQ' => 'DAILY|WEEKLY|MONTHLY|YEARLY',
  45  *        'INTERVAL' => 1...n,
  46  *           'UNTIL' => DateTime,
  47  *           'COUNT' => 1..n,   // number of times
  48  *                      // + more properties (see http://www.kanzaki.com/docs/ical/recur.html)
  49  *          'EXDATE' => array(),  // list of DateTime objects of exception Dates/Times
  50  *      'EXCEPTIONS' => array(<event>),  list of event objects which denote exceptions in the recurrence chain
  51  *    ),
  52  * 'recurrence_id' => 'ID of the recurrence group',   // usually the ID of the starting event
  53  *    'categories' => 'Event category',
  54  *     'free_busy' => 'free|busy|outofoffice|tentative',  // Show time as
  55  *      'priority' => 0-9,     // Event priority (0=undefined, 1=highest, 9=lowest)
  56  *   'sensitivity' => 'public|private|confidential',   // Event sensitivity
  57  *        'alarms' => '-15M:DISPLAY',  // Reminder settings inspired by valarm definition (e.g. display alert 15 minutes before event)
  58  *   'attachments' => array(   // List of attachments
  59  *            'name' => 'File name',
  60  *        'mimetype' => 'Content type',
  61  *            'size' => 1..n, // in bytes
  62  *              'id' => 'Attachment identifier'
  63  *   ),
  64  * 'deleted_attachments' => array(), // array of attachment identifiers to delete when event is updated
  65  *     'attendees' => array(   // List of event participants
  66  *            'name' => 'Participant name',
  67  *           'email' => 'Participant e-mail address',  // used as identifier
  68  *            'role' => 'ORGANIZER|REQ-PARTICIPANT|OPT-PARTICIPANT|CHAIR',
  69  *          'status' => 'NEEDS-ACTION|UNKNOWN|ACCEPTED|TENTATIVE|DECLINED'
  70  *            'rsvp' => true|false,
  71  *    ),
  72  *
  73  *     '_savemode' => 'all|future|current|new',   // How changes on recurring event should be handled
  74  *       '_notify' => true|false,  // whether to notify event attendees about changes
  75  * '_fromcalendar' => 'Calendar identifier where the event was stored before',
  76  *  );
  77  */
  78
  79 /**
  80  * Interface definition for calendar driver classes
  81  */
  82 abstract class calendar_driver
  83 {
  84   // features supported by backend
  85   public $alarms = false;
  86   public $attendees = false;
  87   public $freebusy = false;
  88   public $attachments = false;
  89   public $undelete = false; // event undelete action
  90   public $categoriesimmutable = false;
  91   public $alarm_types = array('DISPLAY');
  92   public $alarm_absolute = true;
  93   public $last_error;
  94
  95   protected $default_categories = array(
  96     'Personal' => 'c0c0c0',
  97     'Work'     => 'ff0000',
  98     'Family'   => '00ff00',
  99     'Holiday'  => 'ff6600',
 100   );
 101
 102   /**
 103    * Get a list of available calendars from this source
 104    *
 105    * @param bool $active   Return only active calendars
 106    * @param bool $personal Return only personal calendars
 107    *
 108    * @return array List of calendars
 109    */
 110   abstract function list_calendars($active = false, $personal = false);
 111
 112   /**
 113    * Create a new calendar assigned to the current user
 114    *
 115    * @param array Hash array with calendar properties
 116    *        name: Calendar name
 117    *       color: The color of the calendar
 118    *  showalarms: True if alarms are enabled
 119    * @return mixed ID of the calendar on success, False on error
 120    */
 121   abstract function create_calendar($prop);
 122
 123   /**
 124    * Update properties of an existing calendar
 125    *
 126    * @param array Hash array with calendar properties
 127    *          id: Calendar Identifier
 128    *        name: Calendar name
 129    *       color: The color of the calendar
 130    *  showalarms: True if alarms are enabled (if supported)
 131    * @return boolean True on success, Fales on failure
 132    */
 133   abstract function edit_calendar($prop);
 134
 135   /**
 136    * Set active/subscribed state of a calendar
 137    *
 138    * @param array Hash array with calendar properties
 139    *          id: Calendar Identifier
 140    *      active: True if calendar is active, false if not
 141    * @return boolean True on success, Fales on failure
 142    */
 143   abstract function subscribe_calendar($prop);
 144
 145   /**
 146    * Delete the given calendar with all its contents
 147    *
 148    * @param array Hash array with calendar properties
 149    *      id: Calendar Identifier
 150    * @return boolean True on success, Fales on failure
 151    */
 152   abstract function remove_calendar($prop);
 153
 154   /**
 155    * Add a single event to the database
 156    *
 157    * @param array Hash array with event properties (see header of this file)
 158    * @return mixed New event ID on success, False on error
 159    */
 160   abstract function new_event($event);
 161
 162   /**
 163    * Update an event entry with the given data
 164    *
 165    * @param array Hash array with event properties (see header of this file)
 166    * @return boolean True on success, False on error
 167    */
 168   abstract function edit_event($event);
 169
 170   /**
 171    * Move a single event
 172    *
 173    * @param array Hash array with event properties:
 174    *      id: Event identifier
 175    *   start: Event start date/time as DateTime object
 176    *     end: Event end date/time as DateTime object
 177    *  allday: Boolean flag if this is an all-day event
 178    * @return boolean True on success, False on error
 179    */
 180   abstract function move_event($event);
 181
 182   /**
 183    * Resize a single event
 184    *
 185    * @param array Hash array with event properties:
 186    *      id: Event identifier
 187    *   start: Event start date/time as DateTime object with timezone
 188    *     end: Event end date/time as DateTime object with timezone
 189    * @return boolean True on success, False on error
 190    */
 191   abstract function resize_event($event);
 192
 193   /**
 194    * Remove a single event from the database
 195    *
 196    * @param array   Hash array with event properties:
 197    *      id: Event identifier
 198    * @param boolean Remove event irreversible (mark as deleted otherwise,
 199    *                if supported by the backend)
 200    *
 201    * @return boolean True on success, False on error
 202    */
 203   abstract function remove_event($event, $force = true);
 204
 205   /**
 206    * Restores a single deleted event (if supported)
 207    *
 208    * @param array Hash array with event properties:
 209    *      id: Event identifier
 210    *
 211    * @return boolean True on success, False on error
 212    */
 213   public function restore_event($event)
 214   {
 215     return false;
 216   }
 217
 218   /**
 219    * Return data of a single event
 220    *
 221    * @param mixed  UID string or hash array with event properties:
 222    *        id: Event identifier
 223    *  calendar: Calendar identifier (optional)
 224    * @param boolean If true, only writeable calendars shall be searched
 225    * @param boolean If true, only active calendars shall be searched
 226    * @param boolean If true, only personal calendars shall be searched
 227    *
 228    * @return array Event object as hash array
 229    */
 230   abstract function get_event($event, $writeable = false, $active = false, $personal = false);
 231
 232   /**
 233    * Get events from source.
 234    *
 235    * @param  integer Event's new start (unix timestamp)
 236    * @param  integer Event's new end (unix timestamp)
 237    * @param  string  Search query (optional)
 238    * @param  mixed   List of calendar IDs to load events from (either as array or comma-separated string)
 239    * @param  boolean Include virtual/recurring events (optional)
 240    * @param  integer Only list events modified since this time (unix timestamp)
 241    * @return array A list of event objects (see header of this file for struct of an event)
 242    */
 243   abstract function load_events($start, $end, $query = null, $calendars = null, $virtual = 1, $modifiedsince = null);
 244
 245   /**
 246    * Get a list of pending alarms to be displayed to the user
 247    *
 248    * @param  integer Current time (unix timestamp)
 249    * @param  mixed   List of calendar IDs to show alarms for (either as array or comma-separated string)
 250    * @return array A list of alarms, each encoded as hash array:
 251    *         id: Event identifier
 252    *        uid: Unique identifier of this event
 253    *      start: Event start date/time as DateTime object
 254    *        end: Event end date/time as DateTime object
 255    *     allday: Boolean flag if this is an all-day event
 256    *      title: Event title/summary
 257    *   location: Location string
 258    */
 259   abstract function pending_alarms($time, $calendars = null);
 260
 261   /**
 262    * (User) feedback after showing an alarm notification
 263    * This should mark the alarm as 'shown' or snooze it for the given amount of time
 264    *
 265    * @param  string  Event identifier
 266    * @param  integer Suspend the alarm for this number of seconds
 267    */
 268   abstract function dismiss_alarm($event_id, $snooze = 0);
 269
 270   /**
 271    * Check the given event object for validity
 272    *
 273    * @param array Event object as hash array
 274    * @return boolean True if valid, false if not
 275    */
 276   public function validate($event)
 277   {
 278     $valid = true;
 279
 280     if (!is_object($event['start']) || !is_a($event['start'], 'DateTime'))
 281       $valid = false;
 282     if (!is_object($event['end']) || !is_a($event['end'], 'DateTime'))
 283       $valid = false;
 284
 285     return $valid;
 286   }
 287
 288
 289   /**
 290    * Get list of event's attachments.
 291    * Drivers can return list of attachments as event property.
 292    * If they will do not do this list_attachments() method will be used.
 293    *
 294    * @param array $event Hash array with event properties:
 295    *         id: Event identifier
 296    *   calendar: Calendar identifier
 297    *
 298    * @return array List of attachments, each as hash array:
 299    *         id: Attachment identifier
 300    *       name: Attachment name
 301    *   mimetype: MIME content type of the attachment
 302    *       size: Attachment size
 303    */
 304   public function list_attachments($event) { }
 305
 306   /**
 307    * Get attachment properties
 308    *
 309    * @param string $id    Attachment identifier
 310    * @param array  $event Hash array with event properties:
 311    *         id: Event identifier
 312    *   calendar: Calendar identifier
 313    *
 314    * @return array Hash array with attachment properties:
 315    *         id: Attachment identifier
 316    *       name: Attachment name
 317    *   mimetype: MIME content type of the attachment
 318    *       size: Attachment size
 319    */
 320   public function get_attachment($id, $event) { }
 321
 322   /**
 323    * Get attachment body
 324    *
 325    * @param string $id    Attachment identifier
 326    * @param array  $event Hash array with event properties:
 327    *         id: Event identifier
 328    *   calendar: Calendar identifier
 329    *
 330    * @return string Attachment body
 331    */
 332   public function get_attachment_body($id, $event) { }
 333
 334   /**
 335    * List availabale categories
 336    * The default implementation reads them from config/user prefs
 337    */
 338   public function list_categories()
 339   {
 340     $rcmail = rcube::get_instance();
 341     return $rcmail->config->get('calendar_categories', $this->default_categories);
 342   }
 343
 344   /**
 345    * Create a new category
 346    */
 347   public function add_category($name, $color) { }
 348
 349   /**
 350    * Remove the given category
 351    */
 352   public function remove_category($name) { }
 353
 354   /**
 355    * Update/replace a category
 356    */
 357   public function replace_category($oldname, $name, $color) { }
 358
 359   /**
 360    * Fetch free/busy information from a person within the given range
 361    *
 362    * @param string  E-mail address of attendee
 363    * @param integer Requested period start date/time as unix timestamp
 364    * @param integer Requested period end date/time as unix timestamp
 365    *
 366    * @return array  List of busy timeslots within the requested range
 367    */
 368   public function get_freebusy_list($email, $start, $end)
 369   {
 370     return false;
 371   }
 372
 373   /**
 374    * Callback function to produce driver-specific calendar create/edit form
 375    *
 376    * @param string Request action 'form-edit|form-new'
 377    * @param array  Calendar properties (e.g. id, color)
 378    * @param array  Edit form fields
 379    *
 380    * @return string HTML content of the form
 381    */
 382   public function calendar_form($action, $calendar, $formfields)
 383   {
 384     $html = '';
 385     foreach ($formfields as $field) {
 386       $html .= html::div('form-section',
 387         html::label($field['id'], $field['label']) .
 388         $field['value']);
 389     }
 390
 391     return $html;
 392   }
 393
 394   /**
 395    * Return a (limited) list of color values to be used for calendar and category coloring
 396    *
 397    * @return mixed List for colors as hex values or false if no presets should be shown
 398    */
 399   public function get_color_values()
 400   {
 401       return false;
 402   }
 403
 404 }
 405