Debian Codegraph @

doc/html/_sources/imap/developer/libraries/imclient.rst.txt

raw
1 .. cyrusman:: imclient(3)
2
3 .. author: Nic Bernstein (Onlight)
4
5 .. _imap-admin-commands-imclient-library:
6
7 ====================
8 **imclient** library
9 ====================
10
11 Authenticating callback interface to IMAP servers
12
13 Synopsis
14 ========
15
16 .. parsed-literal::
17
18 #include <cyrus/imclient.h>
19
20 **int imclient_connect(struct imclient \*\***\ *imclient* **, const char \***\ *host* **,
21 const char \***\ *port*\ **);**
22
23 **void imclient_close (struct imclient \***\ *imclient*\ **);**
24 **void imclient_setflags(struct imclient \***\ *imclient* **, int** *flags*\ **);**
25 **void imclient_clearflags (struct imclient \***\ *imclient* **, int** *flags*\ **);**
26 **char\* imclient_servername (struct imclient \***\ *imclient*\ **);**
27 **void imclient_addcallback (struct imclient \***\ *imclient*\ ,...\ **);**
28 **void imclient_send (struct imclient \***\ *imclient*\ **, void (\***\ *finishproc*\ **)(),
29 void \***\ *finishrock*\ **, const char \***\ *fmt*\ ,...\ **);**
30 **void imclient_getselectinfo (struct imclient \***\ *imclient*\ **, int \*** *fd*\ **,
31 int \*** *wanttowrite*\ **);**
32 **void imclient_processoneevent (struct imclient \***\ *imclient*\ **);**
33 **int imclient_authenticate (struct imclient \***\ *imclient*\ **,
34 struct sasl_client \*\***\ *availmech*\ **, const char \***\ *service*\ **,
35 const char \***\ *user*\ **, int** *protallowed*\ **);**
36 **int imclient_havetls ();**
37 **int imclient_starttls (struct imclient \***\ *imclient*\ **, char \***\ *cert_file*\ **,
38 char \***\ *key_file*\ **, char \***\ *CAfile*\ **, char \***\ *CApath*\ **);**
39
40
41 Description
42 ===========
43
44 The imclient library functions are distributed with Cyrus IMAP.
45 These functions are used for building IMAP client software. These
46 functions handle Kerberos authentication and can set callbacks based on the
47 keyword in untagged replies or based on the command tag at the end of
48 command replies.
49
50 Users must link with the -lcyrus switch, and must supply a function
51 called *fatal* to be called in case of any error within *libcyrus.la*\ .
52
53 All of the **imclient** functions begin with the prefix *imclient* and
54 take an argument of type **struct imclient \*** as the first argument
55 which is initialized by **imclient_connect** and freed by
56 **imclient_close**\ .
57
58 See below for a description of each function.
59
60 **imclient_connect()**
61 Connects the client server to the host. If successful, it returns
62 0 and sets the imclient argument to a pointer to an **imclient**
63 struct. The **imclient** struct represents the current connection,
64 flags, and callbacks. On failure, the current **errno** is returned
65 if a system call failed, -1 is returned if the host name was not
66 found, and -2 is returned if the service name was not found.
67
68 **imclient_close()**
69 Closes and frees the **imclient** connection.
70
71 **imclient_setflags()**
72 Sets the flags specified by the *flags* argument on the **imclient**
73 connection. Currently the only flag allowed is
74 **IMCLIENT_CONN_NONSYNCLITERAL** (this flag indicates that the
75 server supports non-synchronizing literals described by the LITERAL+
76 extension).
77
78 **imclient_clearflags()**
79 Clears the flags specified by the *flags* argument on the
80 **imclient** connection.
81
82 **imclient_servername()**
83 Returns a char * pointer to the name of the server connected to
84 by **imclient**.
85
86 **imclient_addcallback()**
87 Adds an untagged data callback to the **imclient** connection. The
88 function **imclient_addcallback** takes callbacks of the type
89 **imclient_proc_t** which is defined to be:
90
91 ::
92
93 typedef void imclient_proc_t (struct imclient *imclient, void *rock, struct imclient_reply *reply);
94
95 and **struct imclient_reply \***
96 is defined to be:
97
98 ::
99
100 struct imclient_reply {
101 char *keyword;
102 long msgno;
103 char *text;
104 };
105
106 After the first argument, *imclient*, there can be zero or more
107 instances of the set of *keyword*, *flags*, *proc*, and *rock*,
108 each adding or changing a single callback. Each instance adds or
109 changes the callback for *keyword*. The argument *flags* specifies
110 information about the parsing of the untagged data. *proc* and
111 *rock* specify the callback function and rock to invoke when the
112 untagged data is received. *proc* may be a null pointer, in which
113 case no function is invoked. The callback function may not call
114 the functions **imclient_close(), imclient_send(), imclient_eof(),
115 imclient_processoneevent()**, or **imclient_authenticate()** on the
116 connection. The callback function may overwrite the text of
117 untagged data.
118
119 **imclient_send()**
120 Sends a new command to the **imclient** connection. *finishproc*
121 and *finishrock* are the function and rock called when the command
122 completes. *functionproc* may be a null pointer, in which case no
123 callback is made. The callback function may not call the functions
124 **imclient_close(), imclient_send(), imclient_eof(),
125 imclient_processoneevent()**, or **imclient_authenticate()** on the
126 connection. The argument *fmt* is a :manpage:`printf(3)` like
127 specification of the command. It must not include the tag as the
128 tag is automatically added by **imclient_send()**.
129
130 The defined %-sequences are:
131
132 ::
133
134 %% for %
135 %a for an IMAP atom
136 %s for an astring (which will be quoted or literalized as needed)
137 %d for a decimal
138 %u for an unsigned decimal
139 %v for #astring (argument is a null-terminated array of char *
140 which are written as space separated astrings)
141
142 **imclient_getselectinfo()**
143 Gets the information for calling :manpage:`select(2)`. *fd* is
144 filled in with the file descriptor to :manpage:`select(2)` for read.
145 *wanttowrite* is filled in with a nonzero value if **select** should
146 be used for write as well.
147
148 **imclient_processoneevent()**
149 Processes one input or output event on the **imclient** connection.
150
151 **imclient_authenticate()**
152 Authenticates the **imclient** connection using one of the mechanisms
153 in *availmech*. The argument *user*, if not NULL, specifies the user
154 to authenticate as. If the user is NULL, the current user is used.
155 The argument *protallowed* is a bitmask of permissible protection
156 mechanisms.
157 On success, 0 is returned. On failure (i.e., "BAD" keyboard, or
158 no authentication mechanisms worked), 1 is returned. On extreme
159 failure (premature "OK"), 2 is returned.
160
161 **imclient_havetls()**
162 Returns a Boolean indicating whether the **imclient** library was
163 compiled with TLS (SSL) support. If so, **imclient_starttls()** may
164 be used to secure the IMAP connection.
165
166 **imclient_starttls()**
167 Issues a STARTTLS command on an existing IMAP connection and
168 negotiates the secure link. The *cert_file* and *key_file* arguments
169 specify the client certificate and secret key to use to
170 authenticate ourselves to the server. If client authentication is
171 not needed, set both of these arguments to NULL.
172
173 The *CAfile* and *CApath* arguments specify a file or directory,
174 respectively, of CA certificates for validating server
175 certificates. (See :manpage:`SSL_CTX_load_verify_locations(3)` for
176 details.) If both of these are NULL, the client will be unable to
177 validate the server's certificate, in which case the connection may
178 succeed but a warning will be printed to stdout.
179
180 Examples
181 ========
182
183 The following code is a possible skeleton of **imclient** that relies
184 on Kerberos to do authentication. This code performs an IMAP
185 CAPABILITY request and prints out the result.
186
187 ::
188
189 #include <cyrus/xmalloc.h> /* example uses xstrdup */
190 #include <cyrus/sasl.h>
191 #include <cyrus/imclient.h>
192 #include <stdio.h>
193
194 extern struct sasl_client krb_sasl_client;
195
196 struct sasl_client *login_sasl_client[] = {
197 &krb_sasl_client,
198 NULL
199 };
200 struct imclient *imclient;
201 char server[] = "cyrus.andrew.cmu.edu" ;
202 char port[] = "imap";
203
204 void fatal(char* message, int rc) {
205 fprintf(stderr, "fatal error: %s\en", message);
206 exit(rc);
207 }
208
209 static void callback_capability(struct imclient *imclient,
210 void *rock,
211 struct imclient_reply *reply) {
212 if (reply->text != NULL) {
213 *((char**)rock) = xstrdup( reply->text );
214 }
215 }
216
217 static void end_command(struct imclient *connection, void*
218 rock, struct imclient_reply *inmsg) {
219 (*(int*)rock)--;
220 }
221
222 main() {
223 char* capability_string;
224 int nc;
225
226 if (imclient_connect(&imclient, server, port)) {
227 fprintf(stderr,
228 "error: Couldn't connect to %s %s\en",
229 server, port);
230 exit(1);
231 }
232
233 if (imclient_authenticate(imclient, login_sasl_client, "imap"
234 /* service */,
235 NULL /* user */, SASL_PROT_ANY)) {
236 exit(1);
237 }
238
239 imclient_addcallback(imclient, "CAPABILITY",
240 CALLBACK_NOLITERAL,
241 callback_capability,
242 &capability_string,
243 NULL);
244
245 nc = 1;
246
247 imclient_send(imclient, end_command,
248 (void*) &nc, "CAPABILITY");
249
250 while(nc > 0) {
251 imclient_processoneevent(imclient);
252 }
253
254 if (strstr("LITERAL+", capability_string)) {
255 imclient_setflags(imclient, IMCLIENT_CONN_NONSYNCLITERAL);
256 }
257
258 imclient_send(imclient, NULL, NULL, "LOGOUT");
259 imclient_close(imclient);
260
261 printf("capability text is: %s\en", capability_string);
262
263 free(capability_string);
264 }
265
266 Bugs
267 ====
268
269 No known bugs.
270
271 See Also
272 ========
273
274 :cyrusman:`cyradm(8)`,
275 :cyrusman:`imapd(8)`,
276 :rfc:`2033` (IMAP LITERAL+ extension),
277 :rfc:`2060` (IMAP4rev1 specification), and
278 :manpage:`select(2)`
279
280 Keywords
281 ========
282
283 IMAP, ACAP, Kerberos, Authentication