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 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