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
57callback which is invoked when a server or proxy server requires user
58authentication for a particular request.  The
59<parameter>realm</parameter> string is supplied by the server. <!--
60FIXME --> The <parameter>attempt</parameter> is a counter giving the
61number of times the request has been retried with different
62authentication credentials.  The first time the callback is invoked
63for a particular request, <parameter>attempt</parameter> will be zero.</para>
64
65	<para>To retry the request using new authentication
66credentials, the callback should return zero, and the
67<parameter>username</parameter> and <parameter>password</parameter>
68buffers must contain &nul;-terminated strings.  The
69<literal>NE_ABUFSIZ</literal> constant gives the size of these
70buffers.</para>
71
72	<tip>
73	  <para>If you only wish to allow the user one attempt to enter
74credentials, use the value of the <parameter>attempt</parameter>
75parameter as the return value of the callback.</para>
76	</tip>
77
78	<para>To abort the request, the callback should return a
79non-zero value; in which case the contents of the
80<parameter>username</parameter> and <parameter>password</parameter>
81buffers are ignored.</para>
82
83	<para>The <function>ne_forget_auth</function> function can be
84used 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: */
93extern char *prompt_for(const char *prompt);
94
95static int
96my_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
104int main(...)
105{
106   &egsess;
107
108   ne_set_server_auth(sess, my_auth, NULL);
109
110   /* ... */
111}</programlisting>
112      </refsect1>
113
114    </refentry>
115