[libsecret/wip/dueno/simple-item: 1/8] secret-retrievable: New interface to represent read-only item

[Daiki Ueno <dueno src gnome org>]

commit b5b773ff6395fd7c86b4c114ccf938444cfa2199
Author: Daiki Ueno <dueno src gnome org>
Date:   Mon Jun 17 15:30:00 2019 +0200

    secret-retrievable: New interface to represent read-only item
    
    This is a ground work for adding a local storage backend.  As
    SecretItem is derived from GDBusProxy, it cannot be simply exposed to
    the application through the secret_password_search() if the item is
    not backed by the DBus API.  This adds an abstract interface
    representing a read-only view of a secret item for that purpose.

 docs/reference/libsecret/libsecret-docs.sgml    |   1 +
 docs/reference/libsecret/libsecret-sections.txt |  15 ++
 libsecret/Makefile.am                           |   2 +
 libsecret/meson.build                           |   4 +
 libsecret/secret-retrievable.c                  | 278 ++++++++++++++++++++++++
 libsecret/secret-retrievable.h                  |  64 ++++++
 libsecret/secret.h                              |   1 +
 7 files changed, 365 insertions(+)
---
diff --git a/docs/reference/libsecret/libsecret-docs.sgml b/docs/reference/libsecret/libsecret-docs.sgml
index 6ce3dba..0381c5a 100644
--- a/docs/reference/libsecret/libsecret-docs.sgml
+++ b/docs/reference/libsecret/libsecret-docs.sgml
@@ -26,6 +26,7 @@
                <xi:include href="xml/secret-service.xml"/>
                <xi:include href="xml/secret-collection.xml"/>
                <xi:include href="xml/secret-item.xml"/>
+               <xi:include href="xml/secret-retrievable.xml"/>
                <xi:include href="xml/secret-value.xml"/>
                <xi:include href="xml/secret-attributes.xml"/>
                <xi:include href="xml/secret-prompt.xml"/>
diff --git a/docs/reference/libsecret/libsecret-sections.txt b/docs/reference/libsecret/libsecret-sections.txt
index 2ae7250..17ee05f 100644
--- a/docs/reference/libsecret/libsecret-sections.txt
+++ b/docs/reference/libsecret/libsecret-sections.txt
@@ -137,6 +137,21 @@ secret_password_wipe
 secret_password_free
 </SECTION>
 
+<SECTION>
+<FILE>secret-retrievable</FILE>
+<INCLUDE>libsecret/secret.h</INCLUDE>
+SECRET_TYPE_RETRIEVABLE
+SecretRetrievable
+SecretRetrievableInterface
+secret_retrievable_get_attributes
+secret_retrievable_get_created
+secret_retrievable_get_label
+secret_retrievable_get_modified
+secret_retrievable_retrieve_secret
+secret_retrievable_retrieve_secret_finish
+secret_retrievable_retrieve_secret_sync
+</SECTION>
+
 <SECTION>
 <FILE>secret-schema</FILE>
 <INCLUDE>libsecret/secret.h</INCLUDE>
diff --git a/libsecret/Makefile.am b/libsecret/Makefile.am
index c91b733..0e661b8 100644
--- a/libsecret/Makefile.am
+++ b/libsecret/Makefile.am
@@ -12,6 +12,7 @@ libsecret_HEADS = \
        libsecret/secret-password.h \
        libsecret/secret-paths.h \
        libsecret/secret-prompt.h \
+       libsecret/secret-retrievable.h \
        libsecret/secret-schema.h \
        libsecret/secret-schemas.h \
        libsecret/secret-service.h \
@@ -42,6 +43,7 @@ libsecret_PUBLIC = \
        libsecret/secret-methods.c \
        libsecret/secret-password.h libsecret/secret-password.c \
        libsecret/secret-prompt.h libsecret/secret-prompt.c \
+       libsecret/secret-retrievable.h libsecret/secret-retrievable.c \
        libsecret/secret-schema.h libsecret/secret-schema.c \
        libsecret/secret-schemas.h libsecret/secret-schemas.c \
        libsecret/secret-service.h libsecret/secret-service.c \
