[glib] Bug 620519 - GPermission
- From: Ryan Lortie <ryanl src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [glib] Bug 620519 - GPermission
- Date: Fri, 4 Jun 2010 17:05:41 +0000 (UTC)
commit 7a4860d69ad7b6daf6cce0063cbc52070d21bd7b
Author: Ryan Lortie <desrt desrt ca>
Date: Thu Jun 3 22:58:52 2010 +0200
Bug 620519 - GPermission
Add an abstract interface representing the permission to perform an
action.
docs/reference/gio/gio-docs.xml | 4 +
docs/reference/gio/gio-sections.txt | 21 ++
docs/reference/gio/gio.types | 1 +
gio/Makefile.am | 2 +
gio/gio.h | 1 +
gio/gio.symbols | 16 ++
gio/giotypes.h | 1 +
gio/gpermission.c | 390 +++++++++++++++++++++++++++++++++++
gio/gpermission.h | 118 +++++++++++
9 files changed, 554 insertions(+), 0 deletions(-)
---
diff --git a/docs/reference/gio/gio-docs.xml b/docs/reference/gio/gio-docs.xml
index 151e909..950f715 100644
--- a/docs/reference/gio/gio-docs.xml
+++ b/docs/reference/gio/gio-docs.xml
@@ -155,6 +155,10 @@
<xi:include href="xml/gsettings.xml"/>
<xi:include href="xml/gsettingsbackend.xml"/>
</chapter>
+ <chapter id='permissions'>
+ <title>Permissions</title>
+ <xi:include href="xml/gpermission.xml"/>
+ </chapter>
<chapter id="extending">
<title>Extending GIO</title>
<xi:include href="xml/gvfs.xml"/>
diff --git a/docs/reference/gio/gio-sections.txt b/docs/reference/gio/gio-sections.txt
index 1cc15c2..5cb52d2 100644
--- a/docs/reference/gio/gio-sections.txt
+++ b/docs/reference/gio/gio-sections.txt
@@ -2590,3 +2590,24 @@ g_dbus_node_info_get_type
g_dbus_property_info_get_type
g_dbus_signal_info_get_type
</SECTION>
+
+<SECTION>
+<FILE>gpermission</FILE>
+GPermission
+g_permission_get_allowed
+g_permission_get_can_acquire
+g_permission_get_can_release
+<SUBSECTION>
+g_permission_acquire
+g_permission_acquire_async
+g_permission_acquire_finish
+g_permission_release
+g_permission_release_async
+g_permission_release_finish
+<SUBSECTION>
+g_permission_impl_update
+<SUBSECTION Standard>
+g_permission_get_type
+GPermissionPrivate
+GPermissionClass
+</SECTION>
diff --git a/docs/reference/gio/gio.types b/docs/reference/gio/gio.types
index 38ffb55..27db6b1 100644
--- a/docs/reference/gio/gio.types
+++ b/docs/reference/gio/gio.types
@@ -70,6 +70,7 @@ g_network_service_get_type
g_output_stream_get_type
g_output_stream_splice_flags_get_type
g_password_save_get_type
+g_permission_get_type
g_resolver_error_get_type
g_resolver_get_type
g_seekable_get_type
diff --git a/gio/Makefile.am b/gio/Makefile.am
index d0bd37e..485ae4e 100644
--- a/gio/Makefile.am
+++ b/gio/Makefile.am
@@ -327,6 +327,7 @@ libgio_2_0_la_SOURCES = \
gnetworkingprivate.h \
gnetworkservice.c \
goutputstream.c \
+ gpermission.c \
gpollfilemonitor.c \
gpollfilemonitor.h \
gresolver.c \
@@ -473,6 +474,7 @@ gio_headers = \
gnetworkaddress.h \
gnetworkservice.h \
goutputstream.h \
+ gpermission.h \
gresolver.h \
gseekable.h \
gsimpleasyncresult.h \
diff --git a/gio/gio.h b/gio/gio.h
index dd5c811..0e28f93 100644
--- a/gio/gio.h
+++ b/gio/gio.h
@@ -74,6 +74,7 @@
#include <gio/gnetworkaddress.h>
#include <gio/gnetworkservice.h>
#include <gio/goutputstream.h>
+#include <gio/gpermission.h>
#include <gio/gresolver.h>
#include <gio/gseekable.h>
#include <gio/gsettings.h>
diff --git a/gio/gio.symbols b/gio/gio.symbols
index 8aebd44..1717cbb 100644
--- a/gio/gio.symbols
+++ b/gio/gio.symbols
@@ -1730,3 +1730,19 @@ g_unix_credentials_message_is_supported
#endif
#endif
#endif
+
+#if IN_HEADER(__G_PERMISSION_H__)
+#if IN_FILE(__G_PERMISSION_C__)
+g_permission_acquire
+g_permission_acquire_async
+g_permission_acquire_finish
+g_permission_get_allowed
+g_permission_get_can_acquire
+g_permission_get_can_release
+g_permission_get_type
+g_permission_impl_update
+g_permission_release
+g_permission_release_async
+g_permission_release_finish
+#endif
+#endif
diff --git a/gio/giotypes.h b/gio/giotypes.h
index 1d03645..ac97fd9 100644
--- a/gio/giotypes.h
+++ b/gio/giotypes.h
@@ -43,6 +43,7 @@ typedef struct _GConverter GConverter;
typedef struct _GConverterInputStream GConverterInputStream;
typedef struct _GConverterOutputStream GConverterOutputStream;
typedef struct _GDataInputStream GDataInputStream;
+typedef struct _GPermission GPermission;
typedef struct _GZlibCompressor GZlibCompressor;
typedef struct _GZlibDecompressor GZlibDecompressor;
diff --git a/gio/gpermission.c b/gio/gpermission.c
new file mode 100644
index 0000000..004bc81
--- /dev/null
+++ b/gio/gpermission.c
@@ -0,0 +1,390 @@
+/*
+ * 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
+ * version 2 of the licence, 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, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ *
+ * Author: Ryan Lortie <desrt desrt ca>
+ */
+
+#include "gpermission.h"
+
+#include "gioalias.h"
+
+/**
+ * SECTION:gpermission
+ * @title: GPermission
+ * @short_description: an object representing the permission to perform
+ * a certain action
+ *
+ * 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.
+ **/
+
+G_DEFINE_ABSTRACT_TYPE (GPermission, g_permission, G_TYPE_OBJECT)
+
+struct _GPermissionPrivate
+{
+ gboolean allowed;
+ gboolean can_acquire;
+ gboolean can_release;
+};
+
+enum {
+ PROP_NONE,
+ PROP_ALLOWED,
+ PROP_CAN_ACQUIRE,
+ PROP_CAN_RELEASE
+};
+
+/**
+ * g_permission_acquire:
+ * @permission: a #GPermission instance
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a pointer to a %NULL #GError, or %NULL
+ * @returns: %TRUE if the permission was successfully acquired
+ *
+ * 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.
+ **/
+gboolean
+g_permission_acquire (GPermission *permission,
+ GCancellable *cancellable,
+ GError **error)
+{
+ return G_PERMISSION_GET_CLASS (permission)
+ ->acquire (permission, cancellable, error);
+}
+
+/**
+ * g_permission_acquire_async:
+ * @permission: a #GPermission instance
+ * @cancellable: 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().
+ **/
+void
+g_permission_acquire_async (GPermission *permission,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
+{
+ 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
+ * @returns: %TRUE if the permission was successfully acquired
+ *
+ * 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().
+ **/
+gboolean
+g_permission_acquire_finish (GPermission *permission,
+ GAsyncResult *result,
+ GError **error)
+{
+ return G_PERMISSION_GET_CLASS (permission)
+ ->acquire_finish (permission, result, error);
+}
+
+/**
+ * g_permission_release:
+ * @permission: a #GPermission instance
+ * @cancellable: a #GCancellable, or %NULL
+ * @error: a pointer to a %NULL #GError, or %NULL
+ * @returns: %TRUE if the permission was successfully released
+ *
+ * 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.
+ **/
+gboolean
+g_permission_release (GPermission *permission,
+ GCancellable *cancellable,
+ GError **error)
+{
+ return G_PERMISSION_GET_CLASS (permission)
+ ->release (permission, cancellable, error);
+}
+
+/**
+ * g_permission_release_async:
+ * @permission: a #GPermission instance
+ * @cancellable: 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().
+ **/
+void
+g_permission_release_async (GPermission *permission,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data)
+{
+ 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
+ * @returns: %TRUE if the permission was successfully released
+ *
+ * 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().
+ **/
+gboolean
+g_permission_release_finish (GPermission *permission,
+ GAsyncResult *result,
+ GError **error)
+{
+ return G_PERMISSION_GET_CLASS (permission)
+ ->release_finish (permission, result, error);
+}
+
+/**
+ * g_permission_get_allowed:
+ * @permission: a #GPermission instance
+ * @returns: the value of the 'allowed' property
+ *
+ * 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.
+ **/
+gboolean
+g_permission_get_allowed (GPermission *permission)
+{
+ return permission->priv->allowed;
+}
+
+/**
+ * g_permission_get_can_acquire:
+ * @permission: a #GPermission instance
+ * @returns: the value of the 'can-acquire' property
+ *
+ * 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().
+ **/
+gboolean
+g_permission_get_can_acquire (GPermission *permission)
+{
+ return permission->priv->can_acquire;
+}
+
+/**
+ * g_permission_get_can_release:
+ * @permission: a #GPermission instance
+ * @returns: the value of the 'can-release' property
+ *
+ * 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().
+ **/
+gboolean
+g_permission_get_can_release (GPermission *permission)
+{
+ 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.
+ **/
+void
+g_permission_impl_update (GPermission *permission,
+ gboolean allowed,
+ gboolean can_acquire,
+ gboolean can_release)
+{
+ GObject *object = G_OBJECT (permission);
+
+ g_object_freeze_notify (object);
+
+ if (allowed != permission->priv->allowed)
+ {
+ permission->priv->allowed = !!allowed;
+ g_object_notify (object, "allowed");
+ }
+
+ if (can_acquire != permission->priv->can_acquire)
+ {
+ permission->priv->can_acquire = !!can_acquire;
+ g_object_notify (object, "can-acquire");
+ }
+
+ 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_TYPE_INSTANCE_GET_PRIVATE (permission,
+ G_TYPE_PERMISSION,
+ GPermissionPrivate);
+}
+
+static void
+g_permission_class_init (GPermissionClass *class)
+{
+ GObjectClass *object_class = G_OBJECT_CLASS (class);
+
+ object_class->get_property = g_permission_get_property;
+
+ /**
+ * 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", "is allowed",
+ "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", "can acquire",
+ "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", "can release",
+ "if calling g_permission_release() makes sense",
+ FALSE, G_PARAM_STATIC_STRINGS | G_PARAM_READABLE));
+
+ g_type_class_add_private (class, sizeof (GPermissionPrivate));
+}
+
+#define __G_PERMISSION_C__
+#include "gioaliasdef.c"
diff --git a/gio/gpermission.h b/gio/gpermission.h
new file mode 100644
index 0000000..3f74257
--- /dev/null
+++ b/gio/gpermission.h
@@ -0,0 +1,118 @@
+/*
+ * 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
+ * version 2 of the licence, 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, write to the
+ * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+ * Boston, MA 02111-1307, USA.
+ *
+ * Author: Ryan Lortie <desrt desrt ca>
+ */
+
+#if !defined (__GIO_GIO_H_INSIDE__) && !defined (GIO_COMPILATION)
+#error "Only <gio/gio.h> can be included directly."
+#endif
+
+#ifndef __G_PERMISSION_H__
+#define __G_PERMISSION_H__
+
+#include <gio/giotypes.h>
+
+G_BEGIN_DECLS
+
+#define G_TYPE_PERMISSION (g_permission_get_type ())
+#define G_PERMISSION(inst) (G_TYPE_CHECK_INSTANCE_CAST ((inst), \
+ G_TYPE_PERMISSION, GPermission))
+#define G_PERMISSION_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), \
+ G_TYPE_PERMISSION, GPermissionClass))
+#define G_IS_PERMISSION(inst) (G_TYPE_CHECK_INSTANCE_TYPE ((inst), \
+ G_TYPE_PERMISSION))
+#define G_IS_PERMISSION_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), \
+ G_TYPE_PERMISSION))
+#define G_PERMISSION_GET_CLASS(inst) (G_TYPE_INSTANCE_GET_CLASS ((inst), \
+ G_TYPE_PERMISSION, GPermissionClass))
+
+typedef struct _GPermissionPrivate GPermissionPrivate;
+typedef struct _GPermissionClass GPermissionClass;
+
+struct _GPermission
+{
+ GObject parent_instance;
+
+ /*< private >*/
+ GPermissionPrivate *priv;
+};
+
+struct _GPermissionClass {
+ GObjectClass parent_class;
+
+ gboolean (*acquire) (GPermission *permission,
+ GCancellable *cancellable,
+ GError **error);
+ void (*acquire_async) (GPermission *permission,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+ gboolean (*acquire_finish) (GPermission *permission,
+ GAsyncResult *result,
+ GError **error);
+
+ gboolean (*release) (GPermission *permission,
+ GCancellable *cancellable,
+ GError **error);
+ void (*release_async) (GPermission *permission,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+ gboolean (*release_finish) (GPermission *permission,
+ GAsyncResult *result,
+ GError **error);
+
+ gpointer reserved[16];
+};
+
+GType g_permission_get_type (void);
+gboolean g_permission_acquire (GPermission *permission,
+ GCancellable *cancellable,
+ GError **error);
+void g_permission_acquire_async (GPermission *permission,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+gboolean g_permission_acquire_finish (GPermission *permission,
+ GAsyncResult *result,
+ GError **error);
+
+gboolean g_permission_release (GPermission *permission,
+ GCancellable *cancellable,
+ GError **error);
+void g_permission_release_async (GPermission *permission,
+ GCancellable *cancellable,
+ GAsyncReadyCallback callback,
+ gpointer user_data);
+gboolean g_permission_release_finish (GPermission *permission,
+ GAsyncResult *result,
+ GError **error);
+
+gboolean g_permission_get_allowed (GPermission *permission);
+gboolean g_permission_get_can_acquire (GPermission *permission);
+gboolean g_permission_get_can_release (GPermission *permission);
+
+void g_permission_impl_update (GPermission *permission,
+ gboolean allowed,
+ gboolean can_acquire,
+ gboolean can_release);
+
+G_END_DECLS
+
+#endif /* __G_PERMISSION_H__ */
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
