<?php
  
  /**
   * Every CalDAV backend must at least implement this interface.
   * 
   * @package Sabre
   * @subpackage CalDAV
   * @copyright Copyright (C) 2007-2013 Rooftop Solutions. All rights reserved.
   * @author Evert Pot (http://www.rooftopsolutions.nl/) 
   * @license http://code.google.com/p/sabredav/wiki/License Modified BSD License
   */
  interface Sabre_CalDAV_Backend_BackendInterface {
  
      /**
       * Returns a list of calendars for a principal.
       *
       * Every project is an array with the following keys:
       *  * id, a unique id that will be used by other functions to modify the
       *    calendar. This can be the same as the uri or a database key.
       *  * uri, which the basename of the uri with which the calendar is
       *    accessed.
       *  * principaluri. The owner of the calendar. Almost always the same as
       *    principalUri passed to this method.
       *
       * Furthermore it can contain webdav properties in clark notation. A very
       * common one is '{DAV:}displayname'.
       *
       * @param string $principalUri
       * @return array
       */
      public function getCalendarsForUser($principalUri);
  
      /**
       * Creates a new calendar for a principal.
       *
       * If the creation was a success, an id must be returned that can be used to reference
       * this calendar in other methods, such as updateCalendar.
       *
       * @param string $principalUri
       * @param string $calendarUri
       * @param array $properties
       * @return void
       */
      public function createCalendar($principalUri,$calendarUri,array $properties);
  
      /**
       * Updates properties for a calendar.
       *
       * The mutations array uses the propertyName in clark-notation as key,
       * and the array value for the property value. In the case a property
       * should be deleted, the property value will be null.
       *
       * This method must be atomic. If one property cannot be changed, the
       * entire operation must fail.
       *
       * If the operation was successful, true can be returned.
       * If the operation failed, false can be returned.
       *
       * Deletion of a non-existent property is always successful.
       *
       * Lastly, it is optional to return detailed information about any
       * failures. In this case an array should be returned with the following
       * structure:
       *
       * array(
       *   403 => array(
       *      '{DAV:}displayname' => null,
       *   ),
       *   424 => array(
       *      '{DAV:}owner' => null,
       *   )
       * )
       *
       * In this example it was forbidden to update {DAV:}displayname.
       * (403 Forbidden), which in turn also caused {DAV:}owner to fail
       * (424 Failed Dependency) because the request needs to be atomic.
       *
       * @param mixed $calendarId
       * @param array $mutations
       * @return bool|array
       */
      public function updateCalendar($calendarId, array $mutations); 
  
      /**
       * Delete a calendar and all it's objects
       *
       * @param mixed $calendarId
       * @return void
       */
      public function deleteCalendar($calendarId);
  
      /**
       * Returns all calendar objects within a calendar.
       *
       * Every item contains an array with the following keys:
       *   * id - unique identifier which will be used for subsequent updates
       *   * calendardata - The iCalendar-compatible calendar data
       *   * uri - a unique key which will be used to construct the uri. This can be any arbitrary string.
       *   * lastmodified - a timestamp of the last modification time
       *   * etag - An arbitrary string, surrounded by double-quotes. (e.g.:
       *   '  "abcdef"')
       *   * calendarid - The calendarid as it was passed to this function.
       *   * size - The size of the calendar objects, in bytes.
       *
       * Note that the etag is optional, but it's highly encouraged to return for
       * speed reasons.
       *
       * The calendardata is also optional. If it's not returned
       * 'getCalendarObject' will be called later, which *is* expected to return
       * calendardata.
       *
       * If neither etag or size are specified, the calendardata will be
       * used/fetched to determine these numbers. If both are specified the
       * amount of times this is needed is reduced by a great degree.
       *
       * @param mixed $calendarId
       * @return array
       */
      public function getCalendarObjects($calendarId);
  
      /**
       * Returns information from a single calendar object, based on it's object
       * uri.
       *
       * The returned array must have the same keys as getCalendarObjects. The
       * 'calendardata' object is required here though, while it's not required
       * for getCalendarObjects.
       *
       * @param mixed $calendarId
       * @param string $objectUri
       * @return array
       */
      public function getCalendarObject($calendarId,$objectUri);
  
      /**
       * Creates a new calendar object.
       *
       * It is possible return an etag from this function, which will be used in
       * the response to this PUT request. Note that the ETag must be surrounded
       * by double-quotes.
       *
       * However, you should only really return this ETag if you don't mangle the
       * calendar-data. If the result of a subsequent GET to this object is not
       * the exact same as this request body, you should omit the ETag.
       *
       * @param mixed $calendarId
       * @param string $objectUri
       * @param string $calendarData
       * @return string|null
       */
      public function createCalendarObject($calendarId,$objectUri,$calendarData);
  
      /**
       * Updates an existing calendarobject, based on it's uri.
       *
       * It is possible return an etag from this function, which will be used in
       * the response to this PUT request. Note that the ETag must be surrounded
       * by double-quotes.
       *
       * However, you should only really return this ETag if you don't mangle the
       * calendar-data. If the result of a subsequent GET to this object is not
       * the exact same as this request body, you should omit the ETag.
       *
       * @param mixed $calendarId
       * @param string $objectUri
       * @param string $calendarData
       * @return string|null
       */
      public function updateCalendarObject($calendarId,$objectUri,$calendarData);
  
      /**
       * Deletes an existing calendar object.
       *
       * @param mixed $calendarId
       * @param string $objectUri
       * @return void
       */
      public function deleteCalendarObject($calendarId,$objectUri);
  
      /**
       * Performs a calendar-query on the contents of this calendar.
       *
       * The calendar-query is defined in RFC4791 : CalDAV. Using the
       * calendar-query it is possible for a client to request a specific set of
       * object, based on contents of iCalendar properties, date-ranges and
       * iCalendar component types (VTODO, VEVENT).
       *
       * This method should just return a list of (relative) urls that match this
       * query.
       *
       * The list of filters are specified as an array. The exact array is
       * documented by Sabre_CalDAV_CalendarQueryParser.
       *
       * Note that it is extremely likely that getCalendarObject for every path
       * returned from this method will be called almost immediately after. You
       * may want to anticipate this to speed up these requests.
       *
       * This method provides a default implementation, which parses *all* the
       * iCalendar objects in the specified calendar.
       *
       * This default may well be good enough for personal use, and calendars
       * that aren't very large. But if you anticipate high usage, big calendars
       * or high loads, you are strongly adviced to optimize certain paths.
       *
       * The best way to do so is override this method and to optimize
       * specifically for 'common filters'.
       *
       * Requests that are extremely common are:
       *   * requests for just VEVENTS
       *   * requests for just VTODO
       *   * requests with a time-range-filter on either VEVENT or VTODO.
       *
       * ..and combinations of these requests. It may not be worth it to try to
       * handle every possible situation and just rely on the (relatively
       * easy to use) CalendarQueryValidator to handle the rest.
       *
       * Note that especially time-range-filters may be difficult to parse. A
       * time-range filter specified on a VEVENT must for instance also handle
       * recurrence rules correctly.
       * A good example of how to interprete all these filters can also simply
       * be found in Sabre_CalDAV_CalendarQueryFilter. This class is as correct
       * as possible, so it gives you a good idea on what type of stuff you need
       * to think of.
       *
       * @param mixed $calendarId
       * @param array $filters
       * @return array
       */
      public function calendarQuery($calendarId, array $filters); 
  
  }