Fix modest_tny_msg_header_get_all_recipients_list (in case from is empty)
[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
66
67 struct _ModestAccountProtocol {
68         ModestProtocol parent;
69 };
70
71 struct _ModestAccountProtocolClass {
72         ModestProtocolClass parent_class;
73
74         /* Virtual methods */
75         TnyAccount * (*create_account) (ModestAccountProtocol *self);
76         ModestAccountSettingsDialog* (*create_account_settings_dialog) (ModestAccountProtocol* self);
77         ModestPairList* (*get_easysetupwizard_tabs) (ModestAccountProtocol* self);
78         ModestWizardDialogResponseOverrideFunc (*get_wizard_response_override) (ModestAccountProtocol *self);
79         void (*save_settings) (ModestAccountProtocol *self, ModestAccountSettingsDialog *dialog, ModestAccountSettings *settings);
80         void (*save_wizard_settings) (ModestAccountProtocol *self, GList *wizard_pages, ModestAccountSettings *settings);
81         gboolean (*is_supported) (ModestAccountProtocol *self);
82         void (*check_support) (ModestAccountProtocol *self, ModestAccountProtocolCheckSupportFunc func, gpointer userdata);
83         gchar * (*get_from) (ModestAccountProtocol *self, const gchar *account_id, const gchar *mailbox);
84         ModestPairList * (*get_from_list) (ModestAccountProtocol *self, const gchar *account_id);
85         gchar * (*get_signature) (ModestAccountProtocol *self, const gchar *account_id, const gchar *mailbox, gboolean *has_signature);
86         const GdkPixbuf * (*get_icon) (ModestAccountProtocol *self, ModestAccountProtocolIconType icon_type, 
87                                        GObject *object, guint icon_size);
88         gchar * (*get_service_name) (ModestAccountProtocol *self, const gchar *account_id, const gchar *mailbox);
89         const GdkPixbuf * (*get_service_icon) (ModestAccountProtocol *self, const gchar *account_id, const gchar *mailbox, guint icon_size);
90
91         /* Padding for future expansions */
92         void (*_reserved3) (void);
93         void (*_reserved4) (void);
94         void (*_reserved5) (void);
95         void (*_reserved6) (void);
96         void (*_reserved7) (void);
97         void (*_reserved8) (void);
98         void (*_reserved9) (void);
99         void (*_reserved10) (void);
100         void (*_reserved11) (void);
101         void (*_reserved12) (void);
102         void (*_reserved13) (void);
103         void (*_reserved14) (void);
104         void (*_reserved15) (void);
105         void (*_reserved16) (void);
106 };
107
108 /**
109  * modest_account_protocol_get_type:
110  *
111  * Returns: GType of the account protocol type
112  */
113 GType  modest_account_protocol_get_type   (void) G_GNUC_CONST;
114
115 /**
116  * modest_account_protocol_new:
117  *
118  * creates a new instance of #ModestAccountProtocol
119  *
120  * Returns: a #ModestAccountProtocol
121  */
122 ModestProtocol*    modest_account_protocol_new (const gchar *name, const gchar *display_name, 
123                                                 guint port, guint alternate_port,
124                                                 GType account_g_type);
125
126 /**
127  * modest_account_protocol_get_port:
128  * @self: a #ModestAccountProtocol
129  *
130  * get the protocol standard port
131  *
132  * Returns: a string
133  */
134 guint modest_account_protocol_get_port (ModestAccountProtocol *self);
135
136 /**
137  * modest_account_protocol_set_port:
138  * @self: a #ModestAccountProtocol
139  * @port: a #guint
140  *
141  * set @port as the protocol standard port
142  */
143 void         modest_account_protocol_set_port (ModestAccountProtocol *self,
144                                                guint port);
145
146 /**
147  * modest_account_protocol_get_alternate_port:
148  * @self: a #ModestAccountProtocol
149  *
150  * get the protocol standard alternate_port
151  *
152  * Returns: a #guint
153  */
154 guint modest_account_protocol_get_alternate_port (ModestAccountProtocol *self);
155
156 /**
157  * modest_account_protocol_set_alternate_port:
158  * @self: a #ModestAccountProtocol
159  * @alternate_port: a #guint
160  *
161  * set @alternate_port as the protocol alternate port
162  */
163 void         modest_account_protocol_set_alternate_port (ModestAccountProtocol *self,
164                                                          guint alternate_port);
165
166 /**
167  * modest_account_protocol_set_account_options:
168  * @self: a #ModestAccountProtocol
169  * @account_options: a #TnyList of account options and their values
170  *
171  * set the account options that will be passed to TnyCamelAccount for this protocol.
172  * This replaces previous option lists for this protocol
173  */
174 void modest_account_protocol_set_account_options (ModestAccountProtocol *self,
175                                                   TnyList *account_options);
176
177 /**
178  * modest_account_protocol_get_account_options:
179  * @self: a #ModestAccountProtocol
180  *
181  * obtain the account options for this account protocol.
182  *
183  * Returns: a caller-owner copy of the account options list.
184  */
185 TnyList *modest_account_protocol_get_account_options (ModestAccountProtocol *self);
186
187 /**
188  * modest_account_protocol_has_custom_secure_auth_mech:
189  * @self: a #ModestAccountProtocol
190  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
191  *
192  * checks whether there's a custom secure auth mech camel string for @auth_protocol_type.
193  *
194  * Returns: %TRUE if registered, %FALSE otherwise
195  */
196 gboolean
197 modest_account_protocol_has_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type);
198
199 /**
200  * modest_account_protocol_get_custom_secure_auth_mech:
201  * @self: a #ModestAccountProtocol
202  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
203  *
204  * obtains the secure auth mech of @auth_protocol_type in protocol. Be careful as %NULL does not imply
205  * there's no custom auth mech registered (you can register %NULL). To check if it's registered, just
206  * use modest_account_protocol_has_custom_secure_auth_mech().
207  *
208  * Returns: the secure auth mech for this auth protocol type that will be passed to camel.
209  */
210 const gchar *
211 modest_account_protocol_get_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type);
212
213 /**
214  * modest_account_protocol_unset_custom_secure_auth_mech:
215  * @self: a #ModestAccountProtocol
216  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
217  *
218  * Unsets the secure auth meth of @auth_protocol_type in protocol.
219  */
220 void
221 modest_account_protocol_unset_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type);
222
223 /**
224  * modest_account_protocol_set_custom_secure_auth_mech:
225  * @self: a #ModestAccountProtocol
226  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
227  * @secure_auth_mech: a string or %NULL
228  *
229  * sets the secure auth mech of @auth_protocol_type in protocol. Be careful as %NULL does not imply
230  * there's no custom auth mech registered (you can register %NULL). If you set %NULL you're regitering %NULL as the custom secure auth
231  * mechanism instead of unsetting it.
232  */
233 void
234 modest_account_protocol_set_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type, const gchar *secure_auth_mech);
235
236 /**
237  * modest_account_protocol_get_account_g_type:
238  * @self: a #ModestAccountProtocol
239  *
240  * get the protocol type used for factoring new TnyAccount
241  *
242  * Returns: a #GType
243  */
244 GType modest_account_protocol_get_account_g_type (ModestAccountProtocol *self);
245
246 /**
247  * modest_account_protocol_set_account_g_type:
248  * @self: a #ModestAccountProtocol
249  * @account_g_type: a #GType
250  *
251  * set @account_g_type as the type modest_account_protocol_create_account will
252  * instanciate
253  */
254 void         modest_account_protocol_set_account_g_type (ModestAccountProtocol *self,
255                                                          GType account_g_type);
256
257 /**
258  * modest_account_protocol_create_account:
259  * @self: a #ModestAccountProtocol
260  *
261  * create a new account instance for this protocol
262  *
263  * Returns: a #TnyAccount
264  */
265 TnyAccount * modest_account_protocol_create_account (ModestAccountProtocol *self);
266
267 /**
268  * modest_account_protocol_get_account_settings_dialog:
269  * @self: a #ModestAccountProtocol
270  * @account_name: the name of the account we're creating the dialog for
271  * 
272  * retrieves the account settings dialog used to setup the account
273  * represented by this protocol
274  * 
275  * Returns: a #ModestAccountSettingsDialog
276  **/
277 ModestAccountSettingsDialog* modest_account_protocol_get_account_settings_dialog (ModestAccountProtocol *self,
278                                                                                   const gchar *account_name);
279
280 ModestPairList* modest_account_protocol_get_easysetupwizard_tabs (ModestAccountProtocol *self);
281
282 /**
283  * modest_account_protocol_save_settings:
284  * @self: this #ModestAccountProtocol
285  * @dialog: a #ModestAccountSettingsDialog
286  * @settings: the #ModestAccountSettings
287  * 
288  * this function stores the values held by the account settings dialog
289  * in the account settings object that is passed as argument
290  *
291  * NOTE: this function provides a default implementation that calls
292  * the save_settings method of the acocunt settings dialog. So if your
293  * implementation do not do anything more just do not redefine it
294  **/
295 void modest_account_protocol_save_settings (ModestAccountProtocol *self, 
296                                             ModestAccountSettingsDialog *dialog,
297                                             ModestAccountSettings *settings);
298
299 /**
300  * modest_account_protocol_save_wizard_settings:
301  * @self: this #ModestAccountProtocol
302  * @wizard_pages: a list of #ModestEasysetupWizardPage
303  * @settings: the #ModestAccountSettings
304  * 
305  * this function stores the data input by the users in the wizard in
306  * the account settings object passed as argument
307  **/
308 void modest_account_protocol_save_wizard_settings (ModestAccountProtocol *self, 
309                                                    GList *wizard_pages,
310                                                    ModestAccountSettings *settings);
311
312 /**
313  * modest_account_protocol_get_wizard_response_override:
314  * @self: a #ModestAccountProtocol
315  *
316  * obtains the method that should be used to override wizard response behavior when the
317  * wizard is setting up this account type.
318  *
319  * Returns: a #ModestWizardDialogResponseOverrideFunc
320  */
321 ModestWizardDialogResponseOverrideFunc modest_account_protocol_get_wizard_response_override (ModestAccountProtocol *self);
322
323
324 /**
325  * modest_account_protocol_check_support:
326  * @self: a #ModestAccountProtocol
327  * @func: a #ModestAccountProtocolCheckSupportFunc
328  * @userdata: a gpointer
329  *
330  * This method checks asynchronously if the account protocol @self is
331  * supported. Once checked, @func will be called with the result in the
332  * mainloop.
333  *
334  * modest_account_protocol_is_supported() should return the cached response
335  * from this method.
336  */
337 void modest_account_protocol_check_support (ModestAccountProtocol *self, 
338                                             ModestAccountProtocolCheckSupportFunc func, 
339                                             gpointer userdata);
340 /**
341  * modest_account_protocol_is_supported:
342  * @self: a #ModestAccountProtocol
343  *
344  * Determines if the account protocol is supported on this device.
345  *
346  * Returns: %TRUE if the protocol is supported, %FALSE otherwise
347  */
348 gboolean modest_account_protocol_is_supported (ModestAccountProtocol *self);
349
350 /**
351  * modest_account_protocol_get_from:
352  * @self: a #ModestAccountProtocol
353  * @account_id: a transport account name
354  * @mailbox: a mailbox
355  *
356  * Obtain the From: string for the account and mailbox. Should be used only
357  * with transports with multi mailbox support.
358  *
359  * Returns: a newly allocated string
360  */
361 gchar *modest_account_protocol_get_from (ModestAccountProtocol *self,
362                                          const gchar *account_id,
363                                          const gchar *mailbox);
364
365 /**
366  * modest_account_protocol_get_from_list:
367  * @self: a #ModestAccountProtocol
368  * @account_id: a transport account name
369  *
370  * Obtain a list of pairs (mailbox - From: string) for filling the From picker.
371  *
372  * Returns: a ModestPairList
373  */
374 ModestPairList *modest_account_protocol_get_from_list (ModestAccountProtocol *self,
375                                                        const gchar *account_id);
376
377 /**
378  * modest_account_protocol_get_signature:
379  * @self: a #ModestAccountProtocol
380  * @account_id: a transport account name
381  * @mailbox: a mailbox
382  *
383  * Obtain the signature string for the account and mailbox. Should be used only
384  * with transports with multi mailbox support.
385  *
386  * Returns: a newly allocated string
387  */
388 gchar *modest_account_protocol_get_signature (ModestAccountProtocol *self,
389                                               const gchar *account_id,
390                                               const gchar *mailbox,
391                                               gboolean *has_signature);
392
393 /**
394  * modest_account_protocol_get_icon:
395  * @self: a #ModestAccountProtocl
396  * @icon_type: a #ModestAccountProtocolIconType
397  * @object: a #GObject
398  * @icon_size: the icon size to get
399  *
400  * Returns a @self owned #GdkPixbuf with the icon for @icon_type and @object. @object type
401  * should match @icon_type.
402  *
403  * Returns: a #GdkPixbuf (don't free or manipulate this, just copy)
404  */
405 const GdkPixbuf * modest_account_protocol_get_icon (ModestAccountProtocol *self, ModestAccountProtocolIconType icon_type, 
406                                                     GObject *object, guint icon_size);
407
408 /**
409  * modest_account_protocol_get_service_name:
410  * @self: a #ModestAccountProtocol
411  * @account_id: a transport account name
412  * @mailbox: a mailbox
413  *
414  * Obtain the service name string for the account and mailbox.
415  *
416  * Returns: a newly allocated string
417  */
418 gchar *modest_account_protocol_get_service_name (ModestAccountProtocol *self,
419                                                  const gchar *account_id,
420                                                  const gchar *mailbox);
421
422 /**
423  * modest_account_protocol_get_service_icon:
424  * @self: a #ModestAccountProtocol
425  * @account_id: a transport account name
426  * @mailbox: a mailbox
427  *
428  * Obtain the service icon for the account and mailbox.
429  *
430  * Returns: a protocol owned #GdkPixbuf
431  */
432 const GdkPixbuf *modest_account_protocol_get_service_icon (ModestAccountProtocol *self,
433                                                            const gchar *account_id,
434                                                            const gchar *mailbox,
435                                                            guint icon_size);
436
437
438 G_END_DECLS
439
440 #endif /* __MODEST_ACCOUNT_PROTOCOL_H__ */