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