<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="libedataserverui-e-passwords">
<refmeta>
<refentrytitle role="top_of_page" id="libedataserverui-e-passwords.top_of_page">e-passwords</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBEDATASERVERUI Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>e-passwords</refname>
<refpurpose></refpurpose>
</refnamediv>

<refsynopsisdiv id="libedataserverui-e-passwords.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
<link linkend="void">void</link>                <link linkend="e-passwords-init">e_passwords_init</link>                    (void);
<link linkend="void">void</link>                <link linkend="e-passwords-shutdown">e_passwords_shutdown</link>                (void);
<link linkend="void">void</link>                <link linkend="e-passwords-cancel">e_passwords_cancel</link>                  (void);
<link linkend="void">void</link>                <link linkend="e-passwords-set-online">e_passwords_set_online</link>              (<link linkend="int">int</link> state);
<link linkend="void">void</link>                <link linkend="e-passwords-remember-password">e_passwords_remember_password</link>       (const <link linkend="char">char</link> *component,
                                                         const <link linkend="char">char</link> *key);
<link linkend="void">void</link>                <link linkend="e-passwords-add-password">e_passwords_add_password</link>            (const <link linkend="char">char</link> *key,
                                                         const <link linkend="char">char</link> *passwd);
<link linkend="char">char</link> *              <link linkend="e-passwords-get-password">e_passwords_get_password</link>            (const <link linkend="char">char</link> *component,
                                                         const <link linkend="char">char</link> *key);
<link linkend="void">void</link>                <link linkend="e-passwords-forget-password">e_passwords_forget_password</link>         (const <link linkend="char">char</link> *component,
                                                         const <link linkend="char">char</link> *key);
<link linkend="void">void</link>                <link linkend="e-passwords-forget-passwords">e_passwords_forget_passwords</link>        (void);
<link linkend="void">void</link>                <link linkend="e-passwords-clear-passwords">e_passwords_clear_passwords</link>         (const <link linkend="char">char</link> *component);
enum                <link linkend="EPasswordsRememberType">EPasswordsRememberType</link>;
<link linkend="char">char</link> *              <link linkend="e-passwords-ask-password">e_passwords_ask_password</link>            (const <link linkend="char">char</link> *title,
                                                         const <link linkend="char">char</link> *component_name,
                                                         const <link linkend="char">char</link> *key,
                                                         const <link linkend="char">char</link> *prompt,
                                                         <link linkend="EPasswordsRememberType">EPasswordsRememberType</link> remember_type,
                                                         <link linkend="gboolean">gboolean</link> *remember,
                                                         <link linkend="GtkWindow">GtkWindow</link> *parent);
</synopsis>
</refsynopsisdiv>









<refsect1 id="libedataserverui-e-passwords.description" role="desc">
<title role="desc.title">Description</title>
<para>
</para>
</refsect1>

<refsect1 id="libedataserverui-e-passwords.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="e-passwords-init" role="function">
<title>e_passwords_init ()</title>
<indexterm zone="e-passwords-init"><primary sortas="e_passwords_init">e_passwords_init</primary></indexterm><programlisting><link linkend="void">void</link>                e_passwords_init                    (void);</programlisting>
<para>
Initializes the e_passwords routines. Must be called before any other
e_passwords_* function.</para>
<para>
</para></refsect2>
<refsect2 id="e-passwords-shutdown" role="function">
<title>e_passwords_shutdown ()</title>
<indexterm zone="e-passwords-shutdown"><primary sortas="e_passwords_shutdown">e_passwords_shutdown</primary></indexterm><programlisting><link linkend="void">void</link>                e_passwords_shutdown                (void);</programlisting>
<para>
Cleanup routine to call before exiting.</para>
<para>
</para></refsect2>
<refsect2 id="e-passwords-cancel" role="function">
<title>e_passwords_cancel ()</title>
<indexterm zone="e-passwords-cancel"><primary sortas="e_passwords_cancel">e_passwords_cancel</primary></indexterm><programlisting><link linkend="void">void</link>                e_passwords_cancel                  (void);</programlisting>
<para>
Cancel any outstanding password operations and close any dialogues
currently being shown.</para>
<para>
</para></refsect2>
<refsect2 id="e-passwords-set-online" role="function">
<title>e_passwords_set_online ()</title>
<indexterm zone="e-passwords-set-online"><primary sortas="e_passwords_set_online">e_passwords_set_online</primary></indexterm><programlisting><link linkend="void">void</link>                e_passwords_set_online              (<link linkend="int">int</link> state);</programlisting>
<para>
Set the offline-state of the application.  This is a work-around
for having the backends fully offline aware, and returns a
cancellation response instead of prompting for passwords.
</para>
<para>
FIXME: This is not a permanent api, review post 2.0.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>state</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-passwords-remember-password" role="function">
<title>e_passwords_remember_password ()</title>
<indexterm zone="e-passwords-remember-password"><primary sortas="e_passwords_remember_password">e_passwords_remember_password</primary></indexterm><programlisting><link linkend="void">void</link>                e_passwords_remember_password       (const <link linkend="char">char</link> *component,
                                                         const <link linkend="char">char</link> *key);</programlisting>
<para>
Saves the password associated with <parameter>key</parameter> to disk.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>component</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara> the key
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-passwords-add-password" role="function">
<title>e_passwords_add_password ()</title>
<indexterm zone="e-passwords-add-password"><primary sortas="e_passwords_add_password">e_passwords_add_password</primary></indexterm><programlisting><link linkend="void">void</link>                e_passwords_add_password            (const <link linkend="char">char</link> *key,
                                                         const <link linkend="char">char</link> *passwd);</programlisting>
