2 * Copyright © 2010 Codethink Limited
4 * SPDX-License-Identifier: LGPL-2.1-or-later
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
19 * Author: Ryan Lortie <desrt@desrt.ca>
24 #include "gpermission.h"
28 #include "gasyncresult.h"
36 * @short_description: An object representing the permission
37 * to perform a certain action
40 * A #GPermission represents the status of the caller's permission to
41 * perform a certain action.
43 * You can query if the action is currently allowed and if it is
44 * possible to acquire the permission so that the action will be allowed
47 * There is also an API to actually acquire the permission and one to
50 * As an example, a #GPermission might represent the ability for the
51 * user to write to a #GSettings object. This #GPermission object could
52 * then be used to decide if it is appropriate to show a "Click here to
53 * unlock" button in a dialog and to provide the mechanism to invoke
54 * when that button is clicked.
60 * #GPermission is an opaque data structure and can only be accessed
61 * using the following functions.
64 struct _GPermissionPrivate
78 G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GPermission, g_permission, G_TYPE_OBJECT)
81 * g_permission_acquire:
82 * @permission: a #GPermission instance
83 * @cancellable: (nullable): a #GCancellable, or %NULL
84 * @error: a pointer to a %NULL #GError, or %NULL
86 * Attempts to acquire the permission represented by @permission.
88 * The precise method by which this happens depends on the permission
89 * and the underlying authentication mechanism. A simple example is
90 * that a dialog may appear asking the user to enter their password.
92 * You should check with g_permission_get_can_acquire() before calling
95 * If the permission is acquired then %TRUE is returned. Otherwise,
96 * %FALSE is returned and @error is set appropriately.
98 * This call is blocking, likely for a very long time (in the case that
99 * user interaction is required). See g_permission_acquire_async() for
100 * the non-blocking version.
102 * Returns: %TRUE if the permission was successfully acquired
107 g_permission_acquire (GPermission *permission,
108 GCancellable *cancellable,
111 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
112 return G_PERMISSION_GET_CLASS (permission)
113 ->acquire (permission, cancellable, error);
117 * g_permission_acquire_async:
118 * @permission: a #GPermission instance
119 * @cancellable: (nullable): a #GCancellable, or %NULL
120 * @callback: the #GAsyncReadyCallback to call when done
121 * @user_data: the user data to pass to @callback
123 * Attempts to acquire the permission represented by @permission.
125 * This is the first half of the asynchronous version of
126 * g_permission_acquire().
131 g_permission_acquire_async (GPermission *permission,
132 GCancellable *cancellable,
133 GAsyncReadyCallback callback,
136 g_return_if_fail (G_IS_PERMISSION (permission));
137 G_PERMISSION_GET_CLASS (permission)
138 ->acquire_async (permission, cancellable, callback, user_data);
142 * g_permission_acquire_finish:
143 * @permission: a #GPermission instance
144 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
145 * @error: a pointer to a %NULL #GError, or %NULL
147 * Collects the result of attempting to acquire the permission
148 * represented by @permission.
150 * This is the second half of the asynchronous version of
151 * g_permission_acquire().
153 * Returns: %TRUE if the permission was successfully acquired
158 g_permission_acquire_finish (GPermission *permission,
159 GAsyncResult *result,
162 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
163 return G_PERMISSION_GET_CLASS (permission)
164 ->acquire_finish (permission, result, error);
168 * g_permission_release:
169 * @permission: a #GPermission instance
170 * @cancellable: (nullable): a #GCancellable, or %NULL
171 * @error: a pointer to a %NULL #GError, or %NULL
173 * Attempts to release the permission represented by @permission.
175 * The precise method by which this happens depends on the permission
176 * and the underlying authentication mechanism. In most cases the
177 * permission will be dropped immediately without further action.
179 * You should check with g_permission_get_can_release() before calling
182 * If the permission is released then %TRUE is returned. Otherwise,
183 * %FALSE is returned and @error is set appropriately.
185 * This call is blocking, likely for a very long time (in the case that
186 * user interaction is required). See g_permission_release_async() for
187 * the non-blocking version.
189 * Returns: %TRUE if the permission was successfully released
194 g_permission_release (GPermission *permission,
195 GCancellable *cancellable,
198 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
199 return G_PERMISSION_GET_CLASS (permission)
200 ->release (permission, cancellable, error);
204 * g_permission_release_async:
205 * @permission: a #GPermission instance
206 * @cancellable: (nullable): a #GCancellable, or %NULL
207 * @callback: the #GAsyncReadyCallback to call when done
208 * @user_data: the user data to pass to @callback
210 * Attempts to release the permission represented by @permission.
212 * This is the first half of the asynchronous version of
213 * g_permission_release().
218 g_permission_release_async (GPermission *permission,
219 GCancellable *cancellable,
220 GAsyncReadyCallback callback,
223 g_return_if_fail (G_IS_PERMISSION (permission));
224 G_PERMISSION_GET_CLASS (permission)
225 ->release_async (permission, cancellable, callback, user_data);
229 * g_permission_release_finish:
230 * @permission: a #GPermission instance
231 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
232 * @error: a pointer to a %NULL #GError, or %NULL
234 * Collects the result of attempting to release the permission
235 * represented by @permission.
237 * This is the second half of the asynchronous version of
238 * g_permission_release().
240 * Returns: %TRUE if the permission was successfully released
245 g_permission_release_finish (GPermission *permission,
246 GAsyncResult *result,
249 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
250 return G_PERMISSION_GET_CLASS (permission)
251 ->release_finish (permission, result, error);
255 * g_permission_get_allowed:
256 * @permission: a #GPermission instance
258 * Gets the value of the 'allowed' property. This property is %TRUE if
259 * the caller currently has permission to perform the action that
260 * @permission represents the permission to perform.
262 * Returns: the value of the 'allowed' property
267 g_permission_get_allowed (GPermission *permission)
269 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
270 return permission->priv->allowed;
274 * g_permission_get_can_acquire:
275 * @permission: a #GPermission instance
277 * Gets the value of the 'can-acquire' property. This property is %TRUE
278 * if it is generally possible to acquire the permission by calling
279 * g_permission_acquire().
281 * Returns: the value of the 'can-acquire' property
286 g_permission_get_can_acquire (GPermission *permission)
288 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
289 return permission->priv->can_acquire;
293 * g_permission_get_can_release:
294 * @permission: a #GPermission instance
296 * Gets the value of the 'can-release' property. This property is %TRUE
297 * if it is generally possible to release the permission by calling
298 * g_permission_release().
300 * Returns: the value of the 'can-release' property
305 g_permission_get_can_release (GPermission *permission)
307 g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
308 return permission->priv->can_release;
312 * g_permission_impl_update:
313 * @permission: a #GPermission instance
314 * @allowed: the new value for the 'allowed' property
315 * @can_acquire: the new value for the 'can-acquire' property
316 * @can_release: the new value for the 'can-release' property
318 * This function is called by the #GPermission implementation to update
319 * the properties of the permission. You should never call this
320 * function except from a #GPermission implementation.
322 * GObject notify signals are generated, as appropriate.
327 g_permission_impl_update (GPermission *permission,
329 gboolean can_acquire,
330 gboolean can_release)
334 g_return_if_fail (G_IS_PERMISSION (permission));
336 object = G_OBJECT (permission);
337 g_object_freeze_notify (object);
339 allowed = allowed != FALSE;
340 if (allowed != permission->priv->allowed)
342 permission->priv->allowed = allowed;
343 g_object_notify (object, "allowed");
346 can_acquire = can_acquire != FALSE;
347 if (can_acquire != permission->priv->can_acquire)
349 permission->priv->can_acquire = can_acquire;
350 g_object_notify (object, "can-acquire");
353 can_release = can_release != FALSE;
354 if (can_release != permission->priv->can_release)
356 permission->priv->can_release = can_release;
357 g_object_notify (object, "can-release");
360 g_object_thaw_notify (object);
364 g_permission_get_property (GObject *object, guint prop_id,
365 GValue *value, GParamSpec *pspec)
367 GPermission *permission = G_PERMISSION (object);
372 g_value_set_boolean (value, permission->priv->allowed);
375 case PROP_CAN_ACQUIRE:
376 g_value_set_boolean (value, permission->priv->can_acquire);
379 case PROP_CAN_RELEASE:
380 g_value_set_boolean (value, permission->priv->can_release);
384 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
389 g_permission_init (GPermission *permission)
391 permission->priv = g_permission_get_instance_private (permission);
395 acquire_or_release (GPermission *permission,
396 GCancellable *cancellable,
399 g_set_error_literal (error,
400 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
401 "Can't acquire or release permission");
406 acquire_or_release_async (GPermission *permission,
407 GCancellable *cancellable,
408 GAsyncReadyCallback callback,
411 g_task_report_new_error (permission,
414 G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
415 "Can't acquire or release permission");
419 acquire_or_release_finish (GPermission *permission,
420 GAsyncResult *result,
423 return g_task_propagate_boolean (G_TASK (result), error);
427 g_permission_class_init (GPermissionClass *class)
429 GObjectClass *object_class = G_OBJECT_CLASS (class);
431 object_class->get_property = g_permission_get_property;
433 class->acquire = acquire_or_release;
434 class->release = acquire_or_release;
435 class->acquire_async = acquire_or_release_async;
436 class->release_async = acquire_or_release_async;
437 class->acquire_finish = acquire_or_release_finish;
438 class->release_finish = acquire_or_release_finish;
441 * GPermission:allowed:
443 * %TRUE if the caller currently has permission to perform the action that
444 * @permission represents the permission to perform.
446 g_object_class_install_property (object_class, PROP_ALLOWED,
447 g_param_spec_boolean ("allowed",
449 P_("If the caller is allowed to perform the action"),
451 G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
454 * GPermission:can-acquire:
456 * %TRUE if it is generally possible to acquire the permission by calling
457 * g_permission_acquire().
459 g_object_class_install_property (object_class, PROP_CAN_ACQUIRE,
460 g_param_spec_boolean ("can-acquire",
462 P_("If calling g_permission_acquire() makes sense"),
464 G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
467 * GPermission:can-release:
469 * %TRUE if it is generally possible to release the permission by calling
470 * g_permission_release().
472 g_object_class_install_property (object_class, PROP_CAN_RELEASE,
473 g_param_spec_boolean ("can-release",
475 P_("If calling g_permission_release() makes sense"),
477 G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));