From: Jakob Sack <kde@jakobsack.de>
Date: Mon, 18 Apr 2011 08:41:01 +0000 (+0200)
Subject: Better documentation for OC_USER
X-Git-Tag: v3.0~267^2~558^2~70
X-Git-Url: https://source.dussan.org/?a=commitdiff_plain;h=1fe5f5a2dfacb5b1fede2aa112ffb0edd7673048;p=nextcloud-server.git

Better documentation for OC_USER
---

diff --git a/lib/User/backend.php b/lib/User/backend.php
index 29a1932e193..811e0cd75d1 100644
--- a/lib/User/backend.php
+++ b/lib/User/backend.php
@@ -24,64 +24,88 @@
 
 
 /**
- * Base class for user management
- *
+ * abstract base class for user management
  */
 abstract class OC_USER_BACKEND {
 
 	/**
-	 * Try to create a new user
+	 * @brief Create a new user
+	 * @param $username The username of the user to create
+	 * @param $password The password of the new user
+	 * @returns true/false
 	 *
-	 * @param  string  $username  The username of the user to create
-	 * @param  string  $password  The password of the new user
+	 * Creates a new user
 	 */
 	public static function createUser($username, $password){}
 
 	/**
-	 * @brief Delete a new user
-	 * @param $username The username of the user to delete
+	 * @brief delete a user
+	 * @param $uid The username of the user to delete
+	 * @returns true/false
+	 *
+	 * Deletes a user
+	 */
+	public static function deleteUser( $uid ){}
+
+	/**
+	 * @brief Try to login a user
+	 * @param $uid The username of the user to log in
+	 * @param $password The password of the user
+	 * @returns true/false
+	 *
+	 * Log in a user - if the password is ok
 	 */
-	public static function deleteUser( $username ){}
+	public static function login($uid, $password){}
 
 	/**
-	 * Try to login a user
+	 * @brief Kick the user
+	 * @returns true
 	 *
-	 * @param  string  $username  The username of the user to log in
-	 * @param  string  $password  The password of the user
+	 * Logout, destroys session
 	 */
-	public static function login($username, $password){}
+	public static function logout(){}
 
 	/**
-	 * Check if some user is logged in
+	 * @brief Check if the user is logged in
+	 * @returns true/false
 	 *
+	 * Checks if the user is logged in
 	 */
 	public static function isLoggedIn(){}
 
 	/**
-	 * Generate a random password
+	 * @brief Autogenerate a password
+	 * @returns string
+	 *
+	 * generates a password
 	 */
 	public static function generatePassword(){}
 
 	/**
-	 * Set the password of a user
+	 * @brief Set password
+	 * @param $uid The username
+	 * @param $password The new password
+	 * @returns true/false
 	 *
-	 * @param  string  $username  User who password will be changed
-	 * @param  string  $password  The new password for the user
+	 * Change the password of a user
 	 */
-	public static function setPassword($username, $password){}
+	public static function setPassword($uid, $password){}
 
 	/**
-	 * Check if the password of the user is correct
+	 * @brief Check if the password is correct
+	 * @param $uid The username
+	 * @param $password The password
+	 * @returns true/false
 	 *
-	 * @param  string  $username  Name of the user
-	 * @param  string  $password  Password of the user
+	 * Check if the password is correct without logging in the user
 	 */
-	public static function checkPassword($username, $password){}
-
+	public static function checkPassword($uid, $password){}
 
 	/**
-	 * get a list of all users
+	 * @brief Get a list of all users
+	 * @returns array with all uids
 	 *
+	 * Get a list of all users.
 	 */
 	public static function getUsers(){}
 }