diff --git a/libsecret/meson.build b/libsecret/meson.build
index f35c396..60fa11e 100644
--- a/libsecret/meson.build
+++ b/libsecret/meson.build
@@ -7,6 +7,7 @@ libsecret_sources = [
   'secret-methods.c',
   'secret-password.c',
   'secret-prompt.c',
+  'secret-retrievable.c',
   'secret-schema.c',
   'secret-schemas.c',
   'secret-service.c',
@@ -24,6 +25,7 @@ libsecret_headers = [
   'secret-password.h',
   'secret-paths.h',
   'secret-prompt.h',
+  'secret-retrievable.h',
   'secret-schema.h',
   'secret-schemas.h',
   'secret-service.h',
@@ -104,6 +106,8 @@ libsecret_gir_sources = [
   'secret-paths.h',
   'secret-prompt.c',
   'secret-prompt.h',
+  'secret-retrievable.c',
+  'secret-retrievable.h',
   'secret-schema.c',
   'secret-schema.h',
   'secret-schemas.c',
diff --git a/libsecret/secret-retrievable.c b/libsecret/secret-retrievable.c
new file mode 100644
index 0000000..9ac00df
--- /dev/null
+++ b/libsecret/secret-retrievable.c
@@ -0,0 +1,278 @@
+/* libsecret - GLib wrapper for Secret Service
+ *
+ * Copyright 2019 Red Hat, Inc.
+ *
+ * This program 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 licence or (at
+ * your option) any later version.
+ *
+ * See the included COPYING file for more information.
+ *
+ * Author: Daiki Ueno
+ */
+
+#include "config.h"
+
+#include "secret-retrievable.h"
+#include "secret-private.h"
+
+/**
+ * SECTION:secret-retrievable
+ * @title: SecretRetrievable
+ * @short_description: A read-only secret item
+ *
+ * #SecretRetrievable provides a read-only view of a secret item
+ * stored in the Secret Service.
+ *
+ * Each item has a value, represented by a #SecretValue, which can be
+ * retrieved by secret_retrievable_retrieve() and
+ * secret_retrievable_retrieve_finish().
+ *
+ * Stability: Stable
+ */
+
+/**
+ * SecretRetrievable:
+ *
+ * An object representing a read-only view of a secret item in the Secret Service.
+ */
+
+/**
+ * SecretRetrievableInterface:
+ * @parent_iface: the parent interface
+ * @retrieve_secret: implementation of secret_retrievable_retrieve_secret(), required
+ * @retrieve_secret_finish: implementation of secret_retrievable_retrieve_secret_finish(), required
+ *
+ * The interface for #SecretRetrievable.
+ */
+
+G_DEFINE_INTERFACE (SecretRetrievable, secret_retrievable, G_TYPE_OBJECT);
+
+static void
+secret_retrievable_default_init (SecretRetrievableInterface *iface)
+{
+       /**
+        * SecretRetrievable:attributes: (type GLib.HashTable(utf8,utf8)) (transfer full)
+        *
+        * The attributes set on this item. Attributes are used to locate an
+        * item. They are not guaranteed to be stored or transferred securely.
+        */
+       g_object_interface_install_property (iface,
+                    g_param_spec_boxed ("attributes", "Attributes", "Item attributes",
+                                        G_TYPE_HASH_TABLE, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+       /**
+        * SecretRetrievable:label:
+        *
+        * The human readable label for the item.
+        */
+       g_object_interface_install_property (iface,
+                   g_param_spec_string ("label", "Label", "Item label",
+                                        NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+       /**
+        * SecretRetrievable:created:
+        *
+        * The date and time (in seconds since the UNIX epoch) that this
+        * item was created.
+        */
+       g_object_interface_install_property (iface,
+                   g_param_spec_uint64 ("created", "Created", "Item creation date",
+                                        0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+
+       /**
+        * SecretRetrievable:modified:
+        *
+        * The date and time (in seconds since the UNIX epoch) that this
+        * item was last modified.
+        */
+       g_object_interface_install_property (iface,
+                   g_param_spec_uint64 ("modified", "Modified", "Item modified date",
+                                        0UL, G_MAXUINT64, 0UL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
+}
+
+/**
+ * secret_retrievable_retrieve_secret:
+ * @self: a retrievable object
+ * @cancellable: optional cancellation object
+ * @callback: called when the operation completes
+ * @user_data: data to pass to the callback
+ *
+ * Retrieve the secret value of this object.
+ *
+ * Each retrievable object has a single secret which might be a
+ * password or some other secret binary value.
+ *
+ * This function returns immediately and completes asynchronously.
+ */
+void
+secret_retrievable_retrieve_secret (SecretRetrievable *self,
+                                   GCancellable *cancellable,
+                                   GAsyncReadyCallback callback,
+                                   gpointer user_data)
+{
+       SecretRetrievableInterface *iface;
+
+       g_return_if_fail (SECRET_IS_RETRIEVABLE (self));
+       iface = SECRET_RETRIEVABLE_GET_IFACE (self);
+       g_return_if_fail (iface->retrieve_secret != NULL);
+       iface->retrieve_secret (self, cancellable, callback, user_data);
+}
+
+/**
+ * secret_retrievable_retrieve_secret_finish:
+ * @self: a retrievable object
+ * @result: asynchronous result passed to callback
+ * @error: location to place error on failure
+ *
+ * Complete asynchronous operation to retrieve the secret value of this object.
+ *
+ * Returns: (transfer full) (nullable): the secret value which should be
+ *          released with secret_value_unref(), or %NULL
+ */
+SecretValue *
+secret_retrievable_retrieve_secret_finish (SecretRetrievable *self,
+                                          GAsyncResult *result,
+                                          GError **error)
+{
+       SecretRetrievableInterface *iface;
+
+       g_return_val_if_fail (SECRET_IS_RETRIEVABLE (self), NULL);
+       iface = SECRET_RETRIEVABLE_GET_IFACE (self);
+       g_return_val_if_fail (iface->retrieve_secret_finish != NULL, NULL);
+       return iface->retrieve_secret_finish (self, result, error);
+}
+
+/**
+ * secret_retrievable_retrieve_secret_sync:
+ * @self: a retrievable object
+ * @cancellable: optional cancellation object
+ * @error: location to place error on failure
+ *
+ * Retrieve the secret value of this object synchronously.
+ *
+ * Each retrievable object has a single secret which might be a
+ * password or some other secret binary value.
+ *
+ * This method may block indefinitely and should not be used in user interface
+ * threads.
+ *
+ * Returns: (transfer full) (nullable): the secret value which should be
+ *          released with secret_value_unref(), or %NULL
+ */
+SecretValue *
+secret_retrievable_retrieve_secret_sync (SecretRetrievable *self,
+                                        GCancellable *cancellable,
+                                        GError **error)
+{
+       SecretSync *sync;
+       SecretValue *value;
+
+       g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
+       g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
+
+       sync = _secret_sync_new ();
+       g_main_context_push_thread_default (sync->context);
+
+       secret_retrievable_retrieve_secret (self,
+                                           cancellable,
+                                           _secret_sync_on_result, sync);
+
+       g_main_loop_run (sync->loop);
+
+       value = secret_retrievable_retrieve_secret_finish (self,
+                                                          sync->result,
+                                                          error);
+
+       g_main_context_pop_thread_default (sync->context);
+       _secret_sync_free (sync);
+
+       return value;
+}
+
+/**
+ * secret_retrievable_get_attributes:
+ * @self: a retrievable object
+ *
+ * Get the attributes of this object.
+ *
+ * The attributes are a mapping of string keys to string values.
+ * Attributes are used to search for items. Attributes are not stored
+ * or transferred securely by the secret service.
+ *
+ * Do not modify the attribute returned by this method.
+ *
+ * Returns: (transfer full) (element-type utf8 utf8): a new reference
+ *          to the attributes, which should not be modified, and
+ *          released with g_hash_table_unref()
+ */
+GHashTable *
+secret_retrievable_get_attributes (SecretRetrievable *self)
+{
+       GValue value;
+
+       g_return_val_if_fail (SECRET_IS_RETRIEVABLE (self), NULL);
+
+       g_object_get_property (G_OBJECT (self), "attributes", &value);
+       return g_value_dup_boxed (&value);
+}
+
+/**
+ * secret_retrievable_get_label:
+ * @self: a retrievable object
+ *
+ * Get the label of this item.
+ *
+ * Returns: the label
+ */
+const gchar *
+secret_retrievable_get_label (SecretRetrievable *self)
+{
+       GValue value;
+
+       g_return_val_if_fail (SECRET_IS_RETRIEVABLE (self), NULL);
+
+       g_object_get_property (G_OBJECT (self), "label", &value);
+       return g_value_get_string (&value);
+}
+
+/**
+ * secret_retrievable_get_created:
+ * @self: a retrievable object
+ *
+ * Get the created date and time of the object. The return value is
+ * the number of seconds since the unix epoch, January 1st 1970.
+ *
+ * Returns: the created date and time
+ */
+guint64
+secret_retrievable_get_created (SecretRetrievable *self)
+{
+       GValue value;
+
+       g_return_val_if_fail (SECRET_IS_RETRIEVABLE (self), 0);
+
+       g_object_get_property (G_OBJECT (self), "created", &value);
+       return g_value_get_uint64 (&value);
+}
+
+/**
+ * secret_retrievable_get_modified:
+ * @self: a retrievable object
+ *
+ * Get the modified date and time of the object. The return value is
+ * the number of seconds since the unix epoch, January 1st 1970.
+ *
+ * Returns: the modified date and time
+ */
+guint64
+secret_retrievable_get_modified (SecretRetrievable *self)
+{
+       GValue value;
+
+       g_return_val_if_fail (SECRET_IS_RETRIEVABLE (self), 0);
+
+       g_object_get_property (G_OBJECT (self), "modified", &value);
+       return g_value_get_uint64 (&value);
+}
diff --git a/libsecret/secret-retrievable.h b/libsecret/secret-retrievable.h
new file mode 100644
index 0000000..670f501
--- /dev/null
+++ b/libsecret/secret-retrievable.h
@@ -0,0 +1,64 @@
+/* libsecret - GLib wrapper for Secret Service
+ *
+ * Copyright 2019 Red Hat, Inc.
+ *
+ * This program 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 licence or (at
+ * your option) any later version.
+ *
+ * See the included COPYING file for more information.
+ *
+ * Author: Daiki Ueno
+ */
+
+#if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION)
+#error "Only <libsecret/secret.h> can be included directly."
+#endif
+
+#ifndef __SECRET_RETRIEVABLE_H__
+#define __SECRET_RETRIEVABLE_H__
+
+#include <glib-object.h>
+#include "secret-value.h"
+
+G_BEGIN_DECLS
+
+#define SECRET_TYPE_RETRIEVABLE secret_retrievable_get_type ()
+G_DECLARE_INTERFACE (SecretRetrievable, secret_retrievable, SECRET, RETRIEVABLE, GObject)
+
+struct _SecretRetrievableInterface
+{
+       GTypeInterface parent_iface;
+
+       void         (*retrieve_secret)        (SecretRetrievable *self,
+                                               GCancellable *cancellable,
+                                               GAsyncReadyCallback callback,
+                                               gpointer user_data);
+       SecretValue *(*retrieve_secret_finish) (SecretRetrievable *self,
+                                               GAsyncResult *result,
+                                               GError **error);
+};
+
+void         secret_retrievable_retrieve_secret        (SecretRetrievable *self,
+                                                       GCancellable *cancellable,
+                                                       GAsyncReadyCallback callback,
+                                                       gpointer user_data);
+
+SecretValue *secret_retrievable_retrieve_secret_finish (SecretRetrievable *self,
+                                                       GAsyncResult *result,
+                                                       GError **error);
+
+SecretValue *secret_retrievable_retrieve_secret_sync   (SecretRetrievable *self,
+                                                       GCancellable *cancellable,
+                                                       GError **error);
+
+GHashTable  *secret_retrievable_get_attributes         (SecretRetrievable *self);
+const gchar *secret_retrievable_get_label              (SecretRetrievable *self);
+guint64      secret_retrievable_get_created            (SecretRetrievable *self);
+guint64      secret_retrievable_get_modified           (SecretRetrievable *self);
+
+
+G_END_DECLS
+
+#endif /* __SECRET_RETRIEVABLE_H__ */
diff --git a/libsecret/secret.h b/libsecret/secret.h
index 8d11324..7e6e7c6 100644
--- a/libsecret/secret.h
+++ b/libsecret/secret.h
@@ -25,6 +25,7 @@
 #include <libsecret/secret-item.h>
 #include <libsecret/secret-password.h>
 #include <libsecret/secret-prompt.h>
+#include <libsecret/secret-retrievable.h>
 #include <libsecret/secret-schema.h>
 #include <libsecret/secret-schemas.h>
 #include <libsecret/secret-service.h>