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) 2020 (original work) Open Assessment Technologies SA ;
19	*/
20
21	declare(strict_types=1);
22
23	namespace oat\taoQtiTest\models\runner\time;
24
25	use oat\taoQtiTest\models\runner\session\TestSession;
26	use qtism\common\datatypes\QtiDuration;
27	use qtism\data\QtiIdentifiable;
28
29	/**
30	* Interface TimerAdjustmentInterface
31	*
32	* @package oat\taoTests\models\runner\time
33	*/
34	interface TimerAdjustmentServiceInterface
35	{
36	public const SERVICE_ID = 'taoQtiTest/TimerAdjustment';
37
38	public const TYPE_TIME_ADJUSTMENT = 'timeAdjustment';
39	public const TYPE_EXTENDED_TIME = 'extendedTime';
40
41	/**
42	* Increases allotted time by supplied amount of seconds
43	* @param TestSession $testSession
44	* @param int $seconds
45	* @param string $type
46	* @param QtiIdentifiable $source
47	* @return bool
48	*/
49	public function increase(
50	TestSession $testSession,
51	int $seconds,
52	string $type,
53	QtiIdentifiable $source = null
54	): bool;
55
56	/**
57	* Decreases allotted time by supplied amount of seconds
58	* @param TestSession $testSession
59	* @param int $seconds
60	* @param string $type
61	* @param QtiIdentifiable $source
62	* @return bool
63	*/
64	public function decrease(
65	TestSession $testSession,
66	int $seconds,
67	string $type,
68	QtiIdentifiable $source = null
69	): bool;
70
71	/**
72	* Finds adjusted max time limit for a given test component
73	* @param QtiIdentifiable $source
74	* @param QtiTimer $timer
75	* @return QtiDuration|null
76	*/
77	public function getAdjustedMaxTime(
78	QtiIdentifiable $source,
79	QtiTimer $timer
80	): ?QtiDuration;
81
82	/**
83	* Get adjusted seconds
84	* @param QtiIdentifiable $source
85	* @param QtiTimer $qtiTimer
86	* @return int
87	*/
88	public function getAdjustment(QtiIdentifiable $source, QtiTimer $qtiTimer): int;
89
90	/**
91	* Get adjusted time by adjustment type in seconds
92	*
93	* @param QtiIdentifiable $source
94	* @param QtiTimer $timer
95	* @param string|null $adjustmentType
96	* @return int
97	*/
98	public function getAdjustmentByType(QtiIdentifiable $source, QtiTimer $timer, ?string $adjustmentType = null): int;
99	}