gpermission.c 14.3 KB
Newer Older
1 2 3 4 5 6
/*
 * Copyright © 2010 Codethink Limited
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
7
 * version 2.1 of the License, or (at your option) any later version.
8 9 10 11 12 13 14
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * 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 18 19
 *
 * Author: Ryan Lortie <desrt@desrt.ca>
 */

Matthias Clasen's avatar
Matthias Clasen committed
20 21
#include "config.h"

22
#include "gpermission.h"
23 24 25 26

#include "gioerror.h"
#include "gioenums.h"
#include "gasyncresult.h"
27
#include "gtask.h"
Matthias Clasen's avatar
Matthias Clasen committed
28
#include "glibintl.h"
29 30 31 32 33


/**
 * SECTION:gpermission
 * @title: GPermission
34 35 36
 * @short_description: An object representing the permission
 *     to perform a certain action
 * @include: gio/gio.h
37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
 *
 * A #GPermission represents the status of the caller's permission to
 * perform a certain action.
 *
 * You can query if the action is currently allowed and if it is
 * possible to acquire the permission so that the action will be allowed
 * in the future.
 *
 * There is also an API to actually acquire the permission and one to
 * release it.
 *
 * As an example, a #GPermission might represent the ability for the
 * user to write to a #GSettings object.  This #GPermission object could
 * then be used to decide if it is appropriate to show a "Click here to
 * unlock" button in a dialog and to provide the mechanism to invoke
 * when that button is clicked.
 **/

/**
 * GPermission:
 *
 * #GPermission is an opaque data structure and can only be accessed
 * using the following functions.
 **/

struct _GPermissionPrivate
{
  gboolean allowed;
  gboolean can_acquire;
  gboolean can_release;
};

enum  {
  PROP_NONE,
  PROP_ALLOWED,
  PROP_CAN_ACQUIRE,
  PROP_CAN_RELEASE
};

76 77
G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GPermission, g_permission, G_TYPE_OBJECT)

78 79 80
/**
 * g_permission_acquire:
 * @permission: a #GPermission instance
81
 * @cancellable: (nullable): a #GCancellable, or %NULL
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98
 * @error: a pointer to a %NULL #GError, or %NULL
 *
 * Attempts to acquire the permission represented by @permission.
 *
 * The precise method by which this happens depends on the permission
 * and the underlying authentication mechanism.  A simple example is
 * that a dialog may appear asking the user to enter their password.
 *
 * You should check with g_permission_get_can_acquire() before calling
 * this function.
 *
 * If the permission is acquired then %TRUE is returned.  Otherwise,
 * %FALSE is returned and @error is set appropriately.
 *
 * This call is blocking, likely for a very long time (in the case that
 * user interaction is required).  See g_permission_acquire_async() for
 * the non-blocking version.
Matthias Clasen's avatar
Matthias Clasen committed
99
 *
100 101
 * Returns: %TRUE if the permission was successfully acquired
 *
Matthias Clasen's avatar
Matthias Clasen committed
102 103
 * Since: 2.26
 */
104 105 106 107 108
gboolean
g_permission_acquire (GPermission   *permission,
                      GCancellable  *cancellable,
                      GError       **error)
{
109
  g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
110 111 112 113 114 115 116
  return G_PERMISSION_GET_CLASS (permission)
    ->acquire (permission, cancellable, error);
}

/**
 * g_permission_acquire_async:
 * @permission: a #GPermission instance
117
 * @cancellable: (nullable): a #GCancellable, or %NULL
118 119 120 121 122 123 124
 * @callback: the #GAsyncReadyCallback to call when done
 * @user_data: the user data to pass to @callback
 *
 * Attempts to acquire the permission represented by @permission.
 *
 * This is the first half of the asynchronous version of
 * g_permission_acquire().
Matthias Clasen's avatar
Matthias Clasen committed
125 126
 *
 * Since: 2.26
127 128 129 130 131 132 133
 **/