<para>
This stores the <parameter>key</parameter>/<parameter>passwd</parameter> pair in the current session's password
hash.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara> a key
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>passwd</parameter>&#160;:</term>
<listitem><simpara> the password for <parameter>key</parameter>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-passwords-get-password" role="function">
<title>e_passwords_get_password ()</title>
<indexterm zone="e-passwords-get-password"><primary sortas="e_passwords_get_password">e_passwords_get_password</primary></indexterm><programlisting><link linkend="char">char</link> *              e_passwords_get_password            (const <link linkend="char">char</link> *component,
                                                         const <link linkend="char">char</link> *key);</programlisting>
<para>
</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>component</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara> the key
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the password associated with <parameter>key</parameter>, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>.  Caller
must free the returned password.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-passwords-forget-password" role="function">
<title>e_passwords_forget_password ()</title>
<indexterm zone="e-passwords-forget-password"><primary sortas="e_passwords_forget_password">e_passwords_forget_password</primary></indexterm><programlisting><link linkend="void">void</link>                e_passwords_forget_password         (const <link linkend="char">char</link> *component,
                                                         const <link linkend="char">char</link> *key);</programlisting>
<para>
Forgets the password associated with <parameter>key</parameter>, in memory and on disk.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>component</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara> the key
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="e-passwords-forget-passwords" role="function">
<title>e_passwords_forget_passwords ()</title>
<indexterm zone="e-passwords-forget-passwords"><primary sortas="e_passwords_forget_passwords">e_passwords_forget_passwords</primary></indexterm><programlisting><link linkend="void">void</link>                e_passwords_forget_passwords        (void);</programlisting>
<para>
Forgets all cached passwords, in memory and on disk.</para>
<para>
</para></refsect2>
<refsect2 id="e-passwords-clear-passwords" role="function">
<title>e_passwords_clear_passwords ()</title>
<indexterm zone="e-passwords-clear-passwords"><primary sortas="e_passwords_clear_passwords">e_passwords_clear_passwords</primary></indexterm><programlisting><link linkend="void">void</link>                e_passwords_clear_passwords         (const <link linkend="char">char</link> *component);</programlisting>
<para>
Forgets all disk cached passwords for the component.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>component</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="EPasswordsRememberType" role="enum">
<title>enum EPasswordsRememberType</title>
<indexterm zone="EPasswordsRememberType"><primary sortas="EPasswordsRememberType">EPasswordsRememberType</primary></indexterm><programlisting>typedef enum {
	E_PASSWORDS_REMEMBER_NEVER,
	E_PASSWORDS_REMEMBER_SESSION,
	E_PASSWORDS_REMEMBER_FOREVER,
	E_PASSWORDS_REMEMBER_MASK = 0xf,

	/* option bits */
	E_PASSWORDS_SECRET = 1&lt;&lt;8,
	E_PASSWORDS_REPROMPT = 1&lt;&lt;9,
	E_PASSWORDS_ONLINE = 1&lt;&lt;10, /* only ask if we're online */
	E_PASSWORDS_DISABLE_REMEMBER = 1&lt;&lt;11, /* disable the 'remember password' checkbox */
	E_PASSWORDS_PASSPHRASE = 1&lt;&lt;12, /* We are asking a passphrase */
} EPasswordsRememberType;
</programlisting>
<para>
</para></refsect2>
<refsect2 id="e-passwords-ask-password" role="function">
<title>e_passwords_ask_password ()</title>
<indexterm zone="e-passwords-ask-password"><primary sortas="e_passwords_ask_password">e_passwords_ask_password</primary></indexterm><programlisting><link linkend="char">char</link> *              e_passwords_ask_password            (const <link linkend="char">char</link> *title,
                                                         const <link linkend="char">char</link> *component_name,
                                                         const <link linkend="char">char</link> *key,
                                                         const <link linkend="char">char</link> *prompt,
                                                         <link linkend="EPasswordsRememberType">EPasswordsRememberType</link> remember_type,
                                                         <link linkend="gboolean">gboolean</link> *remember,
                                                         <link linkend="GtkWindow">GtkWindow</link> *parent);</programlisting>
<para>
Asks the user for a password.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>title</parameter>&#160;:</term>
<listitem><simpara> title for the password dialog
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>component_name</parameter>&#160;:</term>
<listitem><simpara> the name of the component for which we're storing
the password (e.g. Mail, Addressbook, etc.)
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>key</parameter>&#160;:</term>
<listitem><simpara> key to store the password under
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>prompt</parameter>&#160;:</term>
<listitem><simpara> prompt string
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>remember_type</parameter>&#160;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>remember</parameter>&#160;:</term>
<listitem><simpara> on input, the default state of the remember checkbox.
on output, the state of the checkbox when the dialog was closed.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>parent</parameter>&#160;:</term>
<listitem><simpara> parent window of the dialog, or <link linkend="NULL--CAPS"><literal>NULL</literal></link>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the password, which the caller must free, or <link linkend="NULL--CAPS"><literal>NULL</literal></link> if
the user cancelled the operation. *<parameter>remember</parameter> will be set if the
return value is non-<link linkend="NULL--CAPS"><literal>NULL</literal></link> and <parameter>remember_type</parameter> is not
E_PASSWORDS_DO_NOT_REMEMBER.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
