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