Commit 7a4860d6 authored by Allison Karlitskaya's avatar Allison Karlitskaya

Bug 620519 - GPermission

Add an abstract interface representing the permission to perform an
action.
parent 07b5cee2
......@@ -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"/>
......
......@@ -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>
......@@ -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
......
......@@ -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 \
......
......@@ -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>
......
......@@ -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
......@@ -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;
......
/*
* 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"
/*
* 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__ */
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment