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