From 4d7ed0f2f548516f21d7545283bc2028a2f635d0 Mon Sep 17 00:00:00 2001 From: Jakob Sack Date: Thu, 15 Sep 2011 22:45:58 +0200 Subject: [PATCH] Add documentation to calendar.php --- apps/calendar/lib/calendar.php | 206 +++++++++++++++++++++++++++++---- 1 file changed, 185 insertions(+), 21 deletions(-) diff --git a/apps/calendar/lib/calendar.php b/apps/calendar/lib/calendar.php index 137047214a..c13fdc7d81 100644 --- a/apps/calendar/lib/calendar.php +++ b/apps/calendar/lib/calendar.php @@ -36,7 +36,7 @@ * uri VARCHAR(100), * lastmodified INT(11) * ); - * + * * CREATE TABLE calendar_calendars ( * id INTEGER UNSIGNED NOT NULL PRIMARY KEY AUTO_INCREMENT, * userid VARCHAR(255), @@ -56,16 +56,24 @@ * This class manages our calendars */ class OC_Calendar_Calendar{ + /** + * @brief Returns the list of calendars for a specific user. + * @param string $uid User ID + * @param boolean $active + * @return array + * + * TODO: what is active for? + */ public static function allCalendars($uid, $active=null){ $values = array($uid); $active_where = ''; - if (!is_null($active)){ + if (!is_null($active) && $active){ $active_where = ' AND active = ?'; $values[] = $active; } $stmt = OC_DB::prepare( 'SELECT * FROM *PREFIX*calendar_calendars WHERE userid = ?' . $active_where ); $result = $stmt->execute($values); - + $calendars = array(); while( $row = $result->fetchRow()){ $calendars[] = $row; @@ -73,12 +81,22 @@ class OC_Calendar_Calendar{ return $calendars; } - + + /** + * @brief Returns the list of calendars for a principal (DAV term of user) + * @param string $principaluri + * @return array + */ public static function allCalendarsWherePrincipalURIIs($principaluri){ $uid = self::extractUserID($principaluri); return self::allCalendars($uid); } + /** + * @brief Gets the data of one calendar + * @param integer $id + * @return associative array + */ public static function findCalendar($id){ $stmt = OC_DB::prepare( 'SELECT * FROM *PREFIX*calendar_calendars WHERE id = ?' ); $result = $stmt->execute(array($id)); @@ -86,6 +104,17 @@ class OC_Calendar_Calendar{ return $result->fetchRow(); } + /** + * @brief Creates a new calendar + * @param string $userid + * @param string $name + * @param string $description + * @param string $components Default: "VEVENT,VTODO,VJOURNAL" + * @param string $timezone Default: null + * @param integer $order Default: 1 + * @param string $color Default: null + * @return insertid + */ public static function addCalendar($userid,$name,$description,$components='VEVENT,VTODO,VJOURNAL',$timezone=null,$order=0,$color=null){ $all = self::allCalendars($userid); $uris = array(); @@ -101,15 +130,40 @@ class OC_Calendar_Calendar{ return OC_DB::insertid(); } + /** + * @brief Creates a new calendar from the data sabredav provides + * @param string $principaluri + * @param string $uri + * @param string $name + * @param string $description + * @param string $components + * @param string $timezone + * @param integer $order + * @param string $color + * @return insertid + */ public static function addCalendarFromDAVData($principaluri,$uri,$name,$description,$components,$timezone,$order,$color){ $userid = self::extractUserID($principaluri); - + $stmt = OC_DB::prepare( 'INSERT INTO *PREFIX*calendar_calendars (userid,displayname,uri,ctag,description,calendarorder,calendarcolor,timezone,components) VALUES(?,?,?,?,?,?,?,?,?)' ); $result = $stmt->execute(array($userid,$name,$uri,1,$description,$order,$color,$timezone,$components)); return OC_DB::insertid(); } + /** + * @brief Edits a calendar + * @param integer $id + * @param string $name Default: null + * @param string $description Default: null + * @param string $components Default: null + * @param string $timezone Default: null + * @param integer $order Default: null + * @param string $color Default: null + * @return boolean + * + * Values not null will be set + */ public static function editCalendar($id,$name=null,$description=null,$components=null,$timezone=null,$order=null,$color=null){ // Need these ones for checking uri $calendar = self::findCalendar($id); @@ -121,13 +175,19 @@ class OC_Calendar_Calendar{ if(is_null($timezone)) $timezone = $calendar['timezone']; if(is_null($order)) $order = $calendar['calendarorder']; if(is_null($color)) $color = $calendar['color']; - + $stmt = OC_DB::prepare( 'UPDATE *PREFIX*calendar_calendars SET displayname=?,description=?,calendarorder=?,calendarcolor=?,timezone=?,components=?,ctag=ctag+1 WHERE id=?' ); $result = $stmt->execute(array($name,$description,$order,$color,$timezone,$components,$id)); return true; } + /** + * @brief Sets a calendar (in)active + * @param integer $id + * @param boolean $active + * @return boolean + */ public static function setCalendarActive($id,$active){ $stmt = OC_DB::prepare( 'UPDATE *PREFIX*calendar_calendars SET active = ? WHERE id = ?' ); $stmt->execute(array($active, $id)); @@ -135,6 +195,11 @@ class OC_Calendar_Calendar{ return true; } + /** + * @brief Updates ctag for calendar + * @param integer $id + * @return boolean + */ public static function touchCalendar($id){ $stmt = OC_DB::prepare( 'UPDATE *PREFIX*calendar_calendars SET ctag = ctag + 1 WHERE id = ?' ); $stmt->execute(array($id)); @@ -142,16 +207,29 @@ class OC_Calendar_Calendar{ return true; } + /** + * @brief removes a calendar + * @param integer $id + * @return boolean + */ public static function deleteCalendar($id){ $stmt = OC_DB::prepare( 'DELETE FROM *PREFIX*calendar_calendars WHERE id = ?' ); $stmt->execute(array($id)); - + $stmt = OC_DB::prepare( 'DELETE FROM *PREFIX*calendar_objects WHERE calendarid = ?' ); $stmt->execute(array($id)); return true; } + /** + * @brief Returns all objects of a calendar + * @param integer $id + * @return array + * + * The objects are associative arrays. You'll find the original vObject in + * ['carddata'] + */ public static function allCalendarObjects($id){ $stmt = OC_DB::prepare( 'SELECT * FROM *PREFIX*calendar_objects WHERE calendarid = ?' ); $result = $stmt->execute(array($id)); @@ -163,7 +241,12 @@ class OC_Calendar_Calendar{ return $calendarobjects; } - + + /** + * @brief Returns an object + * @param integer $id + * @return associative array + */ public static function findCalendarObject($id){ $stmt = OC_DB::prepare( 'SELECT * FROM *PREFIX*calendar_objects WHERE id = ?' ); $result = $stmt->execute(array($id)); @@ -171,6 +254,12 @@ class OC_Calendar_Calendar{ return $result->fetchRow(); } + /** + * @brief finds an object by its DAV Data + * @param integer $cid Calendar id + * @param string $uri the uri ('filename') + * @return associative array + */ public static function findCalendarObjectWhereDAVDataIs($cid,$uri){ $stmt = OC_DB::prepare( 'SELECT * FROM *PREFIX*calendar_objects WHERE calendarid = ? AND uri = ?' ); $result = $stmt->execute(array($cid,$uri)); @@ -178,8 +267,14 @@ class OC_Calendar_Calendar{ return $result->fetchRow(); } + /** + * @brief Adds an object + * @param integer $id Calendar id + * @param string $data object + * @return insertid + */ public static function addCalendarObject($id,$data){ - $object = Sabre_VObject_Reader::read($data); + $object = self::parse($data); list($type,$startdate,$enddate,$summary,$repeating,$uid) = self::extractData($object); if(is_null($uid)){ @@ -198,8 +293,15 @@ class OC_Calendar_Calendar{ return OC_DB::insertid(); } + /** + * @brief Adds an object with the data provided by sabredav + * @param integer $id Calendar id + * @param string $uri the uri the card will have + * @param string $data object + * @return insertid + */ public static function addCalendarObjectFromDAVData($id,$uri,$data){ - $object = Sabre_VObject_Reader::read($data); + $object = self::parse($data); list($type,$startdate,$enddate,$summary,$repeating,$uid) = self::extractData($object); $stmt = OC_DB::prepare( 'INSERT INTO *PREFIX*calendar_objects (calendarid,objecttype,startdate,enddate,repeating,summary,calendardata,uri,lastmodified) VALUES(?,?,?,?,?,?,?,?,?)' ); @@ -210,10 +312,16 @@ class OC_Calendar_Calendar{ return OC_DB::insertid(); } + /** + * @brief edits an object + * @param integer $id id of object + * @param string $data object + * @return boolean + */ public static function editCalendarObject($id, $data){ $oldobject = self::findCalendarObject($id); - - $object = Sabre_VObject_Reader::read($data); + + $object = self::parse($data); list($type,$startdate,$enddate,$summary,$repeating,$uid) = self::extractData($object); $stmt = OC_DB::prepare( 'UPDATE *PREFIX*calendar_objects SET objecttype=?,startdate=?,enddate=?,repeating=?,summary=?,calendardata=?, lastmodified = ? WHERE id = ?' ); @@ -224,10 +332,17 @@ class OC_Calendar_Calendar{ return true; } + /** + * @brief edits an object with the data provided by sabredav + * @param integer $id calendar id + * @param string $uri the uri of the object + * @param string $data object + * @return boolean + */ public static function editCalendarObjectFromDAVData($cid,$uri,$data){ $oldobject = self::findCalendarObjectWhereDAVDataIs($cid,$uri); - - $object = Sabre_VObject_Reader::read($data); + + $object = self::parse($data); list($type,$startdate,$enddate,$summary,$repeating,$uid) = self::extractData($object); $stmt = OC_DB::prepare( 'UPDATE *PREFIX*calendar_objects SET objecttype=?,startdate=?,enddate=?,repeating=?,summary=?,calendardata=?, lastmodified = ? WHERE id = ?' ); @@ -237,7 +352,12 @@ class OC_Calendar_Calendar{ return true; } - + + /** + * @brief deletes an object + * @param integer $id id of object + * @return boolean + */ public static function deleteCalendarObject($id){ $stmt = OC_DB::prepare( 'DELETE FROM *PREFIX*calendar_objects WHERE id = ?' ); $stmt->execute(array($id)); @@ -245,13 +365,25 @@ class OC_Calendar_Calendar{ return true; } + /** + * @brief deletes an object with the data provided by sabredav + * @param integer $cid calendar id + * @param string $uri the uri of the object + * @return boolean + */ public static function deleteCalendarObjectFromDAVData($cid,$uri){ $stmt = OC_DB::prepare( 'DELETE FROM *PREFIX*calendar_objects WHERE calendarid = ? AND uri=?' ); $stmt->execute(array($cid,$uri)); return true; } - + + /** + * @brief Creates a URI for Calendar + * @param string $name name of the calendar + * @param array $existing existing calendar URIs + * @return string uri + */ public static function createURI($name,$existing){ $name = strtolower($name); $newname = $name; @@ -263,18 +395,33 @@ class OC_Calendar_Calendar{ return $newname; } + /** + * @brief Creates a UID + * @return string + */ public static function createUID(){ return substr(md5(rand().time()),0,10); } - + + /** + * @brief gets the userid from a principal path + * @return string + */ public static function extractUserID($principaluri){ list($prefix,$userid) = Sabre_DAV_URLUtil::splitPath($principaluri); return $userid; } + /** + * @brief Extracts data from a vObject-Object + * @param Sabre_VObject $object + * @return array + * + * [type, start, end, summary, repeating, uid] + */ protected static function extractData($object){ $return = array('',null,null,'',0,null); - + // Child to use $children = 0; $use = null; @@ -310,7 +457,7 @@ class OC_Calendar_Calendar{ break; } } unset($property); - + // find the data if(!is_null($use)){ $return[0] = $use->name; @@ -332,14 +479,14 @@ class OC_Calendar_Calendar{ } } unset($property); } - + // More than one child means reoccuring! if($children > 1){ $return[4] = 1; } return $return; } - + /** * @brief DateTime to UTC string * @param DateTime $datetime The date to convert @@ -351,4 +498,21 @@ class OC_Calendar_Calendar{ protected static function getUTCforMDB($datetime){ return date('Y-m-d H:i', $datetime->format('U') - $datetime->getOffset()); } + + /** + * @brief Parses the VObject + * @param string VObject as string + * @returns Sabre_VObject or null + * + * This function creates a date string that can be used by MDB2. + * Furthermore it converts the time to UTC. + */ + public static function parse($data){ + try { + $card = Sabre_VObject_Reader::read($data); + return $card; + } catch (Exception $e) { + return null; + } + } }