1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright 2024, 2025 GNOME Foundation, Inc.
SPDX-License-Identifier: LGPL-2.1-or-later
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.
This library 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
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Authors:
- Philip Withnall <pwithnall@gnome.org>
-->
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node name="/">
<!--
org.freedesktop.MalcontentTimer1.Child:
@short_description: Interface for recording screen time and app usage by
a child user account
The `MalcontentTimer1.Child` interface allows a trusted component in a
child user account’s session to record screen time and app usage periods
for that account, to query the time remaining before the limit is reached,
and to request extensions to the screen time limits. Such a component
might be the shell process of the session, for example.
Data is recorded as tuples of
(start time, end time, record type, identifier), where the record type is
one of the following well-known values:
* `login-session`: The user’s login session. No associated identifier.
* `app`: Usage of an app. The app identifier (its reverse-DNS name) is
associated.
Each record should have an identifier in the format stipulated by its
record type, or the empty string.
Overlapping time spans for the same (record type, identifier) will be
merged. Times are given as wall clock seconds (i.e. Unix timestamps), and
the end time of a tuple must never be before the start time. The start and
end time of a tuple can be equal to represent an interval of one second,
i.e. end times are inclusive.
Records submitted with an unknown record type, or an invalid identifier,
will be rejected with error
`org.freedesktop.MalcontentTimer1.Child.Error.InvalidRecord`.
This documentation describes version 1 of this interface.
-->
<interface name="org.freedesktop.MalcontentTimer1.Child">
<!--
RecordUsage:
@usage_entries: Array of one or more usage entries to record, with each
entry in the form (start time, end time, record type, identifier).
Records one or more usage entries for the child account which is running
the calling process. The entries do not have to be related or
continuous; the ability to submit multiple entries at once is purely a
performance optimisation.
If any of the records are invalid, none of the records will be saved,
and `org.freedesktop.MalcontentTimer1.Child.Error.InvalidRecord` will be
returned.
-->
<method name="RecordUsage">
<arg type="a(ttss)" name="usage_entries" direction="in"/>
</method>
<!--
GetEstimatedTimes:
@record_type: Record type to query the time estimates for
@now_secs: Time the daemon considered to be ‘now’ when calculating times
@times_secs: Potentially empty map from identifier to tuple of
estimated times
Queries for the estimated start and end times of all the limits set for
this child account for the given @record_type. The child account is the
one which is running the calling process.
For example, if called with a @record_type of `login-session`, this
would return a map with a single entry mapping the empty string to a
tuple of whether the limit has been reached today, the start and
estimated end time of the current (or most recent) login session, and
the next login session. Times are calculated from the amount of time the
child account has spent active on the login session so far (up to
@now_secs), versus their configured computer use time limit. If no limit
applies, there is no entry in the map.
If called with a @record_type of `app`, this would return a map with
an entry for each app where a limit has been applied to the child’s use
of it, mapping the app ID to a tuple of the estimated time when the
child would use up their time allowance, and the time the app was
started (just as with login sessions). The estimate assumes the child
uses each app non-stop from now onwards.
-->
<method name="GetEstimatedTimes">
<arg type="s" name="record_type" direction="in"/>
<arg type="t" name="now_secs" direction="out"/>
<arg type="a{s(btttt)}" name="times_secs" direction="out"/>
</method>
<!--
EstimatedTimesChanged:
Emitted when one or more of the end times returned by a call to
org.freedesktop.MalcontentTimer1.Child.GetEstimatedTimes() has
potentially changed.
The updated estimates cannot be included in the signal arguments, as
then they’d be broadcast across the bus, potentially to other users.
In order to avoid the service having to maintain state about which bus
connections belong to which user, the signal is therefore kept
stateless.
-->
<signal name="EstimatedTimesChanged"/>
<!--
RequestExtension:
@record_type: Record type to request an extension for
@identifier: Identifier to request an extension for
@duration_secs: Duration of the extension being requested, in seconds,
or zero to indicate the duration be chosen by the parent
@extra_data: Potentially empty dictionary of additional data for the
request
@cookie: Cookie to uniquely identify the extension request — this is in
an arbitrary format which should not be parsed, but which is
guaranteed to be non-empty
Requests an extension to the screen time limit for the calling user,
for the given @record_type and @identifier.
When a decision is available about the request, the `ExtensionResponse`
signal will be emitted with the cookie returned in @cookie. In order to
avoid race conditions in listening for this signal, the calling process
must subscribe to matching signals _before_ calling this method.
Currently there are no supported keys for @extra_data. Unsupported keys
will be ignored.
If @record_type or @identifier are invalid,
`org.freedesktop.MalcontentTimer1.Child.Error.InvalidRecord` will be
returned.
If the request is cancelled before a response is received,
`org.freedesktop.MalcontentTimer1.Child.Error.RequestCancelled` will be
returned.
If the calling user can’t be identified,
`org.freedesktop.MalcontentTimer1.Child.Error.IdentifyingUser` will be
returned.
`org.freedesktop.MalcontentTimer1.Child.Error.CommunicatingWithAgent`
may be returned if there are internal errors.
-->
<method name="RequestExtension">
<arg type="s" name="record_type" direction="in"/>
<arg type="s" name="identifier" direction="in"/>
<arg type="t" name="duration_secs" direction="in"/>
<arg type="a{sv}" name="extra_data" direction="in"/>
<!-- This has type `o` not because we currently use it as a path, but just to give ourselves the option to expand it to a full object in future if needed: -->
<arg type="o" name="cookie" direction="out"/>
</method>
<!--
ExtensionResponse:
@granted: Whether the request was granted
@cookie: Cookie to match the signal to a previous `RequestExtension()`
call
@extra_data: Potentially empty dictionary of additional data from the
response
Emitted when a decision has been made about an extension request made
using `RequestExtension()`, or the extension request was cancelled.
If the extension request is granted, `EstimatedTimesChanged` will be
emitted as well to indicate the updated time limits, which should then
be queried by calling `GetEstimatedTimes()`.
This will be emitted exactly once for each successful call to
`RequestExtension()`. It will not be emitted if `RequestExtension()`
returned an error. It can be thought of as a reply to the
`RequestExtension()` call, but it cannot be implemented as a reply
because it may take many minutes to get a response to an extension
request (as the parent has to think about it) and a method reply might
time out.
The @cookie matches the cookie returned from the `RequestExtension()`
call.
Currently the supported keys for @extra_data are as below. Unsupported
keys must be ignored.
* `error-name`: A D-Bus error name describing the error, if the
request failed due to an error.
-->
<signal name="ExtensionResponse">
<arg type="b" name="granted"/>
<arg type="o" name="cookie"/>
<arg type="a{sv}" name="extra_data"/>
</signal>
</interface>
</node>
|
