git.maemo.org Git - modest/blob - src/modest-account-mgr-helpers.h

   1 /* Copyright (c) 2006, 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 #ifndef __MODEST_ACCOUNT_MGR_HELPERS_H__
  32 #define __MODEST_ACCOUNT_MGR_HELPERS_H__
  33
  34 #include <modest-account-mgr.h>
  35 #include <modest-tny-account-store.h>
  36
  37 #include <tny-account.h>
  38 #include <tny-store-account.h>
  39 #include <tny-transport-account.h>
  40
  41 G_BEGIN_DECLS
  42
  43 typedef struct {
  44         gchar            *account_name;
  45         gchar            *hostname;
  46         gchar            *username;
  47         gchar            *uri;
  48         ModestProtocol    proto; /*< The store or transport. Not ORed. */
  49         gchar            *password;
  50         time_t            last_updated;
  51         gint             port; /* Or 0, if the default should be used. */
  52         ModestProtocol   secure_auth;
  53         ModestProtocol   security;
  54 } ModestServerAccountData;
  55
  56 typedef struct {
  57         gchar            *account_name;
  58         gchar            *display_name;
  59         gchar            *fullname;
  60         gchar            *email;
  61         gboolean         is_enabled;
  62         gboolean         is_default;
  63         ModestServerAccountData *transport_account;
  64         ModestServerAccountData *store_account;
  65 } ModestAccountData;
  66
  67
  68
  69 /**
  70  * modest_account_mgr_get_account_data:
  71  * @self: a ModestAccountMgr instance
  72  * @name: the name of the account
  73  *
  74  * get information about an account
  75  *
  76  * Returns: a ModestAccountData structure with information about the account.
  77  * the data should not be changed, and be freed with modest_account_mgr_free_account_data
  78  * The function does a sanity check, an if it's not returning NULL,
  79  * it is a valid account
  80  */
  81 ModestAccountData *modest_account_mgr_get_account_data     (ModestAccountMgr *self,
  82                                                             const gchar* name);
  83
  84 /**
  85  * modest_account_mgr_get_default_account:
  86  * @self: a ModestAccountMgr instance
  87  *
  88  * get the default account name, or NULL if none is found
  89  *
  90  * Returns: the default account name (as newly allocated string, which
  91  * must be g_free'd), or NULL
  92  */
  93 gchar* modest_account_mgr_get_default_account  (ModestAccountMgr *self);
  94
  95 /**
  96  * modest_account_mgr_set_default_account:
  97  * @self: a ModestAccountMgr instance
  98  * @account: the name of an existing account
  99  *
 100  * set the default account name (which must be valid account)
 101  *
 102  * Returns: TRUE if succeeded, FALSE otherwise
 103  */
 104 gboolean modest_account_mgr_set_default_account  (ModestAccountMgr *self,
 105                                                   const gchar* account);
 106
 107 /**
 108  * modest_account_mgr_unset_default_account:
 109  * @self: a ModestAccountMgr instance
 110  * @account: the name of an account
 111  *
 112  * Unset the default account name, so that no account is the default.
 113  *
 114  * Returns: TRUE if succeeded, FALSE otherwise
 115  */
 116 gboolean modest_account_mgr_unset_default_account  (ModestAccountMgr *self);
 117
 118 /**
 119  * modest_account_mgr_set_first_account_as_default:
 120  * @self: a ModestAccountMgr instance
 121  *
 122  * Guarantees that at least one account, if there are any accounts, is the default,
 123  * so that modest_account_mgr_get_default_account() will return non-NULL if there
 124  * are any accounts.
 125  *
 126  * Returns: TRUE if succeeded, FALSE otherwise
 127  */
 128 gboolean
 129 modest_account_mgr_set_first_account_as_default  (ModestAccountMgr *self);
 130
 131 /**
 132  * modest_account_mgr_free_account_data:
 133  * @self: a ModestAccountMgr instance
 134  * @data: a ModestAccountData instance
 135  *
 136  * free the account data structure
 137  */
 138 void       modest_account_mgr_free_account_data     (ModestAccountMgr *self,
 139                                                      ModestAccountData *data);
 140
 141 /**
 142  * modest_account_mgr_set_enabled
 143  * @self: a ModestAccountMgr instance
 144  * @name: the account name
 145  * @enabled: if TRUE, the account will be enabled, if FALSE, it will be disabled
 146  *
 147  * enable/disabled an account
 148  *
 149  * Returns: TRUE if it worked, FALSE otherwise
 150  */
 151 gboolean modest_account_mgr_set_enabled (ModestAccountMgr *self, const gchar* name,
 152                                          gboolean enabled);
 153
 154 /**
 155  * modest_account_mgr_get_enabled:
 156  * @self: a ModestAccountMgr instance
 157  * @name: the account name to check
 158  *
 159  * check whether a certain account is enabled
 160  *
 161  * Returns: TRUE if it is enabled, FALSE otherwise
 162  */
 163 gboolean modest_account_mgr_get_enabled (ModestAccountMgr *self, const gchar* name);
 164
 165 /**
 166  * modest_account_mgr_get_display_name:
 167  * @self: a ModestAccountMgr instance
 168  * @name: the account name to check
 169  *
 170  * Return the human-readable account title for this account, or NULL.
 171  */
 172 gchar* modest_account_mgr_get_display_name (ModestAccountMgr *self,
 173         const gchar* name);
 174
 175
 176 /**
 177  * modest_account_mgr_set_signature
 178  * @self: a ModestAccountMgr instance
 179  * @name: the account name to check
 180  * @signature: the signature text
 181  * @use_signature: Whether the signature should be used.
 182  *
 183  * Sets the signature text for the account.
 184  *
 185  * Returns: TRUE if it worked, FALSE otherwise
 186  */
 187 gboolean modest_account_mgr_set_signature (ModestAccountMgr *self, const gchar* name,
 188         const gchar* signature, gboolean use_signature);
 189
 190 /**
 191  * modest_account_mgr_get_signature:
 192  * @self: a ModestAccountMgr instance
 193  * @name: the account name
 194  * @use_signature: Pointer to a gboolean taht will be set to TRUE if the signature should be used.
 195  *
 196  * Gets the signature text for this account.
 197  *
 198  * Returns: The signature text, which should be freed with g_free().
 199  */
 200 gchar* modest_account_mgr_get_signature (ModestAccountMgr *self, const gchar* name,
 201         gboolean* use_signature);
 202
 203 /**
 204  * modest_account_mgr_set_connection_specific_smtp
 205  * @self: a ModestAccountMgr instance
 206  * @name: the account name
 207  * @connection_name: A libconic IAP connection name
 208  * @server_account_name: a server account name to use for this connection.
 209  *
 210  * Specify a server account to use with the specific connection for this account.
 211  *
 212  * Returns: TRUE if it worked, FALSE otherwise
 213  */
 214 gboolean modest_account_mgr_set_connection_specific_smtp (ModestAccountMgr *self, const gchar* name,
 215                                          const gchar* connection_name, const gchar* server_account_name);
 216
 217 /**
 218  * modest_account_mgr_remove_connection_specific_smtp
 219  * @self: a ModestAccountMgr instance
 220  * @name: the account name
 221  * @connection_name: A libconic IAP connection name
 222  *
 223  * Disassacoiate a server account to use with the specific connection for this account.
 224  *
 225  * Returns: TRUE if it worked, FALSE otherwise
 226  */
 227 gboolean modest_account_mgr_remove_connection_specific_smtp (ModestAccountMgr *self, const gchar* name,
 228                                          const gchar* connection_name);
 229
 230 /**
 231  * modest_account_mgr_get_connection_specific_smtp
 232  * @self: a ModestAccountMgr instance
 233  * @name: the account name
 234  * @connection_name: A libconic IAP connection name
 235  *
 236  * Retrieve a server account to use with this specific connection for this account.
 237  *
 238  * Returns: a server account name to use for this connection, or NULL if none is specified.
 239  */
 240 gchar* modest_account_mgr_get_connection_specific_smtp (ModestAccountMgr *self, const gchar* name,
 241                                          const gchar* connection_name);
 242
 243
 244 /**
 245  * modest_server_account_get_username:
 246  * @self: a ModestAccountMgr instance
 247  * @account_name: The name of a server account.
 248  *
 249  * Gets the username this server account.
 250  *
 251  * Returns: The username.
 252  */
 253 gchar*
 254 modest_server_account_get_username (ModestAccountMgr *self, const gchar* account_name);
 255
 256 /**
 257  * modest_server_account_set_username:
 258  * @self: a ModestAccountMgr instance
 259  * @account_name: The name of a server account.
 260  * @username: The new username.
 261  *
 262  * Sets the username this server account.
 263  */
 264 void
 265 modest_server_account_set_username (ModestAccountMgr *self, const gchar* account_name,
 266         const gchar* username);
 267
 268 /**
 269  * modest_server_account_get_username_has_succeeded:
 270  * @self: a ModestAccountMgr instance
 271  * @account_name: The name of a server account.
 272  *
 273  * Whether a connection has ever been successfully made to this account with
 274  * the current username. This can be used to avoid asking again for the username
 275  * when asking a second time for a non-stored password.
 276  *
 277  * Returns: TRUE if the username is known to be correct.
 278  */
 279 gboolean
 280 modest_server_account_get_username_has_succeeded (ModestAccountMgr *self, const gchar* account_name);
 281
 282 /**
 283  * modest_server_account_set_username_has_succeeded:
 284  * @self: a ModestAccountMgr instance
 285  * @account_name: The name of a server account.
 286  * @succeeded: Whether the username has succeeded
 287  *
 288  * Sets whether the username is known to be correct.
 289  */
 290 void
 291 modest_server_account_set_username_has_succeeded (ModestAccountMgr *self, const gchar* account_name,
 292         gboolean succeeded);
 293
 294 /**
 295  * modest_server_account_set_password:
 296  * @self: a ModestAccountMgr instance
 297  * @account_name: The name of a server account.
 298  * @password: The new password.
 299  *
 300  * Sets the password this server account.
 301  */
 302 void
 303 modest_server_account_set_password (ModestAccountMgr *self, const gchar* account_name,
 304         const gchar* password);
 305
 306
 307 /**
 308  * modest_server_account_modest_server_account_get_hostnameget_username:
 309  * @self: a ModestAccountMgr instance
 310  * @account_name: The name of a server account.
 311  *
 312  * Gets the hostname this server account.
 313  *
 314  * Returns: The hostname.
 315  */
 316 gchar*
 317 modest_server_account_get_hostname (ModestAccountMgr *self, const gchar* account_name);
 318
 319
 320 /**
 321  * modest_server_account_get_secure_auth:
 322  * @self: a ModestAccountMgr instance
 323  * @account_name: The name of a server account.
 324  *
 325  * Gets the secure authentication method for this server account.
 326  *
 327  * Returns: The secure authentication enum value.
 328  */
 329 ModestProtocol
 330 modest_server_account_get_secure_auth (ModestAccountMgr *self, const gchar* account_name);
 331
 332 /**
 333  * modest_server_account_data_get_secure_auth:
 334  * @self: a ModestAccountMgr instance
 335  * @account_name: The name of a server account.
 336  * @secure_auth: The secure authentication enum value.
 337  *
 338  * Gets the secure authentication method for this server account.
 339  */
 340 void
 341 modest_server_account_set_secure_auth (ModestAccountMgr *self, const gchar* account_name,
 342         ModestProtocol secure_auth);
 343
 344 /**
 345  * modest_server_account_data_get_security:
 346  * @self: a ModestAccountMgr instance
 347  * @account_name: The name of a server account.
 348  *
 349  * Gets the security method for this server account.
 350  *
 351  * Returns: The security enum value.
 352  */
 353 ModestProtocol
 354 modest_server_account_get_security (ModestAccountMgr *self, const gchar* account_name);
 355
 356 /**
 357  * modest_server_account_set_security:
 358  * @self: a ModestAccountMgr instance
 359  * @secure_auth: The security enum value.
 360  *
 361  * Gets the security method for this server account.
 362  */
 363 void
 364 modest_server_account_set_security (ModestAccountMgr *self, const gchar* account_name,
 365         ModestProtocol security);
 366
 367 ModestServerAccountData*
 368 modest_account_mgr_get_server_account_data (ModestAccountMgr *self, const gchar* name);
 369
 370 void
 371 modest_account_mgr_free_server_account_data (ModestAccountMgr *self,
 372                                              ModestServerAccountData* data);
 373
 374 /**
 375  * modest_account_mgr_get_from_string
 376  * @self: a #ModestAccountMgr instance
 377  * @name: the account name
 378  *
 379  * get the From: string for some account; ie. "Foo Bar" <foo.bar@cuux.yy>"
 380  *
 381  * Returns: the newly allocated from-string, or NULL in case of error
 382  */
 383 gchar * modest_account_mgr_get_from_string (ModestAccountMgr *self, const gchar* name);
 384
 385
 386 /**
 387  * modest_account_mgr_get_unused_account_name
 388  * @self: a #ModestAccountMgr instance
 389  * @name: The initial account name
 390  *
 391  * get an unused account name, based on a starting string.
 392  *
 393  * Returns: the newly allocated name.
 394  */
 395 gchar*
 396 modest_account_mgr_get_unused_account_name (ModestAccountMgr *self, const gchar* starting_name,
 397         gboolean server_account);
 398
 399 /**
 400  * modest_account_mgr_get_unused_account_display name
 401  * @self: a #ModestAccountMgr instance
 402  * @name: The initial account display name
 403  *
 404  * get an unused account display name, based on a starting string.
 405  *
 406  * Returns: the newly allocated name.
 407  */
 408 gchar*
 409 modest_account_mgr_get_unused_account_display_name (ModestAccountMgr *self, const gchar* starting_name);
 410
 411 G_END_DECLS
 412
 413 #endif /* __MODEST_ACCOUNT_MGR_H__ */