git.maemo.org Git - modest/blob - 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_yes_no_dialog:
 215  * @parent_window: the parent #GtkWindow of the dialog
 216  * @message: the message to show to the user
 217  *
 218  * runs a dialog that offers yes and no buttons.
 219  *
 220  * Returns: GTK_RESPONSE_YES or GTK_RESPONSE_NO
 221  **/
 222 gint      modest_platform_run_yes_no_dialog      (GtkWindow *parent_window,
 223                                                   const gchar *message);
 224
 225
 226 /**
 227  * modest_platform_run_information_dialog:
 228  * @parent_window: the parent #GtkWindow of the dialog
 229  * @message: the message to show
 230  * @block: whether or not the dialog should block the main loop or not while running
 231  *
 232  * shows an information dialog
 233  **/
 234 void      modest_platform_run_information_dialog       (GtkWindow *parent_window,
 235                                                         const gchar *message,
 236                                                         gboolean block);
 237
 238 /**
 239  * modest_platform_create_sort_dialog:
 240  * @parent_window: the parent #GtkWindow of the dialog
 241  *
 242  * creates a proper sort dialog for the platform
 243  *
 244  * Returns: a #GtkDialog implementing #ModestSortCriteriumView interface
 245  **/
 246 GtkWidget *modest_platform_create_sort_dialog       (GtkWindow *parent_window);
 247
 248 /*
 249  * modest_platform_connect_and_wait:
 250  * @parent_window: the parent #GtkWindow for any interactive or progress feedback UI.
 251  * @account: The account to be used.
 252  * @return value: Whether a connection was made.
 253  *
 254  * Attempts to make a connection, possibly showing interactive UI to achieve this.
 255  * This will return TRUE immediately if a connection is already open.
 256  * Otherwise, this function blocks until the connection attempt has either succeded or failed.
 257  * This also sets the account to online, if it is a store account, in case it has been set to offline mode.
 258  */
 259 gboolean modest_platform_connect_and_wait (GtkWindow *parent_window, TnyAccount *account);
 260
 261
 262 /*
 263  * modest_platform_connect_and_wait_if_network_account:
 264  * @parent_window: the parent #GtkWindow for any interactive or progress feedback UI.
 265  * @account: The account that might need a connection in subsequent operations.
 266  * @return value: Whether a connection was made. Also returns TRUE if no connection is necessary.
 267  *
 268  * Like modest_platform_connect_and_wait(), but only attempts to make a connection if the
 269  * account uses the network. For instance, this just returns TRUE for local maildir accounts.
 270  */
 271 gboolean modest_platform_connect_and_wait_if_network_account (GtkWindow *parent_window, TnyAccount *account);
 272
 273 /*
 274  * modest_platform_connect_and_wait_if_network_account:
 275  * @parent_window: the parent #GtkWindow for any interactive or progress feedback UI.
 276  * @folder_store: The folder store (folder or account) that might need a connection in subsequent operations.
 277  * @return value: Whether a connection was made. Also returns TRUE if no connection is necessary.
 278  *
 279  * Like modest_platform_connect_and_wait(), but only attempts to make a connection if the
 280  * folder store uses the network. For instance, this just returns TRUE for local maildir folders.
 281  */
 282 gboolean modest_platform_connect_and_wait_if_network_folderstore (GtkWindow *parent_window, TnyFolderStore *folder_store);
 283
 284 /**
 285  * modest_platform_set_update_interval:
 286  * @minutes: The number of minutes between updates, or 0 for no updates.
 287  *
 288  * Set the number of minutes between automatic updates of email accounts.
 289  * The platform will cause the send/receive action to happen repeatedly.
 290  **/
 291 gboolean modest_platform_set_update_interval (guint minutes);
 292
 293 /**
 294  * modest_platform_get_global_settings_dialog:
 295  * @void:
 296  *
 297  * returns the global settings dialog
 298  *
 299  * Return value: a new #ModestGlobalSettingsDialog dialog
 300  **/
 301 GtkWidget* modest_platform_get_global_settings_dialog (void);
 302
 303 /**
 304  * modest_platform_push_email_notification:
 305  *
 306  * Notify the user when new e-mail arrives by playing a sound, making
 307  * a light blink, etc.
 308  */
 309 void modest_platform_push_email_notification(void);
 310
 311 /**
 312  * modest_platform_on_new_headers_received:
 313  * @header_list: the list of new received headers
 314  * @show_visual: adds a visual notification
 315  *
 316  * Performs the required actions when new headers are
 317  * received. Tipically it's useful for showing new email notifications
 318  **/
 319 void modest_platform_on_new_headers_received (TnyList *header_list,
 320                                               gboolean show_visual);
 321
 322 /**
 323  * modest_platform_show_help:
 324  * @parent_window:
 325  * @help_id: the help topic id to be shown in the help dialog
 326  *
 327  * shows the application help dialog
 328  **/
 329 void modest_platform_show_help (GtkWindow *parent_window,
 330                                 const gchar *help_id);
 331
 332 /**
 333  * modest_platform_show_search_messages:
 334  * @parent_window: window the dialog will be child of
 335  *
 336  * shows the search messages dialog
 337  **/
 338 void modest_platform_show_search_messages (GtkWindow *parent_window);
 339
 340 /**
 341  * modest_platform_show_addressbook:
 342  * @parent_window: window the dialog will be child of
 343  *
 344  * shows the addressbook
 345  **/
 346 void modest_platform_show_addressbook (GtkWindow *parent_window);
 347
 348
 349 GtkWidget* modest_platform_create_folder_view (TnyFolderStoreQuery *query);
 350
 351 void modest_platform_information_banner (GtkWidget *widget,
 352                                          const gchar *icon_name,
 353                                          const gchar *text);
 354
 355 /* Timeout is in miliseconds */
 356 void modest_platform_information_banner_with_timeout (GtkWidget *parent,
 357                                                       const gchar *icon_name,
 358                                                       const gchar *text,
 359                                                       gint timeout);
 360
 361 GtkWidget *
 362 modest_platform_animation_banner (GtkWidget *parent,
 363                                   const gchar *annimation_name,
 364                                   const gchar *text);
 365
 366 /* TODO: This isn't platform-dependent, so this isn't the best place for this. */
 367 /* Return TRUE immediately if the account is already online,
 368  * otherwise check every second for NUMBER_OF_TRIES seconds and return TRUE as
 369  * soon as the account is online, or FALSE if the account does
 370  * not become online in the NUMBER_OF_TRIES seconds.
 371  * This is useful when the D-Bus method was run immediately after
 372  * the application was started (when using D-Bus activation),
 373  * because the account usually takes a short time to go online.
 374  * The return value is maybe not very useful.
 375  */
 376 gboolean modest_platform_check_and_wait_for_account_is_online(TnyAccount *account);
 377
 378
 379
 380 /**
 381  * modest_platform_run_certificate_confirmation_dialog:
 382  * @server_name: name of the server we get this dialog for
 383  * @certificate: the text representation of the certificate
 384  *
 385  * show the unknown-certificate confirmation dialog
 386  *
 387  *  Returns: TRUE (Ok-pressed) or FALSE (cancel pressed)
 388  **/
 389 gboolean modest_platform_run_certificate_confirmation_dialog (const gchar* server_name,
 390                                                               const gchar *certificate);
 391
 392
 393 /**
 394  * modest_platform_run_alert_dialog:
 395  * @prompt: prompt for the dialog
 396  * @is_question: is it a question dialog?
 397  *
 398  * show the alert dialog for TnyAlerts
 399  * if it's a aquest
 400  *
 401  *  Returns: TRUE (Ok-pressed) or FALSE (cancel pressed)
 402  **/
 403 gboolean modest_platform_run_alert_dialog (const gchar* prompt, gboolean is_question);
 404
 405
 406 /**
 407  * modest_platform_remove_new_mail_notifications:
 408  * @only_visuals: remove only the visual notifications (like LEDs)
 409  *
 410  * Removes all the active new mail notifications
 411  **/
 412 void modest_platform_remove_new_mail_notifications (gboolean only_visuals);
 413
 414 /* ModestConnectedPerformer:
 415  * @canceled: whether or not the user canceled
 416  * @err: whether an error occured during connecting, or NULL of not
 417  * @parent_window: the parent window or NULL
 418  * @account: the account or NULL
 419  * @user_data: your own user data
 420  *
 421  * This is the callback for the modest_platform_connect_and_perform* functions
 422  */
 423 typedef void (*ModestConnectedPerformer) (gboolean canceled,
 424                                           GError *err,
 425                                           GtkWindow *parent_window,
 426                                           TnyAccount *account,
 427                                           gpointer user_data);
 428
 429 typedef struct {
 430         TnyAccount *dst_account;
 431         ModestConnectedPerformer callback;
 432         gpointer data;
 433 } DoubleConnectionInfo;
 434
 435 /*
 436  * modest_platform_connect_and_perform:
 437  * @force: force the device to connect if we're offline, if FALSE then it does not connect if required
 438  * @parent_window: the parent #GtkWindow for any interactive or progress feedback UI.
 439  * @account: The account to be used.
 440  * @callback: will be called when finished, can be NULL
 441  * @user_data: user data for @callback
 442  *
 443  * Attempts to make a connection, possibly showing interactive UI to achieve this.
 444  * This will return immediately if a connection is already open, which results in an instant
 445  * call of @callback. While making a connection, @account, if not NULL, will go online too. If
 446  * @account is NULL, only a network connection is made using the platform's device.
 447  */
 448 void modest_platform_connect_and_perform (GtkWindow *parent_window,
 449                                           gboolean force,
 450                                           TnyAccount *account,
 451                                           ModestConnectedPerformer callback,
 452                                           gpointer user_data);
 453
 454 /*
 455  * modest_platform_connect_if_remote_and_perform:
 456  * @parent_window: the parent #GtkWindow for any interactive or progress feedback UI.
 457  * @folder_store: The folder store (folder or account) that might need a connection in subsequent operations.
 458  * @callback: will be called when finished, can be NULL
 459  * @user_data: user data for @callback
 460  *
 461  * Like modest_platform_connect_and_perform(), but only attempts to make a connection if the
 462  * folder store uses the network. For instance, this just returns for local maildir folders. It
 463  * will in that case synchronously and instantly perform the @callback
 464  */
 465 void modest_platform_connect_if_remote_and_perform (GtkWindow *parent_window,
 466                                                     gboolean force,
 467                                                     TnyFolderStore *folder_store,
 468                                                     ModestConnectedPerformer callback,
 469                                                     gpointer user_data);
 470
 471 /*
 472  * modest_platform_double_connect_and_perform:
 473  * @parent_window: the parent #GtkWindow for any interactive or progress feedback UI.
 474  * @folder_store: The folder store (folder or account) that might need a connection in subsequent operations.
 475  * @callback: will be called when finished, can be NULL
 476  * @info:
 477  *
 478  */
 479 void modest_platform_double_connect_and_perform (GtkWindow *parent_window,
 480                                                  gboolean force,
 481                                                  TnyFolderStore *folder_store,
 482                                                  DoubleConnectionInfo *info);
 483
 484 /**
 485  * modest_platform_get_account_settings_dialog:
 486  * @settings: a #ModestAccountSettings
 487  *
 488  * creates a dialog for editing @settings
 489  *
 490  * Returns: the newly created dialog.
 491  */
 492 GtkWidget *modest_platform_get_account_settings_dialog (ModestAccountSettings *settings);
 493
 494 /**
 495  * modest_platform_get_account_settings_wizard:
 496  * @settings: a #ModestAccountSettings
 497  *
 498  * creates a dialog for editing @settings
 499  *
 500  * Returns: the newly created dialog.
 501  */
 502 GtkWidget *modest_platform_get_account_settings_wizard (void);
 503
 504 ModestConnectedVia modest_platform_get_current_connection (void);
 505
 506
 507
 508
 509 /**
 510  * modest_platform_check_memory_low:
 511  *
 512  * @win: a ModestWindow, or NULL
 513  * @visuals: whether or not show visual information
 514  *
 515  * see if memory is too low for big memory consuming operations
 516  * optionally show a warning dialog if @win was provided
 517  *
 518  * Returns: TRUE if we're in lowmem state, FALSE otherwise
 519  */
 520 gboolean modest_platform_check_memory_low (ModestWindow *win,
 521                                            gboolean visuals);
 522
 523
 524 G_END_DECLS
 525
 526 #endif /* __MODEST_PLATFORM_UTILS_H__ */
 527