git.maemo.org Git - modest/blob - 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
 104         /* Padding for future expansions */
 105         void (*_reserved6) (void);
 106         void (*_reserved7) (void);
 107         void (*_reserved8) (void);
 108         void (*_reserved9) (void);
 109         void (*_reserved10) (void);
 110         void (*_reserved11) (void);
 111         void (*_reserved12) (void);
 112         void (*_reserved13) (void);
 113         void (*_reserved14) (void);
 114         void (*_reserved15) (void);
 115         void (*_reserved16) (void);
 116 };
 117
 118 /**
 119  * modest_account_protocol_get_type:
 120  *
 121  * Returns: GType of the account protocol type
 122  */
 123 GType  modest_account_protocol_get_type   (void) G_GNUC_CONST;
 124
 125 /**
 126  * modest_account_protocol_new:
 127  *
 128  * creates a new instance of #ModestAccountProtocol
 129  *
 130  * Returns: a #ModestAccountProtocol
 131  */
 132 ModestProtocol*    modest_account_protocol_new (const gchar *name, const gchar *display_name,
 133                                                 guint port, guint alternate_port,
 134                                                 GType account_g_type);
 135
 136 /**
 137  * modest_account_protocol_get_port:
 138  * @self: a #ModestAccountProtocol
 139  *
 140  * get the protocol standard port
 141  *
 142  * Returns: a string
 143  */
 144 guint modest_account_protocol_get_port (ModestAccountProtocol *self);
 145
 146 /**
 147  * modest_account_protocol_set_port:
 148  * @self: a #ModestAccountProtocol
 149  * @port: a #guint
 150  *
 151  * set @port as the protocol standard port
 152  */
 153 void         modest_account_protocol_set_port (ModestAccountProtocol *self,
 154                                                guint port);
 155
 156 /**
 157  * modest_account_protocol_get_alternate_port:
 158  * @self: a #ModestAccountProtocol
 159  *
 160  * get the protocol standard alternate_port
 161  *
 162  * Returns: a #guint
 163  */
 164 guint modest_account_protocol_get_alternate_port (ModestAccountProtocol *self);
 165
 166 /**
 167  * modest_account_protocol_set_alternate_port:
 168  * @self: a #ModestAccountProtocol
 169  * @alternate_port: a #guint
 170  *
 171  * set @alternate_port as the protocol alternate port
 172  */
 173 void         modest_account_protocol_set_alternate_port (ModestAccountProtocol *self,
 174                                                          guint alternate_port);
 175
 176 /**
 177  * modest_account_protocol_set_account_options:
 178  * @self: a #ModestAccountProtocol
 179  * @account_options: a #TnyList of account options and their values
 180  *
 181  * set the account options that will be passed to TnyCamelAccount for this protocol.
 182  * This replaces previous option lists for this protocol
 183  */
 184 void modest_account_protocol_set_account_options (ModestAccountProtocol *self,
 185                                                   TnyList *account_options);
 186
 187 /**
 188  * modest_account_protocol_get_account_options:
 189  * @self: a #ModestAccountProtocol
 190  *
 191  * obtain the account options for this account protocol.
 192  *
 193  * Returns: a caller-owner copy of the account options list.
 194  */
 195 TnyList *modest_account_protocol_get_account_options (ModestAccountProtocol *self);
 196
 197 /**
 198  * modest_account_protocol_has_custom_secure_auth_mech:
 199  * @self: a #ModestAccountProtocol
 200  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
 201  *
 202  * checks whether there's a custom secure auth mech camel string for @auth_protocol_type.
 203  *
 204  * Returns: %TRUE if registered, %FALSE otherwise
 205  */
 206 gboolean
 207 modest_account_protocol_has_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type);
 208
 209 /**
 210  * modest_account_protocol_get_custom_secure_auth_mech:
 211  * @self: a #ModestAccountProtocol
 212  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
 213  *
 214  * obtains the secure auth mech of @auth_protocol_type in protocol. Be careful as %NULL does not imply
 215  * there's no custom auth mech registered (you can register %NULL). To check if it's registered, just
 216  * use modest_account_protocol_has_custom_secure_auth_mech().
 217  *
 218  * Returns: the secure auth mech for this auth protocol type that will be passed to camel.
 219  */
 220 const gchar *
 221 modest_account_protocol_get_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type);
 222
 223 /**
 224  * modest_account_protocol_unset_custom_secure_auth_mech:
 225  * @self: a #ModestAccountProtocol
 226  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
 227  *
 228  * Unsets the secure auth meth of @auth_protocol_type in protocol.
 229  */
 230 void
 231 modest_account_protocol_unset_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type);
 232
 233 /**
 234  * modest_account_protocol_set_custom_secure_auth_mech:
 235  * @self: a #ModestAccountProtocol
 236  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
 237  * @secure_auth_mech: a string or %NULL
 238  *
 239  * sets the secure auth mech of @auth_protocol_type in protocol. Be careful as %NULL does not imply
 240  * there's no custom auth mech registered (you can register %NULL). If you set %NULL you're regitering %NULL as the custom secure auth
 241  * mechanism instead of unsetting it.
 242  */
 243 void
 244 modest_account_protocol_set_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type, const gchar *secure_auth_mech);
 245
 246 /**
 247  * modest_account_protocol_get_account_g_type:
 248  * @self: a #ModestAccountProtocol
 249  *
 250  * get the protocol type used for factoring new TnyAccount
 251  *
 252  * Returns: a #GType
 253  */
 254 GType modest_account_protocol_get_account_g_type (ModestAccountProtocol *self);
 255
 256 /**
 257  * modest_account_protocol_set_account_g_type:
 258  * @self: a #ModestAccountProtocol
 259  * @account_g_type: a #GType
 260  *
 261  * set @account_g_type as the type modest_account_protocol_create_account will
 262  * instanciate
 263  */
 264 void         modest_account_protocol_set_account_g_type (ModestAccountProtocol *self,
 265                                                          GType account_g_type);
 266
 267 /**
 268  * modest_account_protocol_create_account:
 269  * @self: a #ModestAccountProtocol
 270  *
 271  * create a new account instance for this protocol
 272  *
 273  * Returns: a #TnyAccount
 274  */
 275 TnyAccount * modest_account_protocol_create_account (ModestAccountProtocol *self);
 276
 277 /**
 278  * modest_account_protocol_get_account_settings_dialog:
 279  * @self: a #ModestAccountProtocol
 280  * @account_name: the name of the account we're creating the dialog for
 281  *
 282  * retrieves the account settings dialog used to setup the account
 283  * represented by this protocol
 284  *
 285  * Returns: a #ModestAccountSettingsDialog
 286  **/
 287 ModestAccountSettingsDialog* modest_account_protocol_get_account_settings_dialog (ModestAccountProtocol *self,
 288                                                                                   const gchar *account_name);
 289
 290 ModestPairList* modest_account_protocol_get_easysetupwizard_tabs (ModestAccountProtocol *self);
 291
 292 /**
 293  * modest_account_protocol_save_settings:
 294  * @self: this #ModestAccountProtocol
 295  * @dialog: a #ModestAccountSettingsDialog
 296  * @settings: the #ModestAccountSettings
 297  *
 298  * this function stores the values held by the account settings dialog
 299  * in the account settings object that is passed as argument
 300  *
 301  * NOTE: this function provides a default implementation that calls
 302  * the save_settings method of the acocunt settings dialog. So if your
 303  * implementation do not do anything more just do not redefine it
 304  **/
 305 void modest_account_protocol_save_settings (ModestAccountProtocol *self,
 306                                             ModestAccountSettingsDialog *dialog,
 307                                             ModestAccountSettings *settings);
 308
 309 /**
 310  * modest_account_protocol_save_wizard_settings:
 311  * @self: this #ModestAccountProtocol
 312  * @wizard_pages: a list of #ModestEasysetupWizardPage
 313  * @settings: the #ModestAccountSettings
 314  *
 315  * this function stores the data input by the users in the wizard in
 316  * the account settings object passed as argument
 317  **/
 318 void modest_account_protocol_save_wizard_settings (ModestAccountProtocol *self,
 319                                                    GList *wizard_pages,
 320                                                    ModestAccountSettings *settings);
 321
 322 /**
 323  * modest_account_protocol_get_wizard_response_override:
 324  * @self: a #ModestAccountProtocol
 325  *
 326  * obtains the method that should be used to override wizard response behavior when the
 327  * wizard is setting up this account type.
 328  *
 329  * Returns: a #ModestWizardDialogResponseOverrideFunc
 330  */
 331 ModestWizardDialogResponseOverrideFunc modest_account_protocol_get_wizard_response_override (ModestAccountProtocol *self);
 332
 333
 334 /**
 335  * modest_account_protocol_check_support:
 336  * @self: a #ModestAccountProtocol
 337  * @func: a #ModestAccountProtocolCheckSupportFunc
 338  * @userdata: a gpointer
 339  *
 340  * This method checks asynchronously if the account protocol @self is
 341  * supported. Once checked, @func will be called with the result in the
 342  * mainloop.
 343  *
 344  * modest_account_protocol_is_supported() should return the cached response
 345  * from this method.
 346  */
 347 void modest_account_protocol_check_support (ModestAccountProtocol *self,
 348                                             ModestAccountProtocolCheckSupportFunc func,
 349                                             gpointer userdata);
 350
 351 /**
 352  * modest_account_protocol_cancel_check_support:
 353  * @self: a #ModestAccountProtocol
 354  *
 355  * This method requests that the check support requests running should be
 356  * immediately cancelled. Once this happens, is_supported should return %FALSE
 357  * until a new succesful check_support request is finished.
 358  */
 359 void modest_account_protocol_cancel_check_support (ModestAccountProtocol *self);
 360
 361 /**
 362  * modest_account_protocol_wizard_finished:
 363  * @self: a #ModestAccountProtocol
 364  *
 365  * Method that let protocol know if the wizard has finished, for the case it's
 366  * needed to do some stuff after check_support.
 367  */
 368 void modest_account_protocol_wizard_finished (ModestAccountProtocol *self);
 369
 370 /**
 371  * modest_account_protocol_is_supported:
 372  * @self: a #ModestAccountProtocol
 373  *
 374  * Determines if the account protocol is supported on this device.
 375  *
 376  * Returns: %TRUE if the protocol is supported, %FALSE otherwise
 377  */
 378 gboolean modest_account_protocol_is_supported (ModestAccountProtocol *self);
 379
 380 /**
 381  * modest_account_protocol_get_from:
 382  * @self: a #ModestAccountProtocol
 383  * @account_id: a transport account name
 384  * @mailbox: a mailbox
 385  *
 386  * Obtain the From: string for the account and mailbox. Should be used only
 387  * with transports with multi mailbox support.
 388  *
 389  * Returns: a newly allocated string
 390  */
 391 gchar *modest_account_protocol_get_from (ModestAccountProtocol *self,
 392                                          const gchar *account_id,
 393                                          const gchar *mailbox);
 394
 395 /**
 396  * modest_account_protocol_get_from_list:
 397  * @self: a #ModestAccountProtocol
 398  * @account_id: a transport account name
 399  *
 400  * Obtain a list of pairs (mailbox - From: string) for filling the From picker.
 401  *
 402  * Returns: a ModestPairList
 403  */
 404 ModestPairList *modest_account_protocol_get_from_list (ModestAccountProtocol *self,
 405                                                        const gchar *account_id);
 406
 407 /**
 408  * modest_account_protocol_get_signature:
 409  * @self: a #ModestAccountProtocol
 410  * @account_id: a transport account name
 411  * @mailbox: a mailbox
 412  *
 413  * Obtain the signature string for the account and mailbox. Should be used only
 414  * with transports with multi mailbox support.
 415  *
 416  * Returns: a newly allocated string
 417  */
 418 gchar *modest_account_protocol_get_signature (ModestAccountProtocol *self,
 419                                               const gchar *account_id,
 420                                               const gchar *mailbox,
 421                                               gboolean *has_signature);
 422
 423 /**
 424  * modest_account_protocol_get_icon:
 425  * @self: a #ModestAccountProtocl
 426  * @icon_type: a #ModestAccountProtocolIconType
 427  * @object: a #GObject
 428  * @icon_size: the icon size to get
 429  *
 430  * Returns a @self owned #GdkPixbuf with the icon for @icon_type and @object. @object type
 431  * should match @icon_type.
 432  *
 433  * Returns: a #GdkPixbuf (don't free or manipulate this, just copy)
 434  */
 435 const GdkPixbuf * modest_account_protocol_get_icon (ModestAccountProtocol *self, ModestAccountProtocolIconType icon_type,
 436                                                     GObject *object, guint icon_size);
 437
 438 /**
 439  * modest_account_protocol_get_service_name:
 440  * @self: a #ModestAccountProtocol
 441  * @account_id: a transport account name
 442  * @mailbox: a mailbox
 443  *
 444  * Obtain the service name string for the account and mailbox.
 445  *
 446  * Returns: a newly allocated string
 447  */
 448 gchar *modest_account_protocol_get_service_name (ModestAccountProtocol *self,
 449                                                  const gchar *account_id,
 450                                                  const gchar *mailbox);
 451
 452 /**
 453  * modest_account_protocol_get_service_icon:
 454  * @self: a #ModestAccountProtocol
 455  * @account_id: a transport account name
 456  * @mailbox: a mailbox
 457  *
 458  * Obtain the service icon for the account and mailbox.
 459  *
 460  * Returns: a protocol owned #GdkPixbuf
 461  */
 462 const GdkPixbuf *modest_account_protocol_get_service_icon (ModestAccountProtocol *self,
 463                                                            const gchar *account_id,
 464                                                            const gchar *mailbox,
 465                                                            guint icon_size);
 466
 467 /**
 468  * modest_account_protocol_save_remote_draft:
 469  * @self: a #ModestAccountProtocol
 470  * @account_id: a transport account_name
 471  * @new_msg: the newly created message in local storage.
 472  * @old_msg: the old message
 473  * @callback: the code that should be executed on finishing the remote message saving
 474  * @userdata: a #gpointer
 475  *
 476  * Saves the just-saved to local draft, into a remote storage.
 477  */
 478 void modest_account_protocol_save_remote_draft (ModestAccountProtocol *self,
 479                                                     const gchar *account_id,
 480                                                     TnyMsg *new_msg,
 481                                                     TnyMsg *old_msg,
 482                                                     ModestAccountProtocolSaveRemoteDraftCallback callback,
 483                                                     gpointer userdata);
 484
 485
 486 G_END_DECLS
 487
 488 #endif /* __MODEST_ACCOUNT_PROTOCOL_H__ */