Add documentation to calendar.php

apps/calendar/lib/calendar.php

@@ -56,10 +56,18 @@
  * 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;
 		}
@@ -74,11 +82,21 @@ 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,6 +130,18 @@ 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);
 
@@ -110,6 +151,19 @@ class OC_Calendar_Calendar{
 		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);
@@ -128,6 +182,12 @@ class OC_Calendar_Calendar{
 		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,6 +207,11 @@ 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));
@@ -152,6 +222,14 @@ class OC_Calendar_Calendar{
 		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));
@@ -164,6 +242,11 @@ 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 = ?' );
@@ -238,6 +353,11 @@ 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,6 +365,12 @@ 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));
@@ -252,6 +378,12 @@ class OC_Calendar_Calendar{
 		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,15 +395,30 @@ 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);
 
@@ -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;
+		}
+	}
 }