Template for caldav_driver.php
[caldav_driver.git] / 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
This page took 0.10164 seconds and 6 git commands to generate.