diff --git a/lib/User/database.php b/lib/User/database.php
index 478ebc0967d..2487d29c1c4 100644
--- a/lib/User/database.php
+++ b/lib/User/database.php
@@ -37,57 +37,70 @@ require_once('User/backend.php');
 
 /**
  * Class for user management in a SQL Database (e.g. MySQL, SQLite)
- *
  */
 class OC_USER_DATABASE extends OC_USER_BACKEND {
 	static private $userGroupCache=array();
 
 	/**
-	 * Try to create a new user
+	 * @brief Create a new user
+	 * @param $username The username of the user to create
+	 * @param $password The password of the new user
+	 * @returns true/false
 	 *
-	 * @param  string  $username  The username of the user to create
-	 * @param  string  $password  The password of the new user
+	 * Creates a new user
 	 */
-	public static function createUser( $uid, $password ){
-		$query = OC_DB::prepare( "SELECT * FROM `*PREFIX*users` WHERE uid = ?" );
-		$result = $query->execute( array( $uid ));
+	public static function createUser( $username, $password ){
 		// Check if the user already exists
+		$query = OC_DB::prepare( "SELECT * FROM `*PREFIX*users` WHERE uid = ?" );
+		$result = $query->execute( array( $username ));
+
 		if ( $result->numRows() > 0 ){
 			return false;
 		}
 		else{
 			$query = OC_DB::prepare( "INSERT INTO `*PREFIX*users` ( `uid`, `password` ) VALUES( ?, ? )" );
-			$result = $query->execute( array( $uid, sha1( $password )));
+			$result = $query->execute( array( $username, sha1( $password )));
 
 			return $result ? true : false;
 		}
 	}
 
 	/**
-	 * Try to delete a user
+	 * @brief delete a user
+	 * @param $uid The username of the user to delete
+	 * @returns true/false
 	 *
-	 * @param  string  $username  The username of the user to delete
+	 * Deletes a user
 	 */
 	public static function deleteUser( $uid ){
+		// Delete user
 		$query = OC_DB::prepare( "DELETE FROM `*PREFIX*users` WHERE uid = ?" );
 		$result = $query->execute( array( $uid ));
 
+		// Delete user-group-relation
+		$query = OC_DB::prepare( "DELETE FROM `*PREFIX*group_user` WHERE uid = ?" );
+		$result = $query->execute( array( $uid ));
 		return true;
 	}
 
 	/**
-	 * Try to login a user
+	 * @brief Try to login a user
+	 * @param $uid The username of the user to log in
+	 * @param $password The password of the user
+	 * @returns true/false
 	 *
-	 * @param  string  $username  The username of the user to log in
-	 * @param  string  $password  The password of the user
+	 * Log in a user - if the password is ok
 	 */
-	public static function login( $username, $password ){
+	public static function login( $uid, $password ){
+		// Query
 		$query = OC_DB::prepare( "SELECT uid FROM *PREFIX*users WHERE uid = ? AND password = ?" );
-		$result = $query->execute( array( $username, sha1( $password )));
+		$result = $query->execute( array( $uid, sha1( $password )));
 
 		if( $result->numRows() > 0 ){
+			// Set username if name and password are known
 			$row = $result->fetchRow();
 			$_SESSION['user_id'] = $row["uid"];
+			OC_LOG::add( "core", $_SESSION['user_id'], "login" );
 			return true;
 		}
 		else{
@@ -96,17 +109,23 @@ class OC_USER_DATABASE extends OC_USER_BACKEND {
 	}
 
 	/**
-	 * Kick the user
+	 * @brief Kick the user
+	 * @returns true
 	 *
+	 * Logout, destroys session
 	 */
-	public static function logout() {
+	public static function logout(){
 		OC_LOG::add( "core", $_SESSION['user_id'], "logout" );
 		$_SESSION['user_id'] = false;
+
+		return true;
 	}
 
 	/**
-	 * Check if the user is logged in
+	 * @brief Check if the user is logged in
+	 * @returns true/false
 	 *
+	 * Checks if the user is logged in
 	 */
 	public static function isLoggedIn() {
 		if( isset($_SESSION['user_id']) AND $_SESSION['user_id'] ){
@@ -118,34 +137,50 @@ class OC_USER_DATABASE extends OC_USER_BACKEND {
 	}
 
 	/**
-	 * Generate a random password
+	 * @brief Autogenerate a password
+	 * @returns string
+	 *
+	 * generates a password
 	 */
 	public static function generatePassword(){
 		return uniqId();
 	}
 
 	/**
-	 * Set the password of a user
+	 * @brief Set password
+	 * @param $uid The username
+	 * @param $password The new password
+	 * @returns true/false
 	 *
-	 * @param  string  $username  User who password will be changed
-	 * @param  string  $password  The new password for the user
+	 * Change the password of a user
 	 */
-	public static function setPassword( $username, $password ){
-		$query = OC_DB::prepare( "UPDATE *PREFIX*users SET password = ? WHERE uid = ?" );
-		$result = $query->execute( array( sha1( $password ), $username ));
+	public static function setPassword( $uid, $password ){
+		// Check if the user already exists
+		$query = OC_DB::prepare( "SELECT * FROM `*PREFIX*users` WHERE uid = ?" );
+		$result = $query->execute( array( $uid ));
 
-		return true;
+		if ( $result->numRows() > 0 ){
+			return false;
+		}
+		else{
+			$query = OC_DB::prepare( "UPDATE *PREFIX*users SET password = ? WHERE uid = ?" );
+			$result = $query->execute( array( sha1( $password ), $uid ));
+
+			return true;
+		}
 	}
 
 	/**
-	 * Check if the password of the user is correct
+	 * @brief Check if the password is correct
+	 * @param $uid The username
+	 * @param $password The password
+	 * @returns true/false
 	 *
-	 * @param  string  $username  Name of the user
-	 * @param  string  $password  Password of the user
+	 * Check if the password is correct without logging in the user
 	 */
-	public static function checkPassword( $username, $password ){
+	public static function checkPassword( $uid, $password ){
 		$query = OC_DB::prepare( "SELECT uid FROM *PREFIX*users WHERE uid = ? AND password = ?" );
-		$result = $query->execute( array( $username, sha1( $password )));
+		$result = $query->execute( array( $uid, sha1( $password )));
 
 		if( $result->numRows() > 0 ){
 			return true;
@@ -156,8 +191,10 @@ class OC_USER_DATABASE extends OC_USER_BACKEND {
 	}
 
 	/**
-	 * get a list of all users
+	 * @brief Get a list of all users
+	 * @returns array with all uids
 	 *
+	 * Get a list of all users.
 	 */
 	public static function getUsers(){
 		$query = OC_DB::prepare( "SELECT uid FROM *PREFIX*users" );
diff --git a/lib/log.php b/lib/log.php
index 3626849f578..231ff7997b1 100644
--- a/lib/log.php
+++ b/lib/log.php
@@ -50,7 +50,7 @@ class OC_LOG {
 	 *
 	 * This function adds another entry to the log database
 	 */
-	public static function add( $subject, $predicate, $object = null ){
+	public static function add( $appid, $subject, $predicate, $object = null ){
 		// TODO: write function
 		return true;
 	}
diff --git a/lib/user.php b/lib/user.php
index 6cfcc6be488..10f08576d4c 100644
--- a/lib/user.php
+++ b/lib/user.php
@@ -87,33 +87,45 @@ class OC_USER {
 	}
 
 	/**
-	 * @brief Creates a new user
+	 * @brief Create a new user
 	 * @param $username The username of the user to create
 	 * @param $password The password of the new user
+	 * @returns true/false
+	 *
+	 * Creates a new user
 	 */
 	public static function createUser( $username, $password ){
 		return self::$_backend->createUser( $username, $password );
 	}
 
 	/**
-	 * @brief Delete a new user
-	 * @param $username The username of the user to delete
+	 * @brief delete a user
+	 * @param $uid The username of the user to delete
+	 * @returns true/false
+	 *
+	 * Deletes a user
 	 */
-	public static function deleteUser( $username ){
-		return self::$_backend->deleteUser( $username );
+	public static function deleteUser( $uid ){
+		return self::$_backend->deleteUser( $uid );
 	}
 
 	/**
-	 * @brief try to login a user
-	 * @param $username The username of the user to log in
+	 * @brief Try to login a user
+	 * @param $uid The username of the user to log in
 	 * @param $password The password of the user
+	 * @returns true/false
+	 *
+	 * Log in a user - if the password is ok
 	 */
-	public static function login( $username, $password ){
-		return self::$_backend->login( $username, $password );
+	public static function login( $uid, $password ){
+		return self::$_backend->login( $uid, $password );
 	}
 
 	/**
 	 * @brief Kick the user
+	 * @returns true
+	 *
+	 * Logout, destroys session
 	 */
 	public static function logout(){
 		return self::$_backend->logout();
@@ -121,39 +133,53 @@ class OC_USER {
 
 	/**
 	 * @brief Check if the user is logged in
+	 * @returns true/false
+	 *
+	 * Checks if the user is logged in
 	 */
 	public static function isLoggedIn(){
 		return self::$_backend->isLoggedIn();
 	}
 
 	/**
-	 * @brief Generate a random password
+	 * @brief Autogenerate a password
+	 * @returns string
+	 *
+	 * generates a password
 	 */
 	public static function generatePassword(){
 		return substr( md5( uniqId().time()), 0, 10 );
 	}
 
 	/**
-	 * @brief Set the password of a user
-	 * @param $username User whose password will be changed
-	 * @param $password The new password for the user
+	 * @brief Set password
+	 * @param $uid The username
+	 * @param $password The new password
+	 * @returns true/false
+	 *
+	 * Change the password of a user
 	 */
-	public static function setPassword( $username, $password ){
-		return self::$_backend->setPassword( $username, $password );
+	public static function setPassword( $uid, $password ){
+		return self::$_backend->setPassword( $uid, $password );
 	}
 
 	/**
-	 * @brief Check if the password of the user is correct
-	 * @param  string  $username  Name of the user
-	 * @param  string  $password  Password of the user
+	 * @brief Check if the password is correct
+	 * @param $uid The username
+	 * @param $password The password
+	 * @returns true/false
+	 *
+	 * Check if the password is correct without logging in the user
 	 */
-	public static function checkPassword( $username, $password ){
-		return self::$_backend->checkPassword( $username, $password );
+	public static function checkPassword( $uid, $password ){
+		return self::$_backend->checkPassword( $uid, $password );
 	}
 
 	/**
-	 * @brief get a list of all users
-	 * @returns array with uids
+	 * @brief Get a list of all users
+	 * @returns array with all uids
+	 *
+	 * Get a list of all users.
 	 */
 	public static function getUsers(){
 		return self::$_backend->getUsers();