<?php
/*
     LoginHandler.php, Base class for implementing new login handlers.
     Copyright (C) 2004 Arend van Beelen, Auton Rijnsburg

     This program is free software; you can redistribute it and/or modify it
     under the terms of the GNU General Public License as published by the Free
     Software Foundation; either version 2 of the License, or (at your option)
     any later version.

     This program is distributed in the hope that it will be useful, but WITHOUT
     ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
     FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
     more details.

     You should have received a copy of the GNU General Public License along
     with this program; if not, write to the Free Software Foundation, Inc.,
     59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

     For any questions, comments or whatever, you may mail me at: hide@address.com
*/

/**
 * @brief Base class for implementing new login handlers.
 *
 * This class is used by the Login class for authentication. When the class is
 * instantiated, either the login() or setUsername() method is called.
 *
 * When implementing your own login method, you should call your class like
 * <code>{$loginMethod}_LoginHandler</code> and save it in a file with the same
 * name (with <code>.php</code> extension) in the
 * <code>plugins/LoginHandlers</code> directory. You can then specify your
 * login method in the <code>global.conf</code> configuration file.
 */
interface LoginHandler
{
	/**
	 * Logs the user in with the given @p username and @p password.
	 *
	 * @return @p true if the user is logged in successfully, @p false
	 *         otherwise.
	 */
	public function login($username, $password);

	/**
	 * Returns the username.
	 *
	 * @return The username of the currently logged in user.
	 */
	public function username();

	/**
	 * Sets the current username to be @p username. This could be a non-existing
	 * anonymous username.
	 *
	 * @return @p true if @p username is an existing username, @p false otherwise.
	 */
	public function setUsername($username);

	/**
	 * Returns the given user's full name.
	 *
	 * @param username Username of the user whose full name to return.
	 *                 This parameter was added in Aukyla 1.1.
	 * @return The full name of the given user.
	 */
	public function fullName($username);

	/**
	 * Returns the given user's email address.
	 *
	 * @param username Username of the user whose email address to return.
	 *                 This parameter was added in Aukyla 1.1.
	 * @return The email address of the given user.
	 */
	public function userMail($username);

	/**
	 * Returns the IP range from which a user may login.
	 *
	 * @param username Username of the user to get the allowed IP range from.
	 * @return The IP range from which the given user may login.
	 *
	 * @since Aukyla 1.1
	 */
	public function ipRange($username);

	/**
	 * Logs out the current user.
	 */
	public function logout();

	/**
	 * Returns all users available on the system.
	 *
	 * @return An array of strings containing the names of all users.
	 */
	public function users();

	/**
	 * Returns all users in a given group.
	 *
	 * @param  group The group in which to look for users.
	 * @return An array of strings containing the names of all users in the given
	 *         group.
	 *
	 * @since Aukyla 1.1
	 */
	public function usersOfGroup($group);

	/**
	 * Returns all groups available on the system.
	 *
	 * @return An array of strings containing the names of all groups.
	 */
	public function groups();

	/**
	 * Returns all groups of which the given user is a member.
	 *
	 * @param username Username of the user whose member groups to return.
	 *                 This parameter was added in Aukyla 1.1.
	 * @return An array of strings containing the names of all groups the
	 *         given user is a member of.
	 */
	public function memberGroups($username);
}

?>