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