Commit 3edec363 authored by Stef Walter's avatar Stef Walter
Browse files

Reference documentation

parent 06e84365
*~
*.o
*.la
*.lo
*.pyc
*.bak
*.gcov
*.gcno
*.gcda
*.gir
*.la
*.lo
*.o
*.pyc
*.pc
*.tar.gz
*.typelib
......@@ -22,6 +23,7 @@ config.*
depcomp
install-sh
INSTALL
gtk-doc.make
libtool
ltmain.sh
Makefile
......@@ -29,6 +31,7 @@ Makefile.in
Makefile.in.in
missing
stamp*
*.stamp
.settings
.project
.cproject
......@@ -37,6 +40,21 @@ stamp*
/build/m4
/build/valgrind-suppressions
/docs/reference/libsecret/version.xml
/docs/reference/libsecret/libsecret-decl-list.txt
/docs/reference/libsecret/libsecret-decl.txt
/docs/reference/libsecret/libsecret-scan.c
/docs/reference/libsecret/html
/docs/reference/libsecret/libsecret-undeclared.txt
/docs/reference/libsecret/libsecret-undocumented.txt
/docs/reference/libsecret/libsecret-unused.txt
/docs/reference/libsecret/libsecret.args
/docs/reference/libsecret/libsecret.hierarchy
/docs/reference/libsecret/libsecret.prerequisites
/docs/reference/libsecret/libsecret.signals
/docs/reference/libsecret/tmpl
/docs/reference/libsecret/xml
/po/POTFILES
/po/libsecret.pot
......
......@@ -3,7 +3,7 @@ include $(top_srcdir)/Makefile.decl
ACLOCAL_AMFLAGS = -I build/m4 ${ACLOCAL_FLAGS}
SUBDIRS = build po egg library
SUBDIRS = build egg library po docs
DISTCHECK_CONFIGURE_FLAGS = \
--enable-debug=yes \
......
......@@ -91,6 +91,8 @@ $ACLOCAL $ACLOCAL_FLAGS || exit $?
libtoolize --force || exit $?
intltoolize --force --copy || exit $?
gtkdocize || exit $?
autoheader || exit $?
$AUTOMAKE --add-missing || exit $?
......
......@@ -66,6 +66,8 @@ PKG_CHECK_MODULES(GLIB,
LIBS="$LIBS $GLIB_LIBS"
CFLAGS="$CFLAGS $GLIB_CFLAGS"
GTK_DOC_CHECK(1.9)
GOBJECT_INTROSPECTION_CHECK([1.29])
AC_PATH_PROG(GLIB_MKENUMS, glib-mkenums)
......@@ -225,6 +227,10 @@ AC_SUBST(SECRET_MINOR)
AC_CONFIG_FILES([
Makefile
build/Makefile
docs/Makefile
docs/reference/Makefile
docs/reference/libsecret/Makefile
docs/reference/libsecret/version.xml
egg/Makefile
egg/tests/Makefile
po/Makefile.in
......
SUBDIRS = reference
This work may be reproduced and distributed in whole or in part, in
any medium, physical or electronic, so as long as this copyright
notice remains intact and unchanged on all copies. Commercial
redistribution is permitted and encouraged, but you may not
redistribute, in whole or in part, under terms more restrictive than
those under which you received it. If you redistribute a modified or
translated version of this work, you must also make the source code to
the modified or translated version available in electronic form
without charge. However, mere aggregation as part of a larger work
shall not count as a modification for this purpose.
All code examples in this work are placed into the public domain,
and may be used, modified and redistributed without restriction.
BECAUSE THIS WORK IS LICENSED FREE OF CHARGE, THERE IS NO
WARRANTY FOR THE WORK, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR
OTHER PARTIES PROVIDE THE WORK "AS IS" WITHOUT WARRANTY OF ANY
KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. SHOULD THE WORK PROVE DEFECTIVE, YOU ASSUME
THE COST OF ALL NECESSARY REPAIR OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY
AND/OR REDISTRIBUTE THE WORK AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE
WORK, EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
SUBDIRS = libsecret
## Process this file with automake to produce Makefile.in
# We require automake 1.6 at least.
AUTOMAKE_OPTIONS = 1.6
# This is a blank Makefile.am for using gtk-doc.
# Copy this to your project's API docs directory and modify the variables to
# suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
# of using the various options.
# The name the module, e.g. 'glib'.
DOC_MODULE=libsecret
# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
DOC_MODULE_VERSION=@SECRET_MAJOR@
# The top-level SGML file. You can change this if you want to.
DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
# The directory containing the source code. Relative to $(srcdir).
# gtk-doc will search all .c & .h files beneath here for inline comments
# documenting the functions and macros.
# e.g. DOC_SOURCE_DIR=../../../gtk
DOC_SOURCE_DIR=$(top_srcdir)/library
# Extra options to pass to gtkdoc-scangobj. Not normally needed.
SCANGOBJ_OPTIONS=
# Extra options to supply to gtkdoc-scan.
# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
SCAN_OPTIONS=--deprecated-guards="SECRET_DISABLE_DEPRECATED"
# Extra options to supply to gtkdoc-mkdb.
# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
MKDB_OPTIONS=--sgml-mode --output-format=xml
# Extra options to supply to gtkdoc-mktmpl
# e.g. MKTMPL_OPTIONS=--only-section-tmpl
MKTMPL_OPTIONS=
# Extra options to supply to gtkdoc-mkhtml
MKHTML_OPTIONS=
# Extra options to supply to gtkdoc-fixref. Not normally needed.
# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
FIXXREF_OPTIONS=
# Used for dependencies. The docs will be rebuilt if any of these change.
# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
HFILE_GLOB=$(top_srcdir)/library/*.h
CFILE_GLOB=$(top_srcdir)/library/*.c
# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
EXTRA_HFILES=
# Header files to ignore when scanning. Use base file name, no paths
# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
IGNORE_HFILES= \
mock-service.h \
secret-dbus-generated.h \
secret-private.h \
$(NULL)
# Images to copy into HTML directory.
# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
HTML_IMAGES=
# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
content_files=
# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
# These files must be listed here *and* in content_files
# e.g. expand_content_files=running.sgml
expand_content_files=
# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
# Only needed if you are using gtkdoc-scangobj to dynamically query widget
# signals and properties.
# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
GTKDOC_CFLAGS= -I$(top_srcdir) -I$(top_builddir) $(GLIB_CFLAGS) -Wno-error
GTKDOC_LIBS= $(GLIB_LIBS) $(GOBJECT_LIBS) \
$(top_builddir)/library/libsecret-@SECRET_MAJOR@.la
# This includes the standard gtk-doc make rules, copied by gtkdocize.
include $(top_srcdir)/gtk-doc.make
# Other files to distribute
# e.g. EXTRA_DIST += version.xml.in
# EXTRA_DIST +=
# Files not to distribute
# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
DISTCLEANFILES = tmpl/secret-unused.sgml
# Comment this out if you want your docs-status tested during 'make check'
#TESTS_ENVIRONMENT = cd $(srcsrc)
#TESTS = $(GTKDOC_CHECK)
<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
<bookinfo>
<title>Libsecret Library Reference Manual</title>
<releaseinfo>
for libsecret &version;.
An online version of this documentation can be found at
<ulink role="online-location" url="http://developer.gnome.org/libsecret/stable/">http://developer.gnome.org/libsecret/stable/</ulink>.
</releaseinfo>
</bookinfo>
<part id="simple">
<title>Simple API</title>
<xi:include href="xml/secret-password.xml"/>
</part>
<part id="complete">
<title>Complete API</title>
<xi:include href="xml/secret-service.xml"/>
<xi:include href="xml/secret-collection.xml"/>
<xi:include href="xml/secret-item.xml"/>
<xi:include href="xml/secret-value.xml"/>
<xi:include href="xml/secret-prompt.xml"/>
<xi:include href="xml/secret-error.xml"/>
</part>
<xi:include href="xml/annotation-glossary.xml">
<xi:fallback />
</xi:include>
</book>
# These are manually-edited to override or add declarations to those scanned
# from the header files.
<SECTION>
<FILE>secret-collection</FILE>
SecretCollection
SecretCollectionClass
secret_collection_new
secret_collection_new_finish
secret_collection_new_sync
secret_collection_create
secret_collection_create_finish
secret_collection_create_sync
secret_collection_delete
secret_collection_delete_finish
secret_collection_delete_sync
secret_collection_get_created
secret_collection_get_items
secret_collection_get_label
secret_collection_set_label
secret_collection_set_label_finish
secret_collection_set_label_sync
secret_collection_get_locked
secret_collection_get_modified
secret_collection_refresh
<SUBSECTION Standard>
SECRET_COLLECTION
SECRET_COLLECTION_CLASS
SECRET_COLLECTION_GET_CLASS
SECRET_IS_COLLECTION
SECRET_IS_COLLECTION_CLASS
SECRET_TYPE_COLLECTION
SecretCollectionPrivate
secret_collection_get_type
</SECTION>
<SECTION>
<FILE>secret-item</FILE>
SecretItem
SecretItemClass
secret_item_new
secret_item_new_finish
secret_item_new_sync
secret_item_create
secret_item_create_finish
secret_item_create_sync
secret_item_delete
secret_item_delete_finish
secret_item_delete_sync
secret_item_get_attributes
secret_item_set_attributes
secret_item_set_attributes_finish
secret_item_set_attributes_sync
secret_item_get_created
secret_item_get_label
secret_item_set_label
secret_item_set_label_finish
secret_item_set_label_sync
secret_item_get_locked
secret_item_get_modified
secret_item_get_schema
secret_item_get_secret
secret_item_get_secret_finish
secret_item_get_secret_sync
secret_item_set_secret
secret_item_set_secret_finish
secret_item_set_secret_sync
secret_item_refresh
<SUBSECTION Standard>
SECRET_IS_ITEM
SECRET_IS_ITEM_CLASS
SECRET_ITEM
SECRET_ITEM_CLASS
SECRET_ITEM_GET_CLASS
SECRET_TYPE_ITEM
SecretItemPrivate
secret_item_get_type
</SECTION>
<SECTION>
<FILE>secret-error</FILE>
SECRET_ERROR
SecretError
<SUBSECTION Standard>
SECRET_TYPE_ERROR
secret_error_get_quark
secret_error_get_type
</SECTION>
<SECTION>
<FILE>secret-password</FILE>
SecretSchema
SecretSchemaType
secret_password_store
secret_password_storev
secret_password_store_finish
secret_password_store_sync
secret_password_storev_sync
secret_password_lookup
secret_password_lookupv
secret_password_lookup_finish
secret_password_lookup_sync
secret_password_lookupv_sync
secret_password_remove
secret_password_removev
secret_password_remove_finish
secret_password_remove_sync
secret_password_removev_sync
secret_password_free
<SUBSECTION Standard>
SECRET_TYPE_SCHEMA_TYPE
secret_schema_type_get_type
</SECTION>
<SECTION>
<FILE>secret-prompt</FILE>
SecretPrompt
SecretPromptClass
secret_prompt_get_result_value
secret_prompt_perform
secret_prompt_perform_finish
secret_prompt_perform_sync
secret_prompt_run
<SUBSECTION Standard>
SECRET_IS_PROMPT
SECRET_IS_PROMPT_CLASS
SECRET_PROMPT
SECRET_PROMPT_CLASS
SECRET_PROMPT_GET_CLASS
SECRET_TYPE_PROMPT
SecretPromptPrivate
secret_prompt_get_type
</SECTION>
<SECTION>
<FILE>secret-service</FILE>
SecretService
SecretServiceClass
SecretServiceFlags
secret_service_get
secret_service_get_sync
secret_service_get_finish
secret_service_new
secret_service_new_finish
secret_service_new_sync
secret_service_get_collections
secret_service_get_flags
secret_service_get_session_algorithms
secret_service_get_session_path
secret_service_ensure_session
secret_service_ensure_session_finish
secret_service_ensure_session_sync
secret_service_ensure_collections
secret_service_ensure_collections_finish
secret_service_ensure_collections_sync
secret_service_search
secret_service_search_finish
secret_service_search_sync
secret_service_search_for_paths
secret_service_search_for_paths_finish
secret_service_search_for_paths_sync
secret_service_get_secrets
secret_service_get_secrets_finish
secret_service_get_secrets_sync
secret_service_get_secrets_for_paths
secret_service_get_secrets_for_paths_finish
secret_service_get_secrets_for_paths_sync
secret_service_get_secret_for_path
secret_service_get_secret_for_path_finish
secret_service_get_secret_for_path_sync
secret_service_lock
secret_service_lock_finish
secret_service_lock_sync
secret_service_lock_paths
secret_service_lock_paths_finish
secret_service_lock_paths_sync
secret_service_unlock
secret_service_unlock_finish
secret_service_unlock_sync
secret_service_unlock_paths
secret_service_unlock_paths_finish
secret_service_unlock_paths_sync
secret_service_store
secret_service_storev
secret_service_store_finish
secret_service_store_sync
secret_service_storev_sync
secret_service_lookup
secret_service_lookupv
secret_service_lookup_finish
secret_service_lookup_sync
secret_service_lookupv_sync
secret_service_remove
secret_service_removev
secret_service_remove_finish
secret_service_remove_sync
secret_service_removev_sync
secret_service_prompt
secret_service_prompt_finish
secret_service_prompt_sync
secret_service_create_collection_path
secret_service_create_collection_path_finish
secret_service_create_collection_path_sync
secret_service_create_item_path
secret_service_create_item_path_finish
secret_service_create_item_path_sync
secret_service_delete_path
secret_service_delete_path_finish
secret_service_delete_path_sync
<SUBSECTION Standard>
SECRET_IS_SERVICE
SECRET_IS_SERVICE_CLASS
SECRET_SERVICE
SECRET_SERVICE_CLASS
SECRET_SERVICE_GET_CLASS
SECRET_TYPE_SERVICE
SECRET_TYPE_SERVICE_FLAGS
SecretServicePrivate
secret_service_flags_get_type
secret_service_get_type
</SECTION>
<SECTION>
<FILE>secret-value</FILE>
SecretValue
secret_value_new
secret_value_new_full
secret_value_get
secret_value_get_content_type
secret_value_ref
secret_value_unref
<SUBSECTION Standard>
SECRET_TYPE_VALUE
secret_value_get_type
</SECTION>
<SECTION>
<FILE>SecretGenService</FILE>
</SECTION>
<SECTION>
<FILE>SecretGenCollection</FILE>
</SECTION>
<SECTION>
<FILE>SecretGenItem</FILE>
</SECTION>
<SECTION>
<FILE>SecretGenSession</FILE>
</SECTION>
<SECTION>
<FILE>SecretGenPrompt</FILE>
</SECTION>
GDBusProxy GDBusInterface GInitable GAsyncInitable
SecretCollection GDBusInterface GInitable GAsyncInitable
SecretItem GDBusInterface GInitable GAsyncInitable
SecretPrompt GDBusInterface GInitable GAsyncInitable
SecretService GDBusInterface GInitable GAsyncInitable
GDBusConnection GInitable GAsyncInitable
secret_collection_get_type
secret_error_get_type
secret_item_get_type
secret_prompt_get_type
secret_value_get_type
secret_service_flags_get_type
secret_service_get_type
\ No newline at end of file
@VERSION@
\ No newline at end of file
......@@ -79,7 +79,7 @@ secret-dbus-generated.c: $(DBUS_XML_DEFINITIONS) Makefile.am
$(AM_V_GEN) gdbus-codegen --interface-prefix org.freedesktop.Secret. \
--generate-c-code secret-dbus-generated --c-namespace SecretGen \
$(DBUS_XML_DEFINITIONS)
$(AM_V_GEN) sed -i -e 's/secret_gen_/_secret_gen_/g' secret-dbus-generated.[ch]
$(AM_V_GEN) sed -i -e 's/secret_gen_/_secret_gen_/g' -e 's/type-/type/g' secret-dbus-generated.[ch]
$(AM_V_GEN) sed -i -e '1i #define GLIB_DISABLE_DEPRECATION_WARNINGS' secret-dbus-generated.c
secret-dbus-generated.h: secret-dbus-generated.c
......
......@@ -21,6 +21,35 @@
#include <glib/gi18n-lib.h>
/**
* SECTION:secret-collection
* @title: SecretCollection
* @short_description: A collection of secret items
*
* #SecretCollection represents a collection of secret items stored in the
* Secret Service.
*
* A collection can be in a locked or unlocked state. Use secret_service_lock()
* or secret_service_unlock() to lock or unlock the collection.
*
* Use the SecretCollection::items property or secret_service_get_items() to
* lookup the items in the collection. There may not be any items exposed when
* the collection is locked.
*/
/**
* SecretCollection:
*
* A proxy object representing a collection of secrets in the Secret Service.
*/
/**
* SecretCollectionClass:
* @parent_class: the parent class
*
* The class for #SecretCollection.
*/
enum {
PROP_0,
PROP_SERVICE,
......@@ -412,26 +441,67 @@ secret_collection_class_init (SecretCollectionClass *klass)
proxy_class->g_properties_changed = secret_collection_properties_changed;
/**
* SecretCollection:service:
*
* The #SecretService object that this collection is associated with and
* uses to interact with the actual DBus Secret Service.
*/
g_object_class_install_property (gobject_class, PROP_SERVICE,
g_param_spec_object ("service", "Service", "Secret Service",
SECRET_TYPE_SERVICE, G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
/**
* SecretCollection:items:
*
* A list of #SecretItem objects representing the items that are in
* this collection. This list will be empty if the collection is locked.
*/
g_object_class_install_property (gobject_class, PROP_ITEMS,
g_param_spec_boxed ("items", "Items", "Items in collection",
_secret_list_get_type (), G_PARAM_READABLE | G_PARAM_STATIC_STRINGS));
/**
* SecretCollection:label:
*
* The human readable label for the collection.
*
* Setting this property will result in the label of the collection being
* set asynchronously. To properly track the changing of the label use the
* secret_collection_set_label() function.
*/
g_object_class_install_property (gobject_class, PROP_LABEL,
g_param_spec_string ("label", "Label", "Item label",
NULL, G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS));
/**
* SecretCollection:locked:
*
* Whether the collection is locked or not.
*