GNOME.org
 

[tracker] libtracker-miner: Document TrackerPasswordProvider and TrackerMinerWeb

commit 97408a7ebd0359c86210a624a6da142ab0522c11
Author: Martyn Russell <martyn lanedo com>
Date:   Thu Mar 18 13:05:01 2010 +0000

    libtracker-miner: Document TrackerPasswordProvider and TrackerMinerWeb

 docs/reference/libtracker-miner/Makefile.am        |   13 +-
 .../libtracker-miner/libtracker-miner-docs.sgml    |    6 +
 .../libtracker-miner/libtracker-miner-sections.txt |   62 +++++++++
 src/libtracker-miner/Makefile.am                   |   11 +-
 src/libtracker-miner/tracker-miner-web-dbus.h      |    2 +-
 src/libtracker-miner/tracker-miner-web.c           |   58 +++++++++
 src/libtracker-miner/tracker-miner-web.h           |  130 +++++++++++++++-----
 src/libtracker-miner/tracker-miner.c               |    2 +-
 src/libtracker-miner/tracker-password-provider.c   |   63 ++++++++++
 src/libtracker-miner/tracker-password-provider.h   |   43 ++++++-
 10 files changed, 341 insertions(+), 49 deletions(-)
---
diff --git a/docs/reference/libtracker-miner/Makefile.am b/docs/reference/libtracker-miner/Makefile.am
index 531e49d..8f9a644 100644
--- a/docs/reference/libtracker-miner/Makefile.am
+++ b/docs/reference/libtracker-miner/Makefile.am
@@ -22,12 +22,13 @@ HFILE_GLOB=$(top_srcdir)/src/libtracker-miner/*.h
 CFILE_GLOB=$(top_srcdir)/src/libtracker-miner/*.c
 
 # Header files to ignore when scanning
-IGNORE_HFILES=	\
-	tracker-crawler.h	\
-	tracker-marshal.h	\
-	tracker-miner-client.h	\
-	tracker-miner-glue.h	\
-	tracker-monitor.h	\
+IGNORE_HFILES=								\
+	tracker-crawler.h						\
+	tracker-marshal.h						\
+	tracker-miner-client.h						\
+	tracker-miner-glue.h						\
+	tracker-miner-web-glue.h					\
+	tracker-monitor.h						\
 	tracker-utils.h
 
 # CFLAGS and LDFLAGS for compiling scan program. Only needed
diff --git a/docs/reference/libtracker-miner/libtracker-miner-docs.sgml b/docs/reference/libtracker-miner/libtracker-miner-docs.sgml
index bfe9175..264fba0 100644
--- a/docs/reference/libtracker-miner/libtracker-miner-docs.sgml
+++ b/docs/reference/libtracker-miner/libtracker-miner-docs.sgml
@@ -4,7 +4,10 @@
 <!ENTITY tracker-miner SYSTEM "xml/tracker-miner.xml">
 <!ENTITY tracker-miner-fs SYSTEM "xml/tracker-miner-fs.xml">
 <!ENTITY tracker-miner-manager SYSTEM "xml/tracker-miner-manager.xml">
+<!ENTITY tracker-miner-web SYSTEM "xml/tracker-miner-web.xml">
+<!ENTITY tracker-password-provider SYSTEM "xml/tracker-password-provider.xml">
 <!ENTITY tracker-storage SYSTEM "xml/tracker-storage.xml">
+<!ENTITY tracker-thumbnailer SYSTEM "xml/tracker-thumbnailer.xml">
 <!ENTITY version SYSTEM "version.xml">
 ]>
 <book id="index">
@@ -29,6 +32,8 @@
     <chapter>
       <title>Base abstract miner class</title>
       &tracker-miner;
+      &tracker-miner-web;
+      &tracker-password-provider;
     </chapter>
 
     <chapter>
@@ -44,5 +49,6 @@
     <chapter>
       <title>Utilities</title>
       &tracker-storage;
+      &tracker-thumbnailer;
     </chapter>
 </book>
diff --git a/docs/reference/libtracker-miner/libtracker-miner-sections.txt b/docs/reference/libtracker-miner/libtracker-miner-sections.txt
index 22c45ed..a35cc96 100644
--- a/docs/reference/libtracker-miner/libtracker-miner-sections.txt
+++ b/docs/reference/libtracker-miner/libtracker-miner-sections.txt
@@ -106,6 +106,68 @@ tracker_miner_dbus_ignore_next_update
 </SECTION>
 
 <SECTION>
+<FILE>tracker-miner-web</FILE>
+TRACKER_MINER_WEB_ERROR_DOMAIN
+TRACKER_MINER_WEB_ERROR
+TrackerMinerWebPrivate
+<TITLE>TrackerMinerWeb</TITLE>
+TrackerMinerWeb
+TrackerMinerWebClass
+tracker_miner_web_error_quark
+TrackerMinerWebAssociationType
+TrackerMinerWebError
+tracker_miner_web_associate
+tracker_miner_web_association_get_type
+tracker_miner_web_authenticate
+tracker_miner_web_dissociate
+tracker_miner_web_get_association_data
+<SUBSECTION Standard>
+TRACKER_MINER_WEB
+TRACKER_IS_MINER_WEB
+TRACKER_TYPE_MINER_WEB
+tracker_miner_web_get_type
+TRACKER_MINER_WEB_CLASS
+TRACKER_IS_MINER_WEB_CLASS
+TRACKER_MINER_WEB_GET_CLASS
+TRACKER_MINER_WEB_ASSOCIATION_TYPE_DB
+</SECTION>
+
+<SECTION>
+<FILE>tracker-miner-web-dbus</FILE>
+TRACKER_MINER_WEB_DBUS_INTERFACE
+tracker_miner_web_dbus_associate
+tracker_miner_web_dbus_dissociate
+tracker_miner_web_dbus_authenticate
+tracker_miner_web_dbus_get_association_data
+</SECTION>
+
+<SECTION>
+<FILE>tracker-password-provider</FILE>
+<TITLE>TrackerPasswordProvider</TITLE>
+TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN
+TRACKER_PASSWORD_PROVIDER_ERROR
+TRACKER_PASSWORD_PROVIDER_GET_INTERFACE
+TrackerPasswordProvider
+TrackerPasswordProviderError
+TrackerPasswordProviderIface
+forget_password
+get_password
+store_password
+tracker_password_provider_error_quark
+tracker_password_provider_get
+tracker_password_provider_get_name
+tracker_password_provider_store_password
+tracker_password_provider_get_password
+tracker_password_provider_forget_password
+tracker_password_provider_strdup_mlock
+<SUBSECTION Standard>
+TRACKER_PASSWORD_PROVIDER
+TRACKER_IS_PASSWORD_PROVIDER
+TRACKER_TYPE_PASSWORD_PROVIDER
+tracker_password_provider_get_type
+</SECTION>
+
+<SECTION>
 <FILE>tracker-thumbnailer</FILE>
 tracker_thumbnailer_init
 tracker_thumbnailer_shutdown
diff --git a/src/libtracker-miner/Makefile.am b/src/libtracker-miner/Makefile.am
index 1ebc70c..53663f4 100644
--- a/src/libtracker-miner/Makefile.am
+++ b/src/libtracker-miner/Makefile.am
@@ -36,10 +36,11 @@ libtracker_miner_ TRACKER_API_VERSION@_la_SOURCES = 	\
 	tracker-miner-dbus.h				\
 	tracker-miner-fs.c				\
 	tracker-miner-fs.h				\
-	tracker-miner-web.c				\
-	tracker-miner-web.h				\
 	tracker-miner-manager.c				\
 	tracker-miner-manager.h				\
+	tracker-miner-web.c				\
+	tracker-miner-web.h				\
+	tracker-miner-web-dbus.h			\
 	tracker-monitor.c				\
 	tracker-monitor.h				\
 	tracker-storage.c				\
@@ -55,10 +56,10 @@ libtracker_minerinclude_HEADERS = 			\
 	tracker-miner-dbus.h 				\
 	tracker-miner-fs.h				\
 	tracker-miner-manager.h				\
-	tracker-storage.h				\
-	tracker-thumbnailer.h				\
 	tracker-miner-web.h				\
-	tracker-password-provider.h
+	tracker-password-provider.h			\
+	tracker-storage.h				\
+	tracker-thumbnailer.h
 
 libtracker_miner_ TRACKER_API_VERSION@_la_LDFLAGS = 	\
 	-version-info $(LT_CURRENT):$(LT_REVISION):$(LT_AGE) \
diff --git a/src/libtracker-miner/tracker-miner-web-dbus.h b/src/libtracker-miner/tracker-miner-web-dbus.h
index ec8f680..b801e63 100644
--- a/src/libtracker-miner/tracker-miner-web-dbus.h
+++ b/src/libtracker-miner/tracker-miner-web-dbus.h
@@ -43,4 +43,4 @@ void tracker_miner_web_dbus_dissociate           (TrackerMinerWeb        *miner,
 
 G_END_DECLS
 
-#endif /* __LIBTRACKER_MINER_DBUS_H__ */
+#endif /* __LIBTRACKER_MINER_WEB_DBUS_H__ */
diff --git a/src/libtracker-miner/tracker-miner-web.c b/src/libtracker-miner/tracker-miner-web.c
index dbd749f..71982cc 100644
--- a/src/libtracker-miner/tracker-miner-web.c
+++ b/src/libtracker-miner/tracker-miner-web.c
@@ -134,6 +134,11 @@ miner_web_constructed (GObject *object)
 	G_OBJECT_CLASS (tracker_miner_web_parent_class)->constructed (object);
 }
 