void
g_permission_acquire_async (GPermission         *permission,
                            GCancellable        *cancellable,
                            GAsyncReadyCallback  callback,
                            gpointer             user_data)
{
134
  g_return_if_fail (G_IS_PERMISSION (permission));
135 136 137 138 139 140 141 142 143 144 145 146 147 148 149
  G_PERMISSION_GET_CLASS (permission)
    ->acquire_async (permission, cancellable, callback, user_data);
}

/**
 * g_permission_acquire_finish:
 * @permission: a #GPermission instance
 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
 * @error: a pointer to a %NULL #GError, or %NULL
 *
 * Collects the result of attempting to acquire the permission
 * represented by @permission.
 *
 * This is the second half of the asynchronous version of
 * g_permission_acquire().
Matthias Clasen's avatar
Matthias Clasen committed
150
 *
151 152
 * Returns: %TRUE if the permission was successfully acquired
 *
Matthias Clasen's avatar
Matthias Clasen committed
153
 * Since: 2.26
154 155 156 157 158 159
 **/
gboolean
g_permission_acquire_finish (GPermission   *permission,
                             GAsyncResult  *result,
                             GError       **error)
{
160
  g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
161 162 163 164 165 166 167
  return G_PERMISSION_GET_CLASS (permission)
    ->acquire_finish (permission, result, error);
}

/**
 * g_permission_release:
 * @permission: a #GPermission instance
168
 * @cancellable: (nullable): a #GCancellable, or %NULL
169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185
 * @error: a pointer to a %NULL #GError, or %NULL
 *
 * Attempts to release the permission represented by @permission.
 *
 * The precise method by which this happens depends on the permission
 * and the underlying authentication mechanism.  In most cases the
 * permission will be dropped immediately without further action.
 *
 * You should check with g_permission_get_can_release() before calling
 * this function.
 *
 * If the permission is released then %TRUE is returned.  Otherwise,
 * %FALSE is returned and @error is set appropriately.
 *
 * This call is blocking, likely for a very long time (in the case that
 * user interaction is required).  See g_permission_release_async() for
 * the non-blocking version.
Matthias Clasen's avatar
Matthias Clasen committed
186
 *
187 188
 * Returns: %TRUE if the permission was successfully released
 *
Matthias Clasen's avatar
Matthias Clasen committed
189
 * Since: 2.26
190 191 192 193 194 195
 **/
gboolean
g_permission_release (GPermission   *permission,
                      GCancellable  *cancellable,
                      GError       **error)
{
196
  g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
197 198 199 200 201 202 203
  return G_PERMISSION_GET_CLASS (permission)
    ->release (permission, cancellable, error);
}

/**
 * g_permission_release_async:
 * @permission: a #GPermission instance
204
 * @cancellable: (nullable): a #GCancellable, or %NULL
205 206 207 208 209 210 211
 * @callback: the #GAsyncReadyCallback to call when done
 * @user_data: the user data to pass to @callback
 *
 * Attempts to release the permission represented by @permission.
 *
 * This is the first half of the asynchronous version of
 * g_permission_release().
Matthias Clasen's avatar
Matthias Clasen committed
212 213
 *
 * Since: 2.26
214 215 216 217 218 219 220
 **/
void
g_permission_release_async (GPermission         *permission,
                            GCancellable        *cancellable,
                            GAsyncReadyCallback  callback,
                            gpointer             user_data)
{
221
  g_return_if_fail (G_IS_PERMISSION (permission));
222 223 224 225 226 227 228 229 230 231 232 233 234 235 236
  G_PERMISSION_GET_CLASS (permission)
    ->release_async (permission, cancellable, callback, user_data);
}

/**
 * g_permission_release_finish:
 * @permission: a #GPermission instance
 * @result: the #GAsyncResult given to the #GAsyncReadyCallback
 * @error: a pointer to a %NULL #GError, or %NULL
 *
 * Collects the result of attempting to release the permission
 * represented by @permission.
 *
 * This is the second half of the asynchronous version of
 * g_permission_release().
Matthias Clasen's avatar
Matthias Clasen committed
237
 *
238 239
 * Returns: %TRUE if the permission was successfully released
 *
Matthias Clasen's avatar
Matthias Clasen committed
240
 * Since: 2.26
241 242 243 244 245 246
 **/
