gio/gpermission.c

   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, write to the
  16  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  17  * Boston, MA 02111-1307, USA.
  18  *
  19  * Author: Ryan Lortie <desrt@desrt.ca>
  20  */
  21
  22 #include "config.h"
  23
  24 #include "gpermission.h"
  25 #include "glibintl.h"
  26
  27
  28 /**
  29  * SECTION:gpermission
  30  * @title: GPermission
  31  * @short_description: an object representing the permission to perform
  32  *                     a certain action
  33  *
  34  * A #GPermission represents the status of the caller's permission to
  35  * perform a certain action.
  36  *
  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
  39  * in the future.
  40  *
  41  * There is also an API to actually acquire the permission and one to
  42  * release it.
  43  *
  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.
  49  **/
  50
  51 /**
  52  * GPermission:
  53  *
  54  * #GPermission is an opaque data structure and can only be accessed
  55  * using the following functions.
  56  **/
  57
  58 G_DEFINE_ABSTRACT_TYPE (GPermission, g_permission, G_TYPE_OBJECT)
  59
  60 struct _GPermissionPrivate
  61 {
  62   gboolean allowed;
  63   gboolean can_acquire;
  64   gboolean can_release;
  65 };
  66
  67 enum  {
  68   PROP_NONE,
  69   PROP_ALLOWED,
  70   PROP_CAN_ACQUIRE,
  71   PROP_CAN_RELEASE
  72 };
  73
  74 /**
  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
  80  *
  81  * Attempts to acquire the permission represented by @permission.
  82  *
  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.
  86  *
  87  * You should check with g_permission_get_can_acquire() before calling
  88  * this function.
  89  *
  90  * If the permission is acquired then %TRUE is returned.  Otherwise,
  91  * %FALSE is returned and @error is set appropriately.
  92  *
  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.
  96  *
  97  * Since: 2.26
  98  */
  99 gboolean
 100 g_permission_acquire (GPermission   *permission,
 101                       GCancellable  *cancellable,
 102                       GError       **error)
 103 {
 104   return G_PERMISSION_GET_CLASS (permission)
 105     ->acquire (permission, cancellable, error);
 106 }
 107
 108 /**
 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
 114  *
 115  * Attempts to acquire the permission represented by @permission.
 116  *
 117  * This is the first half of the asynchronous version of
 118  * g_permission_acquire().
 119  *
 120  * Since: 2.26
 121  **/
 122 void
 123 g_permission_acquire_async (GPermission         *permission,
 124                             GCancellable        *cancellable,
 125                             GAsyncReadyCallback  callback,
 126                             gpointer             user_data)
 127 {
 128   G_PERMISSION_GET_CLASS (permission)
 129     ->acquire_async (permission, cancellable, callback, user_data);
 130 }
 131
 132 /**
 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
 138  *
 139  * Collects the result of attempting to acquire the permission
 140  * represented by @permission.
 141  *
 142  * This is the second half of the asynchronous version of
 143  * g_permission_acquire().
 144  *
 145  * Since: 2.26
 146  **/
 147 gboolean
 148 g_permission_acquire_finish (GPermission   *permission,
 149                              GAsyncResult  *result,
 150                              GError       **error)
 151 {
 152   return G_PERMISSION_GET_CLASS (permission)
 153     ->acquire_finish (permission, result, error);
 154 }
 155
 156 /**
 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
 162  *
 163  * Attempts to release the permission represented by @permission.
 164  *
 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.
 168  *
 169  * You should check with g_permission_get_can_release() before calling
 170  * this function.
 171  *
 172  * If the permission is released then %TRUE is returned.  Otherwise,
 173  * %FALSE is returned and @error is set appropriately.
 174  *
 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.
 178  *
 179  * Since: 2.26
 180  **/
 181 gboolean
 182 g_permission_release (GPermission   *permission,
 183                       GCancellable  *cancellable,
 184                       GError       **error)
 185 {
 186   return G_PERMISSION_GET_CLASS (permission)
 187     ->release (permission, cancellable, error);
 188 }
 189
 190 /**
 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
 196  *
 197  * Attempts to release the permission represented by @permission.
 198  *
 199  * This is the first half of the asynchronous version of
 200  * g_permission_release().
 201  *
 202  * Since: 2.26
 203  **/
 204 void
 205 g_permission_release_async (GPermission         *permission,
 206                             GCancellable        *cancellable,
 207                             GAsyncReadyCallback  callback,
 208                             gpointer             user_data)
 209 {
 210   G_PERMISSION_GET_CLASS (permission)
 211     ->release_async (permission, cancellable, callback, user_data);
 212 }
 213
 214 /**
 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
 220  *
 221  * Collects the result of attempting to release the permission
 222  * represented by @permission.
 223  *
 224  * This is the second half of the asynchronous version of
 225  * g_permission_release().
 226  *
 227  * Since: 2.26
 228  **/
 229 gboolean
 230 g_permission_release_finish (GPermission   *permission,
 231                              GAsyncResult  *result,
 232                              GError       **error)
 233 {
 234   return G_PERMISSION_GET_CLASS (permission)
 235     ->release_finish (permission, result, error);
 236 }
 237
 238 /**
 239  * g_permission_get_allowed:
 240  * @permission: a #GPermission instance
 241  * @returns: the value of the 'allowed' property
 242  *
 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.
 246  *
 247  * Since: 2.26
 248  **/
 249 gboolean
 250 g_permission_get_allowed (GPermission *permission)
 251 {
 252   return permission->priv->allowed;
 253 }
 254
 255 /**
 256  * g_permission_get_can_acquire:
 257  * @permission: a #GPermission instance
 258  * @returns: the value of the 'can-acquire' property
 259  *
 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().
 263  *
 264  * Since: 2.26
 265  **/
 266 gboolean
 267 g_permission_get_can_acquire (GPermission *permission)
 268 {
 269   return permission->priv->can_acquire;
 270 }
 271
 272 /**
 273  * g_permission_get_can_release:
 274  * @permission: a #GPermission instance
 275  * @returns: the value of the 'can-release' property
 276  *
 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().
 280  *
 281  * Since: 2.26
 282  **/
 283 gboolean
 284 g_permission_get_can_release (GPermission *permission)
 285 {
 286   return permission->priv->can_release;
 287 }
 288
 289 /**
 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
 295  *
 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.
 299  *
 300  * GObject notify signals are generated, as appropriate.
 301  *
 302  * Since: 2.26
 303  **/
 304 void
 305 g_permission_impl_update (GPermission *permission,
 306                           gboolean     allowed,
 307                           gboolean     can_acquire,
 308                           gboolean     can_release)
 309 {
 310   GObject *object = G_OBJECT (permission);
 311
 312   g_object_freeze_notify (object);
 313
 314   if (allowed != permission->priv->allowed)
 315     {
 316       permission->priv->allowed = !!allowed;
 317       g_object_notify (object, "allowed");
 318     }
 319
 320   if (can_acquire != permission->priv->can_acquire)
 321     {
 322       permission->priv->can_acquire = !!can_acquire;
 323       g_object_notify (object, "can-acquire");
 324     }
 325
 326   if (can_release != permission->priv->can_release)
 327     {
 328       permission->priv->can_release = !!can_release;
 329       g_object_notify (object, "can-release");
 330     }
 331
 332   g_object_thaw_notify (object);
 333 }
 334
 335 static void
 336 g_permission_get_property (GObject *object, guint prop_id,
 337                            GValue *value, GParamSpec *pspec)
 338 {
 339   GPermission *permission = G_PERMISSION (object);
 340
 341   switch (prop_id)
 342     {
 343     case PROP_ALLOWED:
 344       g_value_set_boolean (value, permission->priv->allowed);
 345       break;
 346
 347     case PROP_CAN_ACQUIRE:
 348       g_value_set_boolean (value, permission->priv->can_acquire);
 349       break;
 350
 351     case PROP_CAN_RELEASE:
 352       g_value_set_boolean (value, permission->priv->can_release);
 353       break;
 354
 355     default:
 356       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 357   }
 358 }
 359
 360 static void
 361 g_permission_init (GPermission *permission)
 362 {
 363   permission->priv = G_TYPE_INSTANCE_GET_PRIVATE (permission,
 364                                                   G_TYPE_PERMISSION,
 365                                                   GPermissionPrivate);
 366 }
 367
 368 static void
 369 g_permission_class_init (GPermissionClass *class)
 370 {
 371   GObjectClass *object_class = G_OBJECT_CLASS (class);
 372
 373   object_class->get_property = g_permission_get_property;
 374
 375   /**
 376    * GPermission:allowed:
 377    *
 378    * %TRUE if the caller currently has permission to perform the action that
 379    * @permission represents the permission to perform.
 380    */
 381    g_object_class_install_property (object_class, PROP_ALLOWED,
 382      g_param_spec_boolean ("allowed",
 383                            P_("Is allowed"),
 384                            P_("If the caller is allowed to perform the action"),
 385                            FALSE,
 386                            G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
 387
 388   /**
 389    * GPermission:can-acquire:
 390    *
 391    * %TRUE if it is generally possible to acquire the permission by calling
 392    * g_permission_acquire().
 393    */
 394    g_object_class_install_property (object_class, PROP_CAN_ACQUIRE,
 395      g_param_spec_boolean ("can-acquire",
 396                            P_("Can acquire"),
 397                            P_("If calling g_permission_acquire() makes sense"),
 398                            FALSE,
 399                            G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
 400
 401   /**
 402    * GPermission:can-release:
 403    *
 404    * %TRUE if it is generally possible to release the permission by calling
 405    * g_permission_release().
 406    */
 407    g_object_class_install_property (object_class, PROP_CAN_RELEASE,
 408      g_param_spec_boolean ("can-release",
 409                            P_("Can release"),
 410                            P_("If calling g_permission_release() makes sense"),
 411                            FALSE,
 412                            G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
 413
 414   g_type_class_add_private (class, sizeof (GPermissionPrivate));
 415 }