<refentry id="libtracker-miner-TrackerPasswordProvider">
<refmeta>
<refentrytitle role="top_of_page" id="libtracker-miner-TrackerPasswordProvider.top_of_page">TrackerPasswordProvider</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBTRACKER-MINER Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>TrackerPasswordProvider</refname>
<refpurpose>Password storage interface for cross platform backends</refpurpose>
</refnamediv>

<refsynopsisdiv id="libtracker-miner-TrackerPasswordProvider.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;libtracker-miner/tracker-miner.h&gt;

#define             <link linkend="TRACKER-PASSWORD-PROVIDER-ERROR-DOMAIN--CAPS">TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN</link>
#define             <link linkend="TRACKER-PASSWORD-PROVIDER-ERROR--CAPS">TRACKER_PASSWORD_PROVIDER_ERROR</link>
#define             <link linkend="TRACKER-PASSWORD-PROVIDER-GET-INTERFACE--CAPS">TRACKER_PASSWORD_PROVIDER_GET_INTERFACE</link>(o)
typedef             <link linkend="TrackerPasswordProvider">TrackerPasswordProvider</link>;
enum                <link linkend="TrackerPasswordProviderError">TrackerPasswordProviderError</link>;
                    <link linkend="TrackerPasswordProviderIface">TrackerPasswordProviderIface</link>;
<link linkend="GQuark">GQuark</link>              <link linkend="tracker-password-provider-error-quark">tracker_password_provider_error_quark</link>
                                                        (void);
