Debian Codegraph @

deps/libneon/doc/man/ne_set_server_auth.3

raw
1 '\" t
2 .\" Title: ne_set_server_auth
3 .\" Author:
4 .\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
5 .\" Date: 3 May 2011
6 .\" Manual: neon API reference
7 .\" Source: neon 0.29.6
8 .\" Language: English
9 .\"
10 .TH "NE_SET_SERVER_AUTH" "3" "3 May 2011" "neon 0.29.6" "neon API reference"
11 .\" -----------------------------------------------------------------
12 .\" * Define some portability stuff
13 .\" -----------------------------------------------------------------
14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
15 .\" http://bugs.debian.org/507673
16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
18 .ie \n(.g .ds Aq \(aq
19 .el .ds Aq '
20 .\" -----------------------------------------------------------------
21 .\" * set default formatting
22 .\" -----------------------------------------------------------------
23 .\" disable hyphenation
24 .nh
25 .\" disable justification (adjust text to left margin only)
26 .ad l
27 .\" -----------------------------------------------------------------
28 .\" * MAIN CONTENT STARTS HERE *
29 .\" -----------------------------------------------------------------
30 .SH "NAME"
31 ne_set_server_auth, ne_set_proxy_auth, ne_forget_auth \- register authentication callbacks
32 .SH "SYNOPSIS"
33 .sp
34 .ft B
35 .nf
36 #include <ne_auth\&.h>
37 .fi
38 .ft
39 .HP \w'typedef\ int\ (*ne_auth_creds)('u
40 .BI "typedef int (*ne_auth_creds)(void\ *" "userdata" ", const\ char\ *" "realm" ", int\ " "attempt" ", char\ *" "username" ", char\ *" "password" ");"
41 .HP \w'void\ ne_set_server_auth('u
42 .BI "void ne_set_server_auth(ne_session\ *" "session" ", ne_auth_creds\ " "callback" ", void\ *" "userdata" ");"
43 .HP \w'void\ ne_set_proxy_auth('u
44 .BI "void ne_set_proxy_auth(ne_session\ *" "session" ", ne_auth_creds\ " "callback" ", void\ *" "userdata" ");"
45 .HP \w'void\ ne_forget_auth('u
46 .BI "void ne_forget_auth(ne_session\ *" "session" ");"
47 .SH "DESCRIPTION"
48 .PP
49 The
50 \fBne_auth_creds\fR
51 function type defines a callback which is invoked when a server or proxy server requires user authentication for a particular request\&. The
52 \fIrealm\fR
53 string is supplied by the server\&.
54 The
55 \fIattempt\fR
56 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,
57 \fIattempt\fR
58 will be zero\&.
59 .PP
60 To retry the request using new authentication credentials, the callback should return zero, and the
61 \fIusername\fR
62 and
63 \fIpassword\fR
64 buffers must contain
65 NUL\-terminated strings\&. The
66 NE_ABUFSIZ
67 constant gives the size of these buffers\&.
68 .if n \{\
69 .sp
70 .\}
71 .RS 4
72 .it 1 an-trap
73 .nr an-no-space-flag 1
74 .nr an-break-flag 1
75 .br
76 .ps +1
77 \fBTip\fR
78 .ps -1
79 .br
80 .PP
81 If you only wish to allow the user one attempt to enter credentials, use the value of the
82 \fIattempt\fR
83 parameter as the return value of the callback\&.
84 .sp .5v
85 .RE
86 .PP
87 To abort the request, the callback should return a non\-zero value; in which case the contents of the
88 \fIusername\fR
89 and
90 \fIpassword\fR
91 buffers are ignored\&.
92 .PP
93 The
94 \fBne_forget_auth\fR
95 function can be used to discard the cached authentication credentials\&.
96 .SH "EXAMPLES"
97 .sp
98 .if n \{\
99 .RS 4
100 .\}
101 .nf
102 /* Function which prompts for a line of user input: */
103 extern char *prompt_for(const char *prompt);
104
105 static int
106 my_auth(void *userdata, const char *realm, int attempts,
107 char *username, char *password)
108 {
109 strncpy(username, prompt_for("Username: "), NE_ABUFSIZ);
110 strncpy(password, prompt_for("Password: "), NE_ABUFSIZ);
111 return attempts;
112 }
113
114 int main(\&.\&.\&.)
115 {
116 ne_session *sess = ne_session_create(\&.\&.\&.);
117
118 ne_set_server_auth(sess, my_auth, NULL);
119
120 /* \&.\&.\&. */
121 }
122 .fi
123 .if n \{\
124 .RE
125 .\}
126 .SH "AUTHOR"
127 .PP
128 \fBJoe Orton\fR <\&[email protected]\&>
129 .RS 4
130 Author.
131 .RE
132 .SH "COPYRIGHT"
133 .br