* Fixes NB#91689. fixes a wrong check for ASCII
[modest] / src / modest-platform.h
1 /* Copyright (c) 2006, 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 #ifndef __MODEST_PLATFORM_H__
31 #define __MODEST_PLATFORM_H__
32
33 #include <tny-device.h>
34 #include "widgets/modest-window.h"
35 #include "widgets/modest-folder-view.h"
36 #include "widgets/modest-sort-criterium-view.h"
37
38 G_BEGIN_DECLS
39
40 typedef enum _ModestConfirmationDialogType {
41         MODEST_CONFIRMATION_DELETE_FOLDER,
42 } ModestConfirmationDialogType;
43
44 typedef enum _ModestConnectedVia {
45         MODEST_CONNECTED_VIA_WLAN_OR_WIMAX = 1,
46         MODEST_CONNECTED_VIA_ANY,
47 } ModestConnectedVia;
48
49 /**
50  * modest_platform_platform_init:
51  *
52  * platform specific initialization function
53  * 
54  * Returns: TRUE if succeeded, FALSE otherwise
55  */
56 gboolean modest_platform_init (int argc, char *argv[]);
57
58
59 /**
60  * modest_platform_platform_init:
61  *
62  * platform specific un-initialization function
63  * 
64  * Returns: TRUE if succeeded, FALSE otherwise
65  */
66 gboolean modest_platform_uninit (void);
67
68
69 /**
70  * modest_platform_get_new_device:
71  *
72  * platform specific initialization function
73  * 
74  * Returns: TRUE if succeeded, FALSE otherwise
75  */
76 TnyDevice*  modest_platform_get_new_device (void);
77
78
79 /**
80  * modest_platform_get_file_icon_name:
81  * @name: the name of the file, or NULL
82  * @mime_type: the mime-type, or NULL
83  * @effective_mime_type: out-param which receives the 'effective mime-type', ie., the mime type
84  * that will be used. May be NULL if you're not interested in this. Note: the returned string
85  * is newly allocated, and should be g_free'd when done with it.
86  *
87  * this function gets the icon for the file, based on the file name and/or the mime type,
88  * using the following strategy:
89  * (1) if mime_type != NULL and mime_type != application/octet-stream, find the
90  *     the icon name for this mime type
91  * (2) otherwise, guess the icon type from the file name, and then goto (1)
92  *
93  * Returns: the icon name
94  */
95 gchar*  modest_platform_get_file_icon_name (const gchar* name, const gchar* mime_type,
96                                             gchar **effective_mime_type);
97
98 /**
99  * modest_platform_activate_uri:
100  * @uri: the uri to activate
101  *
102  * This function activates an URI
103  *
104  * Returns: %TRUE if successful, %FALSE if not.
105  **/
106 gboolean modest_platform_activate_uri (const gchar *uri);
107
108 /**
109  * modest_platform_activate_file:
110  * @path: the path to activate
111  * @mime_type: the mime type of the path, or %NULL to guess
112  *
113  * This function activates a file
114  *
115  * Returns: %TRUE if successful, %FALSE if not.
116  **/
117 gboolean modest_platform_activate_file (const gchar *path, const gchar *mime_type);
118
119 /**
120  * modest_platform_show_uri_popup:
121  * @uri: an URI with the string
122  *
123  * This function show the popup of actions for an URI
124  *
125  * Returns: %TRUE if successful, %FALSE if not.
126  **/
127 gboolean modest_platform_show_uri_popup (const gchar *uri);
128
129 /**
130  * modest_platform_get_icon:
131  * @name: the name of the icon
132  * @size: the icon size, use MODEST_ICON_SMALL or MODEST_ICON_BIG
133  *
134  * this function returns an icon, or NULL in case of error 
135  */
136 GdkPixbuf* modest_platform_get_icon (const gchar *name, guint icon_size);
137
138
139 /**
140  * modest_platform_get_app_name:
141  *
142  * this function returns the name of the application. Do not modify.
143  */
144 const gchar* modest_platform_get_app_name (void);
145
146
147 /**
148  * modest_platform_run_new_folder_dialog:
149  * @parent_window: a #GtkWindow
150  * @parent: the parent of the new folder
151  * @suggested_name: the suggested name for the new folder
152  * @folder_name: the folder name selected by the user for the new folder
153  * 
154  * runs a "new folder" confirmation dialog. The dialog will suggest a
155  * folder name which depends of the platform if the #suggested_name
156  * parametter is NULL. If the user input a valid folder name it's
157  * returned in the #folder_name attribute.
158  * 
159  * Returns: the #GtkResponseType returned by the dialog
160  **/
161 gint      modest_platform_run_new_folder_dialog        (GtkWindow *parent_window,
162                                                         TnyFolderStore *parent,
163                                                         gchar *suggested_name,
164                                                         gchar **folder_name);
165
166 /**
167  * modest_platform_run_rename_folder_dialog:
168  * @parent_window: a #GtkWindow
169  * @parent: the parent of the folder
170  * @suggested_name: current name of the folder
171  * @folder_name: the new folder name selected by the user for the folder
172  * 
173  * runs a "rename folder" confirmation dialog. If the user input a valid folder name it's
174  * returned in the #folder_name attribute.
175  * 
176  * Returns: the #GtkResponseType returned by the dialog
177  **/
178 gint      modest_platform_run_rename_folder_dialog        (GtkWindow *parent_window,
179                                                            TnyFolderStore *parent,
180                                                            const gchar *current_name,
181                                                            gchar **folder_name);
182
183 /**
184  * modest_platform_run_confirmation_dialog:
185  * @parent_window: the parent #GtkWindow of the dialog
186  * @message: the message to show to the user
187  * 
188  * runs a confirmation dialog
189  * 
190  * Returns: GTK_RESPONSE_OK or GTK_RESPONSE_CANCEL
191  **/
192 gint      modest_platform_run_confirmation_dialog      (GtkWindow *parent_window,
193                                                         const gchar *message);
194
195
196 /**
197  * modest_platform_run_confirmation_dialog_with_buttons:
198  * @parent_window: the parent #GtkWindow of the dialog
199  * @message: the message to show to the user
200  * @button_accept: the text to show in the label of the accept button
201  * @button_cancel: the text to show in the label of the cancel button
202  * 
203  * runs a confirmation dialog with the given values for the buttons
204  * 
205  * Returns: GTK_RESPONSE_OK or GTK_RESPONSE_CANCEL
206  **/
207 gint
208 modest_platform_run_confirmation_dialog_with_buttons (GtkWindow *parent_window,
209                                                       const gchar *message,
210                                                       const gchar *button_accept,
211                                                       const gchar *button_cancel);
212
213 /**
214  * modest_platform_run_information_dialog:
215  * @parent_window: the parent #GtkWindow of the dialog
216  * @message: the message to show
217  * @block: whether or not the dialog should block the main loop or not while running
218  * 
219  * shows an information dialog
220  **/
221 void      modest_platform_run_information_dialog       (GtkWindow *parent_window,
222                                                         const gchar *message,
223                                                         gboolean block);
224
225 /**
226  * modest_platform_create_sort_dialog:
227  * @parent_window: the parent #GtkWindow of the dialog
228  * 
229  * creates a proper sort dialog for the platform
230  *
231  * Returns: a #GtkDialog implementing #ModestSortCriteriumView interface
232  **/
233 GtkWidget *modest_platform_create_sort_dialog       (GtkWindow *parent_window);
234                 
235 /*
236  * modest_platform_connect_and_wait:
237  * @parent_window: the parent #GtkWindow for any interactive or progress feedback UI.
238  * @account: The account to be used.
239  * @return value: Whether a connection was made.
240  * 
241  * Attempts to make a connection, possibly showing interactive UI to achieve this.
242  * This will return TRUE immediately if a connection is already open.
243  * Otherwise, this function blocks until the connection attempt has either succeded or failed.
244  * This also sets the account to online, if it is a store account, in case it has been set to offline mode.
245  */             
246 gboolean modest_platform_connect_and_wait (GtkWindow *parent_window, TnyAccount *account);
247
248                 
249 /*
250  * modest_platform_connect_and_wait_if_network_account:
251  * @parent_window: the parent #GtkWindow for any interactive or progress feedback UI.
252  * @account: The account that might need a connection in subsequent operations.
253  * @return value: Whether a connection was made. Also returns TRUE if no connection is necessary.
254  * 
255  * Like modest_platform_connect_and_wait(), but only attempts to make a connection if the 
256  * account uses the network. For instance, this just returns TRUE for local maildir accounts. 
257  */
258 gboolean modest_platform_connect_and_wait_if_network_account (GtkWindow *parent_window, TnyAccount *account);
259
260 /*
261  * modest_platform_connect_and_wait_if_network_account:
262  * @parent_window: the parent #GtkWindow for any interactive or progress feedback UI.
263  * @folder_store: The folder store (folder or account) that might need a connection in subsequent operations.
264  * @return value: Whether a connection was made. Also returns TRUE if no connection is necessary.
265  * 
266  * Like modest_platform_connect_and_wait(), but only attempts to make a connection if the 
267  * folder store uses the network. For instance, this just returns TRUE for local maildir folders. 
268  */
269 gboolean modest_platform_connect_and_wait_if_network_folderstore (GtkWindow *parent_window, TnyFolderStore *folder_store);
270
271 /**
272  * modest_platform_set_update_interval:
273  * @minutes: The number of minutes between updates, or 0 for no updates.
274  * 
275  * Set the number of minutes between automatic updates of email accounts.
276  * The platform will cause the send/receive action to happen repeatedly.
277  **/
278 gboolean modest_platform_set_update_interval (guint minutes);
279
280 /**
281  * modest_platform_get_global_settings_dialog:
282  * @void: 
283  * 
284  * returns the global settings dialog
285  * 
286  * Return value: a new #ModestGlobalSettingsDialog dialog
287  **/
288 GtkWidget* modest_platform_get_global_settings_dialog (void);
289
290 /**
291  * modest_platform_push_email_notification:
292  *
293  * Notify the user when new e-mail arrives by playing a sound, making
294  * a light blink, etc.
295  */
296 void modest_platform_push_email_notification(void);
297
298 /**
299  * modest_platform_on_new_headers_received:
300  * @header_list: the list of new received headers
301  * @show_visual: adds a visual notification 
302  *
303  * Performs the required actions when new headers are
304  * received. Tipically it's useful for showing new email notifications
305  **/
306 void modest_platform_on_new_headers_received (TnyList *header_list,
307                                               gboolean show_visual);
308
309 /**
310  * modest_platform_show_help:
311  * @parent_window: 
312  * @help_id: the help topic id to be shown in the help dialog
313  * 
314  * shows the application help dialog
315  **/
316 void modest_platform_show_help (GtkWindow *parent_window, 
317                                 const gchar *help_id);
318
319 /**
320  * modest_platform_show_search_messages:
321  * @parent_window: window the dialog will be child of
322  *
323  * shows the search messages dialog
324  **/
325 void modest_platform_show_search_messages (GtkWindow *parent_window);
326
327 /**
328  * modest_platform_show_addressbook:
329  * @parent_window: window the dialog will be child of
330  *
331  * shows the addressbook
332  **/
333 void modest_platform_show_addressbook (GtkWindow *parent_window);
334
335
336 GtkWidget* modest_platform_create_folder_view (TnyFolderStoreQuery *query);
337
338 void modest_platform_information_banner (GtkWidget *widget,
339                                          const gchar *icon_name,
340                                          const gchar *text);
341
342 /* Timeout is in miliseconds */
343 void modest_platform_information_banner_with_timeout (GtkWidget *parent,
344                                                       const gchar *icon_name,
345                                                       const gchar *text,
346                                                       gint timeout);
347
348 GtkWidget *
349 modest_platform_animation_banner (GtkWidget *parent,
350                                   const gchar *annimation_name,
351                                   const gchar *text);
352                                   
353 /* TODO: This isn't platform-dependent, so this isn't the best place for this. */
354 /* Return TRUE immediately if the account is already online,
355  * otherwise check every second for NUMBER_OF_TRIES seconds and return TRUE as 
356  * soon as the account is online, or FALSE if the account does 
357  * not become online in the NUMBER_OF_TRIES seconds.
358  * This is useful when the D-Bus method was run immediately after 
359  * the application was started (when using D-Bus activation), 
360  * because the account usually takes a short time to go online.
361  * The return value is maybe not very useful.
362  */
363 gboolean modest_platform_check_and_wait_for_account_is_online(TnyAccount *account);
364
365
366
367 /**
368  * modest_platform_run_certificate_confirmation_dialog:
369  * @server_name: name of the server we get this dialog for
370  * @certificate: the text representation of the certificate
371  *
372  * show the unknown-certificate confirmation dialog
373  *
374  *  Returns: TRUE (Ok-pressed) or FALSE (cancel pressed)
375  **/
376 gboolean modest_platform_run_certificate_confirmation_dialog (const gchar* server_name,
377                                                               const gchar *certificate);
378
379
380 /**
381  * modest_platform_run_alert_dialog:
382  * @prompt: prompt for the dialog
383  * @is_question: is it a question dialog? 
384  *
385  * show the alert dialog for TnyAlerts
386  * if it's a aquest
387  *
388  *  Returns: TRUE (Ok-pressed) or FALSE (cancel pressed)
389  **/
390 gboolean modest_platform_run_alert_dialog (const gchar* prompt, gboolean is_question);
391
392
393 /**
394  * modest_platform_remove_new_mail_notifications:
395  * @only_visuals: remove only the visual notifications (like LEDs)
396  *
397  * Removes all the active new mail notifications
398  **/
399 void modest_platform_remove_new_mail_notifications (gboolean only_visuals);
400
401 /* ModestConnectedPerformer:
402  * @canceled: whether or not the user canceled
403  * @err: whether an error occured during connecting, or NULL of not
404  * @parent_window: the parent window or NULL
405  * @account: the account or NULL
406  * @user_data: your own user data
407  * 
408  * This is the callback for the modest_platform_connect_and_perform* functions
409  */
410 typedef void (*ModestConnectedPerformer) (gboolean canceled, 
411                                           GError *err,
412                                           GtkWindow *parent_window, 
413                                           TnyAccount *account, 
414                                           gpointer user_data);
415
416 typedef struct {
417         TnyAccount *dst_account;
418         ModestConnectedPerformer callback;
419         gpointer data;
420 } DoubleConnectionInfo;
421
422 /*
423  * modest_platform_connect_and_perform:
424  * @force: force the device to connect if we're offline, if FALSE then it does not connect if required
425  * @parent_window: the parent #GtkWindow for any interactive or progress feedback UI.
426  * @account: The account to be used.
427  * @callback: will be called when finished, can be NULL
428  * @user_data: user data for @callback
429  * 
430  * Attempts to make a connection, possibly showing interactive UI to achieve this.
431  * This will return immediately if a connection is already open, which results in an instant
432  * call of @callback. While making a connection, @account, if not NULL, will go online too. If
433  * @account is NULL, only a network connection is made using the platform's device.
434  */             
435 void modest_platform_connect_and_perform (GtkWindow *parent_window, 
436                                           gboolean force,
437                                           TnyAccount *account, 
438                                           ModestConnectedPerformer callback, 
439                                           gpointer user_data);
440                 
441 /*
442  * modest_platform_connect_if_remote_and_perform:
443  * @parent_window: the parent #GtkWindow for any interactive or progress feedback UI.
444  * @folder_store: The folder store (folder or account) that might need a connection in subsequent operations.
445  * @callback: will be called when finished, can be NULL
446  * @user_data: user data for @callback
447  * 
448  * Like modest_platform_connect_and_perform(), but only attempts to make a connection if the 
449  * folder store uses the network. For instance, this just returns for local maildir folders. It
450  * will in that case synchronously and instantly perform the @callback
451  */
452 void modest_platform_connect_if_remote_and_perform (GtkWindow *parent_window, 
453                                                     gboolean force,
454                                                     TnyFolderStore *folder_store,
455                                                     ModestConnectedPerformer callback, 
456                                                     gpointer user_data);
457
458 /*
459  * modest_platform_double_connect_and_perform:
460  * @parent_window: the parent #GtkWindow for any interactive or progress feedback UI.
461  * @folder_store: The folder store (folder or account) that might need a connection in subsequent operations.
462  * @callback: will be called when finished, can be NULL
463  * @info: 
464  * 
465  */
466 void modest_platform_double_connect_and_perform (GtkWindow *parent_window, 
467                                                  gboolean force,
468                                                  TnyFolderStore *folder_store,
469                                                  DoubleConnectionInfo *info);
470
471 /**
472  * modest_platform_get_account_settings_wizard:
473  * @settings: a #ModestAccountSettings
474  *
475  * creates a dialog for editing @settings
476  *
477  * Returns: the newly created dialog.
478  */
479 GtkWidget *modest_platform_get_account_settings_wizard (void);
480
481 ModestConnectedVia modest_platform_get_current_connection (void);
482
483
484
485
486 /**
487  * modest_platform_check_memory_low:
488  * 
489  * @win: a ModestWindow, or NULL
490  * @visuals: whether or not show visual information
491  *
492  * see if memory is too low for big memory consuming operations
493  * optionally show a warning dialog if @win was provided
494  *
495  * Returns: TRUE if we're in lowmem state, FALSE otherwise
496  */
497 gboolean modest_platform_check_memory_low (ModestWindow *win,
498                                            gboolean visuals);
499
500
501 /**
502  * modest_platform_run_folder_details_dialog:
503  * @parent_window: the parent #GtkWindow for the new dialog
504  * @folder: the #TnyFolder whose details will be shown
505  * 
506  * Shows the folder details dialog
507  **/
508 void     modest_platform_run_folder_details_dialog (GtkWindow *parent_window,
509                                                     TnyFolder *folder);
510
511 /**
512  * modest_platform_run_header_details_dialog:
513  * @parent_window: the parent #GtkWindow for the new dialog
514  * @header: the #TnyHeader whose details will be shown
515  * 
516  * Shows the header details dialog
517  **/
518 void     modest_platform_run_header_details_dialog (GtkWindow *parent_window,
519                                                     TnyHeader *header);
520
521
522 G_END_DECLS
523
524 #endif /* __MODEST_PLATFORM_UTILS_H__ */
525