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