Merge branch 'modest-3-0' into part-to-stream-in-plugins
[modest] / src / modest-account-protocol.h
1 /* Copyright (c) 2008, Nokia Corporation
2  * All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are
6  * met:
7  *
8  * * Redistributions of source code must retain the above copyright
9  *   notice, this list of conditions and the following disclaimer.
10  * * Redistributions in binary form must reproduce the above copyright
11  *   notice, this list of conditions and the following disclaimer in the
12  *   documentation and/or other materials provided with the distribution.
13  * * Neither the name of the Nokia Corporation nor the names of its
14  *   contributors may be used to endorse or promote products derived from
15  *   this software without specific prior written permission.
16  *
17  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
18  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
19  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
20  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
21  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
22  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
23  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
24  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
25  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
26  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
27  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
28  */
29
30
31 /* modest-account-settings.h */
32
33 #ifndef __MODEST_ACCOUNT_PROTOCOL_H__
34 #define __MODEST_ACCOUNT_PROTOCOL_H__
35
36 #include "widgets/modest-account-settings-dialog.h"
37 #include "modest-protocol.h"
38 #include "widgets/modest-wizard-dialog.h"
39 #include "modest-pair.h"
40 #include <tny-account.h>
41 #include <tny-list.h>
42
43 G_BEGIN_DECLS
44
45 /* convenience macros */
46 #define MODEST_TYPE_ACCOUNT_PROTOCOL             (modest_account_protocol_get_type())
47 #define MODEST_ACCOUNT_PROTOCOL(obj)             (G_TYPE_CHECK_INSTANCE_CAST((obj),MODEST_TYPE_ACCOUNT_PROTOCOL,ModestAccountProtocol))
48 #define MODEST_ACCOUNT_PROTOCOL_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST((klass),MODEST_TYPE_ACCOUNT_PROTOCOL,ModestAccountProtocolClass))
49 #define MODEST_IS_ACCOUNT_PROTOCOL(obj)          (G_TYPE_CHECK_INSTANCE_TYPE((obj),MODEST_TYPE_ACCOUNT_PROTOCOL))
50 #define MODEST_IS_ACCOUNT_PROTOCOL_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE((klass),MODEST_TYPE_ACCOUNT_PROTOCOL))
51 #define MODEST_ACCOUNT_PROTOCOL_GET_CLASS(obj)   (G_TYPE_INSTANCE_GET_CLASS((obj),MODEST_TYPE_ACCOUNT_PROTOCOL,ModestAccountProtocolClass))
52
53 typedef struct _ModestAccountProtocol      ModestAccountProtocol;
54 typedef struct _ModestAccountProtocolClass ModestAccountProtocolClass;
55
56 typedef enum {
57         MODEST_ACCOUNT_PROTOCOL_ICON_MAILBOX = 0,
58         MODEST_ACCOUNT_PROTOCOL_ICON_PROTOCOL,
59         MODEST_ACCOUNT_PROTOCOL_ICON_ACCOUNT,
60         MODEST_ACCOUNT_PROTOCOL_ICON_FOLDER,
61 } ModestAccountProtocolIconType;
62
63 typedef void (*ModestAccountProtocolCheckSupportFunc) (ModestAccountProtocol *self, 
64                                                        gboolean supported, gpointer userdata);
65 typedef void (*ModestAccountProtocolSaveRemoteDraftCallback) (ModestAccountProtocol *self,
66                                                               GError *error,
67                                                               const gchar *account_id,
68                                                               TnyMsg *new_remote_msg,
69                                                               TnyMsg *new_msg,
70                                                               TnyMsg *old_msg,
71                                                               gpointer userdata);
72
73
74 struct _ModestAccountProtocol {
75         ModestProtocol parent;
76 };
77
78 struct _ModestAccountProtocolClass {
79         ModestProtocolClass parent_class;
80
81         /* Virtual methods */
82         TnyAccount * (*create_account) (ModestAccountProtocol *self);
83         ModestAccountSettingsDialog* (*create_account_settings_dialog) (ModestAccountProtocol* self);
84         ModestPairList* (*get_easysetupwizard_tabs) (ModestAccountProtocol* self);
85         ModestWizardDialogResponseOverrideFunc (*get_wizard_response_override) (ModestAccountProtocol *self);
86         void (*save_settings) (ModestAccountProtocol *self, ModestAccountSettingsDialog *dialog, ModestAccountSettings *settings);
87         void (*save_wizard_settings) (ModestAccountProtocol *self, GList *wizard_pages, ModestAccountSettings *settings);
88         gboolean (*is_supported) (ModestAccountProtocol *self);
89         void (*check_support) (ModestAccountProtocol *self, ModestAccountProtocolCheckSupportFunc func, gpointer userdata);
90         gchar * (*get_from) (ModestAccountProtocol *self, const gchar *account_id, const gchar *mailbox);
91         ModestPairList * (*get_from_list) (ModestAccountProtocol *self, const gchar *account_id);
92         gchar * (*get_signature) (ModestAccountProtocol *self, const gchar *account_id, const gchar *mailbox, gboolean *has_signature);
93         const GdkPixbuf * (*get_icon) (ModestAccountProtocol *self, ModestAccountProtocolIconType icon_type, 
94                                        GObject *object, guint icon_size);
95         gchar * (*get_service_name) (ModestAccountProtocol *self, const gchar *account_id, const gchar *mailbox);
96         const GdkPixbuf * (*get_service_icon) (ModestAccountProtocol *self, const gchar *account_id, const gchar *mailbox, guint icon_size);
97         void (*save_remote_draft) (ModestAccountProtocol *self, 
98                                    const gchar *account_id, TnyMsg *new_msg, TnyMsg *old_msg,
99                                    ModestAccountProtocolSaveRemoteDraftCallback callback,
100                                    gpointer userdata);
101         void (*cancel_check_support) (ModestAccountProtocol *self);
102         void (*wizard_finished) (ModestAccountProtocol *self);
103         gboolean (*decode_part_to_stream) (ModestAccountProtocol *protocol,
104                                            TnyMimePart *part,
105                                            const gchar *stream_uri,
106                                            TnyStream *stream,
107                                            gssize *written,
108                                            GError **error);
109         gboolean (*decode_part_to_stream_async) (ModestAccountProtocol *protocol,
110                                                  TnyMimePart *part,
111                                                  const gchar *stream_uri,
112                                                  TnyStream *stream, 
113                                                  TnyMimePartCallback callback, 
114                                                  TnyStatusCallback status_callback, 
115                                                  gpointer user_data);
116
117         /* Padding for future expansions */
118         void (*_reserved8) (void);
119         void (*_reserved9) (void);
120         void (*_reserved10) (void);
121         void (*_reserved11) (void);
122         void (*_reserved12) (void);
123         void (*_reserved13) (void);
124         void (*_reserved14) (void);
125         void (*_reserved15) (void);
126         void (*_reserved16) (void);
127 };
128
129 /**
130  * modest_account_protocol_get_type:
131  *
132  * Returns: GType of the account protocol type
133  */
134 GType  modest_account_protocol_get_type   (void) G_GNUC_CONST;
135
136 /**
137  * modest_account_protocol_new:
138  *
139  * creates a new instance of #ModestAccountProtocol
140  *
141  * Returns: a #ModestAccountProtocol
142  */
143 ModestProtocol*    modest_account_protocol_new (const gchar *name, const gchar *display_name, 
144                                                 guint port, guint alternate_port,
145                                                 GType account_g_type);
146
147 /**
148  * modest_account_protocol_get_port:
149  * @self: a #ModestAccountProtocol
150  *
151  * get the protocol standard port
152  *
153  * Returns: a string
154  */
155 guint modest_account_protocol_get_port (ModestAccountProtocol *self);
156
157 /**
158  * modest_account_protocol_set_port:
159  * @self: a #ModestAccountProtocol
160  * @port: a #guint
161  *
162  * set @port as the protocol standard port
163  */
164 void         modest_account_protocol_set_port (ModestAccountProtocol *self,
165                                                guint port);
166
167 /**
168  * modest_account_protocol_get_alternate_port:
169  * @self: a #ModestAccountProtocol
170  *
171  * get the protocol standard alternate_port
172  *
173  * Returns: a #guint
174  */
175 guint modest_account_protocol_get_alternate_port (ModestAccountProtocol *self);
176
177 /**
178  * modest_account_protocol_set_alternate_port:
179  * @self: a #ModestAccountProtocol
180  * @alternate_port: a #guint
181  *
182  * set @alternate_port as the protocol alternate port
183  */
184 void         modest_account_protocol_set_alternate_port (ModestAccountProtocol *self,
185                                                          guint alternate_port);
186
187 /**
188  * modest_account_protocol_set_account_options:
189  * @self: a #ModestAccountProtocol
190  * @account_options: a #TnyList of account options and their values
191  *
192  * set the account options that will be passed to TnyCamelAccount for this protocol.
193  * This replaces previous option lists for this protocol
194  */
195 void modest_account_protocol_set_account_options (ModestAccountProtocol *self,
196                                                   TnyList *account_options);
197
198 /**
199  * modest_account_protocol_get_account_options:
200  * @self: a #ModestAccountProtocol
201  *
202  * obtain the account options for this account protocol.
203  *
204  * Returns: a caller-owner copy of the account options list.
205  */
206 TnyList *modest_account_protocol_get_account_options (ModestAccountProtocol *self);
207
208 /**
209  * modest_account_protocol_has_custom_secure_auth_mech:
210  * @self: a #ModestAccountProtocol
211  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
212  *
213  * checks whether there's a custom secure auth mech camel string for @auth_protocol_type.
214  *
215  * Returns: %TRUE if registered, %FALSE otherwise
216  */
217 gboolean
218 modest_account_protocol_has_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type);
219
220 /**
221  * modest_account_protocol_get_custom_secure_auth_mech:
222  * @self: a #ModestAccountProtocol
223  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
224  *
225  * obtains the secure auth mech of @auth_protocol_type in protocol. Be careful as %NULL does not imply
226  * there's no custom auth mech registered (you can register %NULL). To check if it's registered, just
227  * use modest_account_protocol_has_custom_secure_auth_mech().
228  *
229  * Returns: the secure auth mech for this auth protocol type that will be passed to camel.
230  */
231 const gchar *
232 modest_account_protocol_get_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type);
233
234 /**
235  * modest_account_protocol_unset_custom_secure_auth_mech:
236  * @self: a #ModestAccountProtocol
237  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
238  *
239  * Unsets the secure auth meth of @auth_protocol_type in protocol.
240  */
241 void
242 modest_account_protocol_unset_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type);
243
244 /**
245  * modest_account_protocol_set_custom_secure_auth_mech:
246  * @self: a #ModestAccountProtocol
247  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
248  * @secure_auth_mech: a string or %NULL
249  *
250  * sets the secure auth mech of @auth_protocol_type in protocol. Be careful as %NULL does not imply
251  * there's no custom auth mech registered (you can register %NULL). If you set %NULL you're regitering %NULL as the custom secure auth
252  * mechanism instead of unsetting it.
253  */
254 void
255 modest_account_protocol_set_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type, const gchar *secure_auth_mech);
256
257 /**
258  * modest_account_protocol_get_account_g_type:
259  * @self: a #ModestAccountProtocol
260  *
261  * get the protocol type used for factoring new TnyAccount
262  *
263  * Returns: a #GType
264  */
265 GType modest_account_protocol_get_account_g_type (ModestAccountProtocol *self);
266
267 /**
268  * modest_account_protocol_set_account_g_type:
269  * @self: a #ModestAccountProtocol
270  * @account_g_type: a #GType
271  *
272  * set @account_g_type as the type modest_account_protocol_create_account will
273  * instanciate
274  */
275 void         modest_account_protocol_set_account_g_type (ModestAccountProtocol *self,
276                                                          GType account_g_type);
277
278 /**
279  * modest_account_protocol_create_account:
280  * @self: a #ModestAccountProtocol
281  *
282  * create a new account instance for this protocol
283  *
284  * Returns: a #TnyAccount
285  */
286 TnyAccount * modest_account_protocol_create_account (ModestAccountProtocol *self);
287
288 /**
289  * modest_account_protocol_get_account_settings_dialog:
290  * @self: a #ModestAccountProtocol
291  * @account_name: the name of the account we're creating the dialog for
292  * 
293  * retrieves the account settings dialog used to setup the account
294  * represented by this protocol
295  * 
296  * Returns: a #ModestAccountSettingsDialog
297  **/
298 ModestAccountSettingsDialog* modest_account_protocol_get_account_settings_dialog (ModestAccountProtocol *self,
299                                                                                   const gchar *account_name);
300
301 ModestPairList* modest_account_protocol_get_easysetupwizard_tabs (ModestAccountProtocol *self);
302
303 /**
304  * modest_account_protocol_save_settings:
305  * @self: this #ModestAccountProtocol
306  * @dialog: a #ModestAccountSettingsDialog
307  * @settings: the #ModestAccountSettings
308  * 
309  * this function stores the values held by the account settings dialog
310  * in the account settings object that is passed as argument
311  *
312  * NOTE: this function provides a default implementation that calls
313  * the save_settings method of the acocunt settings dialog. So if your
314  * implementation do not do anything more just do not redefine it
315  **/
316 void modest_account_protocol_save_settings (ModestAccountProtocol *self, 
317                                             ModestAccountSettingsDialog *dialog,
318                                             ModestAccountSettings *settings);
319
320 /**
321  * modest_account_protocol_save_wizard_settings:
322  * @self: this #ModestAccountProtocol
323  * @wizard_pages: a list of #ModestEasysetupWizardPage
324  * @settings: the #ModestAccountSettings
325  * 
326  * this function stores the data input by the users in the wizard in
327  * the account settings object passed as argument
328  **/
329 void modest_account_protocol_save_wizard_settings (ModestAccountProtocol *self, 
330                                                    GList *wizard_pages,
331                                                    ModestAccountSettings *settings);
332
333 /**
334  * modest_account_protocol_get_wizard_response_override:
335  * @self: a #ModestAccountProtocol
336  *
337  * obtains the method that should be used to override wizard response behavior when the
338  * wizard is setting up this account type.
339  *
340  * Returns: a #ModestWizardDialogResponseOverrideFunc
341  */
342 ModestWizardDialogResponseOverrideFunc modest_account_protocol_get_wizard_response_override (ModestAccountProtocol *self);
343
344
345 /**
346  * modest_account_protocol_check_support:
347  * @self: a #ModestAccountProtocol
348  * @func: a #ModestAccountProtocolCheckSupportFunc
349  * @userdata: a gpointer
350  *
351  * This method checks asynchronously if the account protocol @self is
352  * supported. Once checked, @func will be called with the result in the
353  * mainloop.
354  *
355  * modest_account_protocol_is_supported() should return the cached response
356  * from this method.
357  */
358 void modest_account_protocol_check_support (ModestAccountProtocol *self, 
359                                             ModestAccountProtocolCheckSupportFunc func, 
360                                             gpointer userdata);
361
362 /**
363  * modest_account_protocol_cancel_check_support:
364  * @self: a #ModestAccountProtocol
365  *
366  * This method requests that the check support requests running should be
367  * immediately cancelled. Once this happens, is_supported should return %FALSE
368  * until a new succesful check_support request is finished.
369  */
370 void modest_account_protocol_cancel_check_support (ModestAccountProtocol *self);
371
372 /**
373  * modest_account_protocol_wizard_finished:
374  * @self: a #ModestAccountProtocol
375  *
376  * Method that let protocol know if the wizard has finished, for the case it's
377  * needed to do some stuff after check_support.
378  */
379 void modest_account_protocol_wizard_finished (ModestAccountProtocol *self);
380
381 /**
382  * modest_account_protocol_is_supported:
383  * @self: a #ModestAccountProtocol
384  *
385  * Determines if the account protocol is supported on this device.
386  *
387  * Returns: %TRUE if the protocol is supported, %FALSE otherwise
388  */
389 gboolean modest_account_protocol_is_supported (ModestAccountProtocol *self);
390
391 /**
392  * modest_account_protocol_get_from:
393  * @self: a #ModestAccountProtocol
394  * @account_id: a transport account name
395  * @mailbox: a mailbox
396  *
397  * Obtain the From: string for the account and mailbox. Should be used only
398  * with transports with multi mailbox support.
399  *
400  * Returns: a newly allocated string
401  */
402 gchar *modest_account_protocol_get_from (ModestAccountProtocol *self,
403                                          const gchar *account_id,
404                                          const gchar *mailbox);
405
406 /**
407  * modest_account_protocol_get_from_list:
408  * @self: a #ModestAccountProtocol
409  * @account_id: a transport account name
410  *
411  * Obtain a list of pairs (mailbox - From: string) for filling the From picker.
412  *
413  * Returns: a ModestPairList
414  */
415 ModestPairList *modest_account_protocol_get_from_list (ModestAccountProtocol *self,
416                                                        const gchar *account_id);
417
418 /**
419  * modest_account_protocol_get_signature:
420  * @self: a #ModestAccountProtocol
421  * @account_id: a transport account name
422  * @mailbox: a mailbox
423  *
424  * Obtain the signature string for the account and mailbox. Should be used only
425  * with transports with multi mailbox support.
426  *
427  * Returns: a newly allocated string
428  */
429 gchar *modest_account_protocol_get_signature (ModestAccountProtocol *self,
430                                               const gchar *account_id,
431                                               const gchar *mailbox,
432                                               gboolean *has_signature);
433
434 /**
435  * modest_account_protocol_get_icon:
436  * @self: a #ModestAccountProtocl
437  * @icon_type: a #ModestAccountProtocolIconType
438  * @object: a #GObject
439  * @icon_size: the icon size to get
440  *
441  * Returns a @self owned #GdkPixbuf with the icon for @icon_type and @object. @object type
442  * should match @icon_type.
443  *
444  * Returns: a #GdkPixbuf (don't free or manipulate this, just copy)
445  */
446 const GdkPixbuf * modest_account_protocol_get_icon (ModestAccountProtocol *self, ModestAccountProtocolIconType icon_type, 
447                                                     GObject *object, guint icon_size);
448
449 /**
450  * modest_account_protocol_get_service_name:
451  * @self: a #ModestAccountProtocol
452  * @account_id: a transport account name
453  * @mailbox: a mailbox
454  *
455  * Obtain the service name string for the account and mailbox.
456  *
457  * Returns: a newly allocated string
458  */
459 gchar *modest_account_protocol_get_service_name (ModestAccountProtocol *self,
460                                                  const gchar *account_id,
461                                                  const gchar *mailbox);
462
463 /**
464  * modest_account_protocol_get_service_icon:
465  * @self: a #ModestAccountProtocol
466  * @account_id: a transport account name
467  * @mailbox: a mailbox
468  *
469  * Obtain the service icon for the account and mailbox.
470  *
471  * Returns: a protocol owned #GdkPixbuf
472  */
473 const GdkPixbuf *modest_account_protocol_get_service_icon (ModestAccountProtocol *self,
474                                                            const gchar *account_id,
475                                                            const gchar *mailbox,
476                                                            guint icon_size);
477
478 /**
479  * modest_account_protocol_save_remote_draft:
480  * @self: a #ModestAccountProtocol
481  * @account_id: a transport account_name
482  * @new_msg: the newly created message in local storage.
483  * @old_msg: the old message
484  * @callback: the code that should be executed on finishing the remote message saving
485  * @userdata: a #gpointer
486  *
487  * Saves the just-saved to local draft, into a remote storage.
488  */
489 void modest_account_protocol_save_remote_draft (ModestAccountProtocol *self,
490                                                     const gchar *account_id,
491                                                     TnyMsg *new_msg,
492                                                     TnyMsg *old_msg,
493                                                     ModestAccountProtocolSaveRemoteDraftCallback callback,
494                                                     gpointer userdata);
495
496 /**
497  * modest_account_protocol_decode_part_to_stream:
498  * @self: a #ModestAccountProtocol
499  * @part: a #TnyMimePart
500  * @stream_uri: a string
501  * @stream: a #TnyStream
502  * @written: a #gssize pointer, with the number of bytes written
503  * @error: a #GError
504  *
505  * This virtual method delegates on the account protocol to decode @part
506  * into @stream. It just allows the provider to decode it as it needs
507  * (i.e. when the original message has a fake attachment, and provider
508  * can return the real attachment).
509  *
510  * The @stream_uri parameter tells the uri of the resource @stream is
511  * wrapping (if known).
512  *
513  * Returns: %TRUE if @protocol does the decode operation, %FALSE if modest
514  * should do it.
515  */
516 gboolean
517 modest_account_protocol_decode_part_to_stream (ModestAccountProtocol *protocol,
518                                                TnyMimePart *part,
519                                                const gchar *stream_uri,
520                                                TnyStream *stream,
521                                                gssize *written,
522                                                GError **error);
523
524 /**
525  * modest_account_protocol_decode_part_to_stream_async:
526  * @self: a #ModestAccountProtocol
527  * @part: a #TnyMimePart
528  * @stream_uri: a string
529  * @stream: a #TnyStream
530  *
531  * This virtual method delegates on the account protocol to decode @part
532  * into @stream, but asynchronously.
533  *
534  * The @stream_uri parameter tells the uri of the resource @stream is
535  * wrapping (if known).
536  *
537  * Returns: %TRUE if @protocol does the decode operation (then we shouldn't expect
538  * callback to happen from this call, %FALSE if modest should do it.
539  */
540 gboolean modest_account_protocol_decode_part_to_stream_async (ModestAccountProtocol *self,
541                                                               TnyMimePart *part, 
542                                                               const gchar *stream_uri,
543                                                               TnyStream *stream, 
544                                                               TnyMimePartCallback callback, 
545                                                               TnyStatusCallback status_callback, 
546                                                               gpointer user_data);
547
548
549 G_END_DECLS
550
551 #endif /* __MODEST_ACCOUNT_PROTOCOL_H__ */