<?php
/* $Id$ */
namespace MCMS\Plugin;

(defined('MCMS') && (basename(__FILE__) != basename($_SERVER['PHP_SELF']))) or die('ACCESS DENIED');

use MCMS\User\iAuthListener;
use MCMS\User\iUser;
use MCMS\User\iGroup;
use MCMS\User\iRole;

/**
 * Authentication plugin interface
 *
 * @author Stefan Daurer <s.daurer@q-spot.org>
 * @package MCMS\System\Plugin
 * @since 1.0.1.0
 */
interface iPlugInAuth extends iPlugIn {
	/**
	 * Plugin can create users.
	 */
	const FEATURE_CREATE_USER = 1;
	/**
	 * Plugin can update users.
	 */
	const FEATURE_UPDATE_USER = 2;
	/**
	 * Plugin can change user password.
	 */
	const FEATURE_CHPASS_USER = 4;
	/**
	 * Plugin can delete users.
	 */
	const FEATURE_DELETE_USER = 8;
	/**
	 * Plugin can alter login name.
	 */
	const FEATURE_ALTER_LOGIN = 16;
	/**
	 * Plugin can create groups.
	 */
	const FEATURE_CREATE_GROUP = 128;
	/**
	 * Plugin can update groups.
	 */
	const FEATURE_UPDATE_GROUP = 256;
	/**
	 * Plugin can modify group members.
	 */
	const FEATURE_UPDATE_GROUPMEMBER = 512;
	/**
	 * Plugin can delete groups.
	 */
	const FEATURE_DELETE_GROUP = 1024;
	/**
	 * Object is hidden (not searchable)
	 */
	const ATT_TYPE_HIDDEN = 1;
	/**
	 * Object is a system object
	 */
	const ATT_TYPE_SYS = 128;
	
	/**
	 * Add an authentication listener to the plugin.
	 *
	 * @param iAuthListener $listener        	
	 */
	public function addAuthListener(iAuthListener $listener);

	/**
	 * Removes an authentication listener from the plugin.
	 *
	 * @param iAuthListener $listener        	
	 */
	public function removeAuthListener(iAuthListener $listener);

	/**
	 * Returns a list of all registered auth listener.
	 */
	public function getAuthListener();

	/**
	 * Remove all auth listener.
	 */
	public function clearAuthListener();

	/**
	 * Try to authenticate a user on this authentication plugin.
	 *
	 * @return iUser the user on success, integer error code if login failed
	 */
	public function loginUser($login, $password, $lifetime = 0);

	/**
	 * Destroys the user session of an active user.
	 */
	public function logoutUser();

	/**
	 * Provides a list of attributes avaible for user objects.
	 *
	 * @param $type int
	 *        	A bitmask that defines what kind of attributes will be returned. By default, only
	 *        	public attributes are returned.
	 * @return array An array which describes the attributes. Keys are the names, while the values are the datatype.
	 */
	public function getUserAttrKeys($type = 0);
	/**
	 * Provides a list of attributes avaible for group objects.
	 *
	 * @param $type int
	 *        	A bitmask that defines what kind of attributes will be returned. By default, only
	 *        	public attributes are returned.
	 * @return array An array which describes the attributes. Keys are the names, while the values are the datatype.
	 */
	public function getGroupAttrKeys($type = 0);
	
	/**
	 * Creates a new user in the database.
	 *
	 * @return iUser the updated user object which represent the new user
	 */
	public function createUser(iUser $user);

	/**
	 * Fetches a user from the data storage.
	 * 
	 * If the user could not be found, the method returns null.
	 *
	 * @param $id mixed
	 *        	login string or the user id integer, use (int) -1 or empty to get the current user
	 * @return iUser the user specified or null if none is found or none was logged in
	 */
	public function getUser($id = -1);

	public function getUserList(array $filer = array());

	/**
	 *
	 * @param array $id
	 *        	a list of group ids of the groups this user is member of
	 */
	public function getUserGroups($id);

	public function setUserPasswd($newPasswd, $id = -1);

	public function setUserAttr($id, $attrname, $value);

	public function getUserAttr($id, $attrname);

	public function removeUser(iUser $user);

	public function createGroup(iGroup $group);

	public function getGroup($id);

	public function getGroupList(array $filer = array());

	/**
	 * Fetches the group member ids.
	 * 
	 * This method searches for all the nummeric user ids of the members of a group and returns them as an array.
	 * 
	 * @param $id mixed
	 *        	a group id or object
	 * @return array a list of user ids of group members
	 */
	public function getGroupMembers($id);

	public function updateGroup(iGroup $group);

	public function removeGroup(iGroup $group);

	/**
	 * Grant privileges to a user.
	 * 
	 * @param iUser $usr
	 * @param integer $siteId
	 * @param string $instance
	 * @param string $key
	 * @param string $value
	 */
	public function userGrantPriv(iUser $usr, $siteId, $instance, $key, $value = null);

