Debian Codegraph @

deps/libneon/doc/ref/auth.xml

raw
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 &lt;ne_auth.h&gt;</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>