From 9c20c4d65ea0e95ee589f50fe66bb4fb13bc5b03 Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Thu, 2 Feb 2012 13:40:47 +0100 Subject: [PATCH] Initial gobject-introspection support --- .gitignore | 3 + build/Makefile.am | 11 +- configure.ac | 27 + library/Makefile.am | 85 +- library/libsecret.pc.in | 14 + library/secret-collection.c | 183 +++-- library/secret-collection.h | 80 +- library/secret-item.c | 598 ++++++++++++--- library/secret-item.h | 150 ++-- library/secret-methods.c | 1449 ++++++++++++++++++++++++++++------- library/secret-password.c | 471 +++++++++--- library/secret-password.h | 124 +-- library/secret-private.h | 90 +-- library/secret-prompt.c | 117 ++- library/secret-prompt.h | 35 +- library/secret-service.c | 439 +++++++++-- library/secret-service.h | 502 ++++++------ library/secret-session.c | 10 +- library/secret-types.h | 4 + library/secret-util.c | 46 +- library/secret-value.c | 88 ++- library/secret-value.h | 30 +- library/secret.h | 34 + library/tests/Makefile.am | 5 +- library/tests/test-prompt.c | 24 +- 25 files changed, 3411 insertions(+), 1208 deletions(-) create mode 100644 library/libsecret.pc.in create mode 100644 library/secret.h diff --git a/.gitignore b/.gitignore index 94adb16..0da3c1e 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,9 @@ *.gcov *.gcno *.gcda +*.gir +*.pc +*.typelib .deps .cproject .libs diff --git a/build/Makefile.am b/build/Makefile.am index 52eb08c..f1cc400 100644 --- a/build/Makefile.am +++ b/build/Makefile.am @@ -1,19 +1,22 @@ +include $(top_srcdir)/Makefile.decl VALGRIND_CONTRIB = \ valgrind.h \ - memcheck.h + memcheck.h \ + $(NULL) SUPPRESSIONS = \ gcrypt.supp \ glib.supp \ pthread.supp \ - unknown.supp + unknown.supp \ + $(NULL) valgrind-suppressions: $(SUPPRESSIONS) $(AM_V_GEN) cat $(SUPPRESSIONS) > $@ EXTRA_DIST = \ - $(VALGRIND_CONTRIB) \ + valgrind \ $(SUPPRESSIONS) -all-local: valgrind-suppressions \ No newline at end of file +all-local: valgrind-suppressions diff --git a/configure.ac b/configure.ac index 0c586c3..4c37406 100644 --- a/configure.ac +++ b/configure.ac @@ -3,6 +3,23 @@ AC_CONFIG_MACRO_DIR([build/m4]) AC_INIT([libsecret],[0.1],[http://bugzilla.gnome.org/enter_bug.cgi?product=libsecret]) +dnl **************************************************************************** +dnl Library package and libtool versioning +dnl +dnl Updating the libtool versions, follow these instructions sequentially: +dnl 1. If the library source code has changed at all since the last update, then increment revision (‘c:r:a’ becomes ‘c:r+1:a’). +dnl 2. If any interfaces have been added, removed, or changed since the last update, increment current, and set revision to 0. +dnl 3. If any interfaces have been added since the last public release, then increment age. +dnl 4. If any interfaces have been removed or changed since the last public release, then set age to 0. + +SECRET_MAJOR=0 +SECRET_MINOR=0 +SECRET_MICRO=0 + +SECRET_CURRENT=0 +SECRET_REVISION=0 +SECRET_AGE=0 + AC_CONFIG_SRCDIR([library/secret-value.c]) AC_CONFIG_HEADERS([config.h]) @@ -41,6 +58,7 @@ PKG_CHECK_MODULES(GLIB, LIBS="$LIBS $GLIB_LIBS" CFLAGS="$CFLAGS $GLIB_CFLAGS" +GOBJECT_INTROSPECTION_CHECK([1.29]) AC_PATH_PROG(GLIB_MKENUMS, glib-mkenums) # -------------------------------------------------------------------- @@ -120,13 +138,16 @@ if test "$enable_strict" = "yes"; then -DGDK_DISABLE_DEPRECATED \ -DG_DISABLE_DEPRECATED \ -DGDK_PIXBUF_DISABLE_DEPRECATED" + INTROSPECTION_FLAGS="--warn-error" TEST_MODE="thorough" else TEST_MODE="quick" + INTROSPECTION_FLAGS="" $enable_strict="no" fi AC_MSG_RESULT($enable_strict) +AC_SUBST(INTROSPECTION_FLAGS) AC_SUBST(TEST_MODE) AC_MSG_CHECKING([for debug mode]) @@ -192,6 +213,11 @@ AC_SUBST(GENHTML) # Results # +SECRET_LT_RELEASE=$SECRET_CURRENT:$SECRET_REVISION:$SECRET_AGE +AC_SUBST(SECRET_LT_RELEASE) +AC_SUBST(SECRET_MAJOR) +AC_SUBST(SECRET_MINOR) + AC_CONFIG_FILES([ Makefile build/Makefile @@ -200,6 +226,7 @@ AC_CONFIG_FILES([ po/Makefile.in po/Makefile library/Makefile + library/libsecret.pc library/tests/Makefile ]) AC_OUTPUT diff --git a/library/Makefile.am b/library/Makefile.am index 086a3da..9f7aa92 100644 --- a/library/Makefile.am +++ b/library/Makefile.am @@ -3,6 +3,7 @@ include $(top_srcdir)/Makefile.decl SUBDIRS = . tests module_flags = \ + -version-info $(SECRET_LT_RELEASE) \ -export_dynamic \ -avoid-version \ -module \ @@ -12,37 +13,58 @@ module_flags = \ INCLUDES = \ -DSECRET_COMPILATION -lib_LTLIBRARIES = libsecret.la +lib_LTLIBRARIES = libsecret-@SECRET_MAJOR@.la + + +incdir = $(includedir)/secret-@SECRET_MAJOR@/secret HEADER_FILES = \ + secret.h \ secret-collection.h \ secret-item.h \ secret-password.h \ secret-prompt.h \ secret-service.h \ - secret-value.h + secret-types.h \ + secret-value.h \ + $(NULL) + +inc_HEADERS = \ + $(HEADER_FILES) \ + secret-enum-types.h \ + $(NULL) BUILT_SOURCES = \ secret-dbus-generated.c secret-dbus-generated.h \ - secret-enum-types.c secret-enum-types.h + secret-enum-types.c secret-enum-types.h \ + $(NULL) -libsecret_la_SOURCES = \ +PUBLIC_FILES = \ secret-collection.h secret-collection.c \ secret-item.h secret-item.c \ secret-methods.c \ secret-password.h secret-password.c \ secret-prompt.h secret-prompt.c \ secret-service.h secret-service.c \ - secret-session.h secret-session.c \ - secret-util.c \ + secret-types.h \ secret-value.h secret-value.c \ + $(NULL) + +INTERNAL_FILES = \ + secret-session.c \ + secret-util.c \ + $(NULL) + +libsecret_@SECRET_MAJOR@_la_SOURCES = \ + $(PUBLIC_FILES) \ + $(INTERNAL_FILES) \ $(BUILT_SOURCES) \ $(NULL) -libsecret_la_CFLAGS = \ +libsecret_@SECRET_MAJOR@_la_CFLAGS = \ $(LIBGCRYPT_CFLAGS) -libsecret_la_LIBADD = \ +libsecret_@SECRET_MAJOR@_la_LIBADD = \ $(top_builddir)/egg/libegg.la \ $(LIBGCRYPT_LIBS) \ $(LIBS) @@ -64,9 +86,52 @@ secret-enum-types.h: secret-enum-types.h.template $(HEADER_FILES) secret-enum-types.c: secret-enum-types.c.template $(HEADER_FILES) $(AM_V_GEN) $(GLIB_MKENUMS) --template $^ > $@ +# ------------------------------------------------------------------ +# INTROSPECTION + +if HAVE_INTROSPECTION + +include $(INTROSPECTION_MAKEFILE) + +INTROSPECTION_GIRS = Secret-@SECRET_MAJOR@.gir +INTROSPECTION_SCANNER_ARGS = $(INTROSPECTION_FLAGS) --warn-all --add-include-path=$(srcdir) --add-include-path=. +INTROSPECTION_COMPILER_ARGS = --includedir=$(srcdir) --includedir=. + +Secret-@SECRET_MAJOR@.gir: libsecret-@SECRET_MAJOR@.la + +Secret_@SECRET_MAJOR@_gir_PACKAGES = gobject-2.0 gio-2.0 +Secret_@SECRET_MAJOR@_gir_EXPORT_PACKAGES = libsecret-@SECRET_MAJOR@ +Secret_@SECRET_MAJOR@_gir_INCLUDES = GObject-2.0 Gio-2.0 +Secret_@SECRET_MAJOR@_gir_LIBS = libsecret-@SECRET_MAJOR@.la +Secret_@SECRET_MAJOR@_gir_CFLAGS = -I$(top_srcdir) -I$(top_builddir) -DSECRET_COMPILATION -DSECRET_API_SUBJECT_TO_CHANGE +Secret_@SECRET_MAJOR@_gir_FILES = $(PUBLIC_FILES) +Secret_@SECRET_MAJOR@_gir_SCANNERFLAGS = --c-include "secret.h" + +girdir = $(datadir)/gir-1.0 +gir_DATA = $(INTROSPECTION_GIRS) + +typelibsdir = $(libdir)/girepository-1.0 +typelibs_DATA = $(INTROSPECTION_GIRS:.gir=.typelib) + +endif + +# ------------------------------------------------------------------ +# PKG CONFIG + +libsecret-$(SECRET_MAJOR).pc: libsecret.pc + cp libsecret.pc libsecret-$(SECRET_MAJOR).pc + +pkgconfigdir = $(libdir)/pkgconfig +pkgconfig_DATA = libsecret-$(SECRET_MAJOR).pc + +# ------------------------------------------------------------------ + + EXTRA_DIST = \ secret-enum-types.h.template \ - secret-enum-types.c.template + secret-enum-types.c.template \ + org.freedesktop.Secrets.xml \ + $(NULL) check-memory: - make -C tests check-memory \ No newline at end of file + make -C tests check-memory diff --git a/library/libsecret.pc.in b/library/libsecret.pc.in new file mode 100644 index 0000000..a42b3b9 --- /dev/null +++ b/library/libsecret.pc.in @@ -0,0 +1,14 @@ +prefix=@prefix@ +exec_prefix=@exec_prefix@ +libdir=@libdir@ +includedir=@includedir@ +datarootdir=@datarootdir@ +datadir=@datadir@ +sysconfdir=@sysconfdir@ + +Name: libsecret-@SECRET_MAJOR@ +Description: GObject bindings for Secret Service API +Version: @VERSION@ +Requires: glib-2.0 gobject-2.0 gio-2.0 +Libs: -L${libdir} -lsecret-@SECRET_MAJOR@ +Cflags: -I${includedir}/secret-@SECRET_MAJOR@ diff --git a/library/secret-collection.c b/library/secret-collection.c index 4033917..ee7ac74 100644 --- a/library/secret-collection.c +++ b/library/secret-collection.c @@ -21,14 +21,6 @@ #include -/** - * SECTION:secret-collection - */ - -/** - * SecretCollection: - */ - enum { PROP_0, PROP_SERVICE, @@ -101,9 +93,9 @@ on_set_label (GObject *source, static void secret_collection_set_property (GObject *obj, - guint prop_id, - const GValue *value, - GParamSpec *pspec) + guint prop_id, + const GValue *value, + GParamSpec *pspec) { SecretCollection *self = SECRET_COLLECTION (obj); @@ -117,8 +109,8 @@ secret_collection_set_property (GObject *obj, break; case PROP_LABEL: secret_collection_set_label (self, g_value_get_string (value), - self->pv->cancellable, on_set_label, - g_object_ref (self)); + self->pv->cancellable, on_set_label, + g_object_ref (self)); break; default: G_OBJECT_WARN_INVALID_PROPERTY_ID (obj, prop_id, pspec); @@ -128,9 +120,9 @@ secret_collection_set_property (GObject *obj, static void secret_collection_get_property (GObject *obj, - guint prop_id, - GValue *value, - GParamSpec *pspec) + guint prop_id, + GValue *value, + GParamSpec *pspec) { SecretCollection *self = SECRET_COLLECTION (obj); @@ -296,7 +288,7 @@ collection_load_items_async (SecretCollection *self, /* No such collection yet create a new one */ if (item == NULL) { secret_item_new (self->pv->service, path, cancellable, - on_load_item, g_object_ref (res)); + on_load_item, g_object_ref (res)); closure->items_loading++; } else { @@ -349,7 +341,7 @@ collection_load_items_sync (SecretCollection *self, /* No such collection yet create a new one */ if (item == NULL) { item = secret_item_new_sync (self->pv->service, path, - cancellable, error); + cancellable, error); if (item == NULL) { ret = FALSE; break; @@ -390,8 +382,8 @@ handle_property_changed (SecretCollection *self, static void secret_collection_properties_changed (GDBusProxy *proxy, - GVariant *changed_properties, - const gchar* const *invalidated_properties) + GVariant *changed_properties, + const gchar* const *invalidated_properties) { SecretCollection *self = SECRET_COLLECTION (proxy); gchar *property_name; @@ -449,8 +441,8 @@ secret_collection_class_init (SecretCollectionClass *klass) static gboolean secret_collection_initable_init (GInitable *initable, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { SecretCollection *self; GDBusProxy *proxy; @@ -523,7 +515,7 @@ on_init_base (GObject *source, GError *error = NULL; if (!secret_collection_async_initable_parent_iface->init_finish (G_ASYNC_INITABLE (self), - result, &error)) { + result, &error)) { g_simple_async_result_take_error (res, error); g_simple_async_result_complete (res); @@ -543,10 +535,10 @@ on_init_base (GObject *source, static void secret_collection_async_initable_init_async (GAsyncInitable *initable, - int io_priority, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + int io_priority, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; InitClosure *closure; @@ -558,17 +550,17 @@ secret_collection_async_initable_init_async (GAsyncInitable *initable, g_simple_async_result_set_op_res_gpointer (res, closure, init_closure_free); secret_collection_async_initable_parent_iface->init_async (initable, io_priority, - cancellable, - on_init_base, - g_object_ref (res)); + cancellable, + on_init_base, + g_object_ref (res)); g_object_unref (res); } static gboolean secret_collection_async_initable_init_finish (GAsyncInitable *initable, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { g_return_val_if_fail (g_simple_async_result_is_valid (result, G_OBJECT (initable), secret_collection_async_initable_init_async), FALSE); @@ -599,16 +591,13 @@ secret_collection_async_initable_iface (GAsyncInitableIface *iface) * Get a new collection proxy for a collection in the secret service. * * This method will return immediately and complete asynchronously. - * - * Returns: (transfer full): the new collection, which should be unreferenced - * with g_object_unref() */ void secret_collection_new (SecretService *service, - const gchar *collection_path, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar *collection_path, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GDBusProxy *proxy; @@ -641,10 +630,9 @@ secret_collection_new (SecretService *service, * Returns: (transfer full): the new collection, which should be unreferenced * with g_object_unref() */ - SecretCollection * secret_collection_new_finish (GAsyncResult *result, - GError **error) + GError **error) { GObject *source_object; GObject *object; @@ -672,16 +660,17 @@ secret_collection_new_finish (GAsyncResult *result, * * Get a new collection proxy for a collection in the secret service. * - * This method may block indefinitely. + * This method may block indefinitely and should not be used in user interface + * threads. * * Returns: (transfer full): the new collection, which should be unreferenced * with g_object_unref() */ SecretCollection * secret_collection_new_sync (SecretService *service, - const gchar *collection_path, - GCancellable *cancellable, - GError **error) + const gchar *collection_path, + GCancellable *cancellable, + GError **error) { GDBusProxy *proxy; @@ -704,6 +693,16 @@ secret_collection_new_sync (SecretService *service, NULL); } +/** + * secret_collection_refresh: + * @self: the collection + * + * Refresh the properties on this collection. This fires off a request to + * refresh, and the properties will be updated later. + * + * Calling this method is not normally necessary, as the secret service + * will notify the client when properties change. + */ void secret_collection_refresh (SecretCollection *self) { @@ -759,7 +758,7 @@ on_create_path (GObject *source, path = secret_service_create_collection_path_finish (service, result, &error); if (error == NULL) { secret_collection_new (service, path, closure->cancellable, - on_create_collection, g_object_ref (res)); + on_create_collection, g_object_ref (res)); } else { g_simple_async_result_take_error (res, error); g_simple_async_result_complete (res); @@ -801,11 +800,11 @@ collection_properties_new (const gchar *label) */ void secret_collection_create (SecretService *service, - const gchar *label, - const gchar *alias, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar *label, + const gchar *alias, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; CreateClosure *closure; @@ -824,7 +823,7 @@ secret_collection_create (SecretService *service, properties = collection_properties_new (label); secret_service_create_collection_path (service, properties, alias, cancellable, - on_create_path, g_object_ref (res)); + on_create_path, g_object_ref (res)); g_hash_table_unref (properties); g_object_unref (res); @@ -842,7 +841,7 @@ secret_collection_create (SecretService *service, */ SecretCollection * secret_collection_create_finish (GAsyncResult *result, - GError **error) + GError **error) { GSimpleAsyncResult *res; CreateClosure *closure; @@ -873,19 +872,19 @@ secret_collection_create_finish (GAsyncResult *result, * * Create a new collection in the secret service. * - * This method may block indefinitely. The secret service may prompt the - * user. secret_service_prompt() will be used to handle any prompts that - * are required. + * This method may block indefinitely and should not be used in user interface + * threads. The secret service may prompt the user. secret_service_prompt() + * will be used to handle any prompts that are required. * * Returns: (transfer full): the new collection, which should be unreferenced * with g_object_unref() */ SecretCollection * secret_collection_create_sync (SecretService *service, - const gchar *label, - const gchar *alias, - GCancellable *cancellable, - GError **error) + const gchar *label, + const gchar *alias, + GCancellable *cancellable, + GError **error) { SecretCollection *collection; GHashTable *properties; @@ -899,7 +898,7 @@ secret_collection_create_sync (SecretService *service, properties = collection_properties_new (label); path = secret_service_create_collection_path_sync (service, properties, alias, - cancellable, error); + cancellable, error); g_hash_table_unref (properties); @@ -924,14 +923,12 @@ secret_collection_create_sync (SecretService *service, * This method returns immediately and completes asynchronously. The secret * service may prompt the user. secret_service_prompt() will be used to handle * any prompts that show up. - * - * Returns: whether the item was successfully deleted or not */ void secret_collection_delete (SecretCollection *self, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { const gchar *object_path; @@ -940,7 +937,7 @@ secret_collection_delete (SecretCollection *self, object_path = g_dbus_proxy_get_object_path (G_DBUS_PROXY (self)); _secret_service_delete_path (self->pv->service, object_path, FALSE, - cancellable, callback, user_data); + cancellable, callback, user_data); } /** @@ -951,12 +948,12 @@ secret_collection_delete (SecretCollection *self, * * Complete operation to delete this collection. * - * Returns: whether the item was successfully deleted or not + * Returns: whether the collection was successfully deleted or not */ gboolean secret_collection_delete_finish (SecretCollection *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { g_return_val_if_fail (SECRET_IS_COLLECTION (self), FALSE); g_return_val_if_fail (error == NULL || *error == NULL, FALSE); @@ -972,16 +969,16 @@ secret_collection_delete_finish (SecretCollection *self, * * Delete this collection. * - * This method may block indefinitely. The secret service may prompt the - * user. secret_service_prompt() will be used to handle any prompts that - * show up. + * This method may block indefinitely and should not be used in user + * interface threads. The secret service may prompt the user. + * secret_service_prompt() will be used to handle any prompts that show up. * - * Returns: whether the item was successfully deleted or not + * Returns: whether the collection was successfully deleted or not */ gboolean secret_collection_delete_sync (SecretCollection *self, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { SecretSync *sync; gboolean ret; @@ -1033,7 +1030,7 @@ secret_collection_get_items (SecretCollection *self) SecretItem * _secret_collection_find_item_instance (SecretCollection *self, - const gchar *item_path) + const gchar *item_path) { SecretItem *item; @@ -1085,18 +1082,18 @@ secret_collection_get_label (SecretCollection *self) */ void secret_collection_set_label (SecretCollection *self, - const gchar *label, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar *label, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { g_return_if_fail (SECRET_IS_COLLECTION (self)); g_return_if_fail (label != NULL); _secret_util_set_property (G_DBUS_PROXY (self), "Label", - g_variant_new_string (label), - secret_collection_set_label, - cancellable, callback, user_data); + g_variant_new_string (label), + secret_collection_set_label, + cancellable, callback, user_data); } /** @@ -1111,14 +1108,14 @@ secret_collection_set_label (SecretCollection *self, */ gboolean secret_collection_set_label_finish (SecretCollection *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { g_return_val_if_fail (SECRET_IS_COLLECTION (self), FALSE); return _secret_util_set_property_finish (G_DBUS_PROXY (self), - secret_collection_set_label, - result, error); + secret_collection_set_label, + result, error); } /** @@ -1137,16 +1134,16 @@ secret_collection_set_label_finish (SecretCollection *self, */ gboolean secret_collection_set_label_sync (SecretCollection *self, - const gchar *label, - GCancellable *cancellable, - GError **error) + const gchar *label, + GCancellable *cancellable, + GError **error) { g_return_val_if_fail (SECRET_IS_COLLECTION (self), FALSE); g_return_val_if_fail (label != NULL, FALSE); return _secret_util_set_property_sync (G_DBUS_PROXY (self), "Label", - g_variant_new_string (label), - cancellable, error); + g_variant_new_string (label), + cancellable, error); } /** diff --git a/library/secret-collection.h b/library/secret-collection.h index a2721d4..8e60d22 100644 --- a/library/secret-collection.h +++ b/library/secret-collection.h @@ -10,6 +10,10 @@ * See the included COPYING file for more information. */ +#if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) +#error "Only can be included directly." +#endif + #ifndef __SECRET_COLLECTION_H__ #define __SECRET_COLLECTION_H__ @@ -42,68 +46,68 @@ struct _SecretCollectionClass { GType secret_collection_get_type (void) G_GNUC_CONST; void secret_collection_new (SecretService *service, - const gchar *collection_path, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar *collection_path, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); -SecretCollection * secret_collection_new_finish (GAsyncResult *result, - GError **error); +SecretCollection * secret_collection_new_finish (GAsyncResult *result, + GError **error); -SecretCollection * secret_collection_new_sync (SecretService *service, - const gchar *collection_path, - GCancellable *cancellable, - GError **error); +SecretCollection * secret_collection_new_sync (SecretService *service, + const gchar *collection_path, + GCancellable *cancellable, + GError **error); void secret_collection_refresh (SecretCollection *self); void secret_collection_create (SecretService *service, - const gchar *label, - const gchar *alias, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar *label, + const gchar *alias, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); -SecretCollection * secret_collection_create_finish (GAsyncResult *result, - GError **error); +SecretCollection * secret_collection_create_finish (GAsyncResult *result, + GError **error); -SecretCollection * secret_collection_create_sync (SecretService *service, - const gchar *label, - const gchar *alias, - GCancellable *cancellable, - GError **error); +SecretCollection * secret_collection_create_sync (SecretService *service, + const gchar *label, + const gchar *alias, + GCancellable *cancellable, + GError **error); void secret_collection_delete (SecretCollection *self, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_collection_delete_finish (SecretCollection *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); gboolean secret_collection_delete_sync (SecretCollection *self, - GCancellable *cancellable, - GError **error); + GCancellable *cancellable, + GError **error); GList * secret_collection_get_items (SecretCollection *self); gchar * secret_collection_get_label (SecretCollection *self); void secret_collection_set_label (SecretCollection *self, - const gchar *label, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar *label, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_collection_set_label_finish (SecretCollection *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); gboolean secret_collection_set_label_sync (SecretCollection *self, - const gchar *label, - GCancellable *cancellable, - GError **error); + const gchar *label, + GCancellable *cancellable, + GError **error); gboolean secret_collection_get_locked (SecretCollection *self); diff --git a/library/secret-item.c b/library/secret-item.c index e55aaa1..75c493e 100644 --- a/library/secret-item.c +++ b/library/secret-item.c @@ -95,9 +95,9 @@ on_set_label (GObject *source, static void secret_item_set_property (GObject *obj, - guint prop_id, - const GValue *value, - GParamSpec *pspec) + guint prop_id, + const GValue *value, + GParamSpec *pspec) { SecretItem *self = SECRET_ITEM (obj); @@ -111,13 +111,13 @@ secret_item_set_property (GObject *obj, break; case PROP_ATTRIBUTES: secret_item_set_attributes (self, g_value_get_boxed (value), - self->pv->cancellable, on_set_attributes, - g_object_ref (self)); + self->pv->cancellable, on_set_attributes, + g_object_ref (self)); break; case PROP_LABEL: secret_item_set_label (self, g_value_get_string (value), - self->pv->cancellable, on_set_label, - g_object_ref (self)); + self->pv->cancellable, on_set_label, + g_object_ref (self)); break; default: G_OBJECT_WARN_INVALID_PROPERTY_ID (obj, prop_id, pspec); @@ -127,9 +127,9 @@ secret_item_set_property (GObject *obj, static void secret_item_get_property (GObject *obj, - guint prop_id, - GValue *value, - GParamSpec *pspec) + guint prop_id, + GValue *value, + GParamSpec *pspec) { SecretItem *self = SECRET_ITEM (obj); @@ -210,8 +210,8 @@ handle_property_changed (GObject *object, static void secret_item_properties_changed (GDBusProxy *proxy, - GVariant *changed_properties, - const gchar* const *invalidated_properties) + GVariant *changed_properties, + const gchar* const *invalidated_properties) { GObject *obj = G_OBJECT (proxy); gchar *property_name; @@ -273,8 +273,8 @@ secret_item_class_init (SecretItemClass *klass) static gboolean secret_item_initable_init (GInitable *initable, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { GDBusProxy *proxy; @@ -312,7 +312,7 @@ on_init_base (GObject *source, GError *error = NULL; if (!secret_item_async_initable_parent_iface->init_finish (G_ASYNC_INITABLE (self), - result, &error)) { + result, &error)) { g_simple_async_result_take_error (res, error); } else if (!_secret_util_have_cached_properties (proxy)) { @@ -327,10 +327,10 @@ on_init_base (GObject *source, static void secret_item_async_initable_init_async (GAsyncInitable *initable, - int io_priority, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + int io_priority, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; @@ -338,17 +338,17 @@ secret_item_async_initable_init_async (GAsyncInitable *initable, secret_item_async_initable_init_async); secret_item_async_initable_parent_iface->init_async (initable, io_priority, - cancellable, - on_init_base, - g_object_ref (res)); + cancellable, + on_init_base, + g_object_ref (res)); g_object_unref (res); } static gboolean secret_item_async_initable_init_finish (GAsyncInitable *initable, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { g_return_val_if_fail (g_simple_async_result_is_valid (result, G_OBJECT (initable), secret_item_async_initable_init_async), FALSE); @@ -368,12 +368,24 @@ secret_item_async_initable_iface (GAsyncInitableIface *iface) iface->init_finish = secret_item_async_initable_init_finish; } +/** + * secret_item_new: + * @service: a secret service object + * @item_path: the dbus path of the collection + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Get a new item proxy for a secret item in the secret service. + * + * This method will return immediately and complete asynchronously. + */ void secret_item_new (SecretService *service, - const gchar *item_path, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar *item_path, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GDBusProxy *proxy; @@ -395,9 +407,20 @@ secret_item_new (SecretService *service, NULL); } +/** + * secret_item_new_finish: + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Finish asynchronous operation to get a new item proxy for an secret + * item in the secret service. + * + * Returns: (transfer full): the new item, which should be unreferenced + * with g_object_unref() + */ SecretItem * secret_item_new_finish (GAsyncResult *result, - GError **error) + GError **error) { GObject *object; GObject *source_object; @@ -413,11 +436,26 @@ secret_item_new_finish (GAsyncResult *result, return SECRET_ITEM (object); } +/** + * secret_item_new_sync: + * @service: a secret service object + * @item_path: the dbus path of the item + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Get a new item proxy for a secret item in the secret service. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: (transfer full): the new item, which should be unreferenced + * with g_object_unref() + */ SecretItem * secret_item_new_sync (SecretService *service, - const gchar *item_path, - GCancellable *cancellable, - GError **error) + const gchar *item_path, + GCancellable *cancellable, + GError **error) { GDBusProxy *proxy; @@ -440,14 +478,24 @@ secret_item_new_sync (SecretService *service, NULL); } +/** + * secret_item_refresh: + * @self: the collection + * + * Refresh the properties on this item. This fires off a request to + * refresh, and the properties will be updated later. + * + * Calling this method is not normally necessary, as the secret service + * will notify the client when properties change. + */ void secret_item_refresh (SecretItem *self) { g_return_if_fail (SECRET_IS_ITEM (self)); _secret_util_get_properties (G_DBUS_PROXY (self), - secret_item_refresh, - NULL, NULL, NULL); + secret_item_refresh, + NULL, NULL, NULL); } @@ -496,7 +544,7 @@ on_create_path (GObject *source, path = secret_service_create_item_path_finish (service, result, &error); if (error == NULL) { secret_item_new (service, path, closure->cancellable, - on_create_item, g_object_ref (res)); + on_create_item, g_object_ref (res)); } else { g_simple_async_result_take_error (res, error); g_simple_async_result_complete (res); @@ -534,16 +582,37 @@ item_properties_new (const gchar *schema_name, return properties; } +/** + * secret_item_create: + * @collection: a secret collection to create this item in + * @schema_name: schema name for the new item + * @label: label for the new item + * @attributes: attributes for the new item + * @value: secret value for the new item + * @replace: whether to replace an existing item with the same attributes + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Create a new item in the secret service. + * + * If the @replace is set to %TRUE, then the secret service will search for + * an item matching the @attributes, and update that item instead of creating + * a new one. + * + * This method may block indefinitely and should not be used in user interface + * threads. The secret service may prompt the user. secret_service_prompt() + * will be used to handle any prompts that are required. + */ void secret_item_create (SecretCollection *collection, - const gchar *schema_name, - const gchar *label, - GHashTable *attributes, - SecretValue *value, - gboolean replace, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar *schema_name, + const gchar *label, + GHashTable *attributes, + SecretValue *value, + gboolean replace, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { SecretService *service = NULL; const gchar *collection_path; @@ -569,17 +638,27 @@ secret_item_create (SecretCollection *collection, collection_path = g_dbus_proxy_get_object_path (G_DBUS_PROXY (collection)); secret_service_create_item_path (service, collection_path, properties, - value, replace, cancellable, - on_create_path, g_object_ref (res)); + value, replace, cancellable, + on_create_path, g_object_ref (res)); g_hash_table_unref (properties); g_object_unref (service); g_object_unref (res); } +/** + * secret_item_create_finish: + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Finish operation to create a new item in the secret service. + * + * Returns: (transfer full): the new item, which should be unreferenced + * with g_object_unref() + */ SecretItem * secret_item_create_finish (GAsyncResult *result, - GError **error) + GError **error) { GSimpleAsyncResult *res; CreateClosure *closure; @@ -600,15 +679,39 @@ secret_item_create_finish (GAsyncResult *result, return g_object_ref (closure->item); } +/** + * secret_item_create_sync: + * @collection: a secret collection to create this item in + * @schema_name: schema name for the new item + * @label: label for the new item + * @attributes: attributes for the new item + * @value: secret value for the new item + * @replace: whether to replace an existing item with the same attributes + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Create a new item in the secret service. + * + * If the @replace is set to %TRUE, then the secret service will search for + * an item matching the @attributes, and update that item instead of creating + * a new one. + * + * This method may block indefinitely and should not be used in user interface + * threads. The secret service may prompt the user. secret_service_prompt() + * will be used to handle any prompts that are required. + * + * Returns: (transfer full): the new item, which should be unreferenced + * with g_object_unref() + */ SecretItem * secret_item_create_sync (SecretCollection *collection, - const gchar *schema_name, - const gchar *label, - GHashTable *attributes, - SecretValue *value, - gboolean replace, - GCancellable *cancellable, - GError **error) + const gchar *schema_name, + const gchar *label, + GHashTable *attributes, + SecretValue *value, + gboolean replace, + GCancellable *cancellable, + GError **error) { SecretService *service = NULL; const gchar *collection_path; @@ -629,7 +732,7 @@ secret_item_create_sync (SecretCollection *collection, collection_path = g_dbus_proxy_get_object_path (G_DBUS_PROXY (collection)); path = secret_service_create_item_path_sync (service, collection_path, properties, - value, replace, cancellable, error); + value, replace, cancellable, error); if (path != NULL) { item = secret_item_new_sync (service, path, cancellable, error); @@ -664,11 +767,24 @@ on_item_deleted (GObject *source, g_object_unref (res); } +/** + * secret_collection_delete: + * @self: a collection + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Delete this collection. + * + * This method returns immediately and completes asynchronously. The secret + * service may prompt the user. secret_service_prompt() will be used to handle + * any prompts that show up. + */ void secret_item_delete (SecretItem *self, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; const gchar *object_path; @@ -681,15 +797,25 @@ secret_item_delete (SecretItem *self, secret_item_delete); _secret_service_delete_path (self->pv->service, object_path, TRUE, - cancellable, on_item_deleted, g_object_ref (res)); + cancellable, on_item_deleted, g_object_ref (res)); g_object_unref (res); } +/** + * secret_item_delete_finish: + * @self: an item + * @result: asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Complete asynchronous operation to delete the secret item. + * + * Returns: whether the item was successfully deleted or not + */ gboolean secret_item_delete_finish (SecretItem *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; @@ -706,10 +832,24 @@ secret_item_delete_finish (SecretItem *self, return g_simple_async_result_get_op_res_gboolean (res); } +/** + * secret_item_delete_sync: + * @self: an item + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Delete this secret item. + * + * This method may block indefinitely and should not be used in user + * interface threads. The secret service may prompt the user. + * secret_service_prompt() will be used to handle any prompts that show up. + * + * Returns: whether the item was successfully deleted or not + */ gboolean secret_item_delete_sync (SecretItem *self, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { SecretSync *sync; gboolean ret; @@ -809,11 +949,25 @@ on_get_ensure_session (GObject *source, g_object_unref (res); } +/** + * secret_item_get_secret: + * @self: an item + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Get the secret value of this item. + * + * Each item has a single secret which might be a password or some + * other secret binary value. + * + * This function returns immediately and completes asynchronously. + */ void secret_item_get_secret (SecretItem *self, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; GetClosure *closure; @@ -828,16 +982,29 @@ secret_item_get_secret (SecretItem *self, g_simple_async_result_set_op_res_gpointer (res, closure, get_closure_free); secret_service_ensure_session (self->pv->service, cancellable, - on_get_ensure_session, - g_object_ref (res)); + on_get_ensure_session, + g_object_ref (res)); g_object_unref (res); } -SecretValue* +/** + * secret_item_get_secret_finish: + * @self: an item + * @result: asynchronous result passed to callback + * @error: location to place error on failure + * + * Get the secret value of this item. + * + * Complete asynchronous operation to get the secret value of this item. + * + * Returns: (transfer full): the newly allocated secret value in this + * item, which should be released with secret_value_unref() + */ +SecretValue * secret_item_get_secret_finish (SecretItem *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; GetClosure *closure; @@ -853,10 +1020,27 @@ secret_item_get_secret_finish (SecretItem *self, return closure->value ? secret_value_ref (closure->value) : NULL; } -SecretValue* +/** + * secret_item_get_secret_sync: + * @self: an item + * @cancellable: optional cancellation object + * @error: location to place error on failure + * + * Get the secret value of this item. + * + * Each item has a single secret which might be a password or some + * other secret binary value. + * + * This function may block indefinetely. Use the asynchronous version + * in user interface threads. + * + * Returns: (transfer full): the newly allocated secret value in this + * item, which should be released with secret_value_unref() + */ +SecretValue * secret_item_get_secret_sync (SecretItem *self, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { SecretSync *sync; SecretValue *value; @@ -944,12 +1128,27 @@ on_set_ensure_session (GObject *source, g_object_unref (res); } +/** + * secret_item_set_secret: + * @self: an item + * @value: a new secret value + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Set the secret value of this item. + * + * Each item has a single secret which might be a password or some + * other secret binary value. + * + * This function returns immediately and completes asynchronously. + */ void secret_item_set_secret (SecretItem *self, - SecretValue *value, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + SecretValue *value, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; SetClosure *closure; @@ -966,16 +1165,26 @@ secret_item_set_secret (SecretItem *self, g_simple_async_result_set_op_res_gpointer (res, closure, set_closure_free); secret_service_ensure_session (self->pv->service, cancellable, - on_set_ensure_session, - g_object_ref (res)); + on_set_ensure_session, + g_object_ref (res)); g_object_unref (res); } +/** + * secret_item_set_secret_finish: + * @self: an item + * @result: asynchronous result passed to callback + * @error: location to place error on failure + * + * Complete asynchronous operation to set the secret value of this item. + * + * Returns: whether the change was successful or not + */ gboolean secret_item_set_secret_finish (SecretItem *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; @@ -989,11 +1198,28 @@ secret_item_set_secret_finish (SecretItem *self, return TRUE; } +/** + * secret_item_set_secret_sync: + * @self: an item + * @value: a new secret value + * @cancellable: optional cancellation object + * @error: location to place error on failure + * + * Set the secret value of this item. + * + * Each item has a single secret which might be a password or some + * other secret binary value. + * + * This function may block indefinetely. Use the asynchronous version + * in user interface threads. + * + * Returns: whether the change was successful or not + */ gboolean secret_item_set_secret_sync (SecretItem *self, - SecretValue *value, - GCancellable *cancellable, - GError **error) + SecretValue *value, + GCancellable *cancellable, + GError **error) { SecretSync *sync; gboolean ret; @@ -1017,6 +1243,22 @@ secret_item_set_secret_sync (SecretItem *self, return ret; } +/** + * secret_item_get_attributes: + * @self: an item + * + * Set the attributes of this item. + * + * 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 attributes returned by this method. Use + * secret_item_set_attributes() instead. + * + * Returns: (transfer full): a new reference to the attributes, which should + * not be modified, and released with g_hash_table_unref() + */ GHashTable * secret_item_get_attributes (SecretItem *self) { @@ -1034,48 +1276,103 @@ secret_item_get_attributes (SecretItem *self) return attributes; } +/** + * secret_item_set_attributes: + * @self: an item + * @attributes: a new set of attributes + * @cancellable: optional cancellation object + * @callback: called when the asynchronous operation completes + * @user_data: data to pass to the callback + * + * Set the attributes of this item. + * + * 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. + * + * This function returns immediately and completes asynchronously. + */ void secret_item_set_attributes (SecretItem *self, - GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { g_return_if_fail (SECRET_IS_ITEM (self)); g_return_if_fail (attributes != NULL); _secret_util_set_property (G_DBUS_PROXY (self), "Attributes", - _secret_util_variant_for_attributes (attributes), - secret_item_set_attributes, cancellable, - callback, user_data); + _secret_util_variant_for_attributes (attributes), + secret_item_set_attributes, cancellable, + callback, user_data); } +/** + * secret_item_set_attributes_finish: + * @self: an item + * @result: asynchronous result passed to the callback + * @error: location to place error on failure + * + * Complete operation to set the attributes of this item. + * + * Returns: whether the change was successful or not + */ gboolean secret_item_set_attributes_finish (SecretItem *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { g_return_val_if_fail (SECRET_IS_ITEM (self), FALSE); return _secret_util_set_property_finish (G_DBUS_PROXY (self), - secret_item_set_attributes, - result, error); + secret_item_set_attributes, + result, error); } +/** + * secret_item_set_attributes_sync: + * @self: an item + * @attributes: a new set of attributes + * @cancellable: optional cancellation object + * @error: location to place error on failure + * + * Set the attributes of this item. + * + * 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. + * + * This function may block indefinetely. Use the asynchronous version + * in user interface threads. + * + * Returns: whether the change was successful or not + */ gboolean secret_item_set_attributes_sync (SecretItem *self, - GHashTable *attributes, - GCancellable *cancellable, - GError **error) + GHashTable *attributes, + GCancellable *cancellable, + GError **error) { g_return_val_if_fail (SECRET_IS_ITEM (self), FALSE); g_return_val_if_fail (attributes != NULL, FALSE); return _secret_util_set_property_sync (G_DBUS_PROXY (self), "Attributes", - _secret_util_variant_for_attributes (attributes), - cancellable, error); + _secret_util_variant_for_attributes (attributes), + cancellable, error); } +/** + * secret_item_get_schema: + * @self: an item + * + * Get the schema of this item. + * + * The schema is a dotted string like org.freedesktop.Secret.Generic. + * A schema describes the set of attributes that should be set on this item. + * + * Returns: (transfer full): the schema, which should be freed with g_free() + */ gchar * secret_item_get_schema (SecretItem *self) { @@ -1094,6 +1391,14 @@ secret_item_get_schema (SecretItem *self) return label; } +/** + * secret_item_get_label: + * @self: an item + * + * Get the label of this item. + * + * Returns: (transfer full): the label, which should be freed with g_free() + */ gchar * secret_item_get_label (SecretItem *self) { @@ -1111,39 +1416,75 @@ secret_item_get_label (SecretItem *self) return label; } +/** + * secret_item_set_label: + * @self: an item + * @label: a new label + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Set the label of this item. + * + * This function returns immediately and completes asynchronously. + */ void secret_item_set_label (SecretItem *self, - const gchar *label, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar *label, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { g_return_if_fail (SECRET_IS_ITEM (self)); g_return_if_fail (label != NULL); _secret_util_set_property (G_DBUS_PROXY (self), "Label", - g_variant_new_string (label), - secret_item_set_label, - cancellable, callback, user_data); + g_variant_new_string (label), + secret_item_set_label, + cancellable, callback, user_data); } +/** + * secret_item_set_label_finish: + * @self: an item + * @result: asynchronous result passed to callback + * @error: location to place error on failure + * + * Complete asynchronous operation to set the label of this collection. + * + * Returns: whether the change was successful or not + */ gboolean secret_item_set_label_finish (SecretItem *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { g_return_val_if_fail (SECRET_IS_ITEM (self), FALSE); return _secret_util_set_property_finish (G_DBUS_PROXY (self), - secret_item_set_label, - result, error); + secret_item_set_label, + result, error); } +/** + * secret_item_set_label_sync: + * @self: an item + * @label: a new label + * @cancellable: optional cancellation object + * @error: location to place error on failure + * + * Set the label of this item. + * + * This function may block indefinetely. Use the asynchronous version + * in user interface threads. + * + * Returns: whether the change was successful or not + */ gboolean secret_item_set_label_sync (SecretItem *self, - const gchar *label, - GCancellable *cancellable, - GError **error) + const gchar *label, + GCancellable *cancellable, + GError **error) { g_return_val_if_fail (SECRET_IS_ITEM (self), FALSE); g_return_val_if_fail (label != NULL, FALSE); @@ -1153,6 +1494,17 @@ secret_item_set_label_sync (SecretItem *self, cancellable, error); } +/** + * secret_item_get_locked: + * @self: an item + * + * Get whether the item is locked or not. + * + * Depending on the secret service an item may not be able to be locked + * independently from the collection that it is in. + * + * Returns: whether the item is locked or not + */ gboolean secret_item_get_locked (SecretItem *self) { @@ -1170,6 +1522,15 @@ secret_item_get_locked (SecretItem *self) return locked; } +/** + * secret_item_get_created: + * @self: an item + * + * Get the created date and time of the item. The return value is + * the number of seconds since the unix epoch, January 1st 1970. + * + * Returns: the created date and time + */ guint64 secret_item_get_created (SecretItem *self) { @@ -1187,6 +1548,15 @@ secret_item_get_created (SecretItem *self) return created; } +/** + * secret_item_get_modified: + * @self: an item + * + * Get the modified date and time of the item. The return value is + * the number of seconds since the unix epoch, January 1st 1970. + * + * Returns: the modified date and time + */ guint64 secret_item_get_modified (SecretItem *self) { diff --git a/library/secret-item.h b/library/secret-item.h index fb2d1be..9c4a117 100644 --- a/library/secret-item.h +++ b/library/secret-item.h @@ -10,6 +10,10 @@ * See the included COPYING file for more information. */ +#if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) +#error "Only can be included directly." +#endif + #ifndef __SECRET_ITEM_H__ #define __SECRET_ITEM_H__ @@ -33,7 +37,7 @@ typedef struct _SecretItemPrivate SecretItemPrivate; struct _SecretItem { GDBusProxy parent_instance; - SecretItemPrivate *pv;; + SecretItemPrivate *pv; }; struct _SecretItemClass { @@ -44,117 +48,117 @@ struct _SecretItemClass { GType secret_item_get_type (void) G_GNUC_CONST; void secret_item_new (SecretService *service, - const gchar *item_path, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar *item_path, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); -SecretItem * secret_item_new_finish (GAsyncResult *result, - GError **error); +SecretItem * secret_item_new_finish (GAsyncResult *result, + GError **error); -SecretItem * secret_item_new_sync (SecretService *service, - const gchar *item_path, - GCancellable *cancellable, - GError **error); +SecretItem * secret_item_new_sync (SecretService *service, + const gchar *item_path, + GCancellable *cancellable, + GError **error); void secret_item_refresh (SecretItem *self); void secret_item_create (SecretCollection *collection, - const gchar *schema_name, - const gchar *label, - GHashTable *attributes, - SecretValue *value, - gboolean replace, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar *schema_name, + const gchar *label, + GHashTable *attributes, + SecretValue *value, + gboolean replace, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); -SecretItem * secret_item_create_finish (GAsyncResult *result, - GError **error); +SecretItem * secret_item_create_finish (GAsyncResult *result, + GError **error); -SecretItem * secret_item_create_sync (SecretCollection *collection, - const gchar *schema_name, - const gchar *label, - GHashTable *attributes, - SecretValue *value, - gboolean replace, - GCancellable *cancellable, - GError **error); +SecretItem * secret_item_create_sync (SecretCollection *collection, + const gchar *schema_name, + const gchar *label, + GHashTable *attributes, + SecretValue *value, + gboolean replace, + GCancellable *cancellable, + GError **error); void secret_item_delete (SecretItem *self, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_item_delete_finish (SecretItem *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); gboolean secret_item_delete_sync (SecretItem *self, - GCancellable *cancellable, - GError **error); + GCancellable *cancellable, + GError **error); void secret_item_get_secret (SecretItem *self, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); -SecretValue * secret_item_get_secret_finish (SecretItem *self, - GAsyncResult *result, - GError **error); +SecretValue * secret_item_get_secret_finish (SecretItem *self, + GAsyncResult *result, + GError **error); -SecretValue * secret_item_get_secret_sync (SecretItem *self, - GCancellable *cancellable, - GError **error); +SecretValue * secret_item_get_secret_sync (SecretItem *self, + GCancellable *cancellable, + GError **error); void secret_item_set_secret (SecretItem *self, - SecretValue *value, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + SecretValue *value, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_item_set_secret_finish (SecretItem *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); gboolean secret_item_set_secret_sync (SecretItem *self, - SecretValue *value, - GCancellable *cancellable, - GError **error); + SecretValue *value, + GCancellable *cancellable, + GError **error); GHashTable* secret_item_get_attributes (SecretItem *self); void secret_item_set_attributes (SecretItem *self, - GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_item_set_attributes_finish (SecretItem *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); gboolean secret_item_set_attributes_sync (SecretItem *self, - GHashTable *attributes, - GCancellable *cancellable, - GError **error); + GHashTable *attributes, + GCancellable *cancellable, + GError **error); gchar * secret_item_get_label (SecretItem *self); void secret_item_set_label (SecretItem *self, - const gchar *label, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar *label, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_item_set_label_finish (SecretItem *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); gboolean secret_item_set_label_sync (SecretItem *self, - const gchar *label, - GCancellable *cancellable, - GError **error); + const gchar *label, + GCancellable *cancellable, + GError **error); gchar * secret_item_get_schema (SecretItem *self); @@ -166,4 +170,4 @@ guint64 secret_item_get_modified (SecretItem *self); G_END_DECLS -#endif /* __G_ITEM_H___ */ +#endif /* __SECRET_ITEM_H___ */ diff --git a/library/secret-methods.c b/library/secret-methods.c index a5468d5..25fd776 100644 --- a/library/secret-methods.c +++ b/library/secret-methods.c @@ -41,12 +41,25 @@ on_search_items_complete (GObject *source, g_object_unref (res); } +/** + * secret_service_search_for_paths: + * @self: the secret service + * @attributes: search for items matching these attributes + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Search for items matching the @attributes. All collections are searched. + * The @attributes should be a table of string keys and string values. + * + * This function returns immediately and completes asynchronously. + */ void secret_service_search_for_paths (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; @@ -66,12 +79,31 @@ secret_service_search_for_paths (SecretService *self, g_object_unref (res); } +/** + * secret_service_search_for_paths_finish: + * @self: the secret service + * @result: asynchronous result passed to callback + * @unlocked: (out) (transfer full) (array zero-terminated=1) (allow-none): + * location to place an array of dbus object paths for matching + * items which were locked. + * @locked: (out) (transfer full) (array zero-terminated=1) (allow-none): + * location to place an array of dbus object paths for matching + * items which were locked. + * @error: location to place error on failure + * + * Complete asynchronous operation to search for items. + * + * Matching items that are locked or unlocked, have their dbus paths placed + * in the @locked or @unlocked arrays respectively. + * + * Returns: whether the search was successful or not + */ gboolean secret_service_search_for_paths_finish (SecretService *self, - GAsyncResult *result, - gchar ***unlocked, - gchar ***locked, - GError **error) + GAsyncResult *result, + gchar ***unlocked, + gchar ***locked, + GError **error) { GVariant *response; GSimpleAsyncResult *res; @@ -98,13 +130,37 @@ secret_service_search_for_paths_finish (SecretService *self, return TRUE; } +/** + * secret_service_search_for_paths_sync: + * @self: the secret service + * @attributes: search for items matching these attributes + * @cancellable: optional cancellation object + * @unlocked: (out) (transfer full) (array zero-terminated=1) (allow-none): + * location to place an array of dbus object paths for matching + * items which were locked. + * @locked: (out) (transfer full) (array zero-terminated=1) (allow-none): + * location to place an array of dbus object paths for matching + * items which were locked. + * @error: location to place error on failure + * + * Search for items matching the @attributes. All collections are searched. + * The @attributes should be a table of string keys and string values. + * + * This function may block indefinetely. Use the asynchronous version + * in user interface threads. + * + * Matching items that are locked or unlocked, have their dbus paths placed + * in the @locked or @unlocked arrays respectively. + * + * Returns: whether the search was successful or not + */ gboolean secret_service_search_for_paths_sync (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - gchar ***unlocked, - gchar ***locked, - GError **error) + GHashTable *attributes, + GCancellable *cancellable, + gchar ***unlocked, + gchar ***locked, + GError **error) { gchar **dummy = NULL; GVariant *response; @@ -233,12 +289,25 @@ on_search_paths (GObject *source, g_object_unref (res); } +/** + * secret_service_search: + * @self: the secret service + * @attributes: search for items matching these attributes + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Search for items matching the @attributes. All collections are searched. + * The @attributes should be a table of string keys and string values. + * + * This function returns immediately and completes asynchronously. + */ void secret_service_search (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; SearchClosure *closure; @@ -255,7 +324,7 @@ secret_service_search (SecretService *self, g_simple_async_result_set_op_res_gpointer (res, closure, search_closure_free); secret_service_search_for_paths (self, attributes, cancellable, - on_search_paths, g_object_ref (res)); + on_search_paths, g_object_ref (res)); g_object_unref (res); } @@ -277,12 +346,29 @@ search_finish_build (gchar **paths, return g_list_reverse (results); } +/** + * secret_service_search_finish: + * @self: the secret service + * @result: asynchronous result passed to callback + * @unlocked: (out) (transfer full) (element-type Secret.Item) (allow-none): + * location to place a list of matching items which were not locked. + * @locked: (out) (transfer full) (element-type Secret.Item) (allow-none): + * location to place a list of matching items which were locked. + * @error: location to place error on failure + * + * Complete asynchronous operation to search for items. + * + * Matching items that are locked or unlocked are placed + * in the @locked or @unlocked lists respectively. + * + * Returns: whether the search was successful or not + */ gboolean secret_service_search_finish (SecretService *self, - GAsyncResult *result, - GList **unlocked, - GList **locked, - GError **error) + GAsyncResult *result, + GList **unlocked, + GList **locked, + GError **error) { GSimpleAsyncResult *res; SearchClosure *closure; @@ -333,13 +419,35 @@ service_load_items_sync (SecretService *self, return TRUE; } +/** + * secret_service_search_sync: + * @self: the secret service + * @attributes: search for items matching these attributes + * @cancellable: optional cancellation object + * @unlocked: (out) (transfer full) (element-type Secret.Item) (allow-none): + * location to place a list of matching items which were not locked. + * @locked: (out) (transfer full) (element-type Secret.Item) (allow-none): + * location to place a list of matching items which were locked. + * @error: location to place error on failure + * + * Search for items matching the @attributes. All collections are searched. + * The @attributes should be a table of string keys and string values. + * + * This function may block indefinetely. Use the asynchronous version + * in user interface threads. + * + * Matching items that are locked or unlocked are placed + * in the @locked or @unlocked lists respectively. + * + * Returns: whether the search was successful or not + */ gboolean secret_service_search_sync (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GList **unlocked, - GList **locked, - GError **error) + GHashTable *attributes, + GCancellable *cancellable, + GList **unlocked, + GList **locked, + GError **error) { gchar **unlocked_paths = NULL; gchar **locked_paths = NULL; @@ -350,8 +458,8 @@ secret_service_search_sync (SecretService *self, g_return_val_if_fail (error == NULL || *error == NULL, FALSE); if (!secret_service_search_for_paths_sync (self, attributes, cancellable, - unlocked ? &unlocked_paths : NULL, - locked ? &locked_paths : NULL, error)) + unlocked ? &unlocked_paths : NULL, + locked ? &locked_paths : NULL, error)) return FALSE; ret = TRUE; @@ -414,7 +522,7 @@ on_get_secrets_session (GObject *source, const gchar *session; session = secret_service_ensure_session_finish (SECRET_SERVICE (source), - result, &error); + result, &error); if (error != NULL) { g_simple_async_result_take_error (res, error); g_simple_async_result_complete (res); @@ -429,18 +537,30 @@ on_get_secrets_session (GObject *source, g_object_unref (res); } +/** + * secret_service_get_secret_for_path: + * @self: the secret service + * @item_path: the dbus path to item to retrieve secret for + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Get the secret value for an secret item stored in the service. + * + * This function returns immediately and completes asynchronously. + */ void secret_service_get_secret_for_path (SecretService *self, - const gchar *object_path, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar *item_path, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; GetClosure *closure; g_return_if_fail (SECRET_IS_SERVICE (self)); - g_return_if_fail (object_path != NULL); + g_return_if_fail (item_path != NULL); g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable)); res = g_simple_async_result_new (G_OBJECT (self), callback, user_data, @@ -448,12 +568,12 @@ secret_service_get_secret_for_path (SecretService *self, closure = g_slice_new0 (GetClosure); closure->cancellable = cancellable ? g_object_ref (cancellable) : NULL; - closure->in = g_variant_ref_sink (g_variant_new_objv (&object_path, 1)); + closure->in = g_variant_ref_sink (g_variant_new_objv (&item_path, 1)); g_simple_async_result_set_op_res_gpointer (res, closure, get_closure_free); secret_service_ensure_session (self, cancellable, - on_get_secrets_session, - g_object_ref (res)); + on_get_secrets_session, + g_object_ref (res)); g_object_unref (res); } @@ -503,10 +623,24 @@ service_decode_get_secrets_all (SecretService *self, return values; } +/** + * secret_service_get_secret_for_path_finish: + * @self: the secret service + * @result: asynchronous result passed to callback + * @error: location to place an error on failure + * + * Complete asynchronous operation to get the secret value for an + * secret item stored in the service. + * + * Will return %NULL if the item is locked. + * + * Returns: (transfer full) (allow-none): the newly allocated secret value + * for the item, which should be released with secret_value_unref() + */ SecretValue * secret_service_get_secret_for_path_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; GetClosure *closure; @@ -524,24 +658,42 @@ secret_service_get_secret_for_path_finish (SecretService *self, return service_decode_get_secrets_first (self, closure->out); } +/** + * secret_service_get_secret_for_path_sync: + * @self: the secret service + * @item_path: the dbus path to item to retrieve secret for + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Get the secret value for an secret item stored in the service. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Will return %NULL if the item is locked. + * + * Returns: (transfer full) (allow-none): the newly allocated secret value + * for the item, which should be released with secret_value_unref() + */ SecretValue * secret_service_get_secret_for_path_sync (SecretService *self, - const gchar *object_path, - GCancellable *cancellable, - GError **error) + const gchar *item_path, + GCancellable *cancellable, + GError **error) { SecretSync *sync; SecretValue *value; g_return_val_if_fail (SECRET_IS_SERVICE (self), NULL); + g_return_val_if_fail (item_path != NULL, NULL); g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL); g_return_val_if_fail (error == NULL || *error == NULL, NULL); sync = _secret_sync_new (); g_main_context_push_thread_default (sync->context); - secret_service_get_secret_for_path (self, object_path, cancellable, - _secret_sync_on_result, sync); + secret_service_get_secret_for_path (self, item_path, cancellable, + _secret_sync_on_result, sync); g_main_loop_run (sync->loop); @@ -551,21 +703,32 @@ secret_service_get_secret_for_path_sync (SecretService *self, _secret_sync_free (sync); return value; - } +/** + * secret_service_get_secrets_for_paths: + * @self: the secret service + * @item_paths: the dbus paths to items to retrieve secrets for + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Get the secret values for an secret items stored in the service. + * + * This function returns immediately and completes asynchronously. + */ void secret_service_get_secrets_for_paths (SecretService *self, - const gchar **object_paths, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar **item_paths, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; GetClosure *closure; g_return_if_fail (SECRET_IS_SERVICE (self)); - g_return_if_fail (object_paths != NULL); + g_return_if_fail (item_paths != NULL); g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable)); res = g_simple_async_result_new (G_OBJECT (self), callback, user_data, @@ -573,20 +736,34 @@ secret_service_get_secrets_for_paths (SecretService *self, closure = g_slice_new0 (GetClosure); closure->cancellable = cancellable ? g_object_ref (cancellable) : NULL; - closure->in = g_variant_ref_sink (g_variant_new_objv (object_paths, -1)); + closure->in = g_variant_ref_sink (g_variant_new_objv (item_paths, -1)); g_simple_async_result_set_op_res_gpointer (res, closure, get_closure_free); secret_service_ensure_session (self, cancellable, - on_get_secrets_session, - g_object_ref (res)); + on_get_secrets_session, + g_object_ref (res)); g_object_unref (res); } +/** + * secret_service_get_secrets_for_paths_finish: + * @self: the secret service + * @result: asynchronous result passed to callback + * @error: location to place an error on failure + * + * Complete asynchronous operation to get the secret values for an + * secret items stored in the service. + * + * Items that are locked will not be included the results. + * + * Returns: (transfer full): a newly allocated hash table of item_path keys to + * #GSecretValue values. + */ GHashTable * secret_service_get_secrets_for_paths_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; GetClosure *closure; @@ -604,24 +781,42 @@ secret_service_get_secrets_for_paths_finish (SecretService *self, return service_decode_get_secrets_all (self, closure->out); } +/** + * secret_service_get_secrets_for_paths_sync: + * @self: the secret service + * @item_paths: the dbus paths to items to retrieve secrets for + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Get the secret values for an secret items stored in the service. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Items that are locked will not be included the results. + * + * Returns: (transfer full): a newly allocated hash table of item_path keys to + * #GSecretValue values. + */ GHashTable * secret_service_get_secrets_for_paths_sync (SecretService *self, - const gchar **object_paths, - GCancellable *cancellable, - GError **error) + const gchar **item_paths, + GCancellable *cancellable, + GError **error) { SecretSync *sync; GHashTable *secrets; g_return_val_if_fail (SECRET_IS_SERVICE (self), NULL); + g_return_val_if_fail (item_paths != NULL, NULL); g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL); g_return_val_if_fail (error == NULL || *error == NULL, NULL); sync = _secret_sync_new (); g_main_context_push_thread_default (sync->context); - secret_service_get_secrets_for_paths (self, object_paths, cancellable, - _secret_sync_on_result, sync); + secret_service_get_secrets_for_paths (self, item_paths, cancellable, + _secret_sync_on_result, sync); g_main_loop_run (sync->loop); @@ -633,12 +828,24 @@ secret_service_get_secrets_for_paths_sync (SecretService *self, return secrets; } +/** + * secret_service_get_secrets: + * @self: the secret service + * @items: (element-type Secret.Item): the items to retrieve secrets for + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Get the secret values for an secret items stored in the service. + * + * This function returns immediately and completes asynchronously. + */ void secret_service_get_secrets (SecretService *self, - GList *items, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GList *items, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; GetClosure *closure; @@ -676,10 +883,24 @@ secret_service_get_secrets (SecretService *self, g_object_unref (res); } +/** + * secret_service_get_secrets_finish: + * @self: the secret service + * @result: asynchronous result passed to callback + * @error: location to place an error on failure + * + * Complete asynchronous operation to get the secret values for an + * secret items stored in the service. + * + * Items that are locked will not be included the results. + * + * Returns: (transfer full): a newly allocated hash table of #GSecretItem keys + * to #GSecretValue values. + */ GHashTable * secret_service_get_secrets_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; GetClosure *closure; @@ -718,11 +939,28 @@ secret_service_get_secrets_finish (SecretService *self, return with_items; } +/** + * secret_service_get_secrets_sync: + * @self: the secret service + * @items: (element-type Secret.Item): the items to retrieve secrets for + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Get the secret values for an secret items stored in the service. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Items that are locked will not be included the results. + * + * Returns: (transfer full): a newly allocated hash table of #GSecretItem keys + * to #GSecretValue values. + */ GHashTable * secret_service_get_secrets_sync (SecretService *self, - GList *items, - GCancellable *cancellable, - GError **error) + GList *items, + GCancellable *cancellable, + GError **error) { SecretSync *sync; GHashTable *secrets; @@ -825,7 +1063,7 @@ on_xlock_called (GObject *source, g_simple_async_result_complete (res); } else { - closure->prompt = secret_prompt_instance (self, prompt); + closure->prompt = _secret_prompt_instance (self, prompt); secret_service_prompt (self, closure->prompt, closure->cancellable, on_xlock_prompted, g_object_ref (res)); } @@ -958,12 +1196,29 @@ service_xlock_finish (SecretService *self, } +/** + * secret_service_lock: + * @self: the secret service + * @objects: (element-type GLib.DBusProxy): the items or collections to lock + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Lock items or collections in the secret service. + * + * The secret service may not be able to lock items individually, and may + * lock an entire collection instead. + * + * This method returns immediately and completes asynchronously. The secret + * service may prompt the user. secret_service_prompt() will be used to handle + * any prompts that show up. + */ void secret_service_lock (SecretService *self, - GList *objects, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GList *objects, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { g_return_if_fail (SECRET_IS_SERVICE (self)); g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable)); @@ -971,11 +1226,27 @@ secret_service_lock (SecretService *self, service_xlock_async (self, "Lock", objects, cancellable, callback, user_data); } +/** + * secret_service_lock_finish: + * @self: the secret service + * @result: asynchronous result passed to the callback + * @locked: (out) (element-type GLib.DBusProxy) (transfer full) (allow-none): + * location to place list of items or collections that were locked + * @error: location to place an error on failure + * + * Complete asynchronous operation to lock items or collections in the secret + * service. + * + * The secret service may not be able to lock items individually, and may + * lock an entire collection instead. + * + * Returns: the number of items or collections that were locked + */ gint secret_service_lock_finish (SecretService *self, - GAsyncResult *result, - GList **locked, - GError **error) + GAsyncResult *result, + GList **locked, + GError **error) { g_return_val_if_fail (SECRET_IS_SERVICE (self), FALSE); g_return_val_if_fail (error == NULL || *error == NULL, FALSE); @@ -983,12 +1254,32 @@ secret_service_lock_finish (SecretService *self, return service_xlock_finish (self, result, locked, error); } +/** + * secret_service_lock_sync: + * @self: the secret service + * @objects: (element-type GLib.DBusProxy): the items or collections to lock + * @cancellable: optional cancellation object + * @locked: (out) (element-type GLib.DBusProxy) (transfer full) (allow-none): + * location to place list of items or collections that were locked + * @error: location to place an error on failure + * + * Lock items or collections in the secret service. + * + * The secret service may not be able to lock items individually, and may + * lock an entire collection instead. + * + * This method may block indefinitely and should not be used in user + * interface threads. The secret service may prompt the user. + * secret_service_prompt() will be used to handle any prompts that show up. + * + * Returns: the number of items or collections that were locked + */ gint secret_service_lock_sync (SecretService *self, - GList *objects, - GCancellable *cancellable, - GList **locked, - GError **error) + GList *objects, + GCancellable *cancellable, + GList **locked, + GError **error) { SecretSync *sync; gint count; @@ -1013,12 +1304,33 @@ secret_service_lock_sync (SecretService *self, return count; } +/** + * secret_service_lock_paths_sync: + * @self: the secret service + * @paths: the dbus paths for items or collections to lock + * @cancellable: optional cancellation object + * @locked: (out) (array zero-terminated=1) (transfer full) (allow-none): + * location to place array of dbus paths of items or collections + * that were locked + * @error: location to place an error on failure + * + * Lock items or collections in the secret service. + * + * The secret service may not be able to lock items individually, and may + * lock an entire collection instead. + * + * This method may block indefinitely and should not be used in user + * interface threads. The secret service may prompt the user. + * secret_service_prompt() will be used to handle any prompts that show up. + * + * Returns: the number of items or collections that were locked + */ gint secret_service_lock_paths_sync (SecretService *self, - const gchar **paths, - GCancellable *cancellable, - gchar ***locked, - GError **error) + const gchar **paths, + GCancellable *cancellable, + gchar ***locked, + GError **error) { SecretSync *sync; gint count; @@ -1045,12 +1357,29 @@ secret_service_lock_paths_sync (SecretService *self, return count; } +/** + * secret_service_lock_paths: + * @self: the secret service + * @paths: the dbus paths for items or collections to lock + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Lock items or collections in the secret service. + * + * The secret service may not be able to lock items individually, and may + * lock an entire collection instead. + * + * This method returns immediately and completes asynchronously. The secret + * service may prompt the user. secret_service_prompt() will be used to handle + * any prompts that show up. + */ void secret_service_lock_paths (SecretService *self, - const gchar **paths, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar **paths, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; @@ -1064,25 +1393,63 @@ secret_service_lock_paths (SecretService *self, g_object_unref (res); } +/** + * secret_service_lock_paths_finish: + * @self: the secret service + * @result: asynchronous result passed to the callback + * @locked: (out) (array zero-terminated=1) (transfer full) (allow-none): + * location to place array of dbus paths of items or collections + * that were locked + * @error: location to place an error on failure + * + * Complete asynchronous operation to lock items or collections in the secret + * service. + * + * The secret service may not be able to lock items individually, and may + * lock an entire collection instead. + * + * Returns: the number of items or collections that were locked + */ gint secret_service_lock_paths_finish (SecretService *self, - GAsyncResult *result, - gchar ***unlocked, - GError **error) + GAsyncResult *result, + gchar ***locked, + GError **error) { g_return_val_if_fail (SECRET_IS_SERVICE (self), -1); - g_return_val_if_fail (unlocked != NULL, -1); + g_return_val_if_fail (locked != NULL, -1); g_return_val_if_fail (error == NULL || *error == NULL, -1); - return service_xlock_paths_finish (self, result, unlocked, error); + return service_xlock_paths_finish (self, result, locked, error); } +/** + * secret_service_unlock_paths_sync: + * @self: the secret service + * @paths: the dbus paths for items or collections to unlock + * @cancellable: optional cancellation object + * @unlocked: (out) (array zero-terminated=1) (transfer full) (allow-none): + * location to place array of dbus paths of items or collections + * that were unlocked + * @error: location to place an error on failure + * + * Unlock items or collections in the secret service. + * + * The secret service may not be able to unlock items individually, and may + * unlock an entire collection instead. + * + * This method may block indefinitely and should not be used in user + * interface threads. The secret service may prompt the user. + * secret_service_prompt() will be used to handle any prompts that show up. + * + * Returns: the number of items or collections that were unlocked + */ gint secret_service_unlock_paths_sync (SecretService *self, - const gchar **paths, - GCancellable *cancellable, - gchar ***unlocked, - GError **error) + const gchar **paths, + GCancellable *cancellable, + gchar ***unlocked, + GError **error) { SecretSync *sync; gint count; @@ -1110,12 +1477,29 @@ secret_service_unlock_paths_sync (SecretService *self, return count; } +/** + * secret_service_unlock_paths: + * @self: the secret service + * @paths: the dbus paths for items or collections to unlock + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Unlock items or collections in the secret service. + * + * The secret service may not be able to unlock items individually, and may + * unlock an entire collection instead. + * + * This method returns immediately and completes asynchronously. The secret + * service may prompt the user. secret_service_prompt() will be used to handle + * any prompts that show up. + */ void secret_service_unlock_paths (SecretService *self, - const gchar **paths, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar **paths, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; @@ -1130,11 +1514,28 @@ secret_service_unlock_paths (SecretService *self, g_object_unref (res); } +/** + * secret_service_unlock_paths_finish: + * @self: the secret service + * @result: asynchronous result passed to the callback + * @unlocked: (out) (array zero-terminated=1) (transfer full) (allow-none): + * location to place array of dbus paths of items or collections + * that were unlocked + * @error: location to place an error on failure + * + * Complete asynchronous operation to unlock items or collections in the secret + * service. + * + * The secret service may not be able to unlock items individually, and may + * unlock an entire collection instead. + * + * Returns: the number of items or collections that were unlocked + */ gint secret_service_unlock_paths_finish (SecretService *self, - GAsyncResult *result, - gchar ***unlocked, - GError **error) + GAsyncResult *result, + gchar ***unlocked, + GError **error) { g_return_val_if_fail (SECRET_IS_SERVICE (self), -1); g_return_val_if_fail (error == NULL || *error == NULL, -1); @@ -1143,12 +1544,29 @@ secret_service_unlock_paths_finish (SecretService *self, unlocked, error); } +/** + * secret_service_unlock: + * @self: the secret service + * @objects: (element-type GLib.DBusProxy): the items or collections to unlock + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to pass to the callback + * + * Unlock items or collections in the secret service. + * + * The secret service may not be able to unlock items individually, and may + * unlock an entire collection instead. + * + * This method may block indefinitely and should not be used in user + * interface threads. The secret service may prompt the user. + * secret_service_prompt() will be used to handle any prompts that show up. + */ void secret_service_unlock (SecretService *self, - GList *objects, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GList *objects, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { g_return_if_fail (SECRET_IS_SERVICE (self)); g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable)); @@ -1156,11 +1574,27 @@ secret_service_unlock (SecretService *self, service_xlock_async (self, "Unlock", objects, cancellable, callback, user_data); } +/** + * secret_service_unlock_finish: + * @self: the secret service + * @result: asynchronous result passed to the callback + * @unlocked: (out) (element-type GLib.DBusProxy) (transfer full) (allow-none): + * location to place list of items or collections that were unlocked + * @error: location to place an error on failure + * + * Complete asynchronous operation to unlock items or collections in the secret + * service. + * + * The secret service may not be able to unlock items individually, and may + * unlock an entire collection instead. + * + * Returns: the number of items or collections that were unlocked + */ gint secret_service_unlock_finish (SecretService *self, - GAsyncResult *result, - GList **unlocked, - GError **error) + GAsyncResult *result, + GList **unlocked, + GError **error) { g_return_val_if_fail (SECRET_IS_SERVICE (self), -1); g_return_val_if_fail (error == NULL || *error == NULL, -1); @@ -1170,12 +1604,32 @@ secret_service_unlock_finish (SecretService *self, return service_xlock_finish (self, result, unlocked, error); } +/** + * secret_service_unlock_sync: + * @self: the secret service + * @objects: (element-type GLib.DBusProxy): the items or collections to unlock + * @cancellable: optional cancellation object + * @unlocked: (out) (element-type GLib.DBusProxy) (transfer full) (allow-none): + * location to place list of items or collections that were unlocked + * @error: location to place an error on failure + * + * Unlock items or collections in the secret service. + * + * The secret service may not be able to unlock items individually, and may + * unlock an entire collection instead. + * + * This method may block indefinitely and should not be used in user + * interface threads. The secret service may prompt the user. + * secret_service_prompt() will be used to handle any prompts that show up. + * + * Returns: the number of items or collections that were unlocked + */ gint secret_service_unlock_sync (SecretService *self, - GList *objects, - GCancellable *cancellable, - GList **unlocked, - GError **error) + GList *objects, + GCancellable *cancellable, + GList **unlocked, + GError **error) { SecretSync *sync; gint count; @@ -1201,16 +1655,40 @@ secret_service_unlock_sync (SecretService *self, return count; } +/** + * secret_service_store: + * @self: the secret service + * @schema: the schema to for attributes + * @collection_path: the dbus path to the collection where to store the secret + * @label: label for the secret + * @value: the secret value + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * @...: the attribute keys and values, terminated with %NULL + * + * Store a secret value in the secret service. + * + * The variable argument list should contain pairs of a) The attribute name as + * a null-terminated string, followed by b) attribute value, either a character + * string, an int number, or a gboolean value, as defined in the password + * @schema. The list of attribtues should be terminated with a %NULL. + * + * If the attributes match a secret item already stored in the collection, then + * the item will be updated with these new values. + * + * This method will return immediately and complete asynchronously. + */ void secret_service_store (SecretService *self, - const SecretSchema *schema, - const gchar *collection_path, - const gchar *label, - SecretValue *value, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data, - ...) + const SecretSchema *schema, + const gchar *collection_path, + const gchar *label, + SecretValue *value, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data, + ...) { GHashTable *attributes; va_list va; @@ -1231,16 +1709,37 @@ secret_service_store (SecretService *self, g_hash_table_unref (attributes); } +/** + * secret_service_storev: + * @self: the secret service + * @schema: the schema to for attributes + * @attributes: the attribute keys and values + * @collection_path: the dbus path to the collection where to store the secret + * @label: label for the secret + * @value: the secret value + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Store a secret value in the secret service. + * + * The @attributes should be a set of key and value string pairs. + * + * If the attributes match a secret item already stored in the collection, then + * the item will be updated with these new values. + * + * This method will return immediately and complete asynchronously. + */ void secret_service_storev (SecretService *self, - const SecretSchema *schema, - GHashTable *attributes, - const gchar *collection_path, - const gchar *label, - SecretValue *value, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const SecretSchema *schema, + GHashTable *attributes, + const gchar *collection_path, + const gchar *label, + SecretValue *value, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GHashTable *properties; GVariant *propval; @@ -1277,10 +1776,20 @@ secret_service_storev (SecretService *self, g_hash_table_unref (properties); } +/** + * secret_service_store_finish: + * @self: the secret service + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Finish asynchronous operation to store a secret value in the secret service. + * + * Returns: whether the storage was successful or not + */ gboolean secret_service_store_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { gchar *path; @@ -1293,15 +1802,41 @@ secret_service_store_finish (SecretService *self, return path != NULL; } +/** + * secret_service_store_sync: + * @self: the secret service + * @schema: the schema to for attributes + * @collection_path: the dbus path to the collection where to store the secret + * @label: label for the secret + * @value: the secret value + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * @...: the attribute keys and values, terminated with %NULL + * + * Store a secret value in the secret service. + * + * The variable argument list should contain pairs of a) The attribute name as + * a null-terminated string, followed by b) attribute value, either a character + * string, an int number, or a gboolean value, as defined in the password + * @schema. The list of attribtues should be terminated with a %NULL. + * + * If the attributes match a secret item already stored in the collection, then + * the item will be updated with these new values. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: whether the storage was successful or not + */ gboolean secret_service_store_sync (SecretService *self, - const SecretSchema *schema, - const gchar *collection_path, - const gchar *label, - SecretValue *value, - GCancellable *cancellable, - GError **error, - ...) + const SecretSchema *schema, + const gchar *collection_path, + const gchar *label, + SecretValue *value, + GCancellable *cancellable, + GError **error, + ...) { GHashTable *attributes; gboolean ret; @@ -1327,15 +1862,38 @@ secret_service_store_sync (SecretService *self, return ret; } +/** + * secret_service_storev_sync: + * @self: the secret service + * @schema: the schema to for attributes + * @attributes: the attribute keys and values + * @collection_path: the dbus path to the collection where to store the secret + * @label: label for the secret + * @value: the secret value + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Store a secret value in the secret service. + * + * The @attributes should be a set of key and value string pairs. + * + * If the attributes match a secret item already stored in the collection, then + * the item will be updated with these new values. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: whether the storage was successful or not + */ gboolean secret_service_storev_sync (SecretService *self, - const SecretSchema *schema, - GHashTable *attributes, - const gchar *collection_path, - const gchar *label, - SecretValue *value, - GCancellable *cancellable, - GError **error) + const SecretSchema *schema, + GHashTable *attributes, + const gchar *collection_path, + const gchar *label, + SecretValue *value, + GCancellable *cancellable, + GError **error) { SecretSync *sync; gboolean ret; @@ -1380,13 +1938,31 @@ lookup_closure_free (gpointer data) g_slice_free (LookupClosure, closure); } +/** + * secret_service_lookup: + * @self: the secret service + * @schema: the schema to for attributes + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * @...: the attribute keys and values, terminated with %NULL + * + * Lookup a secret value in the secret service. + * + * The variable argument list should contain pairs of a) The attribute name as + * a null-terminated string, followed by b) attribute value, either a character + * string, an int number, or a gboolean value, as defined in the password + * @schema. The list of attribtues should be terminated with a %NULL. + * + * This method will return immediately and complete asynchronously. + */ void secret_service_lookup (SecretService *self, - const SecretSchema *schema, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data, - ...) + const SecretSchema *schema, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data, + ...) { GHashTable *attributes; va_list va; @@ -1399,7 +1975,8 @@ secret_service_lookup (SecretService *self, attributes = _secret_util_attributes_for_varargs (schema, va); va_end (va); - secret_service_lookupv (self, attributes, cancellable, callback, user_data); + secret_service_lookupv (self, schema, attributes, cancellable, + callback, user_data); g_hash_table_unref (attributes); } @@ -1441,9 +2018,9 @@ on_lookup_unlocked (GObject *source, } else if (unlocked && unlocked[0]) { secret_service_get_secret_for_path (self, unlocked[0], - closure->cancellable, - on_lookup_get_secret, - g_object_ref (res)); + closure->cancellable, + on_lookup_get_secret, + g_object_ref (res)); } else { g_simple_async_result_complete (res); @@ -1472,16 +2049,16 @@ on_lookup_searched (GObject *source, } else if (unlocked && unlocked[0]) { secret_service_get_secret_for_path (self, unlocked[0], - closure->cancellable, - on_lookup_get_secret, - g_object_ref (res)); + closure->cancellable, + on_lookup_get_secret, + g_object_ref (res)); } else if (locked && locked[0]) { const gchar *paths[] = { locked[0], NULL }; secret_service_unlock_paths (self, paths, - closure->cancellable, - on_lookup_unlocked, - g_object_ref (res)); + closure->cancellable, + on_lookup_unlocked, + g_object_ref (res)); } else { g_simple_async_result_complete (res); @@ -1492,17 +2069,34 @@ on_lookup_searched (GObject *source, g_object_unref (res); } +/** + * secret_service_lookupv: + * @self: the secret service + * @schema: the schema to for attributes + * @attributes: the attribute keys and values + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Lookup a secret value in the secret service. + * + * The @attributes should be a set of key and value string pairs. + * + * This method will return immediately and complete asynchronously. + */ void secret_service_lookupv (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; LookupClosure *closure; g_return_if_fail (SECRET_IS_SERVICE (self)); + g_return_if_fail (schema != NULL); g_return_if_fail (attributes != NULL); g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable)); @@ -1513,15 +2107,28 @@ secret_service_lookupv (SecretService *self, g_simple_async_result_set_op_res_gpointer (res, closure, lookup_closure_free); secret_service_search_for_paths (self, attributes, cancellable, - on_lookup_searched, g_object_ref (res)); + on_lookup_searched, g_object_ref (res)); g_object_unref (res); } +/** + * secret_service_lookup_finish: + * @self: the secret service + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Finish asynchronous operation to lookup a secret value in the secret service. + * + * If no secret is found then %NULL is returned. + * + * Returns: (transfer full): a newly allocated #SecretValue, which should be + * released with secret_value_unref(), or %NULL if no secret found + */ SecretValue * secret_service_lookup_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; LookupClosure *closure; @@ -1542,12 +2149,35 @@ secret_service_lookup_finish (SecretService *self, return value; } +/** + * secret_service_lookup_sync: + * @self: the secret service + * @schema: the schema to for attributes + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * @...: the attribute keys and values, terminated with %NULL + * + * Lookup a secret value in the secret service. + * + * The variable argument list should contain pairs of a) The attribute name as + * a null-terminated string, followed by b) attribute value, either a character + * string, an int number, or a gboolean value, as defined in the password + * @schema. The list of attribtues should be terminated with a %NULL. + * + * If no secret is found then %NULL is returned. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: (transfer full): a newly allocated #SecretValue, which should be + * released with secret_value_unref(), or %NULL if no secret found + */ SecretValue * secret_service_lookup_sync (SecretService *self, - const SecretSchema *schema, - GCancellable *cancellable, - GError **error, - ...) + const SecretSchema *schema, + GCancellable *cancellable, + GError **error, + ...) { GHashTable *attributes; SecretValue *value; @@ -1561,31 +2191,51 @@ secret_service_lookup_sync (SecretService *self, attributes = _secret_util_attributes_for_varargs (schema, va); va_end (va); - value = secret_service_lookupv_sync (self, attributes, cancellable, error); + value = secret_service_lookupv_sync (self, schema, attributes, cancellable, error); g_hash_table_unref (attributes); return value; } +/** + * secret_service_lookupv_sync: + * @self: the secret service + * @schema: the schema to for attributes + * @attributes: the attribute keys and values + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Lookup a secret value in the secret service. + * + * The @attributes should be a set of key and value string pairs. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: (transfer full): a newly allocated #SecretValue, which should be + * released with secret_value_unref(), or %NULL if no secret found + */ SecretValue * secret_service_lookupv_sync (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GError **error) + const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GError **error) { SecretSync *sync; SecretValue *value; g_return_val_if_fail (SECRET_IS_SERVICE (self), NULL); + g_return_val_if_fail (schema != NULL, NULL); g_return_val_if_fail (attributes != NULL, NULL); g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL); sync = _secret_sync_new (); g_main_context_push_thread_default (sync->context); - secret_service_lookupv (self, attributes, cancellable, - _secret_sync_on_result, sync); + secret_service_lookupv (self, schema, attributes, cancellable, + _secret_sync_on_result, sync); g_main_loop_run (sync->loop); @@ -1653,12 +2303,12 @@ on_delete_complete (GObject *source, g_simple_async_result_complete (res); } else { - closure->prompt = secret_prompt_instance (self, prompt_path); + closure->prompt = _secret_prompt_instance (self, prompt_path); secret_service_prompt (self, closure->prompt, - closure->cancellable, - on_delete_prompted, - g_object_ref (res)); + closure->cancellable, + on_delete_prompted, + g_object_ref (res)); } g_variant_unref (retval); @@ -1674,11 +2324,11 @@ on_delete_complete (GObject *source, void _secret_service_delete_path (SecretService *self, - const gchar *object_path, - gboolean is_an_item, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar *object_path, + gboolean is_an_item, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; DeleteClosure *closure; @@ -1703,12 +2353,24 @@ _secret_service_delete_path (SecretService *self, g_object_unref (res); } +/** + * secret_service_delete_path: + * @self: the secret service + * @item_path: dbus path of item to delete + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Delete a secret item from the secret service. + * + * This method will return immediately and complete asynchronously. + */ void secret_service_delete_path (SecretService *self, - const gchar *item_path, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar *item_path, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { g_return_if_fail (SECRET_IS_SERVICE (self)); g_return_if_fail (item_path != NULL); @@ -1717,10 +2379,21 @@ secret_service_delete_path (SecretService *self, _secret_service_delete_path (self, item_path, TRUE, cancellable, callback, user_data); } +/** + * secret_service_delete_path_finish: + * @self: the secret service + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Complete an asynchronous operation to delete a secret item from the secret + * service. + * + * Returns: whether the deletion was successful or not + */ gboolean secret_service_delete_path_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; DeleteClosure *closure; @@ -1738,25 +2411,39 @@ secret_service_delete_path_finish (SecretService *self, return closure->deleted; } +/** + * secret_service_delete_path_sync: + * @self: the secret service + * @item_path: dbus path of item to delete + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Delete a secret item from the secret service. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: whether the deletion was successful or not + */ gboolean secret_service_delete_path_sync (SecretService *self, - const gchar *object_path, - GCancellable *cancellable, - GError **error) + const gchar *item_path, + GCancellable *cancellable, + GError **error) { SecretSync *sync; gboolean result; g_return_val_if_fail (SECRET_IS_SERVICE (self), FALSE); - g_return_val_if_fail (object_path != NULL, FALSE); + g_return_val_if_fail (item_path != NULL, FALSE); 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_service_delete_path (self, object_path, cancellable, - _secret_sync_on_result, sync); + secret_service_delete_path (self, item_path, cancellable, + _secret_sync_on_result, sync); g_main_loop_run (sync->loop); @@ -1822,9 +2509,9 @@ on_search_delete_password (GObject *source, } else { closure->deleted = TRUE; _secret_service_delete_path (self, path, TRUE, - closure->cancellable, - on_delete_password_complete, - g_object_ref (res)); + closure->cancellable, + on_delete_password_complete, + g_object_ref (res)); } } @@ -1834,13 +2521,33 @@ on_search_delete_password (GObject *source, g_object_unref (res); } +/** + * secret_service_remove: + * @self: the secret service + * @schema: the schema to for attributes + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * @...: the attribute keys and values, terminated with %NULL + * + * Remove a secret value from the secret service. + * + * The variable argument list should contain pairs of a) The attribute name as + * a null-terminated string, followed by b) attribute value, either a character + * string, an int number, or a gboolean value, as defined in the password + * @schema. The list of attribtues should be terminated with a %NULL. + * + * If multiple items match the attributes, then only one will be deleted. + * + * This method will return immediately and complete asynchronously. + */ void secret_service_remove (SecretService *self, - const SecretSchema *schema, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data, - ...) + const SecretSchema *schema, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data, + ...) { GHashTable *attributes; va_list va; @@ -1853,23 +2560,42 @@ secret_service_remove (SecretService *self, attributes = _secret_util_attributes_for_varargs (schema, va); va_end (va); - secret_service_removev (self, attributes, cancellable, - callback, user_data); + secret_service_removev (self, schema, attributes, cancellable, + callback, user_data); g_hash_table_unref (attributes); } +/** + * secret_service_removev: + * @self: the secret service + * @schema: the schema to for attributes + * @attributes: the attribute keys and values + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Remove a secret value from the secret service. + * + * The @attributes should be a set of key and value string pairs. + * + * If multiple items match the attributes, then only one will be deleted. + * + * This method will return immediately and complete asynchronously. + */ void secret_service_removev (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; DeleteClosure *closure; g_return_if_fail (SECRET_SERVICE (self)); + g_return_if_fail (schema != NULL); g_return_if_fail (attributes != NULL); g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable)); @@ -1880,15 +2606,26 @@ secret_service_removev (SecretService *self, g_simple_async_result_set_op_res_gpointer (res, closure, delete_closure_free); secret_service_search_for_paths (self, attributes, cancellable, - on_search_delete_password, g_object_ref (res)); + on_search_delete_password, g_object_ref (res)); g_object_unref (res); } +/** + * secret_service_remove_finish: + * @self: the secret service + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Finish asynchronous operation to remove a secret value from the secret + * service. + * + * Returns: whether the removal was successful or not + */ gboolean secret_service_remove_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; DeleteClosure *closure; @@ -1906,18 +2643,41 @@ secret_service_remove_finish (SecretService *self, return closure->deleted; } +/** + * secret_service_remove_sync: + * @self: the secret service + * @schema: the schema to for attributes + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * @...: the attribute keys and values, terminated with %NULL + * + * Remove a secret value from the secret service. + * + * The variable argument list should contain pairs of a) The attribute name as + * a null-terminated string, followed by b) attribute value, either a character + * string, an int number, or a gboolean value, as defined in the password + * @schema. The list of attribtues should be terminated with a %NULL. + * + * If multiple items match the attributes, then only one will be deleted. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: whether the removal was successful or not + */ gboolean secret_service_remove_sync (SecretService *self, - const SecretSchema* schema, - GCancellable *cancellable, - GError **error, - ...) + const SecretSchema* schema, + GCancellable *cancellable, + GError **error, + ...) { GHashTable *attributes; gboolean result; va_list va; g_return_val_if_fail (SECRET_IS_SERVICE (self), FALSE); + g_return_val_if_fail (schema != NULL, FALSE); g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE); g_return_val_if_fail (error == NULL || *error == NULL, FALSE); @@ -1925,31 +2685,52 @@ secret_service_remove_sync (SecretService *self, attributes = _secret_util_attributes_for_varargs (schema, va); va_end (va); - result = secret_service_removev_sync (self, attributes, cancellable, error); + result = secret_service_removev_sync (self, schema, attributes, cancellable, error); g_hash_table_unref (attributes); return result; } +/** + * secret_service_removev_sync: + * @self: the secret service + * @schema: the schema to for attributes + * @attributes: the attribute keys and values + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Remove a secret value from the secret service. + * + * The @attributes should be a set of key and value string pairs. + * + * If multiple items match the attributes, then only one will be deleted. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: whether the removal was successful or not + */ gboolean secret_service_removev_sync (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GError **error) + const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GError **error) { SecretSync *sync; gboolean result; g_return_val_if_fail (SECRET_IS_SERVICE (self), FALSE); + g_return_val_if_fail (schema != NULL, FALSE); 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_service_removev (self, attributes, cancellable, - _secret_sync_on_result, sync); + secret_service_removev (self, schema, attributes, cancellable, + _secret_sync_on_result, sync); g_main_loop_run (sync->loop); @@ -2018,10 +2799,10 @@ on_create_collection_called (GObject *source, if (error == NULL) { g_variant_get (retval, "(&o&o)", &collection_path, &prompt_path); if (!_secret_util_empty_path (prompt_path)) { - closure->prompt = secret_prompt_instance (self, prompt_path); + closure->prompt = _secret_prompt_instance (self, prompt_path); secret_service_prompt (self, closure->prompt, - closure->cancellable, on_create_collection_prompt, - g_object_ref (res)); + closure->cancellable, on_create_collection_prompt, + g_object_ref (res)); } else { closure->collection_path = g_strdup (collection_path); @@ -2039,13 +2820,39 @@ on_create_collection_called (GObject *source, g_object_unref (res); } +/** + * secret_service_create_collection_path: + * @self: a secret service object + * @properties: hash table of properties for the new collection + * @alias: (allow-none): an alias to check for before creating the new + * collection, or to assign to the new collection + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Create a new collection in the secret service. + * + * If a collection with the @alias already exists, then instead of creating a + * new collection, the existing collection will be returned. If no collection + * with this alias exists, then a new collection will be created and this + * alias will be assigned to it. + * + * @properties is a set of properties for the new collection. The keys in the + * hash table should be interface.property strings like + * org.freedesktop.Secret.Collection.Label. The values + * in the hash table should be #GVariant values of the properties. + * + * This method will return immediately and complete asynchronously. The secret + * service may prompt the user. secret_service_prompt() will be used to handle + * any prompts that are required. + */ void secret_service_create_collection_path (SecretService *self, - GHashTable *properties, - const gchar *alias, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GHashTable *properties, + const gchar *alias, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; CollectionClosure *closure; @@ -2084,10 +2891,22 @@ secret_service_create_collection_path (SecretService *self, } +/** + * secret_service_create_collection_path_finish: + * @self: a secret service object + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Finish asynchronous operation to create a new collection in the secret + * service. + * + * Returns: (transfer full): a new string containing the dbus object path + * of the collection + */ gchar * secret_service_create_collection_path_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; CollectionClosure *closure; @@ -2108,12 +2927,40 @@ secret_service_create_collection_path_finish (SecretService *self, return path; } +/** + * secret_service_create_collection_path_sync: + * @self: a secret service object + * @properties: hash table of properties for the new collection + * @alias: (allow-none): an alias to check for before creating the new + * collection, or to assign to the new collection + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Create a new collection in the secret service. + * + * If a collection with the @alias already exists, then instead of creating a + * new collection, the existing collection will be returned. If no collection + * with this alias exists, then a new collection will be created and this + * alias will be assigned to it. + * + * @properties is a set of properties for the new collection. The keys in the + * hash table should be interface.property strings like + * org.freedesktop.Secret.Collection.Label. The values + * in the hash table should be #GVariant values of the properties. + * + * This method may block indefinitely and should not be used in user interface + * threads. The secret service may prompt the user. secret_service_prompt() + * will be used to handle any prompts that are required. + * + * Returns: (transfer full): a new string containing the dbus object path + * of the collection + */ gchar * secret_service_create_collection_path_sync (SecretService *self, - GHashTable *properties, - const gchar *alias, - GCancellable *cancellable, - GError **error) + GHashTable *properties, + const gchar *alias, + GCancellable *cancellable, + GError **error) { SecretSync *sync; gchar *path; @@ -2127,7 +2974,7 @@ secret_service_create_collection_path_sync (SecretService *self, g_main_context_push_thread_default (sync->context); secret_service_create_collection_path (self, properties, alias, cancellable, - _secret_sync_on_result, sync); + _secret_sync_on_result, sync); g_main_loop_run (sync->loop); @@ -2203,10 +3050,10 @@ on_create_item_called (GObject *source, if (error == NULL) { g_variant_get (retval, "(&o&o)", &item_path, &prompt_path); if (!_secret_util_empty_path (prompt_path)) { - closure->prompt = secret_prompt_instance (self, prompt_path); + closure->prompt = _secret_prompt_instance (self, prompt_path); secret_service_prompt (self, closure->prompt, - closure->cancellable, on_create_item_prompt, - g_object_ref (res)); + closure->cancellable, on_create_item_prompt, + g_object_ref (res)); } else { closure->item_path = g_strdup (item_path); @@ -2263,15 +3110,44 @@ on_create_item_session (GObject *source, g_object_unref (res); } +/** + * secret_service_create_item_path: + * @self: a secret service object + * @collection_path: dbus path to collection in which to create item + * @properties: hash table of properties for the new collection + * @value: the secret value to store in the item + * @replace: whether to replace an item with the matching attributes + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Create a new item in a secret service collection. + * + * It is often easier to use secret_password_store() or secret_item_create() + * rather than using this function. + * + * If @replace is set to %TRUE, and an item already in the collection matches + * the attributes (specified in @properties) then the item will be updated + * instead of creating a new item. + * + * @properties is a set of properties for the new collection. The keys in the + * hash table should be interface.property strings like + * org.freedesktop.Secret.Item.Label. The values + * in the hash table should be #GVariant values of the properties. + * + * This method will return immediately and complete asynchronously. The secret + * service may prompt the user. secret_service_prompt() will be used to handle + * any prompts that are required. + */ void secret_service_create_item_path (SecretService *self, - const gchar *collection_path, - GHashTable *properties, - SecretValue *value, - gboolean replace, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar *collection_path, + GHashTable *properties, + SecretValue *value, + gboolean replace, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; ItemClosure *closure; @@ -2293,16 +3169,28 @@ secret_service_create_item_path (SecretService *self, g_simple_async_result_set_op_res_gpointer (res, closure, item_closure_free); secret_service_ensure_session (self, cancellable, - on_create_item_session, - g_object_ref (res)); + on_create_item_session, + g_object_ref (res)); g_object_unref (res); } +/** + * secret_service_create_item_path_finish: + * @self: a secret service object + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Finish asynchronous operation to create a new item in the secret + * service. + * + * Returns: (transfer full): a new string containing the dbus object path + * of the item + */ gchar * secret_service_create_item_path_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; ItemClosure *closure; @@ -2323,14 +3211,45 @@ secret_service_create_item_path_finish (SecretService *self, return path; } +/** + * secret_service_create_item_path_sync: + * @self: a secret service object + * @collection_path: dbus path to collection in which to create item + * @properties: hash table of properties for the new collection + * @value: the secret value to store in the item + * @replace: whether to replace an item with the matching attributes + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Create a new item in a secret service collection. + * + * It is often easier to use secret_password_store_sync() or secret_item_create_sync() + * rather than using this function. + * + * If @replace is set to %TRUE, and an item already in the collection matches + * the attributes (specified in @properties) then the item will be updated + * instead of creating a new item. + * + * @properties is a set of properties for the new collection. The keys in the + * hash table should be interface.property strings like + * org.freedesktop.Secret.Item.Label. The values + * in the hash table should be #GVariant values of the properties. + * + * This method may block indefinitely and should not be used in user interface + * threads. The secret service may prompt the user. secret_service_prompt() + * will be used to handle any prompts that are required. + * + * Returns: (transfer full): a new string containing the dbus object path + * of the item + */ gchar * secret_service_create_item_path_sync (SecretService *self, - const gchar *collection_path, - GHashTable *properties, - SecretValue *value, - gboolean replace, - GCancellable *cancellable, - GError **error) + const gchar *collection_path, + GHashTable *properties, + SecretValue *value, + gboolean replace, + GCancellable *cancellable, + GError **error) { SecretSync *sync; gchar *path; @@ -2344,7 +3263,7 @@ secret_service_create_item_path_sync (SecretService *self, g_main_context_push_thread_default (sync->context); secret_service_create_item_path (self, collection_path, properties, value, replace, - cancellable, _secret_sync_on_result, sync); + cancellable, _secret_sync_on_result, sync); g_main_loop_run (sync->loop); diff --git a/library/secret-password.c b/library/secret-password.c index 069f1be..48dfdc0 100644 --- a/library/secret-password.c +++ b/library/secret-password.c @@ -50,7 +50,7 @@ on_store_complete (GObject *source, GError *error = NULL; closure->created = secret_service_store_finish (SECRET_SERVICE (source), - result, &error); + result, &error); if (error != NULL) g_simple_async_result_take_error (res, error); @@ -71,12 +71,12 @@ on_store_connected (GObject *source, service = secret_service_get_finish (result, &error); if (error == NULL) { secret_service_storev (service, closure->schema, - closure->attributes, - closure->collection_path, - closure->label, closure->value, - closure->cancellable, - on_store_complete, - g_object_ref (res)); + closure->attributes, + closure->collection_path, + closure->label, closure->value, + closure->cancellable, + on_store_complete, + g_object_ref (res)); g_object_unref (service); } else { @@ -87,15 +87,38 @@ on_store_connected (GObject *source, g_object_unref (res); } +/** + * secret_password_store: + * @schema: the schema for attributes + * @collection_path: the dbus path to the collection where to store the secret + * @label: label for the secret + * @password: the null-terminated password to store + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * @...: the attribute keys and values, terminated with %NULL + * + * Store a password in the secret service. + * + * The variable argument list should contain pairs of a) The attribute name as + * a null-terminated string, followed by b) attribute value, either a character + * string, an int number, or a gboolean value, as defined in the @schema. + * The list of attribtues should be terminated with a %NULL. + * + * If the attributes match a secret item already stored in the collection, then + * the item will be updated with these new values. + * + * This method will return immediately and complete asynchronously. + */ void secret_password_store (const SecretSchema *schema, - const gchar *collection_path, - const gchar *label, - const gchar *password, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data, - ...) + const gchar *collection_path, + const gchar *label, + const gchar *password, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data, + ...) { GHashTable *attributes; va_list va; @@ -110,21 +133,41 @@ secret_password_store (const SecretSchema *schema, attributes = _secret_util_attributes_for_varargs (schema, va); va_end (va); - secret_password_storev (schema, collection_path, label, password, attributes, - cancellable, callback, user_data); + secret_password_storev (schema, attributes, collection_path, label, password, + cancellable, callback, user_data); g_hash_table_unref (attributes); } +/** + * secret_password_storev: + * @schema: the schema for attributes + * @attributes: the attribute keys and values + * @collection_path: the dbus path to the collection where to store the secret + * @label: label for the secret + * @password: the null-terminated password to store + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Store a password in the secret service. + * + * The @attributes should be a set of key and value string pairs. + * + * If the attributes match a secret item already stored in the collection, then + * the item will be updated with these new values. + * + * This method will return immediately and complete asynchronously. + */ void secret_password_storev (const SecretSchema *schema, - const gchar *collection_path, - const gchar *label, - const gchar *password, - GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GHashTable *attributes, + const gchar *collection_path, + const gchar *label, + const gchar *password, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; StoreClosure *closure; @@ -148,14 +191,24 @@ secret_password_storev (const SecretSchema *schema, g_simple_async_result_set_op_res_gpointer (res, closure, store_closure_free); secret_service_get (SECRET_SERVICE_OPEN_SESSION, cancellable, - on_store_connected, g_object_ref (res)); + on_store_connected, g_object_ref (res)); g_object_unref (res); } +/** + * secret_service_store_finish: + * @self: the secret service + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Finish asynchronous operation to store a password in the secret service. + * + * Returns: whether the storage was successful or not + */ gboolean secret_password_store_finish (GAsyncResult *result, - GError **error) + GError **error) { GSimpleAsyncResult *res; StoreClosure *closure; @@ -172,14 +225,39 @@ secret_password_store_finish (GAsyncResult *result, return closure->created; } +/** + * secret_password_store_sync: + * @schema: the schema for attributes + * @collection_path: the dbus path to the collection where to store the secret + * @label: label for the secret + * @password: the null-terminated password to store + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * @...: the attribute keys and values, terminated with %NULL + * + * Store a password in the secret service. + * + * The variable argument list should contain pairs of a) The attribute name as + * a null-terminated string, followed by b) attribute value, either a character + * string, an int number, or a gboolean value, as defined in the @schema. + * The list of attribtues should be terminated with a %NULL. + * + * If the attributes match a secret item already stored in the collection, then + * the item will be updated with these new values. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: whether the storage was successful or not + */ gboolean secret_password_store_sync (const SecretSchema *schema, - const gchar *collection_path, - const gchar *label, - const gchar *password, - GCancellable *cancellable, - GError **error, - ...) + const gchar *collection_path, + const gchar *label, + const gchar *password, + GCancellable *cancellable, + GError **error, + ...) { GHashTable *attributes; va_list va; @@ -195,21 +273,43 @@ secret_password_store_sync (const SecretSchema *schema, attributes = _secret_util_attributes_for_varargs (schema, va); va_end (va); - ret = secret_password_storev_sync (schema, collection_path, label, password, - attributes, cancellable, error); + ret = secret_password_storev_sync (schema, attributes, collection_path, + label, password, cancellable, error); g_hash_table_unref (attributes); return ret; } +/** + * secret_password_storev_sync: + * @schema: the schema for attributes + * @attributes: the attribute keys and values + * @collection_path: the dbus path to the collection where to store the secret + * @label: label for the secret + * @password: the null-terminated password to store + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Store a password in the secret service. + * + * The @attributes should be a set of key and value string pairs. + * + * If the attributes match a secret item already stored in the collection, then + * the item will be updated with these new values. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: whether the storage was successful or not + */ gboolean secret_password_storev_sync (const SecretSchema *schema, - const gchar *collection_path, - const gchar *label, - const gchar *password, - GHashTable *attributes, - GCancellable *cancellable, - GError **error) + GHashTable *attributes, + const gchar *collection_path, + const gchar *label, + const gchar *password, + GCancellable *cancellable, + GError **error) { SecretSync *sync; gboolean ret; @@ -225,8 +325,8 @@ secret_password_storev_sync (const SecretSchema *schema, sync = _secret_sync_new (); g_main_context_push_thread_default (sync->context); - secret_password_storev (schema, collection_path, label, password, attributes, - cancellable, _secret_sync_on_result, sync); + secret_password_storev (schema, attributes, collection_path, label, password, + cancellable, _secret_sync_on_result, sync); g_main_loop_run (sync->loop); @@ -242,6 +342,7 @@ typedef struct { GCancellable *cancellable; GHashTable *attributes; SecretValue *value; + const SecretSchema *schema; } LookupClosure; static void @@ -255,12 +356,31 @@ lookup_closure_free (gpointer data) g_slice_free (LookupClosure, closure); } +/** + * secret_password_lookup: + * @schema: the schema to for attributes + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * @...: the attribute keys and values, terminated with %NULL + * + * Lookup a password in the secret service. + * + * The variable argument list should contain pairs of a) The attribute name as + * a null-terminated string, followed by b) attribute value, either a character + * string, an int number, or a gboolean value, as defined in the password + * @schema. The list of attribtues should be terminated with a %NULL. + * + * If no secret is found then %NULL is returned. + * + * This method will return immediately and complete asynchronously. + */ void secret_password_lookup (const SecretSchema *schema, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data, - ...) + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data, + ...) { GHashTable *attributes; va_list va; @@ -272,7 +392,8 @@ secret_password_lookup (const SecretSchema *schema, attributes = _secret_util_attributes_for_varargs (schema, va); va_end (va); - secret_password_lookupv (attributes, cancellable, callback, user_data); + secret_password_lookupv (schema, attributes, cancellable, + callback, user_data); g_hash_table_unref (attributes); } @@ -287,7 +408,7 @@ on_lookup_complete (GObject *source, GError *error = NULL; closure->value = secret_service_lookup_finish (SECRET_SERVICE (source), - result, &error); + result, &error); if (error != NULL) g_simple_async_result_take_error (res, error); @@ -312,42 +433,72 @@ on_lookup_connected (GObject *source, g_simple_async_result_complete (res); } else { - secret_service_lookupv (service, closure->attributes, closure->cancellable, - on_lookup_complete, g_object_ref (res)); + secret_service_lookupv (service, closure->schema, closure->attributes, + closure->cancellable, on_lookup_complete, + g_object_ref (res)); g_object_unref (service); } g_object_unref (res); } +/** + * secret_password_lookupv: + * @schema: the schema for attributes + * @attributes: the attribute keys and values + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Lookup a password in the secret service. + * + * The @attributes should be a set of key and value string pairs. + * + * If no secret is found then %NULL is returned. + * + * This method will return immediately and complete asynchronously. + */ void -secret_password_lookupv (GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) +secret_password_lookupv (const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; LookupClosure *closure; + g_return_if_fail (schema != NULL); g_return_if_fail (attributes != NULL); g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable)); res = g_simple_async_result_new (NULL, callback, user_data, secret_password_lookupv); closure = g_slice_new0 (LookupClosure); + closure->schema = schema; closure->cancellable = cancellable ? g_object_ref (cancellable) : NULL; closure->attributes = g_hash_table_ref (attributes); g_simple_async_result_set_op_res_gpointer (res, closure, lookup_closure_free); secret_service_get (SECRET_SERVICE_OPEN_SESSION, cancellable, - on_lookup_connected, g_object_ref (res)); + on_lookup_connected, g_object_ref (res)); g_object_unref (res); } +/** + * secret_password_lookup_finish: + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Finish an asynchronous operation to lookup a password in the secret service. + * + * Returns: (transfer full): a new password string which should be freed with + * secret_password_free() when done + */ gchar * secret_password_lookup_finish (GAsyncResult *result, - GError **error) + GError **error) { GSimpleAsyncResult *res; LookupClosure *closure; @@ -372,11 +523,33 @@ secret_password_lookup_finish (GAsyncResult *result, return password; } +/** + * secret_password_lookup_sync: + * @schema: the schema to for attributes + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * @...: the attribute keys and values, terminated with %NULL + * + * Lookup a password in the secret service. + * + * The variable argument list should contain pairs of a) The attribute name as + * a null-terminated string, followed by b) attribute value, either a character + * string, an int number, or a gboolean value, as defined in the password + * @schema. The list of attribtues should be terminated with a %NULL. + * + * If no secret is found then %NULL is returned. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: (transfer full): a new password string which should be freed with + * secret_password_free() when done + */ gchar * secret_password_lookup_sync (const SecretSchema *schema, - GCancellable *cancellable, - GError **error, - ...) + GCancellable *cancellable, + GError **error, + ...) { GHashTable *attributes; gchar *password; @@ -390,21 +563,43 @@ secret_password_lookup_sync (const SecretSchema *schema, attributes = _secret_util_attributes_for_varargs (schema, va); va_end (va); - password = secret_password_lookupv_sync (attributes, cancellable, error); + password = secret_password_lookupv_sync (schema, attributes, + cancellable, error); g_hash_table_unref (attributes); return password; } +/** + * secret_password_lookupv_sync: + * @schema: the schema for attributes + * @attributes: the attribute keys and values + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Lookup a password in the secret service. + * + * The @attributes should be a set of key and value string pairs. + * + * If no secret is found then %NULL is returned. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: (transfer full): a new password string which should be freed with + * secret_password_free() when done + */ gchar * -secret_password_lookupv_sync (GHashTable *attributes, - GCancellable *cancellable, - GError **error) +secret_password_lookupv_sync (const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GError **error) { SecretSync *sync; gchar *password; + g_return_val_if_fail (schema != NULL, NULL); g_return_val_if_fail (attributes != NULL, NULL); g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL); g_return_val_if_fail (error == NULL || *error == NULL, NULL); @@ -412,8 +607,8 @@ secret_password_lookupv_sync (GHashTable *attributes, sync = _secret_sync_new (); g_main_context_push_thread_default (sync->context); - secret_password_lookupv (attributes, cancellable, - _secret_sync_on_result, sync); + secret_password_lookupv (schema, attributes, cancellable, + _secret_sync_on_result, sync); g_main_loop_run (sync->loop); @@ -429,6 +624,7 @@ typedef struct { GCancellable *cancellable; GHashTable *attributes; gboolean deleted; + const SecretSchema *schema; } DeleteClosure; static void @@ -440,12 +636,31 @@ delete_closure_free (gpointer data) g_slice_free (DeleteClosure, closure); } +/** + * secret_password_remove: + * @schema: the schema to for attributes + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * @...: the attribute keys and values, terminated with %NULL + * + * Remove a password from the secret service. + * + * The variable argument list should contain pairs of a) The attribute name as + * a null-terminated string, followed by b) attribute value, either a character + * string, an int number, or a gboolean value, as defined in the password + * @schema. The list of attribtues should be terminated with a %NULL. + * + * If multiple items match the attributes, then only one will be deleted. + * + * This method will return immediately and complete asynchronously. + */ void secret_password_remove (const SecretSchema *schema, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data, - ...) + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data, + ...) { GHashTable *attributes; va_list va; @@ -457,8 +672,8 @@ secret_password_remove (const SecretSchema *schema, attributes = _secret_util_attributes_for_varargs (schema, va); va_end (va); - secret_password_removev (attributes, cancellable, - callback, user_data); + secret_password_removev (schema, attributes, cancellable, + callback, user_data); g_hash_table_unref (attributes); } @@ -473,7 +688,7 @@ on_delete_complete (GObject *source, GError *error = NULL; closure->deleted = secret_service_remove_finish (SECRET_SERVICE (source), - result, &error); + result, &error); if (error != NULL) g_simple_async_result_take_error (res, error); g_simple_async_result_complete (res); @@ -493,9 +708,9 @@ on_delete_connect (GObject *source, service = secret_service_get_finish (result, &error); if (error == NULL) { - secret_service_removev (service, closure->attributes, - closure->cancellable, on_delete_complete, - g_object_ref (res)); + secret_service_removev (service, closure->schema, closure->attributes, + closure->cancellable, on_delete_complete, + g_object_ref (res)); g_object_unref (service); } else { @@ -506,34 +721,63 @@ on_delete_connect (GObject *source, g_object_unref (res); } +/** + * secret_password_removev: + * @schema: the schema to for attributes + * @attributes: the attribute keys and values + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Remove a password from the secret service. + * + * The @attributes should be a set of key and value string pairs. + * + * If multiple items match the attributes, then only one will be deleted. + * + * This method will return immediately and complete asynchronously. + */ void -secret_password_removev (GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) +secret_password_removev (const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; DeleteClosure *closure; + g_return_if_fail (schema != NULL); g_return_if_fail (attributes != NULL); g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable)); res = g_simple_async_result_new (NULL, callback, user_data, secret_password_removev); closure = g_slice_new0 (DeleteClosure); + closure->schema = schema; closure->attributes = g_hash_table_ref (attributes); closure->cancellable = cancellable ? g_object_ref (cancellable) : NULL; g_simple_async_result_set_op_res_gpointer (res, closure, delete_closure_free); secret_service_get (SECRET_SERVICE_NONE, cancellable, - on_delete_connect, g_object_ref (res)); + on_delete_connect, g_object_ref (res)); g_object_unref (res); } +/** + * secret_password_remove_finish + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Finish an asynchronous operation to remove a password from the secret + * service. + * + * Returns: whether the removal was successful or not + */ gboolean secret_password_remove_finish (GAsyncResult *result, - GError **error) + GError **error) { DeleteClosure *closure; GSimpleAsyncResult *res; @@ -550,11 +794,32 @@ secret_password_remove_finish (GAsyncResult *result, return closure->deleted; } +/** + * secret_password_remove_sync: + * @schema: the schema to for attributes + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * @...: the attribute keys and values, terminated with %NULL + * + * Remove a password from the secret service. + * + * The variable argument list should contain pairs of a) The attribute name as + * a null-terminated string, followed by b) attribute value, either a character + * string, an int number, or a gboolean value, as defined in the password + * @schema. The list of attribtues should be terminated with a %NULL. + * + * If multiple items match the attributes, then only one will be deleted. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: whether the removal was successful or not + */ gboolean secret_password_remove_sync (const SecretSchema* schema, - GCancellable *cancellable, - GError **error, - ...) + GCancellable *cancellable, + GError **error, + ...) { GHashTable *attributes; gboolean result; @@ -568,21 +833,42 @@ secret_password_remove_sync (const SecretSchema* schema, attributes = _secret_util_attributes_for_varargs (schema, va); va_end (va); - result = secret_password_removev_sync (attributes, cancellable, error); + result = secret_password_removev_sync (schema, attributes, + cancellable, error); g_hash_table_unref (attributes); return result; } +/** + * secret_password_removev_sync: + * @schema: the schema to for attributes + * @attributes: the attribute keys and values + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Remove a password from the secret service. + * + * The @attributes should be a set of key and value string pairs. + * + * If multiple items match the attributes, then only one will be deleted. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: whether the removal was successful or not + */ gboolean -secret_password_removev_sync (GHashTable *attributes, - GCancellable *cancellable, - GError **error) +secret_password_removev_sync (const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GError **error) { SecretSync *sync; gboolean result; + g_return_val_if_fail (schema != NULL, FALSE); g_return_val_if_fail (attributes != NULL, FALSE); g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE); g_return_val_if_fail (error == NULL || *error == NULL, FALSE); @@ -590,8 +876,8 @@ secret_password_removev_sync (GHashTable *attributes, sync = _secret_sync_new (); g_main_context_push_thread_default (sync->context); - secret_password_removev (attributes, cancellable, - _secret_sync_on_result, sync); + secret_password_removev (schema, attributes, cancellable, + _secret_sync_on_result, sync); g_main_loop_run (sync->loop); @@ -603,6 +889,13 @@ secret_password_removev_sync (GHashTable *attributes, return result; } +/** + * secret_password_free: + * @password: (type utf8) (allow-none): password to free + * + * Free a password returned by secret_password_lookup_finish(), + * secret_password_lookup_sync() or secret_password_lookupv_sync(). + */ void secret_password_free (gpointer password) { diff --git a/library/secret-password.h b/library/secret-password.h index db100dd..a1d039c 100644 --- a/library/secret-password.h +++ b/library/secret-password.h @@ -10,6 +10,10 @@ * See the included COPYING file for more information. */ +#if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) +#error "Only can be included directly." +#endif + #ifndef __SECRET_PASSWORD_H__ #define __SECRET_PASSWORD_H__ @@ -20,90 +24,94 @@ G_BEGIN_DECLS #include "secret-types.h" void secret_password_store (const SecretSchema *schema, - const gchar *collection_path, - const gchar *label, - const gchar *password, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data, - ...) G_GNUC_NULL_TERMINATED; + const gchar *collection_path, + const gchar *label, + const gchar *password, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data, + ...) G_GNUC_NULL_TERMINATED; void secret_password_storev (const SecretSchema *schema, - const gchar *collection_path, - const gchar *label, - const gchar *password, - GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GHashTable *attributes, + const gchar *collection_path, + const gchar *label, + const gchar *password, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_password_store_finish (GAsyncResult *result, - GError **error); + GError **error); gboolean secret_password_store_sync (const SecretSchema *schema, - const gchar *collection_path, - const gchar *label, - const gchar *password, - GCancellable *cancellable, - GError **error, - ...) G_GNUC_NULL_TERMINATED; + const gchar *collection_path, + const gchar *label, + const gchar *password, + GCancellable *cancellable, + GError **error, + ...) G_GNUC_NULL_TERMINATED; gboolean secret_password_storev_sync (const SecretSchema *schema, - const gchar *collection_path, - const gchar *display_name, - const gchar *password, - GHashTable *attributes, - GCancellable *cancellable, - GError **error); + GHashTable *attributes, + const gchar *collection_path, + const gchar *label, + const gchar *password, + GCancellable *cancellable, + GError **error); void secret_password_lookup (const SecretSchema *schema, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data, - ...) G_GNUC_NULL_TERMINATED; + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data, + ...) G_GNUC_NULL_TERMINATED; -void secret_password_lookupv (GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); +void secret_password_lookupv (const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gchar * secret_password_lookup_finish (GAsyncResult *result, - GError **error); + GError **error); gchar * secret_password_lookup_sync (const SecretSchema *schema, - GCancellable *cancellable, - GError **error, - ...) G_GNUC_NULL_TERMINATED; + GCancellable *cancellable, + GError **error, + ...) G_GNUC_NULL_TERMINATED; -gchar * secret_password_lookupv_sync (GHashTable *attributes, - GCancellable *cancellable, - GError **error); +gchar * secret_password_lookupv_sync (const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GError **error); void secret_password_remove (const SecretSchema *schema, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data, - ...) G_GNUC_NULL_TERMINATED; + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data, + ...) G_GNUC_NULL_TERMINATED; -void secret_password_removev (GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); +void secret_password_removev (const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_password_remove_finish (GAsyncResult *result, - GError **error); + GError **error); gboolean secret_password_remove_sync (const SecretSchema* schema, - GCancellable *cancellable, - GError **error, - ...) G_GNUC_NULL_TERMINATED; + GCancellable *cancellable, + GError **error, + ...) G_GNUC_NULL_TERMINATED; -gboolean secret_password_removev_sync (GHashTable *attributes, - GCancellable *cancellable, - GError **error); +gboolean secret_password_removev_sync (const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GError **error); void secret_password_free (gpointer password); G_END_DECLS -#endif /* __G_SERVICE_H___ */ +#endif /* __SECRET_PASSWORD_H___ */ diff --git a/library/secret-private.h b/library/secret-private.h index 4c1acab..cc5779b 100644 --- a/library/secret-private.h +++ b/library/secret-private.h @@ -41,16 +41,16 @@ typedef struct _SecretSession SecretSession; #define SECRET_PROPERTIES_INTERFACE "org.freedesktop.DBus.Properties" -SecretSync * _secret_sync_new (void); +SecretSync * _secret_sync_new (void); void _secret_sync_free (gpointer data); void _secret_sync_on_result (GObject *source, - GAsyncResult *result, - gpointer user_data); + GAsyncResult *result, + gpointer user_data); -SecretPrompt * _secret_prompt_instance (GDBusConnection *connection, - const gchar *object_path); +SecretPrompt * _secret_prompt_instance (SecretService *service, + const gchar *prompt_path); gchar * _secret_util_parent_path (const gchar *path); @@ -63,61 +63,61 @@ GVariant * _secret_util_variant_for_attributes (GHashTable *attri GHashTable * _secret_util_attributes_for_variant (GVariant *variant); GHashTable * _secret_util_attributes_for_varargs (const SecretSchema *schema, - va_list va); + va_list va); GVariant * _secret_util_variant_for_properties (GHashTable *properties); void _secret_util_get_properties (GDBusProxy *proxy, - gpointer result_tag, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + gpointer result_tag, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean _secret_util_get_properties_finish (GDBusProxy *proxy, - gpointer result_tag, - GAsyncResult *result, - GError **error); + gpointer result_tag, + GAsyncResult *result, + GError **error); void _secret_util_set_property (GDBusProxy *proxy, - const gchar *property, - GVariant *value, - gpointer result_tag, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar *property, + GVariant *value, + gpointer result_tag, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean _secret_util_set_property_finish (GDBusProxy *proxy, - gpointer result_tag, - GAsyncResult *result, - GError **error); + gpointer result_tag, + GAsyncResult *result, + GError **error); gboolean _secret_util_set_property_sync (GDBusProxy *proxy, - const gchar *property, - GVariant *value, - GCancellable *cancellable, - GError **error); + const gchar *property, + GVariant *value, + GCancellable *cancellable, + GError **error); gboolean _secret_util_have_cached_properties (GDBusProxy *proxy); void _secret_service_set_default_bus_name (const gchar *bus_name); -SecretSession * _secret_service_get_session (SecretService *self); +SecretSession * _secret_service_get_session (SecretService *self); void _secret_service_take_session (SecretService *self, - SecretSession *session); + SecretSession *session); void _secret_service_delete_path (SecretService *self, - const gchar *object_path, - gboolean is_an_item, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar *object_path, + gboolean is_an_item, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); -SecretItem * _secret_service_find_item_instance (SecretService *self, - const gchar *item_path); +SecretItem * _secret_service_find_item_instance (SecretService *self, + const gchar *item_path); -SecretItem * _secret_collection_find_item_instance (SecretCollection *self, - const gchar *item_path); +SecretItem * _secret_collection_find_item_instance (SecretCollection *self, + const gchar *item_path); gchar * _secret_value_unref_to_password (SecretValue *value); @@ -128,19 +128,19 @@ const gchar * _secret_session_get_algorithms (SecretSession *se const gchar * _secret_session_get_path (SecretSession *session); void _secret_session_open (SecretService *service, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean _secret_session_open_finish (GAsyncResult *result, - GError **error); + GError **error); GVariant * _secret_session_encode_secret (SecretSession *session, - SecretValue *value); + SecretValue *value); -SecretValue * _secret_session_decode_secret (SecretSession *session, - GVariant *encoded); +SecretValue * _secret_session_decode_secret (SecretSession *session, + GVariant *encoded); G_END_DECLS -#endif /* __G_SERVICE_H___ */ +#endif /* __SECRET_PRIVATE_H___ */ diff --git a/library/secret-prompt.c b/library/secret-prompt.c index 0309e22..d33f6f4 100644 --- a/library/secret-prompt.c +++ b/library/secret-prompt.c @@ -77,7 +77,7 @@ on_prompt_run_complete (GObject *source, } SecretPrompt * -secret_prompt_instance (SecretService *service, +_secret_prompt_instance (SecretService *service, const gchar *prompt_path) { GDBusProxy *proxy; @@ -106,11 +106,33 @@ secret_prompt_instance (SecretService *service, return prompt; } +/** + * secret_prompt_run: + * @self: a prompt + * @window_id: XWindow id for parent window to be transient for + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Runs a prompt and performs the prompting. Returns %TRUE if the prompt + * was completed and not dismissed. + * + * If @window_id is non-zero then it is used as an XWindow id. The Secret + * Service can make its prompt transient for the window with this id. In some + * Secret Service implementations this is not possible, so the behavior + * depending on this should degrade gracefully. + * + * This runs the dialog in a recursive mainloop. When run from a user interface + * thread, this means the user interface will remain responsive. Care should be + * taken that appropriate user interface actions are disabled while running the + * prompt. + * + * Returns: %FALSE if the prompt was dismissed or an error occurred + */ gboolean secret_prompt_run (SecretPrompt *self, - gulong window_id, - GCancellable *cancellable, - GError **error) + gulong window_id, + GCancellable *cancellable, + GError **error) { GMainContext *context; RunClosure *closure; @@ -126,7 +148,7 @@ secret_prompt_run (SecretPrompt *self, closure->loop = g_main_loop_new (context, FALSE); secret_prompt_perform (self, window_id, cancellable, - on_prompt_run_complete, closure); + on_prompt_run_complete, closure); g_main_loop_run (closure->loop); @@ -139,11 +161,31 @@ secret_prompt_run (SecretPrompt *self, return ret; } +/** + * secret_prompt_perform_sync: + * @self: a prompt + * @window_id: XWindow id for parent window to be transient for + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Runs a prompt and performs the prompting. Returns %TRUE if the prompt + * was completed and not dismissed. + * + * If @window_id is non-zero then it is used as an XWindow id. The Secret + * Service can make its prompt transient for the window with this id. In some + * Secret Service implementations this is not possible, so the behavior + * depending on this should degrade gracefully. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: %FALSE if the prompt was dismissed or an error occurred + */ gboolean secret_prompt_perform_sync (SecretPrompt *self, - gulong window_id, - GCancellable *cancellable, - GError **error) + gulong window_id, + GCancellable *cancellable, + GError **error) { GMainContext *context; gboolean ret; @@ -341,12 +383,30 @@ on_prompt_cancelled (GCancellable *cancellable, g_object_unref (self); } +/** + * secret_prompt_perform: + * @self: a prompt + * @window_id: XWindow id for parent window to be transient for + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Runs a prompt and performs the prompting. Returns %TRUE if the prompt + * was completed and not dismissed. + * + * If @window_id is non-zero then it is used as an XWindow id. The Secret + * Service can make its prompt transient for the window with this id. In some + * Secret Service implementations this is not possible, so the behavior + * depending on this should degrade gracefully. + * + * This method will return immediately and complete asynchronously. + */ void secret_prompt_perform (SecretPrompt *self, - gulong window_id, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + gulong window_id, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; PerformClosure *closure; @@ -415,10 +475,20 @@ secret_prompt_perform (SecretPrompt *self, g_object_unref (res); } +/** + * secret_prompt_perform_finish: + * @self: a prompt + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Complete asynchronous operation to run a prompt and perform the prompting. + * + * Returns: %FALSE if the prompt was dismissed or an error occurred + */ gboolean secret_prompt_perform_finish (SecretPrompt *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { PerformClosure *closure; GSimpleAsyncResult *res; @@ -437,9 +507,26 @@ secret_prompt_perform_finish (SecretPrompt *self, return !closure->dismissed; } +/** + * secret_prompt_get_result_value: + * @self: a prompt + * @expected_type: (allow-none): expected variant type of the result + * + * Get the result returned from a completed prompt. + * + * After performing a prompt in the Secret Service API, the prompt can + * return a result value. The type of value returned is dependent on + * the prompt. + * + * It is not normally necessary to call this function, as this is done + * automatically by other functions in this library. + * + * Returns: (transfer full): the result value which should be released with + * g_variant_unref() when done, or %NULL if no result + */ GVariant * secret_prompt_get_result_value (SecretPrompt *self, - const GVariantType *expected_type) + const GVariantType *expected_type) { GVariant *last_result; gchar *string; diff --git a/library/secret-prompt.h b/library/secret-prompt.h index a0767e9..2894ca9 100644 --- a/library/secret-prompt.h +++ b/library/secret-prompt.h @@ -10,6 +10,10 @@ * See the included COPYING file for more information. */ +#if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) +#error "Only can be included directly." +#endif + #ifndef __SECRET_PROMPT_H__ #define __SECRET_PROMPT_H__ @@ -41,32 +45,29 @@ struct _SecretPromptClass { GType secret_prompt_get_type (void) G_GNUC_CONST; -SecretPrompt * secret_prompt_instance (SecretService *service, - const gchar *prompt_path); - gboolean secret_prompt_run (SecretPrompt *self, - gulong window_id, - GCancellable *cancellable, - GError **error); + gulong window_id, + GCancellable *cancellable, + GError **error); gboolean secret_prompt_perform_sync (SecretPrompt *self, - gulong window_id, - GCancellable *cancellable, - GError **error); + gulong window_id, + GCancellable *cancellable, + GError **error); void secret_prompt_perform (SecretPrompt *self, - gulong window_id, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + gulong window_id, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_prompt_perform_finish (SecretPrompt *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); GVariant * secret_prompt_get_result_value (SecretPrompt *self, - const GVariantType *expected_type); + const GVariantType *expected_type); G_END_DECLS -#endif /* __G_SERVICE_H___ */ +#endif /* __SECRET_PROMPT_H___ */ diff --git a/library/secret-service.c b/library/secret-service.c index e7769f8..f486c05 100644 --- a/library/secret-service.c +++ b/library/secret-service.c @@ -73,9 +73,9 @@ secret_service_init (SecretService *self) static void secret_service_get_property (GObject *obj, - guint prop_id, - GValue *value, - GParamSpec *pspec) + guint prop_id, + GValue *value, + GParamSpec *pspec) { SecretService *self = SECRET_SERVICE (obj); @@ -94,9 +94,9 @@ secret_service_get_property (GObject *obj, static void secret_service_set_property (GObject *obj, - guint prop_id, - const GValue *value, - GParamSpec *pspec) + guint prop_id, + const GValue *value, + GParamSpec *pspec) { SecretService *self = SECRET_SERVICE (obj); @@ -135,9 +135,9 @@ secret_service_finalize (GObject *obj) static gboolean secret_service_real_prompt_sync (SecretService *self, - SecretPrompt *prompt, - GCancellable *cancellable, - GError **error) + SecretPrompt *prompt, + GCancellable *cancellable, + GError **error) { return secret_prompt_perform_sync (prompt, 0, cancellable, error); } @@ -162,10 +162,10 @@ on_real_prompt_completed (GObject *source, static void secret_service_real_prompt_async (SecretService *self, - SecretPrompt *prompt, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + SecretPrompt *prompt, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; @@ -173,16 +173,16 @@ secret_service_real_prompt_async (SecretService *self, secret_service_real_prompt_async); secret_prompt_perform (prompt, 0, cancellable, - on_real_prompt_completed, - g_object_ref (res)); + on_real_prompt_completed, + g_object_ref (res)); g_object_unref (res); } static gboolean secret_service_real_prompt_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res = G_SIMPLE_ASYNC_RESULT (result); @@ -212,8 +212,8 @@ handle_property_changed (SecretService *self, static void secret_service_properties_changed (GDBusProxy *proxy, - GVariant *changed_properties, - const gchar* const *invalidated_properties) + GVariant *changed_properties, + const gchar* const *invalidated_properties) { SecretService *self = SECRET_SERVICE (proxy); gchar *property_name; @@ -323,7 +323,7 @@ on_ensure_session (GObject *source, } else if (closure->flags & SECRET_SERVICE_LOAD_COLLECTIONS) { secret_service_ensure_collections (self, closure->cancellable, - on_ensure_collections, g_object_ref (res)); + on_ensure_collections, g_object_ref (res)); } else { g_simple_async_result_complete_in_idle (res); @@ -343,11 +343,11 @@ service_ensure_for_flags_async (SecretService *self, if (closure->flags & SECRET_SERVICE_OPEN_SESSION) secret_service_ensure_session (self, closure->cancellable, - on_ensure_session, g_object_ref (res)); + on_ensure_session, g_object_ref (res)); else if (closure->flags & SECRET_SERVICE_LOAD_COLLECTIONS) secret_service_ensure_collections (self, closure->cancellable, - on_ensure_collections, g_object_ref (res)); + on_ensure_collections, g_object_ref (res)); else g_simple_async_result_complete_in_idle (res); @@ -355,8 +355,8 @@ service_ensure_for_flags_async (SecretService *self, static gboolean secret_service_initable_init (GInitable *initable, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { SecretService *self; @@ -385,7 +385,7 @@ on_init_base (GObject *source, GError *error = NULL; if (!secret_service_async_initable_parent_iface->init_finish (G_ASYNC_INITABLE (self), - result, &error)) { + result, &error)) { g_simple_async_result_take_error (res, error); g_simple_async_result_complete (res); } else { @@ -398,32 +398,32 @@ on_init_base (GObject *source, static void secret_service_async_initable_init_async (GAsyncInitable *initable, - int io_priority, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + int io_priority, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; InitClosure *closure; res = g_simple_async_result_new (G_OBJECT (initable), callback, user_data, - secret_service_async_initable_init_async); + secret_service_async_initable_init_async); closure = g_slice_new0 (InitClosure); closure->cancellable = cancellable ? g_object_ref (cancellable) : NULL; g_simple_async_result_set_op_res_gpointer (res, closure, init_closure_free); secret_service_async_initable_parent_iface->init_async (initable, io_priority, - cancellable, - on_init_base, - g_object_ref (res)); + cancellable, + on_init_base, + g_object_ref (res)); g_object_unref (res); } static gboolean secret_service_async_initable_init_finish (GAsyncInitable *initable, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { g_return_val_if_fail (g_simple_async_result_is_valid (result, G_OBJECT (initable), secret_service_async_initable_init_async), FALSE); @@ -462,11 +462,26 @@ on_service_instance_gone (gpointer user_data, G_UNLOCK (service_instance); } +/** + * secret_service_get: + * @flags: flags for which service functionality to ensure is initialized + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Get a #SecretService proxy for the Secret Service. If such a proxy object + * already exists, then the same proxy is returned. + * + * If @flags contains any flags of which parts of the secret service to + * ensure are initialized, then those will be initialized before completing. + * + * This method will return immediately and complete asynchronously. + */ void secret_service_get (SecretServiceFlags flags, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { SecretService *service = NULL; GSimpleAsyncResult *res; @@ -506,9 +521,20 @@ secret_service_get (SecretServiceFlags flags, } } +/** + * secret_service_get_finish: + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Complete an asynchronous operation to get a #SecretService proxy for the + * Secret Service. + * + * Returns: (transfer full): a new reference to a #SecretService proxy, which + * should be released with g_object_unref(). + */ SecretService * secret_service_get_finish (GAsyncResult *result, - GError **error) + GError **error) { GObject *service = NULL; GObject *source_object; @@ -546,10 +572,28 @@ secret_service_get_finish (GAsyncResult *result, return SECRET_SERVICE (service); } +/** + * secret_service_get_sync: + * @flags: flags for which service functionality to ensure is initialized + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Get a #SecretService proxy for the Secret Service. If such a proxy object + * already exists, then the same proxy is returned. + * + * If @flags contains any flags of which parts of the secret service to + * ensure are initialized, then those will be initialized before returning. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: (transfer full): a new reference to a #SecretService proxy, which + * should be released with g_object_unref(). + */ SecretService * secret_service_get_sync (SecretServiceFlags flags, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { SecretService *service = NULL; @@ -588,12 +632,31 @@ secret_service_get_sync (SecretServiceFlags flags, return service; } +/** + * secret_service_new: + * @service_bus_name: (allow-none): dbus service name of the secret service + * @flags: flags for which service functionality to ensure is initialized + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Create a new #SecretService proxy for the Secret Service. + * + * This function is rarely used, see secret_service_get() instead. + * + * If @flags contains any flags of which parts of the secret service to + * ensure are initialized, then those will be initialized before returning. + * + * If @service_bus_name is %NULL then the default is used. + * + * This method will return immediately and complete asynchronously. + */ void secret_service_new (const gchar *service_bus_name, - SecretServiceFlags flags, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + SecretServiceFlags flags, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable)); @@ -612,9 +675,20 @@ secret_service_new (const gchar *service_bus_name, NULL); } +/** + * secret_service_new_finish: + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Complete an asynchronous operation to create a new #SecretService proxy for + * the Secret Service. + * + * Returns: (transfer full): a new reference to a #SecretService proxy, which + * should be released with g_object_unref(). + */ SecretService * secret_service_new_finish (GAsyncResult *result, - GError **error) + GError **error) { GObject *source_object; GObject *object; @@ -633,11 +707,33 @@ secret_service_new_finish (GAsyncResult *result, return SECRET_SERVICE (object); } +/** + * secret_service_new_sync: + * @service_bus_name: (allow-none): dbus service name of the secret service + * @flags: flags for which service functionality to ensure is initialized + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Create a new #SecretService proxy for the Secret Service. + * + * This function is rarely used, see secret_service_get_sync() instead. + * + * If @flags contains any flags of which parts of the secret service to + * ensure are initialized, then those will be initialized before returning. + * + * If @service_bus_name is %NULL then the default is used. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: (transfer full): a new reference to a #SecretService proxy, which + * should be released with g_object_unref(). + */ SecretService * secret_service_new_sync (const gchar *service_bus_name, - SecretServiceFlags flags, - GCancellable *cancellable, - GError **error) + SecretServiceFlags flags, + GCancellable *cancellable, + GError **error) { g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), NULL); @@ -655,6 +751,18 @@ secret_service_new_sync (const gchar *service_bus_name, NULL); } +/** + * secret_service_get_flags: + * @self: the secret service proxy + * + * Get the flags representing what features of the #SecretService proxy + * have been initialized. + * + * Use secret_service_ensure_session() or secret_service_ensure_collections() + * to initialize further features and change the flags. + * + * Returns: the flags for features initialized + */ SecretServiceFlags secret_service_get_flags (SecretService *self) { @@ -674,6 +782,20 @@ secret_service_get_flags (SecretService *self) return flags; } +/** + * secret_service_get_collections: + * @self: the secret service proxy + * + * Get a list of #SecretCollection objects representing all the collections + * in the secret service. + * + * If the %SECRET_SERVICE_LOAD_COLLECTIONS flag was not specified when + * initializing #SecretService proxy object, then this method will return + * %NULL. Use secret_service_ensure_collections() to load the collections. + * + * Returns: (transfer full) (element-type Secret.Collection) (allow-none): a + * list of the collections in the secret service + */ GList * secret_service_get_collections (SecretService *self) { @@ -699,7 +821,7 @@ secret_service_get_collections (SecretService *self) SecretItem * _secret_service_find_item_instance (SecretService *self, - const gchar *item_path) + const gchar *item_path) { SecretCollection *collection = NULL; gchar *collection_path; @@ -742,7 +864,7 @@ _secret_service_get_session (SecretService *self) void _secret_service_take_session (SecretService *self, - SecretSession *session) + SecretSession *session) { g_return_if_fail (SECRET_IS_SERVICE (self)); g_return_if_fail (session != NULL); @@ -755,6 +877,19 @@ _secret_service_take_session (SecretService *self, g_mutex_unlock (&self->pv->mutex); } +/** + * secret_service_get_session_algorithms: + * @self: the secret service proxy + * + * Get the set of algorithms being used to transfer secrets between this + * secret service proxy and the Secret Service itself. + * + * This will be %NULL if no session has been established. Use + * secret_service_ensure_session() to establish a session. + * + * Returns: (allow-none): a string representing the algorithms for transferring + * secrets + */ const gchar * secret_service_get_session_algorithms (SecretService *self) { @@ -772,6 +907,19 @@ secret_service_get_session_algorithms (SecretService *self) return algorithms; } +/** + * secret_service_get_session_path: + * @self: the secret service proxy + * + * Get the dbus object path of the session object being used to transfer + * secrets between this secret service proxy and the Secret Service itself. + * + * This will be %NULL if no session has been established. Use + * secret_service_ensure_session() to establish a session. + * + * Returns: (allow-none): a string representing the dbus object path of the + * session + */ const gchar * secret_service_get_session_path (SecretService *self) { @@ -789,11 +937,28 @@ secret_service_get_session_path (SecretService *self) return path; } +/** + * secret_service_ensure_session: + * @self: the secret service + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Ensure that the #SecretService proxy has established a session with the + * Secret Service. This session is used to transfer secrets. + * + * It is not normally necessary to call this method, as the session is + * established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION + * to secret_service_get() in order to ensure that a session has been established + * by the time you get the #SecretService proxy. + * + * This method will return immediately and complete asynchronously. + */ void secret_service_ensure_session (SecretService *self, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; SecretSession *session; @@ -816,10 +981,21 @@ secret_service_ensure_session (SecretService *self, } } +/** + * secret_service_ensure_session_finish: + * @self: the secret service + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Finish an asynchronous operation to ensure that the #SecretService proxy + * has established a session with the Secret Service. + * + * Returns: the path of the established session + */ const gchar * secret_service_ensure_session_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { g_return_val_if_fail (SECRET_IS_SERVICE (self), NULL); g_return_val_if_fail (error == NULL || *error == NULL, NULL); @@ -834,10 +1010,29 @@ secret_service_ensure_session_finish (SecretService *self, return secret_service_get_session_path (self); } +/** + * secret_service_ensure_session_sync: + * @self: the secret service + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Ensure that the #SecretService proxy has established a session with the + * Secret Service. This session is used to transfer secrets. + * + * It is not normally necessary to call this method, as the session is + * established as necessary. You can also pass the %SECRET_SERVICE_OPEN_SESSION + * to secret_service_get_sync() in order to ensure that a session has been + * established by the time you get the #SecretService proxy. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: the path of the established session + */ const gchar * secret_service_ensure_session_sync (SecretService *self, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { SecretSync *sync; const gchar *path; @@ -850,7 +1045,7 @@ secret_service_ensure_session_sync (SecretService *self, g_main_context_push_thread_default (sync->context); secret_service_ensure_session (self, cancellable, - _secret_sync_on_result, sync); + _secret_sync_on_result, sync); g_main_loop_run (sync->loop); @@ -955,11 +1150,28 @@ on_ensure_collection (GObject *source, g_object_unref (res); } +/** + * secret_service_ensure_collections: + * @self: the secret service + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Ensure that the #SecretService proxy has loaded all the collections present + * in the Secret Service. This affects the result of + * secret_service_get_collections(). + * + * You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to + * secret_service_get_sync() in order to ensure that the collections have been + * loaded by the time you get the #SecretService proxy. + * + * This method will return immediately and complete asynchronously. + */ void secret_service_ensure_collections (SecretService *self, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { EnsureClosure *closure; SecretCollection *collection; @@ -988,7 +1200,7 @@ secret_service_ensure_collections (SecretService *self, /* No such collection yet create a new one */ if (collection == NULL) { secret_collection_new (self, path, cancellable, - on_ensure_collection, g_object_ref (res)); + on_ensure_collection, g_object_ref (res)); closure->collections_loading++; } else { g_hash_table_insert (closure->collections, g_strdup (path), collection); @@ -1004,10 +1216,21 @@ secret_service_ensure_collections (SecretService *self, g_object_unref (res); } +/** + * secret_service_ensure_collections_finish: + * @self: the secret service + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Complete an asynchronous operation to ensure that the #SecretService proxy + * has loaded all the collections present in the Secret Service. + * + * Returns: whether the load was successful or not + */ gboolean secret_service_ensure_collections_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { g_return_val_if_fail (SECRET_IS_SERVICE (self), FALSE); g_return_val_if_fail (error == NULL || *error == NULL, FALSE); @@ -1020,10 +1243,29 @@ secret_service_ensure_collections_finish (SecretService *self, return TRUE; } +/** + * secret_service_ensure_collections_sync: + * @self: the secret service + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Ensure that the #SecretService proxy has loaded all the collections present + * in the Secret Service. This affects the result of + * secret_service_get_collections(). + * + * You can also pass the %SECRET_SERVICE_LOAD_COLLECTIONS to + * secret_service_get_sync() in order to ensure that the collections have been + * loaded by the time you get the #SecretService proxy. + * + * This method may block indefinitely and should not be used in user interface + * threads. + * + * Returns: whether the load was successful or not + */ gboolean secret_service_ensure_collections_sync (SecretService *self, - GCancellable *cancellable, - GError **error) + GCancellable *cancellable, + GError **error) { SecretCollection *collection; GHashTable *collections; @@ -1065,11 +1307,29 @@ secret_service_ensure_collections_sync (SecretService *self, return ret; } +/** + * secret_service_prompt_sync: + * @self: the secret service + * @prompt: the prompt + * @cancellable: optional cancellation object + * @error: location to place an error on failure + * + * Perform prompting for a #SecretPrompt. + * + * This function is called by other parts of this library to handle prompts + * for the various actions that can require prompting. + * + * Override the #SecretService prompt_sync() virtual method + * to change the behavior of the propmting. The default behavior is to simply + * run secret_prompt_perform_sync() on the prompt. + * + * Returns: %FALSE if the prompt was dismissed or an error occurred + */ gboolean secret_service_prompt_sync (SecretService *self, - SecretPrompt *prompt, - GCancellable *cancellable, - GError **error) + SecretPrompt *prompt, + GCancellable *cancellable, + GError **error) { SecretServiceClass *klass; @@ -1084,12 +1344,29 @@ secret_service_prompt_sync (SecretService *self, return (klass->prompt_sync) (self, prompt, cancellable, error); } +/** + * secret_service_prompt: + * @self: the secret service + * @prompt: the prompt + * @cancellable: optional cancellation object + * @callback: called when the operation completes + * @user_data: data to be passed to the callback + * + * Perform prompting for a #SecretPrompt. + * + * This function is called by other parts of this library to handle prompts + * for the various actions that can require prompting. + * + * Override the #SecretService prompt_async() virtual method + * to change the behavior of the propmting. The default behavior is to simply + * run secret_prompt_perform() on the prompt. + */ void secret_service_prompt (SecretService *self, - SecretPrompt *prompt, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + SecretPrompt *prompt, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { SecretServiceClass *klass; @@ -1103,10 +1380,20 @@ secret_service_prompt (SecretService *self, (klass->prompt_async) (self, prompt, cancellable, callback, user_data); } +/** + * secret_service_prompt_finish: + * @self: the secret service + * @result: the asynchronous result passed to the callback + * @error: location to place an error on failure + * + * Complete asynchronous operation to perform prompting for a #SecretPrompt. + * + * Returns: %FALSE if the prompt was dismissed or an error occurred + */ gboolean secret_service_prompt_finish (SecretService *self, - GAsyncResult *result, - GError **error) + GAsyncResult *result, + GError **error) { SecretServiceClass *klass; diff --git a/library/secret-service.h b/library/secret-service.h index 75f4d89..48af16e 100644 --- a/library/secret-service.h +++ b/library/secret-service.h @@ -11,6 +11,10 @@ * See the included COPYING file for more information. */ +#if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) +#error "Only can be included directly." +#endif + #ifndef __SECRET_SERVICE_H__ #define __SECRET_SERVICE_H__ @@ -70,32 +74,32 @@ struct _SecretServiceClass { GType secret_service_get_type (void) G_GNUC_CONST; void secret_service_get (SecretServiceFlags flags, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); -SecretService * secret_service_get_finish (GAsyncResult *result, - GError **error); +SecretService * secret_service_get_finish (GAsyncResult *result, + GError **error); -SecretService * secret_service_get_sync (SecretServiceFlags flags, - GCancellable *cancellable, - GError **error); +SecretService * secret_service_get_sync (SecretServiceFlags flags, + GCancellable *cancellable, + GError **error); void secret_service_new (const gchar *service_bus_name, - SecretServiceFlags flags, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + SecretServiceFlags flags, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); -SecretService * secret_service_new_finish (GAsyncResult *result, - GError **error); +SecretService * secret_service_new_finish (GAsyncResult *result, + GError **error); -SecretService * secret_service_new_sync (const gchar *service_bus_name, - SecretServiceFlags flags, - GCancellable *cancellable, - GError **error); +SecretService * secret_service_new_sync (const gchar *service_bus_name, + SecretServiceFlags flags, + GCancellable *cancellable, + GError **error); -SecretServiceFlags secret_service_get_flags (SecretService *self); +SecretServiceFlags secret_service_get_flags (SecretService *self); const gchar * secret_service_get_session_algorithms (SecretService *self); @@ -104,347 +108,351 @@ const gchar * secret_service_get_session_path (SecretService GList * secret_service_get_collections (SecretService *self); void secret_service_ensure_session (SecretService *self, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); const gchar * secret_service_ensure_session_finish (SecretService *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); const gchar * secret_service_ensure_session_sync (SecretService *self, - GCancellable *cancellable, - GError **error); + GCancellable *cancellable, + GError **error); void secret_service_ensure_collections (SecretService *self, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_service_ensure_collections_finish (SecretService *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); gboolean secret_service_ensure_collections_sync (SecretService *self, - GCancellable *cancellable, - GError **error); + GCancellable *cancellable, + GError **error); void secret_service_search (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_service_search_finish (SecretService *self, - GAsyncResult *result, - GList **unlocked, - GList **locked, - GError **error); + GAsyncResult *result, + GList **unlocked, + GList **locked, + GError **error); gboolean secret_service_search_sync (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GList **unlocked, - GList **locked, - GError **error); + GHashTable *attributes, + GCancellable *cancellable, + GList **unlocked, + GList **locked, + GError **error); void secret_service_search_for_paths (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_service_search_for_paths_finish (SecretService *self, - GAsyncResult *result, - gchar ***unlocked, - gchar ***locked, - GError **error); + GAsyncResult *result, + gchar ***unlocked, + gchar ***locked, + GError **error); gboolean secret_service_search_for_paths_sync (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - gchar ***unlocked, - gchar ***locked, - GError **error); + GHashTable *attributes, + GCancellable *cancellable, + gchar ***unlocked, + gchar ***locked, + GError **error); void secret_service_get_secret_for_path (SecretService *self, - const gchar *object_path, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar *item_path, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); -SecretValue * secret_service_get_secret_for_path_finish (SecretService *self, - GAsyncResult *result, - GError **error); +SecretValue * secret_service_get_secret_for_path_finish (SecretService *self, + GAsyncResult *result, + GError **error); -SecretValue * secret_service_get_secret_for_path_sync (SecretService *self, - const gchar *object_path, - GCancellable *cancellable, - GError **error); +SecretValue * secret_service_get_secret_for_path_sync (SecretService *self, + const gchar *item_path, + GCancellable *cancellable, + GError **error); void secret_service_get_secrets_for_paths (SecretService *self, - const gchar **object_paths, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar **item_paths, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); GHashTable * secret_service_get_secrets_for_paths_finish (SecretService *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); GHashTable * secret_service_get_secrets_for_paths_sync (SecretService *self, - const gchar **object_paths, - GCancellable *cancellable, - GError **error); + const gchar **item_paths, + GCancellable *cancellable, + GError **error); void secret_service_get_secrets (SecretService *self, - GList *items, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GList *items, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); GHashTable * secret_service_get_secrets_finish (SecretService *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); GHashTable * secret_service_get_secrets_sync (SecretService *self, - GList *items, - GCancellable *cancellable, - GError **error); + GList *items, + GCancellable *cancellable, + GError **error); void secret_service_lock (SecretService *self, - GList *objects, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GList *objects, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gint secret_service_lock_finish (SecretService *self, - GAsyncResult *result, - GList **locked, - GError **error); + GAsyncResult *result, + GList **locked, + GError **error); gint secret_service_lock_sync (SecretService *self, - GList *objects, - GCancellable *cancellable, - GList **locked, - GError **error); + GList *objects, + GCancellable *cancellable, + GList **locked, + GError **error); gint secret_service_lock_paths_sync (SecretService *self, - const gchar **paths, - GCancellable *cancellable, - gchar ***locked, - GError **error); + const gchar **paths, + GCancellable *cancellable, + gchar ***locked, + GError **error); void secret_service_lock_paths (SecretService *self, - const gchar **paths, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar **paths, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gint secret_service_lock_paths_finish (SecretService *self, - GAsyncResult *result, - gchar ***locked, - GError **error); + GAsyncResult *result, + gchar ***locked, + GError **error); void secret_service_unlock (SecretService *self, - GList *objects, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GList *objects, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gint secret_service_unlock_finish (SecretService *self, - GAsyncResult *result, - GList **unlocked, - GError **error); + GAsyncResult *result, + GList **unlocked, + GError **error); gint secret_service_unlock_sync (SecretService *self, - GList *objects, - GCancellable *cancellable, - GList **unlocked, - GError **error); + GList *objects, + GCancellable *cancellable, + GList **unlocked, + GError **error); gint secret_service_unlock_paths_sync (SecretService *self, - const gchar **paths, - GCancellable *cancellable, - gchar ***unlocked, - GError **error); + const gchar **paths, + GCancellable *cancellable, + gchar ***unlocked, + GError **error); void secret_service_unlock_paths (SecretService *self, - const gchar **paths, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar **paths, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gint secret_service_unlock_paths_finish (SecretService *self, - GAsyncResult *result, - gchar ***unlocked, - GError **error); + GAsyncResult *result, + gchar ***unlocked, + GError **error); gboolean secret_service_prompt_sync (SecretService *self, - SecretPrompt *prompt, - GCancellable *cancellable, - GError **error); + SecretPrompt *prompt, + GCancellable *cancellable, + GError **error); void secret_service_prompt (SecretService *self, - SecretPrompt *prompt, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + SecretPrompt *prompt, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_service_prompt_finish (SecretService *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); void secret_service_store (SecretService *self, - const SecretSchema *schema, - const gchar *collection_path, - const gchar *label, - SecretValue *value, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data, - ...) G_GNUC_NULL_TERMINATED; + const SecretSchema *schema, + const gchar *collection_path, + const gchar *label, + SecretValue *value, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data, + ...) G_GNUC_NULL_TERMINATED; void secret_service_storev (SecretService *self, - const SecretSchema *schema, - GHashTable *attributes, - const gchar *collection_path, - const gchar *label, - SecretValue *value, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const SecretSchema *schema, + GHashTable *attributes, + const gchar *collection_path, + const gchar *label, + SecretValue *value, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_service_store_finish (SecretService *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); gboolean secret_service_store_sync (SecretService *self, - const SecretSchema *schema, - const gchar *collection_path, - const gchar *label, - SecretValue *value, - GCancellable *cancellable, - GError **error, - ...) G_GNUC_NULL_TERMINATED; + const SecretSchema *schema, + const gchar *collection_path, + const gchar *label, + SecretValue *value, + GCancellable *cancellable, + GError **error, + ...) G_GNUC_NULL_TERMINATED; gboolean secret_service_storev_sync (SecretService *self, - const SecretSchema *schema, - GHashTable *attributes, - const gchar *collection_path, - const gchar *label, - SecretValue *value, - GCancellable *cancellable, - GError **error); + const SecretSchema *schema, + GHashTable *attributes, + const gchar *collection_path, + const gchar *label, + SecretValue *value, + GCancellable *cancellable, + GError **error); void secret_service_lookup (SecretService *self, - const SecretSchema *schema, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data, - ...) G_GNUC_NULL_TERMINATED; + const SecretSchema *schema, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data, + ...) G_GNUC_NULL_TERMINATED; void secret_service_lookupv (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); -SecretValue * secret_service_lookup_finish (SecretService *self, - GAsyncResult *result, - GError **error); +SecretValue * secret_service_lookup_finish (SecretService *self, + GAsyncResult *result, + GError **error); -SecretValue * secret_service_lookup_sync (SecretService *self, - const SecretSchema *schema, - GCancellable *cancellable, - GError **error, - ...) G_GNUC_NULL_TERMINATED; +SecretValue * secret_service_lookup_sync (SecretService *self, + const SecretSchema *schema, + GCancellable *cancellable, + GError **error, + ...) G_GNUC_NULL_TERMINATED; -SecretValue * secret_service_lookupv_sync (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GError **error); +SecretValue * secret_service_lookupv_sync (SecretService *self, + const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GError **error); void secret_service_delete_path (SecretService *self, - const gchar *object_path, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar *item_path, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_service_delete_path_finish (SecretService *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); gboolean secret_service_delete_path_sync (SecretService *self, - const gchar *object_path, - GCancellable *cancellable, - GError **error); + const gchar *item_path, + GCancellable *cancellable, + GError **error); void secret_service_remove (SecretService *self, - const SecretSchema *schema, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data, - ...) G_GNUC_NULL_TERMINATED; + const SecretSchema *schema, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data, + ...) G_GNUC_NULL_TERMINATED; void secret_service_removev (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gboolean secret_service_remove_finish (SecretService *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); gboolean secret_service_remove_sync (SecretService *self, - const SecretSchema* schema, - GCancellable *cancellable, - GError **error, - ...) G_GNUC_NULL_TERMINATED; + const SecretSchema* schema, + GCancellable *cancellable, + GError **error, + ...) G_GNUC_NULL_TERMINATED; gboolean secret_service_removev_sync (SecretService *self, - GHashTable *attributes, - GCancellable *cancellable, - GError **error); + const SecretSchema *schema, + GHashTable *attributes, + GCancellable *cancellable, + GError **error); void secret_service_create_collection_path (SecretService *self, - GHashTable *properties, - const gchar *alias, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + GHashTable *properties, + const gchar *alias, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gchar * secret_service_create_collection_path_finish (SecretService *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); gchar * secret_service_create_collection_path_sync (SecretService *self, - GHashTable *properties, - const gchar *alias, - GCancellable *cancellable, - GError **error); + GHashTable *properties, + const gchar *alias, + GCancellable *cancellable, + GError **error); void secret_service_create_item_path (SecretService *self, - const gchar *collection_path, - GHashTable *properties, - SecretValue *value, - gboolean replace, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data); + const gchar *collection_path, + GHashTable *properties, + SecretValue *value, + gboolean replace, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data); gchar * secret_service_create_item_path_finish (SecretService *self, - GAsyncResult *result, - GError **error); + GAsyncResult *result, + GError **error); gchar * secret_service_create_item_path_sync (SecretService *self, - const gchar *collection_path, - GHashTable *properties, - SecretValue *value, - gboolean replace, - GCancellable *cancellable, - GError **error); + const gchar *collection_path, + GHashTable *properties, + SecretValue *value, + gboolean replace, + GCancellable *cancellable, + GError **error); G_END_DECLS diff --git a/library/secret-session.c b/library/secret-session.c index 00d7ff0..1d7c1c3 100644 --- a/library/secret-session.c +++ b/library/secret-session.c @@ -305,9 +305,9 @@ on_service_open_session_aes (GObject *source, void _secret_session_open (SecretService *service, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; OpenSessionClosure *closure; @@ -464,7 +464,7 @@ service_decode_plain_secret (SecretSession *session, SecretValue * _secret_session_decode_secret (SecretSession *session, - GVariant *encoded) + GVariant *encoded) { SecretValue *result; gconstpointer param; @@ -621,7 +621,7 @@ service_encode_plain_secret (SecretSession *session, GVariant * _secret_session_encode_secret (SecretSession *session, - SecretValue *value) + SecretValue *value) { GVariantBuilder *builder; GVariant *result = NULL; diff --git a/library/secret-types.h b/library/secret-types.h index 91bd11a..ce6eb0f 100644 --- a/library/secret-types.h +++ b/library/secret-types.h @@ -10,6 +10,10 @@ * See the included COPYING file for more information. */ +#if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) +#error "Only can be included directly." +#endif + #ifndef __SECRET_TYPES_H__ #define __SECRET_TYPES_H__ diff --git a/library/secret-util.c b/library/secret-util.c index dd538e4..b5392e7 100644 --- a/library/secret-util.c +++ b/library/secret-util.c @@ -143,7 +143,7 @@ _secret_util_attributes_for_variant (GVariant *variant) GHashTable * _secret_util_attributes_for_varargs (const SecretSchema *schema, - va_list args) + va_list args) { const gchar *attribute_name; SecretSchemaType type; @@ -262,10 +262,10 @@ on_get_properties (GObject *source, void _secret_util_get_properties (GDBusProxy *proxy, - gpointer result_tag, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + gpointer result_tag, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; @@ -288,9 +288,9 @@ _secret_util_get_properties (GDBusProxy *proxy, gboolean _secret_util_get_properties_finish (GDBusProxy *proxy, - gpointer result_tag, - GAsyncResult *result, - GError **error) + gpointer result_tag, + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; @@ -349,12 +349,12 @@ on_set_property (GObject *source, void _secret_util_set_property (GDBusProxy *proxy, - const gchar *property, - GVariant *value, - gpointer result_tag, - GCancellable *cancellable, - GAsyncReadyCallback callback, - gpointer user_data) + const gchar *property, + GVariant *value, + gpointer result_tag, + GCancellable *cancellable, + GAsyncReadyCallback callback, + gpointer user_data) { GSimpleAsyncResult *res; SetClosure *closure; @@ -386,9 +386,9 @@ _secret_util_set_property (GDBusProxy *proxy, gboolean _secret_util_set_property_finish (GDBusProxy *proxy, - gpointer result_tag, - GAsyncResult *result, - GError **error) + gpointer result_tag, + GAsyncResult *result, + GError **error) { GSimpleAsyncResult *res; SetClosure *closure; @@ -407,10 +407,10 @@ _secret_util_set_property_finish (GDBusProxy *proxy, gboolean _secret_util_set_property_sync (GDBusProxy *proxy, - const gchar *property, - GVariant *value, - GCancellable *cancellable, - GError **error) + const gchar *property, + GVariant *value, + GCancellable *cancellable, + GError **error) { gboolean result = FALSE; GVariant *retval; @@ -480,8 +480,8 @@ _secret_sync_free (gpointer data) void _secret_sync_on_result (GObject *source, - GAsyncResult *result, - gpointer user_data) + GAsyncResult *result, + gpointer user_data) { SecretSync *sync = user_data; g_assert (sync->result == NULL); diff --git a/library/secret-value.c b/library/secret-value.c index 768701e..20afd2d 100644 --- a/library/secret-value.c +++ b/library/secret-value.c @@ -45,8 +45,24 @@ secret_value_get_type (void) return type; } -SecretValue* -secret_value_new (const gchar *secret, gssize length, const gchar *content_type) +/** + * secret_value_new_full: + * @secret: the secret data + * @length: the length of the data + * @content_type: the content type of the data + * + * Create a #SecretValue for the secret data passed in. The secret data is + * copied into non-pageable 'secure' memory. + * + * If the length is less than zero, then @secret is assumed to be + * null-terminated. + * + * Returns: (transfer full): the new #SecretValue + */ +SecretValue * +secret_value_new (const gchar *secret, + gssize length, + const gchar *content_type) { gchar *copy; @@ -62,9 +78,26 @@ secret_value_new (const gchar *secret, gssize length, const gchar *content_type) return secret_value_new_full (copy, length, content_type, egg_secure_free); } -SecretValue* -secret_value_new_full (gchar *secret, gssize length, - const gchar *content_type, GDestroyNotify destroy) +/** + * secret_value_new_full: + * @secret: the secret data + * @length: the length of the data + * @content_type: the content type of the data + * @destroy: function to call to free the secret data + * + * Create a #SecretValue for the secret data passed in. The secret data is + * not copied, and will later be freed with the @destroy function. + * + * If the length is less than zero, then @secret is assumed to be + * null-terminated. + * + * Returns: (transfer full): the new #SecretValue + */ +SecretValue * +secret_value_new_full (gchar *secret, + gssize length, + const gchar *content_type, + GDestroyNotify destroy) { SecretValue *value; @@ -84,8 +117,20 @@ secret_value_new_full (gchar *secret, gssize length, return value; } -const gchar* -secret_value_get (SecretValue *value, gsize *length) +/** + * secret_value_get: + * @value: the value + * @length: (out): the length of the secret + * + * Get the secret data in the #SecretValue. The value is not necessarily + * null-terminated unless it was created with secret_value_new() or a + * null-terminated string was passed to secret_value_new_full(). + * + * Returns: (array length=length): the secret data + */ +const gchar * +secret_value_get (SecretValue *value, + gsize *length) { g_return_val_if_fail (value, NULL); if (length) @@ -93,14 +138,32 @@ secret_value_get (SecretValue *value, gsize *length) return value->secret; } -const gchar* +/** + * secret_value_get_content_type: + * @value: the value + * + * Get the content type of the secret value, such as + * text/plain. + * + * Returns: the content type + */ +const gchar * secret_value_get_content_type (SecretValue *value) { g_return_val_if_fail (value, NULL); return value->content_type; } -SecretValue* +/** + * secret_value_unref: + * @value: value to reference + * + * Add another reference to the #SecretValue. For each reference + * secret_value_unref() should be called to unreference the value. + * + * Returns: (transfer full): the value + */ +SecretValue * secret_value_ref (SecretValue *value) { g_return_val_if_fail (value, NULL); @@ -108,6 +171,13 @@ secret_value_ref (SecretValue *value) return value; } +/** + * secret_value_unref: + * @value: (type Secret.Value) (allow-none): value to unreference + * + * Unreference a #SecretValue. When the last reference is gone, then + * the value will be freed. + */ void secret_value_unref (gpointer value) { diff --git a/library/secret-value.h b/library/secret-value.h index badcd2f..bc1b6cb 100644 --- a/library/secret-value.h +++ b/library/secret-value.h @@ -10,6 +10,10 @@ * See the included COPYING file for more information. */ +#if !defined (__SECRET_INSIDE_HEADER__) && !defined (SECRET_COMPILATION) +#error "Only can be included directly." +#endif + #ifndef __SECRET_VALUE_H__ #define __SECRET_VALUE_H__ @@ -23,24 +27,24 @@ G_BEGIN_DECLS GType secret_value_get_type (void) G_GNUC_CONST; -SecretValue* secret_value_new (const gchar *secret, - gssize length, - const gchar *content_type); +SecretValue * secret_value_new (const gchar *secret, + gssize length, + const gchar *content_type); -SecretValue* secret_value_new_full (gchar *secret, - gssize length, - const gchar *content_type, - GDestroyNotify destroy); +SecretValue * secret_value_new_full (gchar *secret, + gssize length, + const gchar *content_type, + GDestroyNotify destroy); -const gchar* secret_value_get (SecretValue *value, - gsize *length); +const gchar * secret_value_get (SecretValue *value, + gsize *length); -const gchar* secret_value_get_content_type (SecretValue *value); +const gchar * secret_value_get_content_type (SecretValue *value); -SecretValue* secret_value_ref (SecretValue *value); +SecretValue * secret_value_ref (SecretValue *value); -void secret_value_unref (gpointer value); +void secret_value_unref (gpointer value); G_END_DECLS -#endif /* __G_SERVICE_H___ */ +#endif /* __SECRET_VALUE_H___ */ diff --git a/library/secret.h b/library/secret.h new file mode 100644 index 0000000..3b6a47b --- /dev/null +++ b/library/secret.h @@ -0,0 +1,34 @@ +/* libsecret - GLib wrapper for Secret Service + * + * Copyright 2012 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 of the licence or (at + * your option) any later version. + * + * See the included COPYING file for more information. + */ + +#ifndef SECRET_API_SUBJECT_TO_CHANGE +#error "This API has not yet reached stability." +#endif + +#ifndef __SECRET_H__ +#define __SECRET_H__ + +#include + +#define __SECRET_INSIDE_HEADER__ + +#include +#include +#include +#include +#include +#include +#include + +#undef __SECRET_INSIDE_HEADER__ + +#endif /* __SECRET_H__ */ diff --git a/library/tests/Makefile.am b/library/tests/Makefile.am index 17c3650..5941894 100644 --- a/library/tests/Makefile.am +++ b/library/tests/Makefile.am @@ -3,6 +3,7 @@ include $(top_srcdir)/Makefile.decl INCLUDES = \ -I$(top_srcdir)/library \ -DSRCDIR="\"@abs_srcdir@\"" \ + -DSECRET_COMPILATION \ $(NULL) noinst_LTLIBRARIES = libmock_service.la @@ -16,12 +17,12 @@ libmock_service_la_CFLAGS = \ libmock_service_la_LIBADD = \ $(top_builddir)/egg/libegg.la \ - $(top_builddir)/library/libsecret.la \ + $(top_builddir)/library/libsecret-@SECRET_MAJOR@.la \ $(LIBGCRYPT_LIBS) LDADD = \ $(top_builddir)/egg/libegg.la \ - $(top_builddir)/library/libsecret.la \ + $(top_builddir)/library/libsecret-@SECRET_MAJOR@.la \ $(top_builddir)/library/tests/libmock_service.la \ $(NULL) diff --git a/library/tests/test-prompt.c b/library/tests/test-prompt.c index 3a89df0..e84bebe 100644 --- a/library/tests/test-prompt.c +++ b/library/tests/test-prompt.c @@ -90,7 +90,7 @@ test_perform_sync (Test *test, /* Verify that main loop does not run during this call */ increment_id = g_idle_add (on_idle_increment, &value); - prompt = secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/simple"); + prompt = _secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/simple"); ret = secret_prompt_perform_sync (prompt, 0, NULL, &error); g_assert_no_error (error); @@ -116,7 +116,7 @@ test_perform_run (Test *test, /* Verify that main loop does run during this call */ increment_id = g_idle_add (on_idle_increment, &value); - prompt = secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/simple"); + prompt = _secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/simple"); ret = secret_prompt_run (prompt, 0, NULL, &error); g_assert_no_error (error); @@ -141,7 +141,7 @@ test_perform_async (Test *test, GAsyncResult *result = NULL; gboolean ret; - prompt = secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/simple"); + prompt = _secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/simple"); secret_prompt_perform (prompt, 0, NULL, on_async_result, &result); g_assert (result == NULL); @@ -170,7 +170,7 @@ test_perform_cancel (Test *test, GCancellable *cancellable; gboolean ret; - prompt = secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/delay"); + prompt = _secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/delay"); cancellable = g_cancellable_new (); secret_prompt_perform (prompt, 0, cancellable, on_async_result, &result); @@ -202,7 +202,7 @@ test_perform_fail (Test *test, GError *error = NULL; gboolean ret; - prompt = secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/error"); + prompt = _secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/error"); ret = secret_prompt_perform_sync (prompt, 0, NULL, &error); g_assert_error (error, G_DBUS_ERROR, G_DBUS_ERROR_NOT_SUPPORTED); @@ -220,7 +220,7 @@ test_perform_vanish (Test *test, GError *error = NULL; gboolean ret; - prompt = secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/vanish"); + prompt = _secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/vanish"); ret = secret_prompt_perform_sync (prompt, 0, NULL, &error); g_assert_no_error (error); @@ -239,7 +239,7 @@ test_prompt_result (Test *test, gboolean ret; GVariant *result; - prompt = secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/result"); + prompt = _secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/result"); result = secret_prompt_get_result_value (prompt, NULL); g_assert (result == NULL); @@ -266,7 +266,7 @@ test_prompt_window_id (Test *test, gboolean ret; GVariant *result; - prompt = secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/window"); + prompt = _secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/window"); ret = secret_prompt_perform_sync (prompt, 555, NULL, &error); g_assert_no_error (error); @@ -289,7 +289,7 @@ test_service_sync (Test *test, GError *error = NULL; gboolean ret; - prompt = secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/simple"); + prompt = _secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/simple"); ret = secret_service_prompt_sync (test->service, prompt, NULL, &error); g_assert_no_error (error); @@ -308,7 +308,7 @@ test_service_async (Test *test, GAsyncResult *result = NULL; gboolean ret; - prompt = secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/simple"); + prompt = _secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/simple"); secret_service_prompt (test->service, prompt, NULL, on_async_result, &result); g_assert (result == NULL); @@ -336,7 +336,7 @@ test_service_fail (Test *test, GAsyncResult *result = NULL; gboolean ret; - prompt = secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/error"); + prompt = _secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/error"); secret_service_prompt (test->service, prompt, NULL, on_async_result, &result); g_assert (result == NULL); @@ -364,7 +364,7 @@ test_service_path (Test *test, SecretPrompt *prompt; gboolean ret; - prompt = secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/simple"); + prompt = _secret_prompt_instance (test->service, "/org/freedesktop/secrets/prompts/simple"); secret_service_prompt (test->service, prompt, NULL, on_async_result, &result); g_assert (result == NULL);