| 1 |
<refentry id="refauth"> |
| 2 |
|
| 3 |
<refmeta> |
| 4 |
<refentrytitle>ne_set_server_auth</refentrytitle> |
| 5 |
<manvolnum>3</manvolnum> |
| 6 |
</refmeta> |
| 7 |
|
| 8 |
<refnamediv> |
| 9 |
<refname id="ne_set_server_auth">ne_set_server_auth</refname> |
| 10 |
<refname id="ne_set_proxy_auth">ne_set_proxy_auth</refname> |
| 11 |
<refname id="ne_forget_auth">ne_forget_auth</refname> |
| 12 |
<refpurpose>register authentication callbacks</refpurpose> |
| 13 |
</refnamediv> |
| 14 |
|
| 15 |
<refsynopsisdiv> |
| 16 |
|
| 17 |
<funcsynopsis> |
| 18 |
|
| 19 |
<funcsynopsisinfo>#include <ne_auth.h></funcsynopsisinfo> |
| 20 |
|
| 21 |
<funcprototype> |
| 22 |
<funcdef>typedef int (*<function>ne_auth_creds</function>)</funcdef> |
| 23 |
<paramdef>void *<parameter>userdata</parameter></paramdef> |
| 24 |
<paramdef>const char *<parameter>realm</parameter></paramdef> |
| 25 |
<paramdef>int <parameter>attempt</parameter></paramdef> |
| 26 |
<paramdef>char *<parameter>username</parameter></paramdef> |
| 27 |
<paramdef>char *<parameter>password</parameter></paramdef> |
| 28 |
</funcprototype> |
| 29 |
|
| 30 |
<funcprototype> |
| 31 |
<funcdef>void <function>ne_set_server_auth</function></funcdef> |
| 32 |
<paramdef>ne_session *<parameter>session</parameter></paramdef> |
| 33 |
<paramdef>ne_auth_creds <parameter>callback</parameter></paramdef> |
| 34 |
<paramdef>void *<parameter>userdata</parameter></paramdef> |
| 35 |
</funcprototype> |
| 36 |
|
| 37 |
<funcprototype> |
| 38 |
<funcdef>void <function>ne_set_proxy_auth</function></funcdef> |
| 39 |
<paramdef>ne_session *<parameter>session</parameter></paramdef> |
| 40 |
<paramdef>ne_auth_creds <parameter>callback</parameter></paramdef> |
| 41 |
<paramdef>void *<parameter>userdata</parameter></paramdef> |
| 42 |
</funcprototype> |
| 43 |
|
| 44 |
<funcprototype> |
| 45 |
<funcdef>void <function>ne_forget_auth</function></funcdef> |
| 46 |
<paramdef>ne_session *<parameter>session</parameter></paramdef> |
| 47 |
</funcprototype> |
| 48 |
|
| 49 |
</funcsynopsis> |
| 50 |
|
| 51 |
</refsynopsisdiv> |
| 52 |
|
| 53 |
<refsect1> |
| 54 |
<title>Description</title> |
| 55 |
|
| 56 |
<para>The <type>ne_auth_creds</type> function type defines a |
| 57 |
callback which is invoked when a server or proxy server requires user |
| 58 |
authentication for a particular request. The |
| 59 |
<parameter>realm</parameter> string is supplied by the server. <!-- |
| 60 |
FIXME --> The <parameter>attempt</parameter> is a counter giving the |
| 61 |
number of times the request has been retried with different |
| 62 |
authentication credentials. The first time the callback is invoked |
| 63 |
for a particular request, <parameter>attempt</parameter> will be zero.</para> |
| 64 |
|
| 65 |
<para>To retry the request using new authentication |
| 66 |
credentials, the callback should return zero, and the |
| 67 |
<parameter>username</parameter> and <parameter>password</parameter> |
| 68 |
buffers must contain &nul;-terminated strings. The |
| 69 |
<literal>NE_ABUFSIZ</literal> constant gives the size of these |
| 70 |
buffers.</para> |
| 71 |
|
| 72 |
<tip> |
| 73 |
<para>If you only wish to allow the user one attempt to enter |
| 74 |
credentials, use the value of the <parameter>attempt</parameter> |
| 75 |
parameter as the return value of the callback.</para> |
| 76 |
</tip> |
| 77 |
|
| 78 |
<para>To abort the request, the callback should return a |
| 79 |
non-zero value; in which case the contents of the |
| 80 |
<parameter>username</parameter> and <parameter>password</parameter> |
| 81 |
buffers are ignored.</para> |
| 82 |
|
| 83 |
<para>The <function>ne_forget_auth</function> function can be |
| 84 |
used to discard the cached authentication credentials.</para> |
| 85 |
|
| 86 |
</refsect1> |
| 87 |
|
| 88 |
<refsect1> |
| 89 |
<title>Examples</title> |
| 90 |
|
| 91 |
<programlisting> |
| 92 |
/* Function which prompts for a line of user input: */ |
| 93 |
extern char *prompt_for(const char *prompt); |
| 94 |
|
| 95 |
static int |
| 96 |
my_auth(void *userdata, const char *realm, int attempts, |
| 97 |
char *username, char *password) |
| 98 |
{ |
| 99 |
strncpy(username, prompt_for("Username: "), NE_ABUFSIZ); |
| 100 |
strncpy(password, prompt_for("Password: "), NE_ABUFSIZ); |
| 101 |
return attempts; |
| 102 |
} |
| 103 |
|
| 104 |
int main(...) |
| 105 |
{ |
| 106 |
&egsess; |
| 107 |
|
| 108 |
ne_set_server_auth(sess, my_auth, NULL); |
| 109 |
|
| 110 |
/* ... */ |
| 111 |
}</programlisting> |
| 112 |
</refsect1> |
| 113 |
|
| 114 |
</refentry> |