src/mn-client-session.h (7605B) - raw
1 /*
2 * Mail Notification
3 * Copyright (C) 2003-2008 Jean-Yves Lefort <jylefort@brutele.be>
4 *
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 3 of the License, or
8 * (at your option) any later version.
9 *
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
14 *
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
18 */
19
20 #ifndef _MN_CLIENT_SESSION_H
21 #define _MN_CLIENT_SESSION_H
22
23 #include <glib.h>
24 #if WITH_SASL
25 #include <sasl/sasl.h>
26 #endif
27
28 typedef struct _MNClientSession MNClientSession;
29 typedef struct _MNClientSessionPrivate MNClientSessionPrivate;
30 typedef struct _MNClientSessionResponse MNClientSessionResponse;
31
32 #define MN_CLIENT_SESSION_ERROR (mn_client_session_error_quark())
33
34 typedef enum
35 {
36 MN_CLIENT_SESSION_ERROR_OTHER,
37 MN_CLIENT_SESSION_ERROR_CONNECTION_LOST
38 } MNClientSessionError;
39
40 enum
41 {
42 /* read the next input line */
43 MN_CLIENT_SESSION_RESULT_CONTINUE = -1,
44 /* signal an uncompliant response and disconnect */
45 MN_CLIENT_SESSION_RESULT_BAD_RESPONSE_FOR_CONTEXT = -2,
46 /* disconnect */
47 MN_CLIENT_SESSION_RESULT_DISCONNECT = -3
48 };
49
50 /*
51 * In all the session callbacks below, @session is the session which
52 * is being run, and @private is the opaque data pointer which was
53 * passed to mn_client_session_run().
54 */
55
56 typedef struct
57 {
58 /*
59 * The state ID, which must be a positive non-zero integer.
60 */
61 unsigned int id;
62
63 /*
64 * enter_cb (optional):
65 *
66 * Enters the state. If set to %NULL, does nothing and returns
67 * %MN_CLIENT_SESSION_RESULT_CONTINUE.
68 *
69 * Return value: must return a state ID to switch to, or one of the
70 * MN_CLIENT_SESSION_RESULT_ codes above
71 */
72 int (*enter_cb) (MNClientSession *session,
73 MNClientSessionPrivate *private);
74
75 /*
76 * handle_cb (required):
77 * @response: the #MNClientSessionResponse returned by the response_new()
78 * callback.
79 *
80 * Handles a response received while the state is active.
81 *
82 * Return value: must return a state ID to switch to, or one of the
83 * MN_CLIENT_SESSION_RESULT_ codes above
84 */
85 int (*handle_cb) (MNClientSession *session,
86 MNClientSessionResponse *response,
87 MNClientSessionPrivate *private);
88 } MNClientSessionState;
89
90 /* the state to enter after connecting */
91 #define MN_CLIENT_SESSION_INITIAL_STATE 1
92 /* the MNClientSessionState array canary */
93 #define MN_CLIENT_SESSION_STATES_END { 0, NULL, NULL }
94
95 typedef struct
96 {
97 /*
98 * notice (optional):
99 * @message: the notice message
100 *
101 * Handles a notice.
102 */
103 void (*notice) (MNClientSession *session,
104 const char *message,
105 MNClientSessionPrivate *private);
106
107 /*
108 * warning (optional):
109 * @message: the warning message
110 *
111 * Handles a warning.
112 */
113 void (*warning) (MNClientSession *session,
114 const char *message,
115 MNClientSessionPrivate *private);
116
117 /*
118 * response_new (required):
119 * @input: an input line received from the server
120 *
121 * Parses server input.
122 *
123 * Return value: must return an opaque data pointer on success, or
124 * %NULL on failure
125 */
126 MNClientSessionResponse *(*response_new) (MNClientSession *session,
127 const char *input,
128 MNClientSessionPrivate *private);
129
130 /*
131 * response_free (optional):
132 * @response: a response that was returned by response_new()
133 *
134 * Releases all the memory associated with @response.
135 */
136 void (*response_free) (MNClientSession *session,
137 MNClientSessionResponse *response,
138 MNClientSessionPrivate *private);
139
140 /*
141 * pre_read (optional):
142 *
143 * Called before calling read() or one of its variants.
144 */
145 void (*pre_read) (MNClientSession *session,
146 MNClientSessionPrivate *private);
147
148 /*
149 * post_read (optional):
150 *
151 * Called after calling read() or one of its variants.
152 */
153 void (*post_read) (MNClientSession *session,
154 MNClientSessionPrivate *private);
155
156 #if WITH_SASL
157 /*
158 * sasl_get_credentials (required if
159 * mn_client_session_sasl_authentication_start() is needed, optional
160 * otherwise):
161 * @username: a pointer to store the username, or %NULL
162 * @password: a pointer to store the password, or %NULL
163 *
164 * Fills in the requested credentials.
165 *
166 * Return value: must return %TRUE in case of success, or %FALSE if
167 * a requested credential cannot be provided (in such case, the SASL
168 * authentication exchange will be aborted)
169 */
170 gboolean (*sasl_get_credentials) (MNClientSession *session,
171 MNClientSessionPrivate *priv,
172 const char **username,
173 const char **password);
174 #endif /* WITH_SASL */
175
176 #if WITH_SSL
177 /*
178 * ssl_trust_server (required if SSL support was compiled in):
179 *
180 * Decides whether to trust the given server after SSL verification
181 * failed. If the server provided a certificate, the @fingerprint
182 * and @verify_error arguments will be set.
183 *
184 * Return value: must return %TRUE if the given server should be trusted.
185 */
186 gboolean (*ssl_trust_server) (MNClientSession *session,
187 const char *server,
188 int port,
189 const char *fingerprint,
190 const char *verify_error,
191 MNClientSessionPrivate *priv);
192 #endif /* WITH_SSL */
193 } MNClientSessionCallbacks;
194
195 gboolean mn_client_session_run (const MNClientSessionState *states,
196 const MNClientSessionCallbacks *callbacks,
197 #if WITH_SSL
198 gboolean use_ssl,
199 #endif
200 const char *hostname,
201 int port,
202 MNClientSessionPrivate *private,
203 GError **err);
204
205 gconstpointer mn_client_session_read (MNClientSession *session, unsigned int nbytes);
206 const char *mn_client_session_read_line (MNClientSession *session);
207
208 int mn_client_session_write (MNClientSession *session,
209 const char *format,
210 ...) G_GNUC_PRINTF(2, 3);
211
212 #if WITH_SSL
213 gboolean mn_client_session_enable_ssl (MNClientSession *session);
214 #endif
215
216 #if WITH_SASL
217 gboolean mn_client_session_sasl_authentication_start (MNClientSession *session,
218 const char *service,
219 GSList *mechanisms,
220 const char *forced_mechanism,
221 const char **used_mechanism,
222 const char **initial_clientout,
223 unsigned int *initial_clientoutlen);
224 int mn_client_session_sasl_authentication_step (MNClientSession *session,
225 const char *input);
226 gboolean mn_client_session_sasl_authentication_done (MNClientSession *session);
227
228 void mn_client_session_sasl_dispose (MNClientSession *session);
229 sasl_ssf_t mn_client_session_sasl_get_ssf (MNClientSession *session);
230 #endif /* WITH_SASL */
231
232 void mn_client_session_notice (MNClientSession *session,
233 const char *format,
234 ...) G_GNUC_PRINTF(2, 3);
235 void mn_client_session_warning (MNClientSession *session,
236 const char *format,
237 ...) G_GNUC_PRINTF(2, 3);
238
239 int mn_client_session_set_error (MNClientSession *session,
240 int code,
241 const char *format,
242 ...) G_GNUC_PRINTF(3, 4);
243 int mn_client_session_set_error_from_response (MNClientSession *session,
244 int code,
245 const char *response);
246
247 GQuark mn_client_session_error_quark (void);
248
249 #endif /* _MN_CLIENT_SESSION_H */