gboolean
g_permission_release_finish (GPermission   *permission,
                             GAsyncResult  *result,
                             GError       **error)
{
247
  g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
248 249 250 251 252 253 254 255 256 257 258
  return G_PERMISSION_GET_CLASS (permission)
    ->release_finish (permission, result, error);
}

/**
 * g_permission_get_allowed:
 * @permission: a #GPermission instance
 *
 * Gets the value of the 'allowed' property.  This property is %TRUE if
 * the caller currently has permission to perform the action that
 * @permission represents the permission to perform.
Matthias Clasen's avatar
Matthias Clasen committed
259
 *
260 261
 * Returns: the value of the 'allowed' property
 *
Matthias Clasen's avatar
Matthias Clasen committed
262
 * Since: 2.26
263 264 265 266
 **/
gboolean
g_permission_get_allowed (GPermission *permission)
{
267
  g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
268 269 270 271 272 273 274 275 276 277
  return permission->priv->allowed;
}

/**
 * g_permission_get_can_acquire:
 * @permission: a #GPermission instance
 *
 * Gets the value of the 'can-acquire' property.  This property is %TRUE
 * if it is generally possible to acquire the permission by calling
 * g_permission_acquire().
Matthias Clasen's avatar
Matthias Clasen committed
278
 *
279 280
 * Returns: the value of the 'can-acquire' property
 *
Matthias Clasen's avatar
Matthias Clasen committed
281
 * Since: 2.26
282 283 284 285
 **/
gboolean
g_permission_get_can_acquire (GPermission *permission)
{
286
  g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
287 288 289 290 291 292 293 294 295 296
  return permission->priv->can_acquire;
}

/**
 * g_permission_get_can_release:
 * @permission: a #GPermission instance
 *
 * Gets the value of the 'can-release' property.  This property is %TRUE
 * if it is generally possible to release the permission by calling
 * g_permission_release().
Matthias Clasen's avatar
Matthias Clasen committed
297
 *
298 299
 * Returns: the value of the 'can-release' property
 *
Matthias Clasen's avatar
Matthias Clasen committed
300
 * Since: 2.26
301 302 303 304
 **/
gboolean
g_permission_get_can_release (GPermission *permission)
{
305
  g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
306 307 308 309 310 311 312 313 314 315 316 317 318 319 320
  return permission->priv->can_release;
}

/**
 * g_permission_impl_update:
 * @permission: a #GPermission instance
 * @allowed: the new value for the 'allowed' property
 * @can_acquire: the new value for the 'can-acquire' property
 * @can_release: the new value for the 'can-release' property
 *
 * This function is called by the #GPermission implementation to update
 * the properties of the permission.  You should never call this
 * function except from a #GPermission implementation.
 *
 * GObject notify signals are generated, as appropriate.
Matthias Clasen's avatar
Matthias Clasen committed
321 322
 *
 * Since: 2.26
323 324 325 326 327 328 329
 **/
void
g_permission_impl_update (GPermission *permission,
                          gboolean     allowed,
                          gboolean     can_acquire,
                          gboolean     can_release)
{
330
  GObject *object;
331

332 333 334
  g_return_if_fail (G_IS_PERMISSION (permission));

  object = G_OBJECT (permission);
335 336
  g_object_freeze_notify (object);

337
  allowed = allowed != FALSE;
338 339
  if (allowed != permission->priv->allowed)
    {
340
      permission->priv->allowed = allowed;
341 342 343
      g_object_notify (object, "allowed");
    }

344
  can_acquire = can_acquire != FALSE;
345 346
  if (can_acquire != permission->priv->can_acquire)
    {
347
      permission->priv->can_acquire = can_acquire;
348 349 350
      g_object_notify (object, "can-acquire");
    }

351
  can_release = can_release != FALSE;
352 353
  if (can_release != permission->priv->can_release)
    {
354
      permission->priv->can_release = can_release;
355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388
      g_object_notify (object, "can-release");
    }

  g_object_thaw_notify (object);
}

