nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 /*
2 * Copyright © 2010 Codethink Limited
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the licence, or (at your option) any later version.
8 *
9 * This library 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 GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
16 *
17 * Author: Ryan Lortie <desrt@desrt.ca>
18 */
19  
20 #include "config.h"
21  
22 #include "gpermission.h"
23  
24 #include "gioerror.h"
25 #include "gioenums.h"
26 #include "gasyncresult.h"
27 #include "gtask.h"
28 #include "glibintl.h"
29  
30  
31 /**
32 * SECTION:gpermission
33 * @title: GPermission
34 * @short_description: An object representing the permission
35 * to perform a certain action
36 * @include: gio/gio.h
37 *
38 * A #GPermission represents the status of the caller's permission to
39 * perform a certain action.
40 *
41 * You can query if the action is currently allowed and if it is
42 * possible to acquire the permission so that the action will be allowed
43 * in the future.
44 *
45 * There is also an API to actually acquire the permission and one to
46 * release it.
47 *
48 * As an example, a #GPermission might represent the ability for the
49 * user to write to a #GSettings object. This #GPermission object could
50 * then be used to decide if it is appropriate to show a "Click here to
51 * unlock" button in a dialog and to provide the mechanism to invoke
52 * when that button is clicked.
53 **/
54  
55 /**
56 * GPermission:
57 *
58 * #GPermission is an opaque data structure and can only be accessed
59 * using the following functions.
60 **/
61  
62 struct _GPermissionPrivate
63 {
64 gboolean allowed;
65 gboolean can_acquire;
66 gboolean can_release;
67 };
68  
69 enum {
70 PROP_NONE,
71 PROP_ALLOWED,
72 PROP_CAN_ACQUIRE,
73 PROP_CAN_RELEASE
74 };
75  
76 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GPermission, g_permission, G_TYPE_OBJECT)
77  
78 /**
79 * g_permission_acquire:
80 * @permission: a #GPermission instance
81 * @cancellable: (allow-none): a #GCancellable, or %NULL
82 * @error: a pointer to a %NULL #GError, or %NULL
83 *
84 * Attempts to acquire the permission represented by @permission.
85 *
86 * The precise method by which this happens depends on the permission
87 * and the underlying authentication mechanism. A simple example is
88 * that a dialog may appear asking the user to enter their password.
89 *
90 * You should check with g_permission_get_can_acquire() before calling
91 * this function.
92 *
93 * If the permission is acquired then %TRUE is returned. Otherwise,
94 * %FALSE is returned and @error is set appropriately.
95 *
96 * This call is blocking, likely for a very long time (in the case that
97 * user interaction is required). See g_permission_acquire_async() for
98 * the non-blocking version.
99 *
100 * Returns: %TRUE if the permission was successfully acquired
101 *
102 * Since: 2.26
103 */
104 gboolean
105 g_permission_acquire (GPermission *permission,
106 GCancellable *cancellable,
107 GError **error)
108 {
109 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
110 return G_PERMISSION_GET_CLASS (permission)
111 ->acquire (permission, cancellable, error);
112 }
113  
114 /**
115 * g_permission_acquire_async:
116 * @permission: a #GPermission instance
117 * @cancellable: (allow-none): a #GCancellable, or %NULL
118 * @callback: the #GAsyncReadyCallback to call when done
119 * @user_data: the user data to pass to @callback
120 *
121 * Attempts to acquire the permission represented by @permission.
122 *
123 * This is the first half of the asynchronous version of
124 * g_permission_acquire().
125 *
126 * Since: 2.26
127 **/
128 void
129 g_permission_acquire_async (GPermission *permission,
130 GCancellable *cancellable,
131 GAsyncReadyCallback callback,
132 gpointer user_data)
133 {
134 g_return_if_fail (G_IS_PERMISSION (permission));
135 G_PERMISSION_GET_CLASS (permission)
136 ->acquire_async (permission, cancellable, callback, user_data);
137 }
138  
139 /**
140 * g_permission_acquire_finish:
141 * @permission: a #GPermission instance
142 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
143 * @error: a pointer to a %NULL #GError, or %NULL
144 *
145 * Collects the result of attempting to acquire the permission
146 * represented by @permission.
147 *
148 * This is the second half of the asynchronous version of
149 * g_permission_acquire().
150 *
151 * Returns: %TRUE if the permission was successfully acquired
152 *
153 * Since: 2.26
154 **/
155 gboolean
156 g_permission_acquire_finish (GPermission *permission,
157 GAsyncResult *result,
158 GError **error)
159 {
160 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
161 return G_PERMISSION_GET_CLASS (permission)
162 ->acquire_finish (permission, result, error);
163 }
164  
165 /**
166 * g_permission_release:
167 * @permission: a #GPermission instance
168 * @cancellable: (allow-none): a #GCancellable, or %NULL
169 * @error: a pointer to a %NULL #GError, or %NULL
170 *
171 * Attempts to release the permission represented by @permission.
172 *
173 * The precise method by which this happens depends on the permission
174 * and the underlying authentication mechanism. In most cases the
175 * permission will be dropped immediately without further action.
176 *
177 * You should check with g_permission_get_can_release() before calling
178 * this function.
179 *
180 * If the permission is released then %TRUE is returned. Otherwise,
181 * %FALSE is returned and @error is set appropriately.
182 *
183 * This call is blocking, likely for a very long time (in the case that
184 * user interaction is required). See g_permission_release_async() for
185 * the non-blocking version.
186 *
187 * Returns: %TRUE if the permission was successfully released
188 *
189 * Since: 2.26
190 **/
191 gboolean
192 g_permission_release (GPermission *permission,
193 GCancellable *cancellable,
194 GError **error)
195 {
196 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
197 return G_PERMISSION_GET_CLASS (permission)
198 ->release (permission, cancellable, error);
199 }
200  
201 /**
202 * g_permission_release_async:
203 * @permission: a #GPermission instance
204 * @cancellable: (allow-none): a #GCancellable, or %NULL
205 * @callback: the #GAsyncReadyCallback to call when done
206 * @user_data: the user data to pass to @callback
207 *
208 * Attempts to release the permission represented by @permission.
209 *
210 * This is the first half of the asynchronous version of
211 * g_permission_release().
212 *
213 * Since: 2.26
214 **/
215 void
216 g_permission_release_async (GPermission *permission,
217 GCancellable *cancellable,
218 GAsyncReadyCallback callback,
219 gpointer user_data)
220 {
221 g_return_if_fail (G_IS_PERMISSION (permission));
222 G_PERMISSION_GET_CLASS (permission)
223 ->release_async (permission, cancellable, callback, user_data);
224 }
225  
226 /**
227 * g_permission_release_finish:
228 * @permission: a #GPermission instance
229 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
230 * @error: a pointer to a %NULL #GError, or %NULL
231 *
232 * Collects the result of attempting to release the permission
233 * represented by @permission.
234 *
235 * This is the second half of the asynchronous version of
236 * g_permission_release().
237 *
238 * Returns: %TRUE if the permission was successfully released
239 *
240 * Since: 2.26
241 **/
242 gboolean
243 g_permission_release_finish (GPermission *permission,
244 GAsyncResult *result,
245 GError **error)
246 {
247 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
248 return G_PERMISSION_GET_CLASS (permission)
249 ->release_finish (permission, result, error);
250 }
251  
252 /**
253 * g_permission_get_allowed:
254 * @permission: a #GPermission instance
255 *
256 * Gets the value of the 'allowed' property. This property is %TRUE if
257 * the caller currently has permission to perform the action that
258 * @permission represents the permission to perform.
259 *
260 * Returns: the value of the 'allowed' property
261 *
262 * Since: 2.26
263 **/
264 gboolean
265 g_permission_get_allowed (GPermission *permission)
266 {
267 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
268 return permission->priv->allowed;
269 }
270  
271 /**
272 * g_permission_get_can_acquire:
273 * @permission: a #GPermission instance
274 *
275 * Gets the value of the 'can-acquire' property. This property is %TRUE
276 * if it is generally possible to acquire the permission by calling
277 * g_permission_acquire().
278 *
279 * Returns: the value of the 'can-acquire' property
280 *
281 * Since: 2.26
282 **/
283 gboolean
284 g_permission_get_can_acquire (GPermission *permission)
285 {
286 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
287 return permission->priv->can_acquire;
288 }
289  
290 /**
291 * g_permission_get_can_release:
292 * @permission: a #GPermission instance
293 *
294 * Gets the value of the 'can-release' property. This property is %TRUE
295 * if it is generally possible to release the permission by calling
296 * g_permission_release().
297 *
298 * Returns: the value of the 'can-release' property
299 *
300 * Since: 2.26
301 **/
302 gboolean
303 g_permission_get_can_release (GPermission *permission)
304 {
305 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
306 return permission->priv->can_release;
307 }
308  
309 /**
310 * g_permission_impl_update:
311 * @permission: a #GPermission instance
312 * @allowed: the new value for the 'allowed' property
313 * @can_acquire: the new value for the 'can-acquire' property
314 * @can_release: the new value for the 'can-release' property
315 *
316 * This function is called by the #GPermission implementation to update
317 * the properties of the permission. You should never call this
318 * function except from a #GPermission implementation.
319 *
320 * GObject notify signals are generated, as appropriate.
321 *
322 * Since: 2.26
323 **/
324 void
325 g_permission_impl_update (GPermission *permission,
326 gboolean allowed,
327 gboolean can_acquire,
328 gboolean can_release)
329 {
330 GObject *object;
331  
332 g_return_if_fail (G_IS_PERMISSION (permission));
333  
334 object = G_OBJECT (permission);
335 g_object_freeze_notify (object);
336  
337 allowed = allowed != FALSE;
338 if (allowed != permission->priv->allowed)
339 {
340 permission->priv->allowed = allowed;
341 g_object_notify (object, "allowed");
342 }
343  
344 can_acquire = can_acquire != FALSE;
345 if (can_acquire != permission->priv->can_acquire)
346 {
347 permission->priv->can_acquire = can_acquire;
348 g_object_notify (object, "can-acquire");
349 }
350  
351 can_release = can_release != FALSE;
352 if (can_release != permission->priv->can_release)
353 {
354 permission->priv->can_release = can_release;
355 g_object_notify (object, "can-release");
356 }
357  
358 g_object_thaw_notify (object);
359 }
360  
361 static void
362 g_permission_get_property (GObject *object, guint prop_id,
363 GValue *value, GParamSpec *pspec)
364 {
365 GPermission *permission = G_PERMISSION (object);
366  
367 switch (prop_id)
368 {
369 case PROP_ALLOWED:
370 g_value_set_boolean (value, permission->priv->allowed);
371 break;
372  
373 case PROP_CAN_ACQUIRE:
374 g_value_set_boolean (value, permission->priv->can_acquire);
375 break;
376  
377 case PROP_CAN_RELEASE:
378 g_value_set_boolean (value, permission->priv->can_release);
379 break;
380  
381 default:
382 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
383 }
384 }
385  
386 static void
387 g_permission_init (GPermission *permission)
388 {
389 permission->priv = g_permission_get_instance_private (permission);
390 }
391  
392 static gboolean
393 acquire_or_release (GPermission *permission,
394 GCancellable *cancellable,
395 GError **error)
396 {
397 g_set_error_literal (error,
398 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
399 "Can't acquire or release permission");
400 return FALSE;
401 }
402  
403 static void
404 acquire_or_release_async (GPermission *permission,
405 GCancellable *cancellable,
406 GAsyncReadyCallback callback,
407 gpointer user_data)
408 {
409 g_task_report_new_error (permission,
410 callback, user_data,
411 NULL,
412 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
413 "Can't acquire or release permission");
414 }
415  
416 static gboolean
417 acquire_or_release_finish (GPermission *permission,
418 GAsyncResult *result,
419 GError **error)
420 {
421 return g_task_propagate_boolean (G_TASK (result), error);
422 }
423  
424 static void
425 g_permission_class_init (GPermissionClass *class)
426 {
427 GObjectClass *object_class = G_OBJECT_CLASS (class);
428  
429 object_class->get_property = g_permission_get_property;
430  
431 class->acquire = acquire_or_release;
432 class->release = acquire_or_release;
433 class->acquire_async = acquire_or_release_async;
434 class->release_async = acquire_or_release_async;
435 class->acquire_finish = acquire_or_release_finish;
436 class->release_finish = acquire_or_release_finish;
437  
438 /**
439 * GPermission:allowed:
440 *
441 * %TRUE if the caller currently has permission to perform the action that
442 * @permission represents the permission to perform.
443 */
444 g_object_class_install_property (object_class, PROP_ALLOWED,
445 g_param_spec_boolean ("allowed",
446 P_("Is allowed"),
447 P_("If the caller is allowed to perform the action"),
448 FALSE,
449 G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
450  
451 /**
452 * GPermission:can-acquire:
453 *
454 * %TRUE if it is generally possible to acquire the permission by calling
455 * g_permission_acquire().
456 */
457 g_object_class_install_property (object_class, PROP_CAN_ACQUIRE,
458 g_param_spec_boolean ("can-acquire",
459 P_("Can acquire"),
460 P_("If calling g_permission_acquire() makes sense"),
461 FALSE,
462 G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
463  
464 /**
465 * GPermission:can-release:
466 *
467 * %TRUE if it is generally possible to release the permission by calling
468 * g_permission_release().
469 */
470 g_object_class_install_property (object_class, PROP_CAN_RELEASE,
471 g_param_spec_boolean ("can-release",
472 P_("Can release"),
473 P_("If calling g_permission_release() makes sense"),
474 FALSE,
475 G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
476 }