+/**
+ * tracker_miner_web_association_get_type:
+ *
+ * Returns: a #GType enumeration for all association types.
+ **/
 GType
 tracker_miner_web_association_get_type (void)
 {
@@ -156,12 +161,19 @@ tracker_miner_web_association_get_type (void)
 	return etype;
 }
 
+/**
+ * tracker_miner_web_error_quark:
+ *
+ * Returns: the #GQuark used to identify miner web errors in GError
+ * structures.
+ **/
 GQuark
 tracker_miner_web_error_quark (void)
 {
 	return g_quark_from_static_string (TRACKER_MINER_WEB_ERROR_DOMAIN);
 }
 
+/* DBus methods */
 void
 tracker_miner_web_dbus_authenticate (TrackerMinerWeb        *miner,
                                      DBusGMethodInvocation  *context,
@@ -242,6 +254,14 @@ tracker_miner_web_dbus_dissociate (TrackerMinerWeb        *miner,
 	}
 }
 
+/**
+ * tracker_miner_web_authenticate:
+ * @miner: a #TrackerMinerWeb
+ * @error: return location for errors
+ *
+ * Asks @miner to authenticate with a remote service. On failure
+ * @error will be set.
+ **/
 void
 tracker_miner_web_authenticate (TrackerMinerWeb  *miner,
                                 GError          **error)