static void
g_permission_get_property (GObject *object, guint prop_id,
                           GValue *value, GParamSpec *pspec)
{
  GPermission *permission = G_PERMISSION (object);

  switch (prop_id)
    {
    case PROP_ALLOWED:
      g_value_set_boolean (value, permission->priv->allowed);
      break;

    case PROP_CAN_ACQUIRE:
      g_value_set_boolean (value, permission->priv->can_acquire);
      break;

    case PROP_CAN_RELEASE:
      g_value_set_boolean (value, permission->priv->can_release);
      break;

    default:
      G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
  }
}

static void
g_permission_init (GPermission *permission)
{
389
  permission->priv = g_permission_get_instance_private (permission);
390 391
}

392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408
static gboolean
acquire_or_release (GPermission   *permission,
                    GCancellable  *cancellable,
                    GError       **error)
{
  g_set_error_literal  (error,
                        G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
                        "Can't acquire or release permission");
  return FALSE;
}

static void
acquire_or_release_async (GPermission         *permission,
                          GCancellable        *cancellable,
                          GAsyncReadyCallback  callback,
                          gpointer             user_data)
{
409 410 411 412 413
  g_task_report_new_error (permission,
                           callback, user_data,
                           NULL,
                           G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
                           "Can't acquire or release permission");
414 415 416 417 418 419 420
}

static gboolean
acquire_or_release_finish (GPermission   *permission,
                           GAsyncResult  *result,
                           GError       **error)
{
421
  return g_task_propagate_boolean (G_TASK (result), error);
422 423
}

424 425 426 427 428 429 430
static void
g_permission_class_init (GPermissionClass *class)
{
  GObjectClass *object_class = G_OBJECT_CLASS (class);

  object_class->get_property = g_permission_get_property;

431 432 433 434 435 436 437
  class->acquire = acquire_or_release;
  class->release = acquire_or_release;
  class->acquire_async = acquire_or_release_async;
  class->release_async = acquire_or_release_async;
  class->acquire_finish = acquire_or_release_finish;
  class->release_finish = acquire_or_release_finish;

438 439 440 441 442 443 444
  /**
   * GPermission:allowed:
   *
   * %TRUE if the caller currently has permission to perform the action that
   * @permission represents the permission to perform.
   */
   g_object_class_install_property (object_class, PROP_ALLOWED,
Matthias Clasen's avatar
Matthias Clasen committed
445
     g_param_spec_boolean ("allowed",
Michael Natterer's avatar
Michael Natterer committed
446
                           P_("Is allowed"),
Matthias Clasen's avatar
Matthias Clasen committed
447 448 449
                           P_("If the caller is allowed to perform the action"),
                           FALSE,
                           G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
450 451 452 453 454 455 456 457

  /**
   * GPermission:can-acquire:
   *
   * %TRUE if it is generally possible to acquire the permission by calling
   * g_permission_acquire().
   */
   g_object_class_install_property (object_class, PROP_CAN_ACQUIRE,
Matthias Clasen's avatar
Matthias Clasen committed
458 459 460 461 462
     g_param_spec_boolean ("can-acquire",
                           P_("Can acquire"),
                           P_("If calling g_permission_acquire() makes sense"),
                           FALSE,
                           G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
463 464 465 466 467 468 469 470

  /**
   * GPermission:can-release:
   *
   * %TRUE if it is generally possible to release the permission by calling
   * g_permission_release().
   */
   g_object_class_install_property (object_class, PROP_CAN_RELEASE,
Matthias Clasen's avatar
Matthias Clasen committed
471 472 473 474 475
     g_param_spec_boolean ("can-release",
                           P_("Can release"),
                           P_("If calling g_permission_release() makes sense"),
                           FALSE,
                           G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
476
}