.\"Generated by db2man.xsl. Don't modify this, modify the source.
.de Sh \" Subsection
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.TH "NE_SET_SERVER_AUTH" 3 "20 January 2006" "neon 0.25.5" "neon API reference"
.SH NAME
ne_set_server_auth, ne_set_proxy_auth, ne_forget_auth \- register authentication callbacks
.SH "SYNOPSIS"
.ad l
.hy 0

#include <ne_auth\&.h>
.sp
.HP 33
typedef\ int\ (*\fBne_request_auth\fR)\ (void\ *\fIuserdata\fR, const\ char\ *\fIrealm\fR, int\ \fIattempt\fR, char\ *\fIusername\fR, char\ *\fIpassword\fR);
.HP 25
void\ \fBne_set_server_auth\fR\ (ne_session\ *\fIsession\fR, ne_request_auth\ \fIcallback\fR, void\ *\fIuserdata\fR);
.HP 24
void\ \fBne_set_proxy_auth\fR\ (ne_session\ *\fIsession\fR, ne_request_auth\ \fIcallback\fR, void\ *\fIuserdata\fR);
.HP 21
void\ \fBne_forget_auth\fR\ (ne_session\ *\fIsession\fR);
.ad
.hy

.SH "DESCRIPTION"

.PP
The \fBne_request_auth\fR function type defines a callback which is invoked when a server or proxy server requires user authentication for a particular request\&. The \fIrealm\fR string is supplied by the server\&.  The \fIattempt\fR 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, \fIattempt\fR will be zero\&.

.PP
To retry the request using new authentication credentials, the callback should return zero, and the \fIusername\fR and \fIpassword\fR buffers must contain NUL\-terminated strings\&. The NE_ABUFSIZ constant gives the size of these buffers\&.

.RS
.Sh "Tip"

.PP
If you only wish to allow the user one attempt to enter credentials, use the value of the \fIattempt\fR parameter as the return value of the callback\&.

.RE

.PP
To abort the request, the callback should return a non\-zero value; in which case the contents of the \fIusername\fR and \fIpassword\fR buffers are ignored\&.

.PP
The \fBne_forget_auth\fR function can be used to discard the cached authentication credentials\&.

.SH "EXAMPLES"

.nf

/* 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(\&.\&.\&.)
{
   ne_session *sess = ne_session_create(\&.\&.\&.);

   ne_set_server_auth(sess, my_auth, NULL);

   /* \&.\&.\&. */
}
.fi

.SH AUTHOR
Joe Orton <neon@webdav\&.org>.