diff options
Diffstat (limited to 'doc/ref/auth.xml')
| -rw-r--r-- | doc/ref/auth.xml | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/doc/ref/auth.xml b/doc/ref/auth.xml new file mode 100644 index 0000000..9b20201 --- /dev/null +++ b/doc/ref/auth.xml @@ -0,0 +1,114 @@ + <refentry id="refauth"> + + <refmeta> + <refentrytitle>ne_set_server_auth</refentrytitle> + <manvolnum>3</manvolnum> + </refmeta> + + <refnamediv> + <refname id="ne_set_server_auth">ne_set_server_auth</refname> + <refname id="ne_set_proxy_auth">ne_set_proxy_auth</refname> + <refname id="ne_forget_auth">ne_forget_auth</refname> + <refpurpose>register authentication callbacks</refpurpose> + </refnamediv> + + <refsynopsisdiv> + + <funcsynopsis> + + <funcsynopsisinfo>#include <ne_auth.h></funcsynopsisinfo> + + <funcprototype> + <funcdef>typedef int (*<function>ne_request_auth</function>)</funcdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + <paramdef>const char *<parameter>realm</parameter></paramdef> + <paramdef>int <parameter>attempt</parameter></paramdef> + <paramdef>char *<parameter>username</parameter></paramdef> + <paramdef>char *<parameter>password</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>ne_set_server_auth</function></funcdef> + <paramdef>ne_session *<parameter>session</parameter></paramdef> + <paramdef>ne_request_auth <parameter>callback</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>ne_set_proxy_auth</function></funcdef> + <paramdef>ne_session *<parameter>session</parameter></paramdef> + <paramdef>ne_request_auth <parameter>callback</parameter></paramdef> + <paramdef>void *<parameter>userdata</parameter></paramdef> + </funcprototype> + + <funcprototype> + <funcdef>void <function>ne_forget_auth</function></funcdef> + <paramdef>ne_session *<parameter>session</parameter></paramdef> + </funcprototype> + + </funcsynopsis> + + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <type>ne_request_auth</type> function type defines a +callback which is invoked when a server or proxy server requires user +authentication for a particular request. The +<parameter>realm</parameter> string is supplied by the server. <!-- +FIXME --> The <parameter>attempt</parameter> is a counter giving the +number of times the request has been retried with different +authentication credentials. The first time the callback is invoked +for a particular request, <parameter>attempt</parameter> will be zero.</para> + + <para>To retry the request using new authentication +credentials, the callback should return zero, and the +<parameter>username</parameter> and <parameter>password</parameter> +buffers must contain &nul;-terminated strings. The +<literal>NE_ABUFSIZ</literal> constant gives the size of these +buffers.</para> + + <tip> + <para>If you only wish to allow the user one attempt to enter +credentials, use the value of the <parameter>attempt</parameter> +parameter as the return value of the callback.</para> + </tip> + + <para>To abort the request, the callback should return a +non-zero value; in which case the contents of the +<parameter>username</parameter> and <parameter>password</parameter> +buffers are ignored.</para> + + <para>The <function>ne_forget_auth</function> function can be +used to discard the cached authentication credentials.</para> + + </refsect1> + + <refsect1> + <title>Examples</title> + + <programlisting> +/* Function which prompts for a line of user input: */ +extern char *prompt_for(const char *prompt); + +static int +my_auth(void *userdata, const char *realm, int attempts, + char *username, char *password) +{ + strncpy(username, prompt_for("Username: "), NE_ABUFSIZ); + strncpy(password, prompt_for("Password: "), NE_ABUFSIZ); + return attempts; +} + +int main(...) +{ + &egsess; + + ne_set_server_auth(sess, my_auth, NULL); + + /* ... */ +}</programlisting> + </refsect1> + + </refentry> |