@@ -251,6 +271,19 @@ tracker_miner_web_authenticate (TrackerMinerWeb  *miner,
 	TRACKER_MINER_WEB_GET_CLASS (miner)->authenticate (miner, error);
 }
 
+/**
+ * tracker_miner_web_get_association_data:
+ * @miner: a #TrackerMinerWeb
+ * @error: return location for errors
+ *
+ * Asks @miner to retrieve association_data for. The data returned in
+ * the %GHashTable depends on the @miner implementation and the type
+ * of authentication. See <classname>TrackerMinerWebClass</classname>
+ * for more information.
+ *
+ * Returns: a %GHashTable with the data. On failure @error will be set
+ * and %NULL will be returned.
+ **/
 GHashTable *
 tracker_miner_web_get_association_data (TrackerMinerWeb  *miner,
                                         GError          **error)
@@ -260,6 +293,20 @@ tracker_miner_web_get_association_data (TrackerMinerWeb  *miner,
 	return TRACKER_MINER_WEB_GET_CLASS (miner)->get_association_data (miner, error);
 }
 
+/**
+ * tracker_miner_web_associate:
+ * @miner: a #TrackerMinerWeb
+ * @association_data: a %GHashTable with the data to use for
+ * associating with a remote service.
+ * @error: return location for errors
+ *
+ * Asks @miner to associate with a remote service using
+ * @association_data. To know what data to put into @association_data,
+ * see <classname>TrackerMinerWebClass</classname> for more
+ * information.
+ *
+ * On failure @error will be set.
+ **/
 void
 tracker_miner_web_associate (TrackerMinerWeb  *miner,
                              GHashTable       *association_data,
@@ -271,6 +318,17 @@ tracker_miner_web_associate (TrackerMinerWeb  *miner,
 	TRACKER_MINER_WEB_GET_CLASS (miner)->associate (miner, association_data, error);
 }
 
+/**
+ * tracker_miner_web_dissociate:
+ * @miner: a #TrackerMinerWeb
+ * @error: return location for errors
+ *
+ * Asks @miner to dissociate from a remote service. At this point, the
+ * miner should stop storing any credentials or sensitive information
+ * which could be used to authenticate with the remote service.
+ *
+ * On failure @error will be set.
+ **/
 void
 tracker_miner_web_dissociate (TrackerMinerWeb   *miner,
                               GError           **error)
diff --git a/src/libtracker-miner/tracker-miner-web.h b/src/libtracker-miner/tracker-miner-web.h
index 6953127..2c1a9e3 100644
--- a/src/libtracker-miner/tracker-miner-web.h
+++ b/src/libtracker-miner/tracker-miner-web.h
@@ -43,14 +43,21 @@ typedef struct TrackerMinerWebPrivate TrackerMinerWebPrivate;
 
 /**
  * TrackerMinerWebError:
- * @TRACKER_MINER_WEB_ERROR_WRONG_CREDENTIALS: The stored credentials are refused by the remote service
- * @TRACKER_MINER_WEB_ERROR_TOKEN_EXPIRED    : The service says the stored token has expired
- * @TRACKER_MINER_WEB_ERROR_NO_CREDENTIALS   : There are currenty no credentials stored for this service
- * @TRACKER_MINER_WEB_ERROR_KEYRING          : Error while contacting the credentials storage
- * @TRACKER_MINER_WEB_ERROR_SERVICE          : Error while contacting the remote service
- * @TRACKER_MINER_WEB_ERROR_TRACKER          : Error while contacting Tracker
- *
- * Describes the different errors that can occur while operating with the remote service.
+ * @TRACKER_MINER_WEB_ERROR_WRONG_CREDENTIALS: The credentials were
+ * refused by the remote service
+ * @TRACKER_MINER_WEB_ERROR_TOKEN_EXPIRED: The remote service
+ * token has expired
+ * @TRACKER_MINER_WEB_ERROR_NO_CREDENTIALS: There are currenty no
+ * credentials stored for this service
+ * @TRACKER_MINER_WEB_ERROR_KEYRING: The credential storage failed to
+ * retrieve the relevant information. See <classname>TrackerPasswordProvider</classname>
+ * @TRACKER_MINER_WEB_ERROR_SERVICE: Could not contact the remote service
+ * @TRACKER_MINER_WEB_ERROR_TRACKER: Could not contact the Tracker service
+ *
+ * The following errors are possible during any of the performed
+ * actions with a remote service.
+ *
+ * Since: 0.8
  **/
 typedef enum {
 	TRACKER_MINER_WEB_ERROR_WRONG_CREDENTIALS,
@@ -66,10 +73,17 @@ typedef enum {
 
 /**
  * TrackerMinerWebAssociationStatus:
- * @TRACKER_MINER_WEB_UNASSOCIATED : The miner is currently unassociated with the remote service
- * @TRACKER_MINER_WEB_ASSOCIATED   : The miner is currently associated with the remote service
+ * @TRACKER_MINER_WEB_UNASSOCIATED: The miner is currently
+ * not associated with the remote service. This means it needs to
+ * authenticate to be able to use any data from a remote service.
+ * @TRACKER_MINER_WEB_ASSOCIATED: The miner is currently associated
+ * with the remote service. This means that the miner can obtain
+ * remote data from the service.
  *
- * Describes if the miner can currently communicate (import data) with the web service.
+ * Describes if the current state of the miner's ability to retrieve
+ * data from the remote service.
+ *
+ * Since: 0.8
  **/
 typedef enum {
 	TRACKER_MINER_WEB_UNASSOCIATED,
@@ -82,28 +96,78 @@ struct TrackerMinerWeb {
 
 /**
  * TrackerMinerWebClass
- * @parent_class        : parent object class
- * @authenticate        : called when the miner is told to authenticate against the remote service
- * @get_association_data: called when one requests the miner's association data.
- *                        In the case of a user/pass based authentication, this should return
- *                        an empty hash table.
- *                        In the case of a token based authentication, the following keys must
- *                        be defined in the returned hash table:
- *                        - url: the url to point the user too
- *                        Additionally, the miner can define the following keys :
- *                        - post_message: a message to display after the user completes the
- *                                        association process
- *                        - post_url: a url to point the user after he completes the association
- *
- *                        If both post_message and post_url are defined, the message will be
- *                        displayed before the url is opened.
- * @associate           : called when the miner is told to associate with the web service.
- *                        In the case of a user/pass based authentication, the following keys must be defined
- *                        - username: the provided username
- *                        - password: the provided password
- *                        In the case of a token based authentication, the hash table can be ignored
- *                        since it will be empty.
- * @dissociate          : called when the miner is told to forget any user credentials it has stored
+ * @parent_class: parent object class
+ * @authenticate: called when a miner must authenticate against a
+ * remote service
+ * @get_association_data: called when one requests the miner's
+ * associated data
+ * @associate: called when the miner is asked to associate a remote
+ * service
+ * @dissociate: called when the miner is asked to revoke an
+ * association with a remote service
+ *
+ * For the @authenticate function, a username/password can be used and
+ * this should return an empty %GHashTable. If the authentication is
+ * based on a token, the following keys <emphasis>must</emphasis> be
+ * returned in the %GHashTable:
+ *
+ * <itemizedlist>
+ *   <listitem>
+ *     <para>
+ *       <emphasis>url</emphasis>: the url to point the user to.
+ *     </para>
+ *   </listitem>
+ * </itemizedlist>
+ *
+ * Additionally, the miner <emphasis>may</emphasis> define the
+ * following keys:
+ *
+ * <itemizedlist>
+ *   <listitem>
+ *     <para>
+ *       <emphasis>post_message</emphasis>: a message to display after
+ *       the user completes the association process.
+ *     </para>
+ *   </listitem>
+ *   <listitem>
+ *     <para>
+ *       <emphasis>post_url</emphasis>: a url to point the user to
+ *       after they have completed the association.
+ *     </para>
+ *   </listitem>
+ * </itemizedlist>
+ *
+ * <note>
+ *   <para>
+ *      If both <emphasis>post_message</emphasis> and
+ *      <emphasis>post_url</emphasis> are defined, the message will be
+ *      displayed before the url is opened.
+ *   </para>
+ * </note>
+ *
+ * For the @associate function, in the case of a username/password
+ * based authentication, the following keys must be defined:
+ *
+ * <itemizedlist>
+ *   <listitem>
+ *     <para>
+ *       <emphasis>username</emphasis>: the username.
+ *     </para>
+ *   </listitem>
+ *   <listitem>
+ *     <para>
+ *       <emphasis>password</emphasis>: the password.
+ *     </para>
+ *   </listitem>
+ * </itemizedlist>
+ *
+ * In the case of a token based authentication, the %GHashTable can be
+ * ignored since it will be empty.
+ *
+ * For the @dissociate function, miners <emphasis>must</emphasis>
+ * forget any user credentials stored.
+ *
+ * Since: 0.8.
  **/
 typedef struct {
 	TrackerMinerClass parent_class;
diff --git a/src/libtracker-miner/tracker-miner.c b/src/libtracker-miner/tracker-miner.c
index 61f040f..1839ad4 100644
--- a/src/libtracker-miner/tracker-miner.c
+++ b/src/libtracker-miner/tracker-miner.c
@@ -875,7 +875,7 @@ tracker_miner_execute_sparql (TrackerMiner        *miner,
  * Finishes the async operation and returns the query results. If an error
  * occured during the query, @error will be set.
  *
-* Returns: a #GPtrArray with the sparql results which should not be freed.
+ * Returns: a #GPtrArray with the sparql results which should not be freed.
  **/
 const GPtrArray *
 tracker_miner_execute_sparql_finish (TrackerMiner  *miner,
diff --git a/src/libtracker-miner/tracker-password-provider.c b/src/libtracker-miner/tracker-password-provider.c
index 17ffd02..3d73f8e 100644
--- a/src/libtracker-miner/tracker-password-provider.c
+++ b/src/libtracker-miner/tracker-password-provider.c
@@ -41,6 +41,11 @@ tracker_password_provider_init (gpointer object_class)
 }
 
 /* That would be better done with G_DECLARE_INTERFACE, but it's GLib 2.24. */
+/**
+ * tracker_password_provider_get_type:
+ *
+ * Returns: a #GType representing a %TrackerPasswordProvider.
+ **/
 GType
 tracker_password_provider_get_type (void)
 {
@@ -62,12 +67,29 @@ tracker_password_provider_get_type (void)
 	return iface_type;
 }
 
+/**
+ * tracker_password_provider_error_quark:
+ *
+ * Returns: the #GQuark used to identify password provider errors in
+ * GError structures.
+ **/
 GQuark
 tracker_password_provider_error_quark (void)
 {
 	return g_quark_from_static_string (TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN);
 }
 
+/**
+ * tracker_password_provider_get_name:
+ * @provider: a TrackerPasswordProvider
+ *
+ * At the moment there are only two providers, "GNOME Keyring" and
+ * "GKeyFile". Either of these is what will be returned unless new
+ * providers are written.
+ *
+ * Returns: a newly allocated string representing the #Object:name
+ * which must be freed with g_free().
+ **/
 gchar *
 tracker_password_provider_get_name (TrackerPasswordProvider *provider)
 {
@@ -80,6 +102,22 @@ tracker_password_provider_get_name (TrackerPasswordProvider *provider)
 	return name;
 }
 
+/**
+ * tracker_password_provider_store_password:
+ * @provider: a TrackerPasswordProvider
+ * @service: the name of the remote service associated with @username
+ * and @password
+ * @description: the description for @service
+ * @username: the username to store
+ * @password: the password to store
+ * @error: return location for errors
+ *
+ * This function calls the password provider's "store_password"
+ * implementation with @service, @description, @username and @password.
+ *
+ * Returns: %TRUE if the password was saved, otherwise %FALSE is
+ * returned and @error will be set.
+ **/
 gboolean
 tracker_password_provider_store_password (TrackerPasswordProvider  *provider,
                                           const gchar              *service,
@@ -104,6 +142,20 @@ tracker_password_provider_store_password (TrackerPasswordProvider  *provider,
 	return iface->store_password (provider, service, description, username, password, error);
 }
 
+/**
+ * tracker_password_provider_get_password:
+ * @provider: a TrackerPasswordProvider
+ * @service: the name of the remote service associated with @username
+ * @username: the username associated with the password we are returning
+ * @error: return location for errors
+ *
+ * This function calls the password provider's "get_password"
+ * implementation with @service and @username.
+ *
+ * Returns: a newly allocated string representing a password which
+ * must be freed with g_free(), otherwise %NULL is returned and @error
+ * will be set.
+ **/
 gchar *
 tracker_password_provider_get_password (TrackerPasswordProvider  *provider,
                                         const gchar              *service,
@@ -124,6 +176,17 @@ tracker_password_provider_get_password (TrackerPasswordProvider  *provider,
 	return iface->get_password (provider, service, username, error);
 }
 
+/**
+ * tracker_password_provider_forget_password:
+ * @provider: a TrackerPasswordProvider
+ * @service: the name of the remote service associated with @username
+ * @error: return location for errors
+ *
+ * This function calls the password provider's "forget_password"
+ * implementation with @service.
+ *
+ * On failure @error will be set.
+ **/
 void
 tracker_password_provider_forget_password (TrackerPasswordProvider  *provider,
                                            const gchar              *service,
diff --git a/src/libtracker-miner/tracker-password-provider.h b/src/libtracker-miner/tracker-password-provider.h
index 0d4c8e8..cd745d2 100644
--- a/src/libtracker-miner/tracker-password-provider.h
+++ b/src/libtracker-miner/tracker-password-provider.h
@@ -35,11 +35,34 @@ G_BEGIN_DECLS
 typedef struct TrackerPasswordProvider TrackerPasswordProvider;
 typedef struct TrackerPasswordProviderIface TrackerPasswordProviderIface;
 
+/**
+ * TrackerPasswordProviderError:
+ * @TRACKER_PASSWORD_PROVIDER_ERROR_SERVICE: An internal error
+ * occurred which meant the operation failed.
+ * @TRACKER_PASSWORD_PROVIDER_ERROR_NOTFOUND: No password provider was
+ * found to store/retrieve the remote service's authentication
+ * credentials
+ *
+ * The following errors are possible during any of the performed
+ * actions with a password provider.
+ *
+ * Since: 0.8
+ **/
 typedef enum {
 	TRACKER_PASSWORD_PROVIDER_ERROR_SERVICE,
 	TRACKER_PASSWORD_PROVIDER_ERROR_NOTFOUND
 } TrackerPasswordProviderError;
 
+/**
+ * TrackerPasswordProviderIface
+ * @parent_iface: parent object interface
+ * @store_password: save the service, username and password
+ * @get_password: get a password for a given service
+ * @forget_password: forget any password associated with a given
+ * service
+ *
+ * Since: 0.8.
+ **/
 struct TrackerPasswordProviderIface {
 	GTypeInterface parent_iface;
 
@@ -63,9 +86,6 @@ GQuark   tracker_password_provider_error_quark     (void);
 
 gchar*   tracker_password_provider_get_name        (TrackerPasswordProvider  *provider);
 
-/* Must be defined by the selected implementation */
-TrackerPasswordProvider*
-         tracker_password_provider_get             (void);
 gboolean tracker_password_provider_store_password  (TrackerPasswordProvider  *provider,
                                                     const gchar              *service,
                                                     const gchar              *description,
@@ -81,6 +101,23 @@ void     tracker_password_provider_forget_password (TrackerPasswordProvider  *pr
                                                     GError                  **error);
 gchar*   tracker_password_provider_strdup_mlock    (const gchar              *source);
 
+/* Must be defined by the selected implementation */
+/**
+ * tracker_password_provider_get:
+ *
+ * This function <emphasis>MUST</emphasis> be defined by the
+ * implementation of TrackerPasswordProvider.
+ *
+ * For example, tracker-password-provider-gnome.c should include this
+ * function for a GNOME Keyring implementation.
+ *
+ * Only one implementation can exist at once.
+ *
+ * Returns: a %TrackerPasswordProvider.
+ **/
+TrackerPasswordProvider *
+         tracker_password_provider_get             (void);
+
 G_END_DECLS
 
 #endif /* __LIBTRACKER_MINER_PASSWORD_PROVIDER_H__ */
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]