2 * Copyright © 2010 Codethink Limited
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.
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.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
19 * Author: Ryan Lortie <desrt@desrt.ca>
24 #include "gpermission.h"
31 * @short_description: An object representing the permission to perform
34 * A #GPermission represents the status of the caller's permission to
35 * perform a certain action.
37 * You can query if the action is currently allowed and if it is
38 * possible to acquire the permission so that the action will be allowed
41 * There is also an API to actually acquire the permission and one to
44 * As an example, a #GPermission might represent the ability for the
45 * user to write to a #GSettings object. This #GPermission object could
46 * then be used to decide if it is appropriate to show a "Click here to
47 * unlock" button in a dialog and to provide the mechanism to invoke
48 * when that button is clicked.
54 * #GPermission is an opaque data structure and can only be accessed
55 * using the following functions.
58 G_DEFINE_ABSTRACT_TYPE (GPermission, g_permission, G_TYPE_OBJECT)
60 struct _GPermissionPrivate
75 * g_permission_acquire:
76 * @permission: a #GPermission instance
77 * @cancellable: a #GCancellable, or %NULL
78 * @error: a pointer to a %NULL #GError, or %NULL
79 * @returns: %TRUE if the permission was successfully acquired
81 * Attempts to acquire the permission represented by @permission.
83 * The precise method by which this happens depends on the permission
84 * and the underlying authentication mechanism. A simple example is
85 * that a dialog may appear asking the user to enter their password.
87 * You should check with g_permission_get_can_acquire() before calling
90 * If the permission is acquired then %TRUE is returned. Otherwise,
91 * %FALSE is returned and @error is set appropriately.
93 * This call is blocking, likely for a very long time (in the case that
94 * user interaction is required). See g_permission_acquire_async() for
95 * the non-blocking version.
100 g_permission_acquire (GPermission *permission,
101 GCancellable *cancellable,
104 return G_PERMISSION_GET_CLASS (permission)
105 ->acquire (permission, cancellable, error);
109 * g_permission_acquire_async:
110 * @permission: a #GPermission instance
111 * @cancellable: a #GCancellable, or %NULL
112 * @callback: the #GAsyncReadyCallback to call when done
113 * @user_data: the user data to pass to @callback
115 * Attempts to acquire the permission represented by @permission.
117 * This is the first half of the asynchronous version of
118 * g_permission_acquire().
123 g_permission_acquire_async (GPermission *permission,
124 GCancellable *cancellable,
125 GAsyncReadyCallback callback,
128 G_PERMISSION_GET_CLASS (permission)
129 ->acquire_async (permission, cancellable, callback, user_data);
133 * g_permission_acquire_finish:
134 * @permission: a #GPermission instance
135 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
136 * @error: a pointer to a %NULL #GError, or %NULL
137 * @returns: %TRUE if the permission was successfully acquired
139 * Collects the result of attempting to acquire the permission
140 * represented by @permission.
142 * This is the second half of the asynchronous version of
143 * g_permission_acquire().
148 g_permission_acquire_finish (GPermission *permission,
149 GAsyncResult *result,
152 return G_PERMISSION_GET_CLASS (permission)
153 ->acquire_finish (permission, result, error);
157 * g_permission_release:
158 * @permission: a #GPermission instance
159 * @cancellable: a #GCancellable, or %NULL
160 * @error: a pointer to a %NULL #GError, or %NULL
161 * @returns: %TRUE if the permission was successfully released
163 * Attempts to release the permission represented by @permission.
165 * The precise method by which this happens depends on the permission
166 * and the underlying authentication mechanism. In most cases the
167 * permission will be dropped immediately without further action.
169 * You should check with g_permission_get_can_release() before calling
172 * If the permission is released then %TRUE is returned. Otherwise,
173 * %FALSE is returned and @error is set appropriately.
175 * This call is blocking, likely for a very long time (in the case that
176 * user interaction is required). See g_permission_release_async() for
177 * the non-blocking version.
182 g_permission_release (GPermission *permission,
183 GCancellable *cancellable,
186 return G_PERMISSION_GET_CLASS (permission)
187 ->release (permission, cancellable, error);
191 * g_permission_release_async:
192 * @permission: a #GPermission instance
193 * @cancellable: a #GCancellable, or %NULL
194 * @callback: the #GAsyncReadyCallback to call when done
195 * @user_data: the user data to pass to @callback
197 * Attempts to release the permission represented by @permission.
199 * This is the first half of the asynchronous version of
200 * g_permission_release().
205 g_permission_release_async (GPermission *permission,
206 GCancellable *cancellable,
207 GAsyncReadyCallback callback,
210 G_PERMISSION_GET_CLASS (permission)
211 ->release_async (permission, cancellable, callback, user_data);
215 * g_permission_release_finish:
216 * @permission: a #GPermission instance
217 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
218 * @error: a pointer to a %NULL #GError, or %NULL
219 * @returns: %TRUE if the permission was successfully released
221 * Collects the result of attempting to release the permission
222 * represented by @permission.
224 * This is the second half of the asynchronous version of
225 * g_permission_release().
230 g_permission_release_finish (GPermission *permission,
231 GAsyncResult *result,
234 return G_PERMISSION_GET_CLASS (permission)
235 ->release_finish (permission, result, error);
239 * g_permission_get_allowed:
240 * @permission: a #GPermission instance
241 * @returns: the value of the 'allowed' property
243 * Gets the value of the 'allowed' property. This property is %TRUE if
244 * the caller currently has permission to perform the action that
245 * @permission represents the permission to perform.
250 g_permission_get_allowed (GPermission *permission)
252 return permission->priv->allowed;
256 * g_permission_get_can_acquire:
257 * @permission: a #GPermission instance
258 * @returns: the value of the 'can-acquire' property
260 * Gets the value of the 'can-acquire' property. This property is %TRUE
261 * if it is generally possible to acquire the permission by calling
262 * g_permission_acquire().
267 g_permission_get_can_acquire (GPermission *permission)
269 return permission->priv->can_acquire;
273 * g_permission_get_can_release:
274 * @permission: a #GPermission instance
275 * @returns: the value of the 'can-release' property
277 * Gets the value of the 'can-release' property. This property is %TRUE
278 * if it is generally possible to release the permission by calling
279 * g_permission_release().
284 g_permission_get_can_release (GPermission *permission)
286 return permission->priv->can_release;
290 * g_permission_impl_update:
291 * @permission: a #GPermission instance
292 * @allowed: the new value for the 'allowed' property
293 * @can_acquire: the new value for the 'can-acquire' property
294 * @can_release: the new value for the 'can-release' property
296 * This function is called by the #GPermission implementation to update
297 * the properties of the permission. You should never call this
298 * function except from a #GPermission implementation.
300 * GObject notify signals are generated, as appropriate.
305 g_permission_impl_update (GPermission *permission,
307 gboolean can_acquire,
308 gboolean can_release)
310 GObject *object = G_OBJECT (permission);
312 g_object_freeze_notify (object);
314 if (allowed != permission->priv->allowed)
316 permission->priv->allowed = !!allowed;
317 g_object_notify (object, "allowed");
320 if (can_acquire != permission->priv->can_acquire)
322 permission->priv->can_acquire = !!can_acquire;
323 g_object_notify (object, "can-acquire");
326 if (can_release != permission->priv->can_release)
328 permission->priv->can_release = !!can_release;
329 g_object_notify (object, "can-release");
332 g_object_thaw_notify (object);
336 g_permission_get_property (GObject *object, guint prop_id,
337 GValue *value, GParamSpec *pspec)
339 GPermission *permission = G_PERMISSION (object);
344 g_value_set_boolean (value, permission->priv->allowed);
347 case PROP_CAN_ACQUIRE:
348 g_value_set_boolean (value, permission->priv->can_acquire);
351 case PROP_CAN_RELEASE:
352 g_value_set_boolean (value, permission->priv->can_release);
356 G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
361 g_permission_init (GPermission *permission)
363 permission->priv = G_TYPE_INSTANCE_GET_PRIVATE (permission,
369 g_permission_class_init (GPermissionClass *class)
371 GObjectClass *object_class = G_OBJECT_CLASS (class);
373 object_class->get_property = g_permission_get_property;
376 * GPermission:allowed:
378 * %TRUE if the caller currently has permission to perform the action that
379 * @permission represents the permission to perform.
381 g_object_class_install_property (object_class, PROP_ALLOWED,
382 g_param_spec_boolean ("allowed",
384 P_("If the caller is allowed to perform the action"),
386 G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
389 * GPermission:can-acquire:
391 * %TRUE if it is generally possible to acquire the permission by calling
392 * g_permission_acquire().
394 g_object_class_install_property (object_class, PROP_CAN_ACQUIRE,
395 g_param_spec_boolean ("can-acquire",
397 P_("If calling g_permission_acquire() makes sense"),
399 G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
402 * GPermission:can-release:
404 * %TRUE if it is generally possible to release the permission by calling
405 * g_permission_release().
407 g_object_class_install_property (object_class, PROP_CAN_RELEASE,
408 g_param_spec_boolean ("can-release",
410 P_("If calling g_permission_release() makes sense"),
412 G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
414 g_type_class_add_private (class, sizeof (GPermissionPrivate));