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