	/**
	 * Checks if an user has a privilege.
	 *
	 * If no additional value is set or $siteId is null, it checks for the global masteradmin status only.
	 * If only the $siteId is set, it checks for the global masteradmin of this page.
	 * The fields $instance and $key must be set both or none and enable instance privilege checking.
	 * The $strict flag defines the checking on the object only (true), or the object and its groups (false).
	 *
	 * @param iUser $usr
	 *        	user object
	 * @param integer $siteId
	 *        	the site id to check
	 * @param string $instance
	 *        	the instance id to check
	 * @param string $key
	 *        	the privilege key to check
	 * @param boolean $strict
	 *        	enable/disable strict privilege checking
	 */
	public function userHasPriv(iUser $usr, $siteId = null, $instance = false, $key = false, $strict = false);
	
	/**
	 * Checks if an user has an admin interface privilege.
	 */
	public function userHasAdminPriv(iUser $usr, $siteId = null, $instance = false, $key = false, $strict = false);
	
	/**
	 * Removes all privileges from a user.
	 * 
	 * If $siteId is null, than this method removes ALL privileges defined for the user.
	 * 
	 * @param iUser $usr
	 *        	user object
	 * @param integer $siteId
	 *        	a valid site id or null
	 */
	public function userClearPriv(iUser $usr, $siteId = null);

	/**
	 * Grant privileges to a group.
	 * 
	 * @param iGroup $grp
	 * @param integer $siteId
	 * @param string $instance
	 * @param string $key
	 * @param string $value
	 */
	public function groupGrantPriv(iGroup $grp, $siteId, $instance, $key, $value = null);

	/**
	 * Checks if an group has a privilege.
	 *
	 * If no additional value is set or $siteId is null, it checks for the global masteradmin status only.
	 * If only the $siteId is set, it checks for the global masteradmin of this page.
	 * The fields $instance and $key must be set both or none and enable instance privilege checking.
	 * The $strict flag defines the checking on the object only (true), or the object and its subgroups (false, if supported) .
	 *
	 * @param iGroup $grp
	 *        	group object
	 * @param integer $siteId
	 *        	the site id to check
	 * @param string $instance
	 *        	the instance id to check
	 * @param string $key
	 *        	the privilege key to check
	 * @param boolean $strict
	 *        	enable/disable strict privilege checking
	 */
	public function groupHasPriv(iGroup $grp, $siteId = null, $instance = false, $key = false, $strict = false);

	/**
	 * Removes all privileges from a group.
	 * 
	 * If $siteId is null, than this method removes ALL privileges defined for the group. 
	 * 
	 * @param iGroup $grp
	 *        	group object
	 * @param integer $siteId
	 *        	a valid site id or null
	 */
	public function groupClearPriv(iGroup $grp, $siteId = null);
	
	/**
	 * Grant privileges to a role.
	 * 
	 * @param iRole $role
	 * @param integer $siteId
	 * @param string $instance
	 * @param string $key
	 * @param string $value
	 */
	public function roleGrantPriv(iRole $role, $siteId, $instance, $key, $value = null);
	
	/**
	 * Checks if an group has a privilege.
	 *
	 * If no additional value is set or $siteId is null, it checks for the global masteradmin status only.
	 * If only the $siteId is set, it checks for the global masteradmin of this page.
	 * The fields $instance and $key must be set both or none and enable instance privilege checking.
	 * The $strict flag defines the checking on the object only (true), or the object and its subgroups (false, if supported) .
	 *
	 * @param iRole $role
	 *        	role object
	 * @param integer $siteId
	 *        	the site id to check
	 * @param string $instance
	 *        	the instance id to check
	 * @param string $key
	 *        	the privilege key to check
	 * @param boolean $strict
	 *        	enable/disable strict privilege checking
	*/
	public function roleHasPriv(iRole $role, $siteId = null, $instance = false, $key = false, $strict = false);
	
	/**
	 * Removes all privileges from a group.
	 * 
	 * If $siteId is null, than this method removes ALL privileges defined for the group.
	 * 
	 * @param iRole $role
	 *        	role object
	 * @param integer $siteId
	 *        	a valid site id or null
	*/
	public function roleClearPriv(iRole $role, $siteId = null);
	
	/**
	 * Fetches a bitmask of allowed user/group manipulation features of the plugin.
	 * Those features are defined by the FEATURE_* constants.
	 *
	 * @return int the bitmask
	 */
	public function getUserEditOptions();

	/**
	 * Fetches a bitmask of allowed user/group manipulation features of the plugin.
	 * Those features are defined by the FEATURE_* constants.
	 *
	 * @return int the bitmask
	 */
	public function getGroupEditOptions();
}