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 void (*ModestAccountProtocolCheckSupportFunc) (ModestAccountProtocol *self,
  57                                                        gboolean supported, gpointer userdata);
  58
  59
  60 struct _ModestAccountProtocol {
  61         ModestProtocol parent;
  62 };
  63
  64 struct _ModestAccountProtocolClass {
  65         ModestProtocolClass parent_class;
  66
  67         /* Virtual methods */
  68         TnyAccount * (*create_account) (ModestAccountProtocol *self);
  69         ModestAccountSettingsDialog* (*create_account_settings_dialog) (ModestAccountProtocol* self);
  70         ModestPairList* (*get_easysetupwizard_tabs) (ModestAccountProtocol* self);
  71         ModestWizardDialogResponseOverrideFunc (*get_wizard_response_override) (ModestAccountProtocol *self);
  72         void (*save_settings) (ModestAccountProtocol *self, ModestAccountSettingsDialog *dialog, ModestAccountSettings *settings);
  73         void (*save_wizard_settings) (ModestAccountProtocol *self, GList *wizard_pages, ModestAccountSettings *settings);
  74         gboolean (*is_supported) (ModestAccountProtocol *self);
  75         void (*check_support) (ModestAccountProtocol *self, ModestAccountProtocolCheckSupportFunc func, gpointer userdata);
  76 };
  77
  78 /**
  79  * modest_account_protocol_get_type:
  80  *
  81  * Returns: GType of the account protocol type
  82  */
  83 GType  modest_account_protocol_get_type   (void) G_GNUC_CONST;
  84
  85 /**
  86  * modest_account_protocol_new:
  87  *
  88  * creates a new instance of #ModestAccountProtocol
  89  *
  90  * Returns: a #ModestAccountProtocol
  91  */
  92 ModestProtocol*    modest_account_protocol_new (const gchar *name, const gchar *display_name,
  93                                                 guint port, guint alternate_port,
  94                                                 GType account_g_type);
  95
  96 /**
  97  * modest_account_protocol_get_port:
  98  * @self: a #ModestAccountProtocol
  99  *
 100  * get the protocol standard port
 101  *
 102  * Returns: a string
 103  */
 104 guint modest_account_protocol_get_port (ModestAccountProtocol *self);
 105
 106 /**
 107  * modest_account_protocol_set_port:
 108  * @self: a #ModestAccountProtocol
 109  * @port: a #guint
 110  *
 111  * set @port as the protocol standard port
 112  */
 113 void         modest_account_protocol_set_port (ModestAccountProtocol *self,
 114                                                guint port);
 115
 116 /**
 117  * modest_account_protocol_get_alternate_port:
 118  * @self: a #ModestAccountProtocol
 119  *
 120  * get the protocol standard alternate_port
 121  *
 122  * Returns: a #guint
 123  */
 124 guint modest_account_protocol_get_alternate_port (ModestAccountProtocol *self);
 125
 126 /**
 127  * modest_account_protocol_set_alternate_port:
 128  * @self: a #ModestAccountProtocol
 129  * @alternate_port: a #guint
 130  *
 131  * set @alternate_port as the protocol alternate port
 132  */
 133 void         modest_account_protocol_set_alternate_port (ModestAccountProtocol *self,
 134                                                          guint alternate_port);
 135
 136 /**
 137  * modest_account_protocol_set_account_options:
 138  * @self: a #ModestAccountProtocol
 139  * @account_options: a #TnyList of account options and their values
 140  *
 141  * set the account options that will be passed to TnyCamelAccount for this protocol.
 142  * This replaces previous option lists for this protocol
 143  */
 144 void modest_account_protocol_set_account_options (ModestAccountProtocol *self,
 145                                                   TnyList *account_options);
 146
 147 /**
 148  * modest_account_protocol_get_account_options:
 149  * @self: a #ModestAccountProtocol
 150  *
 151  * obtain the account options for this account protocol.
 152  *
 153  * Returns: a caller-owner copy of the account options list.
 154  */
 155 TnyList *modest_account_protocol_get_account_options (ModestAccountProtocol *self);
 156
 157 /**
 158  * modest_account_protocol_has_custom_secure_auth_mech:
 159  * @self: a #ModestAccountProtocol
 160  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
 161  *
 162  * checks whether there's a custom secure auth mech camel string for @auth_protocol_type.
 163  *
 164  * Returns: %TRUE if registered, %FALSE otherwise
 165  */
 166 gboolean
 167 modest_account_protocol_has_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type);
 168
 169 /**
 170  * modest_account_protocol_get_custom_secure_auth_mech:
 171  * @self: a #ModestAccountProtocol
 172  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
 173  *
 174  * obtains the secure auth mech of @auth_protocol_type in protocol. Be careful as %NULL does not imply
 175  * there's no custom auth mech registered (you can register %NULL). To check if it's registered, just
 176  * use modest_account_protocol_has_custom_secure_auth_mech().
 177  *
 178  * Returns: the secure auth mech for this auth protocol type that will be passed to camel.
 179  */
 180 const gchar *
 181 modest_account_protocol_get_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type);
 182
 183 /**
 184  * modest_account_protocol_unset_custom_secure_auth_mech:
 185  * @self: a #ModestAccountProtocol
 186  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
 187  *
 188  * Unsets the secure auth meth of @auth_protocol_type in protocol.
 189  */
 190 void
 191 modest_account_protocol_unset_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type);
 192
 193 /**
 194  * modest_account_protocol_set_custom_secure_auth_mech:
 195  * @self: a #ModestAccountProtocol
 196  * @auth_protocol_type: a #ModestProtocolType for an auth protocol
 197  * @secure_auth_mech: a string or %NULL
 198  *
 199  * sets the secure auth mech of @auth_protocol_type in protocol. Be careful as %NULL does not imply
 200  * there's no custom auth mech registered (you can register %NULL). If you set %NULL you're regitering %NULL as the custom secure auth
 201  * mechanism instead of unsetting it.
 202  */
 203 void
 204 modest_account_protocol_set_custom_secure_auth_mech (ModestAccountProtocol *self, ModestProtocolType auth_protocol_type, const gchar *secure_auth_mech);
 205
 206 /**
 207  * modest_account_protocol_get_account_g_type:
 208  * @self: a #ModestAccountProtocol
 209  *
 210  * get the protocol type used for factoring new TnyAccount
 211  *
 212  * Returns: a #GType
 213  */
 214 GType modest_account_protocol_get_account_g_type (ModestAccountProtocol *self);
 215
 216 /**
 217  * modest_account_protocol_set_account_g_type:
 218  * @self: a #ModestAccountProtocol
 219  * @account_g_type: a #GType
 220  *
 221  * set @account_g_type as the type modest_account_protocol_create_account will
 222  * instanciate
 223  */
 224 void         modest_account_protocol_set_account_g_type (ModestAccountProtocol *self,
 225                                                          GType account_g_type);
 226
 227 /**
 228  * modest_account_protocol_create_account:
 229  * @self: a #ModestAccountProtocol
 230  *
 231  * create a new account instance for this protocol
 232  *
 233  * Returns: a #TnyAccount
 234  */
 235 TnyAccount * modest_account_protocol_create_account (ModestAccountProtocol *self);
 236
 237 /**
 238  * modest_account_protocol_get_account_settings_dialog:
 239  * @self: a #ModestAccountProtocol
 240  * @account_name: the name of the account we're creating the dialog for
 241  *
 242  * retrieves the account settings dialog used to setup the account
 243  * represented by this protocol
 244  *
 245  * Returns: a #ModestAccountSettingsDialog
 246  **/
 247 ModestAccountSettingsDialog* modest_account_protocol_get_account_settings_dialog (ModestAccountProtocol *self,
 248                                                                                   const gchar *account_name);
 249
 250 ModestPairList* modest_account_protocol_get_easysetupwizard_tabs (ModestAccountProtocol *self);
 251
 252 /**
 253  * modest_account_protocol_save_settings:
 254  * @self: this #ModestAccountProtocol
 255  * @dialog: a #ModestAccountSettingsDialog
 256  * @settings: the #ModestAccountSettings
 257  *
 258  * this function stores the values held by the account settings dialog
 259  * in the account settings object that is passed as argument
 260  *
 261  * NOTE: this function provides a default implementation that calls
 262  * the save_settings method of the acocunt settings dialog. So if your
 263  * implementation do not do anything more just do not redefine it
 264  **/
 265 void modest_account_protocol_save_settings (ModestAccountProtocol *self,
 266                                             ModestAccountSettingsDialog *dialog,
 267                                             ModestAccountSettings *settings);
 268
 269 /**
 270  * modest_account_protocol_save_wizard_settings:
 271  * @self: this #ModestAccountProtocol
 272  * @wizard_pages: a list of #ModestEasysetupWizardPage
 273  * @settings: the #ModestAccountSettings
 274  *
 275  * this function stores the data input by the users in the wizard in
 276  * the account settings object passed as argument
 277  **/
 278 void modest_account_protocol_save_wizard_settings (ModestAccountProtocol *self,
 279                                                    GList *wizard_pages,
 280                                                    ModestAccountSettings *settings);
 281
 282 /**
 283  * modest_account_protocol_get_wizard_response_override:
 284  * @self: a #ModestAccountProtocol
 285  *
 286  * obtains the method that should be used to override wizard response behavior when the
 287  * wizard is setting up this account type.
 288  *
 289  * Returns: a #ModestWizardDialogResponseOverrideFunc
 290  */
 291 ModestWizardDialogResponseOverrideFunc modest_account_protocol_get_wizard_response_override (ModestAccountProtocol *self);
 292
 293
 294 /**
 295  * modest_account_protocol_check_support:
 296  * @self: a #ModestAccountProtocol
 297  * @func: a #ModestAccountProtocolCheckSupportFunc
 298  * @userdata: a gpointer
 299  *
 300  * This method checks asynchronously if the account protocol @self is
 301  * supported. Once checked, @func will be called with the result in the
 302  * mainloop.
 303  *
 304  * modest_account_protocol_is_supported() should return the cached response
 305  * from this method.
 306  */
 307 void modest_account_protocol_check_support (ModestAccountProtocol *self,
 308                                             ModestAccountProtocolCheckSupportFunc func,
 309                                             gpointer userdata);
 310 /**
 311  * modest_account_protocol_is_supported:
 312  * @self: a #ModestAccountProtocol
 313  *
 314  * Determines if the account protocol is supported on this device.
 315  *
 316  * Returns: %TRUE if the protocol is supported, %FALSE otherwise
 317  */
 318 gboolean modest_account_protocol_is_supported (ModestAccountProtocol *self);
 319
 320 G_END_DECLS
 321
 322 #endif /* __MODEST_ACCOUNT_PROTOCOL_H__ */