mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-12-24 22:46:15 +01:00
5942cd7984
Add SPDX license (but not copyright) headers to all files which follow a certain pattern in their existing non-machine-readable header comment. This commit was entirely generated using the command: ``` git ls-files gio/*.[ch] | xargs perl -0777 -pi -e 's/\n \*\n \* This library is free software; you can redistribute it and\/or\n \* modify it under the terms of the GNU Lesser General Public/\n \*\n \* SPDX-License-Identifier: LGPL-2.1-or-later\n \*\n \* This library is free software; you can redistribute it and\/or\n \* modify it under the terms of the GNU Lesser General Public/igs' ``` Signed-off-by: Philip Withnall <pwithnall@endlessos.org> Helps: #1415
479 lines
14 KiB
C
479 lines
14 KiB
C
/*
|
|
* Copyright © 2010 Codethink Limited
|
|
*
|
|
* SPDX-License-Identifier: LGPL-2.1-or-later
|
|
*
|
|
* 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
|
|
* version 2.1 of the License, or (at your option) any later version.
|
|
*
|
|
* 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
|
|
* License along with this library; if not, see <http://www.gnu.org/licenses/>.
|
|
*
|
|
* Author: Ryan Lortie <desrt@desrt.ca>
|
|
*/
|
|
|
|
#include "config.h"
|
|
|
|
#include "gpermission.h"
|
|
|
|
#include "gioerror.h"
|
|
#include "gioenums.h"
|
|
#include "gasyncresult.h"
|
|
#include "gtask.h"
|
|
#include "glibintl.h"
|
|
|
|
|
|
/**
|
|
* SECTION:gpermission
|
|
* @title: GPermission
|
|
* @short_description: An object representing the permission
|
|
* to perform a certain action
|
|
* @include: gio/gio.h
|
|
*
|
|
* 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
|
|
};
|
|
|
|
G_DEFINE_ABSTRACT_TYPE_WITH_PRIVATE (GPermission, g_permission, G_TYPE_OBJECT)
|
|
|
|
/**
|
|
* g_permission_acquire:
|
|
* @permission: a #GPermission instance
|
|
* @cancellable: (nullable): a #GCancellable, or %NULL
|
|
* @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.
|
|
*
|
|
* Returns: %TRUE if the permission was successfully acquired
|
|
*
|
|
* Since: 2.26
|
|
*/
|
|
gboolean
|
|
g_permission_acquire (GPermission *permission,
|
|
GCancellable *cancellable,
|
|
GError **error)
|
|
{
|
|
g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
|
|
return G_PERMISSION_GET_CLASS (permission)
|
|
->acquire (permission, cancellable, error);
|
|
}
|
|
|
|
/**
|
|
* g_permission_acquire_async:
|
|
* @permission: a #GPermission instance
|
|
* @cancellable: (nullable): a #GCancellable, or %NULL
|
|
* @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().
|
|
*
|
|
* Since: 2.26
|
|
**/
|
|
void
|
|
g_permission_acquire_async (GPermission *permission,
|
|
GCancellable *cancellable,
|
|
GAsyncReadyCallback callback,
|
|
gpointer user_data)
|
|
{
|
|
g_return_if_fail (G_IS_PERMISSION (permission));
|
|
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().
|
|
*
|
|
* Returns: %TRUE if the permission was successfully acquired
|
|
*
|
|
* Since: 2.26
|
|
**/
|
|
gboolean
|
|
g_permission_acquire_finish (GPermission *permission,
|
|
GAsyncResult *result,
|
|
GError **error)
|
|
{
|
|
g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
|
|
return G_PERMISSION_GET_CLASS (permission)
|
|
->acquire_finish (permission, result, error);
|
|
}
|
|
|
|
/**
|
|
* g_permission_release:
|
|
* @permission: a #GPermission instance
|
|
* @cancellable: (nullable): a #GCancellable, or %NULL
|
|
* @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.
|
|
*
|
|
* Returns: %TRUE if the permission was successfully released
|
|
*
|
|
* Since: 2.26
|
|
**/
|
|
gboolean
|
|
g_permission_release (GPermission *permission,
|
|
GCancellable *cancellable,
|
|
GError **error)
|
|
{
|
|
g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
|
|
return G_PERMISSION_GET_CLASS (permission)
|
|
->release (permission, cancellable, error);
|
|
}
|
|
|
|
/**
|
|
* g_permission_release_async:
|
|
* @permission: a #GPermission instance
|
|
* @cancellable: (nullable): a #GCancellable, or %NULL
|
|
* @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().
|
|
*
|
|
* Since: 2.26
|
|
**/
|
|
void
|
|
g_permission_release_async (GPermission *permission,
|
|
GCancellable *cancellable,
|
|
GAsyncReadyCallback callback,
|
|
gpointer user_data)
|
|
{
|
|
g_return_if_fail (G_IS_PERMISSION (permission));
|
|
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().
|
|
*
|
|
* Returns: %TRUE if the permission was successfully released
|
|
*
|
|
* Since: 2.26
|
|
**/
|
|
gboolean
|
|
g_permission_release_finish (GPermission *permission,
|
|
GAsyncResult *result,
|
|
GError **error)
|
|
{
|
|
g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
|
|
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.
|
|
*
|
|
* Returns: the value of the 'allowed' property
|
|
*
|
|
* Since: 2.26
|
|
**/
|
|
gboolean
|
|
g_permission_get_allowed (GPermission *permission)
|
|
{
|
|
g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
|
|
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().
|
|
*
|
|
* Returns: the value of the 'can-acquire' property
|
|
*
|
|
* Since: 2.26
|
|
**/
|
|
gboolean
|
|
g_permission_get_can_acquire (GPermission *permission)
|
|
{
|
|
g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
|
|
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().
|
|
*
|
|
* Returns: the value of the 'can-release' property
|
|
*
|
|
* Since: 2.26
|
|
**/
|
|
gboolean
|
|
g_permission_get_can_release (GPermission *permission)
|
|
{
|
|
g_return_val_if_fail (G_IS_PERMISSION (permission), FALSE);
|
|
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.
|
|
*
|
|
* Since: 2.26
|
|
**/
|
|
void
|
|
g_permission_impl_update (GPermission *permission,
|
|
gboolean allowed,
|
|
gboolean can_acquire,
|
|
gboolean can_release)
|
|
{
|
|
GObject *object;
|
|
|
|
g_return_if_fail (G_IS_PERMISSION (permission));
|
|
|
|
object = G_OBJECT (permission);
|
|
g_object_freeze_notify (object);
|
|
|
|
allowed = allowed != FALSE;
|
|
if (allowed != permission->priv->allowed)
|
|
{
|
|
permission->priv->allowed = allowed;
|
|
g_object_notify (object, "allowed");
|
|
}
|
|
|
|
can_acquire = can_acquire != FALSE;
|
|
if (can_acquire != permission->priv->can_acquire)
|
|
{
|
|
permission->priv->can_acquire = can_acquire;
|
|
g_object_notify (object, "can-acquire");
|
|
}
|
|
|
|
can_release = can_release != FALSE;
|
|
if (can_release != permission->priv->can_release)
|
|
{
|
|
permission->priv->can_release = can_release;
|
|
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)
|
|
{
|
|
permission->priv = g_permission_get_instance_private (permission);
|
|
}
|
|
|
|
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)
|
|
{
|
|
g_task_report_new_error (permission,
|
|
callback, user_data,
|
|
NULL,
|
|
G_IO_ERROR, G_IO_ERROR_NOT_SUPPORTED,
|
|
"Can't acquire or release permission");
|
|
}
|
|
|
|
static gboolean
|
|
acquire_or_release_finish (GPermission *permission,
|
|
GAsyncResult *result,
|
|
GError **error)
|
|
{
|
|
return g_task_propagate_boolean (G_TASK (result), error);
|
|
}
|
|
|
|
static void
|
|
g_permission_class_init (GPermissionClass *class)
|
|
{
|
|
GObjectClass *object_class = G_OBJECT_CLASS (class);
|
|
|
|
object_class->get_property = g_permission_get_property;
|
|
|
|
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;
|
|
|
|
/**
|
|
* 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,
|
|
g_param_spec_boolean ("allowed",
|
|
P_("Is allowed"),
|
|
P_("If the caller is allowed to perform the action"),
|
|
FALSE,
|
|
G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
|
|
|
|
/**
|
|
* 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,
|
|
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));
|
|
|
|
/**
|
|
* 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,
|
|
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));
|
|
}
|