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