1	<?php
2
3	/**
4	* This program is free software; you can redistribute it and/or
5	* modify it under the terms of the GNU General Public License
6	* as published by the Free Software Foundation; under version 2
7	* of the License (non-upgradable).
8	*
9	* This program is distributed in the hope that it will be useful,
10	* but WITHOUT ANY WARRANTY; without even the implied warranty of
11	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12	* GNU General Public License for more details.
13	*
14	* You should have received a copy of the GNU General Public License
15	* along with this program; if not, write to the Free Software
16	* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
17	*
18	* Copyright (c) 2002-2008 (original work) Public Research Centre Henri Tudor & University of Luxembourg
19	*                         (under the project TAO & TAO2);
20	*               2008-2010 (update and modification) Deutsche Institut für Internationale Pädagogische Forschung
21	*                         (under the project TAO-TRANSFER);
22	*               2009-2012 (update and modification) Public Research Centre Henri Tudor
23	*                         (under the project TAO-SUSTAIN & TAO-DEV);
24	*
25	*/
26
27	/**
28	* Short description of class core_kernel_users_UsersManagement
29	*
30	* @access public
31	* @author Jerome Bogaerts, <jerome.bogaerts@tudor.lu>
32	* @package generis
33
34	*/
35	interface core_kernel_users_UsersManagement
36	{
37	// --- OPERATIONS ---
38
39	/**
40	* Returns true if the a user with login = $login is currently in the
41	* memory of Generis.
42	*
43	* @access public
44	* @author Jerome Bogaerts, <jerome.bogaerts@tudor.lu>
45	* @param  string login A string that is used as a Generis user login in the persistent memory.
46	* @param  Class class A specific sub class of User where the login must be searched into.
47	* @return boolean
48	*/
49	public function loginExists($login, core_kernel_classes_Class $class = null);
50
51	/**
52	* Create a new Generis User with a specific Role. If the $role is not
53	* the user will be given the Generis Role.
54	*
55	* @access public
56	* @author Jerome Bogaerts, <jerome.bogaerts@tudor.lu>
57	* @param  string login A specific login for the User to create.
58	* @param  string password A password for the User to create (md5 hash).
59	* @param  Resource role A Role to grant to the new User.
60	* @return core_kernel_classes_Resource
61	*/
62	public function addUser($login, $password, core_kernel_classes_Resource $role = null);
63
64	/**
65	* Remove a Generis User from persistent memory. Bound roles will remain
66	*
67	* @access public
68	* @author Jerome Bogaerts, <jerome.bogaerts@tudor.lu>
69	* @param  Resource user A reference to the User to be removed from the persistent memory of Generis.
70	* @return boolean
71	*/
72	public function removeUser(core_kernel_classes_Resource $user);
73
74	/**
75	* Get a specific Generis User from the persistent memory of Generis that
76	* a specific login. If multiple users have the same login, a UserException
77	* be thrown.
78	*
79	* @access public
80	* @author Jerome Bogaerts, <jerome.bogaerts@tudor.lu>
81	* @param  string login A Generis User login.
82	* @param  Class class A specific sub Class of User where in the User has to be searched in.
83	* @return core_kernel_classes_Resource
84	*/
85	public function getOneUser($login, core_kernel_classes_Class $class = null);
86
87	/**
88	* Indicates if an Authenticated Session is open.
89	*
90	* @access public
91	* @author Jerome Bogaerts, <jerome.bogaerts@tudor.lu>
92	* @return boolean
93	*/
94	public function isASessionOpened();
95
96	/**
97	* used in conjunction with the callback validator
98	* to test the pasword entered
99	*
100	* @access public
101	* @author Jerome Bogaerts, <jerome.bogaerts@tudor.lu>
102	* @param  string password used in conjunction with the callback validator
103	to test the pasword entered
104	* @param  Resource user used in conjunction with the callback validator
105	to test the pasword entered
106	* @return boolean
107	*/
108	public function isPasswordValid($password, core_kernel_classes_Resource $user);
109
110	/**
111	* Set the password of a specifc user.
112	*
113	* @access public
114	* @author Jerome Bogaerts, <jerome.bogaerts@tudor.lu>
115	* @param  Resource user The user you want to set the password.
116	* @param  string password The md5 hash of the password you want to set to the user.
117	* @return void
118	*/
119	public function setPassword(core_kernel_classes_Resource $user, $password);
120
121	/**
122	* Get the roles that a given user has.
123	*
124	* @access public
125	* @author Jerome Bogaerts, <jerome.bogaerts@tudor.lu>
126	* @param  Resource user A Generis User.
127	* @return array
128	*/
129	public function getUserRoles(core_kernel_classes_Resource $user);
130
131	/**
132	* Indicates if a user is granted with a set of Roles.
133	*
134	* @access public
135	* @author Jerome Bogaerts, <jerome.bogaerts@tudor.lu>
136	* @param  Resource user The User instance you want to check Roles.
137	* @param  roles Can be either a single Resource or an array of Resource depicting Role(s).
138	* @return boolean
139	*/
140	public function userHasRoles(core_kernel_classes_Resource $user, $roles);
141
142	/**
143	* Attach a Generis Role to a given Generis User. A UserException will be
144	* if an error occurs. If the User already has the role, nothing happens.
145	*
146	* @access public
147	* @author Jerome Bogaerts, <jerome.bogaerts@tudor.lu>
148	* @param  Resource user The User you want to attach a Role.
149	* @param  Resource role A Role to attach to a User.
150	* @return void
151	*/
152	public function attachRole(core_kernel_classes_Resource $user, core_kernel_classes_Resource $role);
153
154	/**
155	* Short description of method unnatachRole
156	*
157	* @access public
158	* @author Jerome Bogaerts, <jerome.bogaerts@tudor.lu>
159	* @param  Resource user A Generis user from which you want to unnattach the Generis Role.
160	* @param  Resource role The Generis Role you want to Unnatach from the Generis User.
161	* @return void
162	*/
163	public function unnatachRole(core_kernel_classes_Resource $user, core_kernel_classes_Resource $role);
164
165	/**
166	* Returns an array of Roles (as Resources) where keys are their URIs. The
167	* roles represent which kind of Roles are accepted to be identified against
168	* system.
169	*
170	* @access public
171	* @author Jerome Bogaerts, <jerome@taotesting.com>
172	* @return array
173	*/
174	public function getAllowedRoles();
175	/**
176	* Returns a Role (as a Resource) which represents the default role of the
177	* If a user has to be created but no Role is given to him, it will receive
178	* role.
179	*
180	* @access public
181	* @author Jerome Bogaerts, <jerome@taotesting.com>
182	* @return core_kernel_classes_Resource
183	*/
184	public function getDefaultRole();
185	}