<link linkend="TrackerPasswordProvider">TrackerPasswordProvider</link> * <link linkend="tracker-password-provider-get">tracker_password_provider_get</link> (void);
<link linkend="gchar">gchar</link> *             <link linkend="tracker-password-provider-get-name">tracker_password_provider_get_name</link>  (<link linkend="TrackerPasswordProvider">TrackerPasswordProvider</link> *provider);
<link linkend="gboolean">gboolean</link>            <link linkend="tracker-password-provider-store-password">tracker_password_provider_store_password</link>
                                                        (<link linkend="TrackerPasswordProvider">TrackerPasswordProvider</link> *provider,
                                                         const <link linkend="gchar">gchar</link> *service,
                                                         const <link linkend="gchar">gchar</link> *description,
                                                         const <link linkend="gchar">gchar</link> *username,
                                                         const <link linkend="gchar">gchar</link> *password,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link> *             <link linkend="tracker-password-provider-get-password">tracker_password_provider_get_password</link>
                                                        (<link linkend="TrackerPasswordProvider">TrackerPasswordProvider</link> *provider,
                                                         const <link linkend="gchar">gchar</link> *service,
                                                         <link linkend="gchar">gchar</link> **username,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="void">void</link>                <link linkend="tracker-password-provider-forget-password">tracker_password_provider_forget_password</link>
                                                        (<link linkend="TrackerPasswordProvider">TrackerPasswordProvider</link> *provider,
                                                         const <link linkend="gchar">gchar</link> *service,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="gchar">gchar</link> *             <link linkend="tracker-password-provider-lock-password">tracker_password_provider_lock_password</link>
                                                        (const <link linkend="gchar">gchar</link> *password);
<link linkend="gboolean">gboolean</link>            <link linkend="tracker-password-provider-unlock-password">tracker_password_provider_unlock_password</link>
                                                        (<link linkend="gchar">gchar</link> *password);
</synopsis>
</refsynopsisdiv>









<refsect1 id="libtracker-miner-TrackerPasswordProvider.description" role="desc">
<title role="desc.title">Description</title>
<para>
The <link linkend="TrackerPasswordProvider"><type>TrackerPasswordProvider</type></link> allows different backends to be
written for storing sensitive information about web services which
are needed to authenticate and mine data. Currently, there are two
implementations. One for GNOME Keyring and one using <link linkend="GKeyFile"><type>GKeyFile</type></link> (as a
fallback if GNOME Keyring is installed).</para>
<para>
</para>
</refsect1>

<refsect1 id="libtracker-miner-TrackerPasswordProvider.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="TRACKER-PASSWORD-PROVIDER-ERROR-DOMAIN--CAPS" role="macro">
<title>TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN</title>
<indexterm zone="TRACKER-PASSWORD-PROVIDER-ERROR-DOMAIN--CAPS"><primary sortas="TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN">TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN</primary></indexterm><programlisting>#define TRACKER_PASSWORD_PROVIDER_ERROR_DOMAIN  "TrackerPasswordProvider"
</programlisting>
<para>
</para></refsect2>
<refsect2 id="TRACKER-PASSWORD-PROVIDER-ERROR--CAPS" role="macro">
<title>TRACKER_PASSWORD_PROVIDER_ERROR</title>
<indexterm zone="TRACKER-PASSWORD-PROVIDER-ERROR--CAPS"><primary sortas="TRACKER_PASSWORD_PROVIDER_ERROR">TRACKER_PASSWORD_PROVIDER_ERROR</primary></indexterm><programlisting>#define TRACKER_PASSWORD_PROVIDER_ERROR         tracker_password_provider_error_quark()
</programlisting>
<para>
</para></refsect2>
<refsect2 id="TRACKER-PASSWORD-PROVIDER-GET-INTERFACE--CAPS" role="macro">
<title>TRACKER_PASSWORD_PROVIDER_GET_INTERFACE()</title>
<indexterm zone="TRACKER-PASSWORD-PROVIDER-GET-INTERFACE--CAPS"><primary sortas="TRACKER_PASSWORD_PROVIDER_GET_INTERFACE">TRACKER_PASSWORD_PROVIDER_GET_INTERFACE</primary></indexterm><programlisting>#define TRACKER_PASSWORD_PROVIDER_GET_INTERFACE(o) (G_TYPE_INSTANCE_GET_INTERFACE ((o),  TRACKER_TYPE_PASSWORD_PROVIDER, TrackerPasswordProviderIface))
</programlisting>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>o</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="TrackerPasswordProvider" role="typedef">
<title>TrackerPasswordProvider</title>
<indexterm zone="TrackerPasswordProvider"><primary sortas="TrackerPasswordProvider">TrackerPasswordProvider</primary></indexterm><programlisting>typedef struct TrackerPasswordProvider TrackerPasswordProvider;
</programlisting>
<para>
</para></refsect2>
<refsect2 id="TrackerPasswordProviderError" role="enum" condition="since:0.8">
<title>enum TrackerPasswordProviderError</title>
<indexterm zone="TrackerPasswordProviderError" role="0.8"><primary sortas="TrackerPasswordProviderError">TrackerPasswordProviderError</primary></indexterm><programlisting>typedef enum {
	TRACKER_PASSWORD_PROVIDER_ERROR_SERVICE,
	TRACKER_PASSWORD_PROVIDER_ERROR_NOTFOUND
} TrackerPasswordProviderError;
</programlisting>
<para>
The following errors are possible during any of the performed
actions with a password provider.</para>
<para>
</para><variablelist role="enum">
<varlistentry id="TRACKER-PASSWORD-PROVIDER-ERROR-SERVICE--CAPS" role="constant">
<term><literal>TRACKER_PASSWORD_PROVIDER_ERROR_SERVICE</literal></term>
<listitem><simpara> An internal error
occurred which meant the operation failed.
</simpara></listitem>
</varlistentry>
<varlistentry id="TRACKER-PASSWORD-PROVIDER-ERROR-NOTFOUND--CAPS" role="constant">
<term><literal>TRACKER_PASSWORD_PROVIDER_ERROR_NOTFOUND</literal></term>
<listitem><simpara> No password provider was
found to store/retrieve the remote service's authentication
credentials
</simpara></listitem>
</varlistentry>
</variablelist><para role="since">Since 0.8</para></refsect2>
<refsect2 id="TrackerPasswordProviderIface" role="struct" condition="since:0.8.">
<title>TrackerPasswordProviderIface</title>
<indexterm zone="TrackerPasswordProviderIface" role="0.8."><primary sortas="TrackerPasswordProviderIface">TrackerPasswordProviderIface</primary></indexterm><programlisting>typedef struct {
	GTypeInterface parent_iface;

	gboolean (* store_password)  (TrackerPasswordProvider  *provider,
	                              const gchar              *service,
	                              const gchar              *description,
	                              const gchar              *username,
	                              const gchar              *password,
	                              GError                  **error);
	gchar *  (* get_password)    (TrackerPasswordProvider  *provider,
	                              const gchar              *service,
	                              gchar                   **username,
	                              GError                  **error);
	gboolean (* forget_password) (TrackerPasswordProvider  *provider,
	                              const gchar              *service,
	                              GError                  **error);
} TrackerPasswordProviderIface;
</programlisting>
<para>
</para>
<para>
</para><variablelist role="struct">
<varlistentry>
<term><link linkend="GTypeInterface">GTypeInterface</link>&#160;<structfield>parent_iface</structfield>;</term>
<listitem><simpara> parent object interface
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>store_password</structfield>&#160;()</term>
<listitem><simpara> save the service, username and password
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>get_password</structfield>&#160;()</term>
<listitem><simpara> get a password for a given service
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><structfield>forget_password</structfield>&#160;()</term>
<listitem><simpara> forget any password associated with a given
service
</simpara></listitem>
</varlistentry>
</variablelist><para role="since">Since 0.8.</para></refsect2>
<refsect2 id="tracker-password-provider-error-quark" role="function">
<title>tracker_password_provider_error_quark ()</title>
<indexterm zone="tracker-password-provider-error-quark"><primary sortas="tracker_password_provider_error_quark">tracker_password_provider_error_quark</primary></indexterm><programlisting><link linkend="GQuark">GQuark</link>              tracker_password_provider_error_quark
                                                        (void);</programlisting>
<para>
</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <link linkend="GQuark"><type>GQuark</type></link> used to identify password provider errors in
GError structures.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="tracker-password-provider-get" role="function">
<title>tracker_password_provider_get ()</title>
<indexterm zone="tracker-password-provider-get"><primary sortas="tracker_password_provider_get">tracker_password_provider_get</primary></indexterm><programlisting><link linkend="TrackerPasswordProvider">TrackerPasswordProvider</link> * tracker_password_provider_get (void);</programlisting>
<para>
This function <emphasis>MUST</emphasis> be defined by the
implementation of TrackerPasswordProvider.
</para>
<para>
For example, tracker-password-provider-gnome.c should include this
function for a GNOME Keyring implementation.
</para>
<para>
Only one implementation can exist at once.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a <link linkend="TrackerPasswordProvider"><literal>TrackerPasswordProvider</literal></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="tracker-password-provider-get-name" role="function">
<title>tracker_password_provider_get_name ()</title>
<indexterm zone="tracker-password-provider-get-name"><primary sortas="tracker_password_provider_get_name">tracker_password_provider_get_name</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             tracker_password_provider_get_name  (<link linkend="TrackerPasswordProvider">TrackerPasswordProvider</link> *provider);</programlisting>
<para>
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.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>provider</parameter>&#160;:</term>
<listitem><simpara> a TrackerPasswordProvider
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated string representing the <link linkend="Object--name"><type>"name"</type></link>
which must be freed with <link linkend="g-free"><function>g_free()</function></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="tracker-password-provider-store-password" role="function">
<title>tracker_password_provider_store_password ()</title>
<indexterm zone="tracker-password-provider-store-password"><primary sortas="tracker_password_provider_store_password">tracker_password_provider_store_password</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            tracker_password_provider_store_password
                                                        (<link linkend="TrackerPasswordProvider">TrackerPasswordProvider</link> *provider,
                                                         const <link linkend="gchar">gchar</link> *service,
                                                         const <link linkend="gchar">gchar</link> *description,
                                                         const <link linkend="gchar">gchar</link> *username,
                                                         const <link linkend="gchar">gchar</link> *password,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
This function calls the password provider's "store_password"
implementation with <parameter>service</parameter>, <parameter>description</parameter>, <parameter>username</parameter> and <parameter>password</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>provider</parameter>&#160;:</term>
<listitem><simpara> a TrackerPasswordProvider
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>service</parameter>&#160;:</term>
<listitem><simpara> the name of the remote service associated with <parameter>username</parameter>
and <parameter>password</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>description</parameter>&#160;:</term>
<listitem><simpara> the description for <parameter>service</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>username</parameter>&#160;:</term>
<listitem><simpara> the username to store
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>password</parameter>&#160;:</term>
<listitem><simpara> the password to store
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> return location for errors
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if the password was saved, otherwise <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> is
returned and <parameter>error</parameter> will be set.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="tracker-password-provider-get-password" role="function">
<title>tracker_password_provider_get_password ()</title>
<indexterm zone="tracker-password-provider-get-password"><primary sortas="tracker_password_provider_get_password">tracker_password_provider_get_password</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             tracker_password_provider_get_password
                                                        (<link linkend="TrackerPasswordProvider">TrackerPasswordProvider</link> *provider,
                                                         const <link linkend="gchar">gchar</link> *service,
                                                         <link linkend="gchar">gchar</link> **username,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
This function calls the password provider's "get_password"
implementation with <parameter>service</parameter> and <parameter>username</parameter>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>provider</parameter>&#160;:</term>
<listitem><simpara> a TrackerPasswordProvider
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>service</parameter>&#160;:</term>
<listitem><simpara> the name of the remote service associated with <parameter>username</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>username</parameter>&#160;:</term>
<listitem><simpara> the username associated with the password we are returning
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> return location for errors
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated string representing a password which
must be freed with <link linkend="g-free"><function>g_free()</function></link>, otherwise <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned and <parameter>error</parameter>
will be set.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="tracker-password-provider-forget-password" role="function">
<title>tracker_password_provider_forget_password ()</title>
<indexterm zone="tracker-password-provider-forget-password"><primary sortas="tracker_password_provider_forget_password">tracker_password_provider_forget_password</primary></indexterm><programlisting><link linkend="void">void</link>                tracker_password_provider_forget_password
                                                        (<link linkend="TrackerPasswordProvider">TrackerPasswordProvider</link> *provider,
                                                         const <link linkend="gchar">gchar</link> *service,
                                                         <link linkend="GError">GError</link> **error);</programlisting>
<para>
This function calls the password provider's "forget_password"
implementation with <parameter>service</parameter>.
</para>
<para>
On failure <parameter>error</parameter> will be set.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>provider</parameter>&#160;:</term>
<listitem><simpara> a TrackerPasswordProvider
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>service</parameter>&#160;:</term>
<listitem><simpara> the name of the remote service associated with <parameter>username</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>error</parameter>&#160;:</term>
<listitem><simpara> return location for errors
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="tracker-password-provider-lock-password" role="function">
<title>tracker_password_provider_lock_password ()</title>
<indexterm zone="tracker-password-provider-lock-password"><primary sortas="tracker_password_provider_lock_password">tracker_password_provider_lock_password</primary></indexterm><programlisting><link linkend="gchar">gchar</link> *             tracker_password_provider_lock_password
                                                        (const <link linkend="gchar">gchar</link> *password);</programlisting>
<para>
This function calls <link linkend="mlock"><function>mlock()</function></link> to secure a memory region newly
allocated and <parameter>password</parameter> is copied using <link linkend="memcpy"><function>memcpy()</function></link> into the new
address.
</para>
<para>
Password can not be <link linkend="NULL--CAPS"><literal>NULL</literal></link> or an empty string ("").</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>password</parameter>&#160;:</term>
<listitem><simpara> a string pointer
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> a newly allocated string which <emphasis>MUST</emphasis>
be freed with <link linkend="tracker-password-provider-unlock-password"><function>tracker_password_provider_unlock_password()</function></link>. On
failure <link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="tracker-password-provider-unlock-password" role="function">
<title>tracker_password_provider_unlock_password ()</title>
<indexterm zone="tracker-password-provider-unlock-password"><primary sortas="tracker_password_provider_unlock_password">tracker_password_provider_unlock_password</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link>            tracker_password_provider_unlock_password
                                                        (<link linkend="gchar">gchar</link> *password);</programlisting>
<para>
This function calls <link linkend="munlock"><function>munlock()</function></link> on <parameter>password</parameter> which should be a
secured memory region. The <parameter>password</parameter> is zeroed first with <link linkend="bzero"><function>bzero()</function></link>
and once unlocked it is freed with <link linkend="g-free"><function>g_free()</function></link>. 
</para>
<para>
The <parameter>password</parameter> can not be <link linkend="NULL--CAPS"><literal>NULL</literal></link> or an empty string (""). In
addition, <parameter>password</parameter> <emphasis>MUST</emphasis> be a string created
with <link linkend="tracker-password-provider-lock-password"><function>tracker_password_provider_lock_password()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>password</parameter>&#160;:</term>
<listitem><simpara> a string pointer
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <link linkend="munlock"><function>munlock()</function></link> succeeded, otherwise <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> is returned.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
