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 #include "gioalias.h"
  28
  29 /**
  30  * SECTION:gpermission
  31  * @title: GPermission
  32  * @short_description: an object representing the permission to perform
  33  *                     a certain action
  34  *
  35  * A #GPermission represents the status of the caller's permission to
  36  * perform a certain action.
  37  *
  38  * You can query if the action is currently allowed and if it is
  39  * possible to acquire the permission so that the action will be allowed
  40  * in the future.
  41  *
  42  * There is also an API to actually acquire the permission and one to
  43  * release it.
  44  *
  45  * As an example, a #GPermission might represent the ability for the
  46  * user to write to a #GSettings object.  This #GPermission object could
  47  * then be used to decide if it is appropriate to show a "Click here to
  48  * unlock" button in a dialog and to provide the mechanism to invoke
  49  * when that button is clicked.
  50  **/
  51
  52 /**
  53  * GPermission:
  54  *
  55  * #GPermission is an opaque data structure and can only be accessed
  56  * using the following functions.
  57  **/
  58
  59 G_DEFINE_ABSTRACT_TYPE (GPermission, g_permission, G_TYPE_OBJECT)
  60
  61 struct _GPermissionPrivate
  62 {
  63   gboolean allowed;
  64   gboolean can_acquire;
  65   gboolean can_release;
  66 };
  67
  68 enum  {
  69   PROP_NONE,
  70   PROP_ALLOWED,
  71   PROP_CAN_ACQUIRE,
  72   PROP_CAN_RELEASE
  73 };
  74
  75 /**
  76  * g_permission_acquire:
  77  * @permission: a #GPermission instance
  78  * @cancellable: a #GCancellable, or %NULL
  79  * @error: a pointer to a %NULL #GError, or %NULL
  80  * @returns: %TRUE if the permission was successfully acquired
  81  *
  82  * Attempts to acquire the permission represented by @permission.
  83  *
  84  * The precise method by which this happens depends on the permission
  85  * and the underlying authentication mechanism.  A simple example is
  86  * that a dialog may appear asking the user to enter their password.
  87  *
  88  * You should check with g_permission_get_can_acquire() before calling
  89  * this function.
  90  *
  91  * If the permission is acquired then %TRUE is returned.  Otherwise,
  92  * %FALSE is returned and @error is set appropriately.
  93  *
  94  * This call is blocking, likely for a very long time (in the case that
  95  * user interaction is required).  See g_permission_acquire_async() for
  96  * the non-blocking version.
  97  *
  98  * Since: 2.26
  99  */
 100 gboolean
 101 g_permission_acquire (GPermission   *permission,
 102                       GCancellable  *cancellable,
 103                       GError       **error)
 104 {
 105   return G_PERMISSION_GET_CLASS (permission)
 106     ->acquire (permission, cancellable, error);
 107 }
 108
 109 /**
 110  * g_permission_acquire_async:
 111  * @permission: a #GPermission instance
 112  * @cancellable: a #GCancellable, or %NULL
 113  * @callback: the #GAsyncReadyCallback to call when done
 114  * @user_data: the user data to pass to @callback
 115  *
 116  * Attempts to acquire the permission represented by @permission.
 117  *
 118  * This is the first half of the asynchronous version of
 119  * g_permission_acquire().
 120  *
 121  * Since: 2.26
 122  **/
 123 void
 124 g_permission_acquire_async (GPermission         *permission,
 125                             GCancellable        *cancellable,
 126                             GAsyncReadyCallback  callback,
 127                             gpointer             user_data)
 128 {
 129   G_PERMISSION_GET_CLASS (permission)
 130     ->acquire_async (permission, cancellable, callback, user_data);
 131 }
 132
 133 /**
 134  * g_permission_acquire_finish:
 135  * @permission: a #GPermission instance
 136  * @result: the #GAsyncResult given to the #GAsyncReadyCallback
 137  * @error: a pointer to a %NULL #GError, or %NULL
 138  * @returns: %TRUE if the permission was successfully acquired
 139  *
 140  * Collects the result of attempting to acquire the permission
 141  * represented by @permission.
 142  *
 143  * This is the second half of the asynchronous version of
 144  * g_permission_acquire().
 145  *
 146  * Since: 2.26
 147  **/
 148 gboolean
 149 g_permission_acquire_finish (GPermission   *permission,
 150                              GAsyncResult  *result,
 151                              GError       **error)
 152 {
 153   return G_PERMISSION_GET_CLASS (permission)
 154     ->acquire_finish (permission, result, error);
 155 }
 156
 157 /**
 158  * g_permission_release:
 159  * @permission: a #GPermission instance
 160  * @cancellable: a #GCancellable, or %NULL
 161  * @error: a pointer to a %NULL #GError, or %NULL
 162  * @returns: %TRUE if the permission was successfully released
 163  *
 164  * Attempts to release the permission represented by @permission.
 165  *
 166  * The precise method by which this happens depends on the permission
 167  * and the underlying authentication mechanism.  In most cases the
 168  * permission will be dropped immediately without further action.
 169  *
 170  * You should check with g_permission_get_can_release() before calling
 171  * this function.
 172  *
 173  * If the permission is released then %TRUE is returned.  Otherwise,
 174  * %FALSE is returned and @error is set appropriately.
 175  *
 176  * This call is blocking, likely for a very long time (in the case that
 177  * user interaction is required).  See g_permission_release_async() for
 178  * the non-blocking version.
 179  *
 180  * Since: 2.26
 181  **/
 182 gboolean
 183 g_permission_release (GPermission   *permission,
 184                       GCancellable  *cancellable,
 185                       GError       **error)
 186 {
 187   return G_PERMISSION_GET_CLASS (permission)
 188     ->release (permission, cancellable, error);
 189 }
 190
 191 /**
 192  * g_permission_release_async:
 193  * @permission: a #GPermission instance
 194  * @cancellable: a #GCancellable, or %NULL
 195  * @callback: the #GAsyncReadyCallback to call when done
 196  * @user_data: the user data to pass to @callback
 197  *
 198  * Attempts to release the permission represented by @permission.
 199  *
 200  * This is the first half of the asynchronous version of
 201  * g_permission_release().
 202  *
 203  * Since: 2.26
 204  **/
 205 void
 206 g_permission_release_async (GPermission         *permission,
 207                             GCancellable        *cancellable,
 208                             GAsyncReadyCallback  callback,
 209                             gpointer             user_data)
 210 {
 211   G_PERMISSION_GET_CLASS (permission)
 212     ->release_async (permission, cancellable, callback, user_data);
 213 }
 214
 215 /**
 216  * g_permission_release_finish:
 217  * @permission: a #GPermission instance
 218  * @result: the #GAsyncResult given to the #GAsyncReadyCallback
 219  * @error: a pointer to a %NULL #GError, or %NULL
 220  * @returns: %TRUE if the permission was successfully released
 221  *
 222  * Collects the result of attempting to release the permission
 223  * represented by @permission.
 224  *
 225  * This is the second half of the asynchronous version of
 226  * g_permission_release().
 227  *
 228  * Since: 2.26
 229  **/
 230 gboolean
 231 g_permission_release_finish (GPermission   *permission,
 232                              GAsyncResult  *result,
 233                              GError       **error)
 234 {
 235   return G_PERMISSION_GET_CLASS (permission)
 236     ->release_finish (permission, result, error);
 237 }
 238
 239 /**
 240  * g_permission_get_allowed:
 241  * @permission: a #GPermission instance
 242  * @returns: the value of the 'allowed' property
 243  *
 244  * Gets the value of the 'allowed' property.  This property is %TRUE if
 245  * the caller currently has permission to perform the action that
 246  * @permission represents the permission to perform.
 247  *
 248  * Since: 2.26
 249  **/
 250 gboolean
 251 g_permission_get_allowed (GPermission *permission)
 252 {
 253   return permission->priv->allowed;
 254 }
 255
 256 /**
 257  * g_permission_get_can_acquire:
 258  * @permission: a #GPermission instance
 259  * @returns: the value of the 'can-acquire' property
 260  *
 261  * Gets the value of the 'can-acquire' property.  This property is %TRUE
 262  * if it is generally possible to acquire the permission by calling
 263  * g_permission_acquire().
 264  *
 265  * Since: 2.26
 266  **/
 267 gboolean
 268 g_permission_get_can_acquire (GPermission *permission)
 269 {
 270   return permission->priv->can_acquire;
 271 }
 272
 273 /**
 274  * g_permission_get_can_release:
 275  * @permission: a #GPermission instance
 276  * @returns: the value of the 'can-release' property
 277  *
 278  * Gets the value of the 'can-release' property.  This property is %TRUE
 279  * if it is generally possible to release the permission by calling
 280  * g_permission_release().
 281  *
 282  * Since: 2.26
 283  **/
 284 gboolean
 285 g_permission_get_can_release (GPermission *permission)
 286 {
 287   return permission->priv->can_release;
 288 }
 289
 290 /**
 291  * g_permission_impl_update:
 292  * @permission: a #GPermission instance
 293  * @allowed: the new value for the 'allowed' property
 294  * @can_acquire: the new value for the 'can-acquire' property
 295  * @can_release: the new value for the 'can-release' property
 296  *
 297  * This function is called by the #GPermission implementation to update
 298  * the properties of the permission.  You should never call this
 299  * function except from a #GPermission implementation.
 300  *
 301  * GObject notify signals are generated, as appropriate.
 302  *
 303  * Since: 2.26
 304  **/
 305 void
 306 g_permission_impl_update (GPermission *permission,
 307                           gboolean     allowed,
 308                           gboolean     can_acquire,
 309                           gboolean     can_release)
 310 {
 311   GObject *object = G_OBJECT (permission);
 312
 313   g_object_freeze_notify (object);
 314
 315   if (allowed != permission->priv->allowed)
 316     {
 317       permission->priv->allowed = !!allowed;
 318       g_object_notify (object, "allowed");
 319     }
 320
 321   if (can_acquire != permission->priv->can_acquire)
 322     {
 323       permission->priv->can_acquire = !!can_acquire;
 324       g_object_notify (object, "can-acquire");
 325     }
 326
 327   if (can_release != permission->priv->can_release)
 328     {
 329       permission->priv->can_release = !!can_release;
 330       g_object_notify (object, "can-release");
 331     }
 332
 333   g_object_thaw_notify (object);
 334 }
 335
 336 static void
 337 g_permission_get_property (GObject *object, guint prop_id,
 338                            GValue *value, GParamSpec *pspec)
 339 {
 340   GPermission *permission = G_PERMISSION (object);
 341
 342   switch (prop_id)
 343     {
 344     case PROP_ALLOWED:
 345       g_value_set_boolean (value, permission->priv->allowed);
 346       break;
 347
 348     case PROP_CAN_ACQUIRE:
 349       g_value_set_boolean (value, permission->priv->can_acquire);
 350       break;
 351
 352     case PROP_CAN_RELEASE:
 353       g_value_set_boolean (value, permission->priv->can_release);
 354       break;
 355
 356     default:
 357       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 358   }
 359 }
 360
 361 static void
 362 g_permission_init (GPermission *permission)
 363 {
 364   permission->priv = G_TYPE_INSTANCE_GET_PRIVATE (permission,
 365                                                   G_TYPE_PERMISSION,
 366                                                   GPermissionPrivate);
 367 }
 368
 369 static void
 370 g_permission_class_init (GPermissionClass *class)
 371 {
 372   GObjectClass *object_class = G_OBJECT_CLASS (class);
 373
 374   object_class->get_property = g_permission_get_property;
 375
 376   /**
 377    * GPermission:allowed:
 378    *
 379    * %TRUE if the caller currently has permission to perform the action that
 380    * @permission represents the permission to perform.
 381    */
 382    g_object_class_install_property (object_class, PROP_ALLOWED,
 383      g_param_spec_boolean ("allowed",
 384                            P(("Is allowed"),
 385                            P_("If the caller is allowed to perform the action"),
 386                            FALSE,
 387                            G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
 388
 389   /**
 390    * GPermission:can-acquire:
 391    *
 392    * %TRUE if it is generally possible to acquire the permission by calling
 393    * g_permission_acquire().
 394    */
 395    g_object_class_install_property (object_class, PROP_CAN_ACQUIRE,
 396      g_param_spec_boolean ("can-acquire",
 397                            P_("Can acquire"),
 398                            P_("If calling g_permission_acquire() makes sense"),
 399                            FALSE,
 400                            G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
 401
 402   /**
 403    * GPermission:can-release:
 404    *
 405    * %TRUE if it is generally possible to release the permission by calling
 406    * g_permission_release().
 407    */
 408    g_object_class_install_property (object_class, PROP_CAN_RELEASE,
 409      g_param_spec_boolean ("can-release",
 410                            P_("Can release"),
 411                            P_("If calling g_permission_release() makes sense"),
 412                            FALSE,
 413                            G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
 414
 415   g_type_class_add_private (class, sizeof (GPermissionPrivate));
 416 }
 417
 418 #define __G_PERMISSION_C__
 419 #include "gioaliasdef.c"