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; /*< Only for mbox and maildir accounts. */
  48         ModestTransportStoreProtocol    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         ModestAuthProtocol   secure_auth;
  53         ModestConnectionProtocol   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 /** Get the first one, alphabetically, by title. */
 132 gchar*
 133 modest_account_mgr_get_first_account_name (ModestAccountMgr *self);
 134
 135 /**
 136  * modest_account_mgr_free_account_data:
 137  * @self: a ModestAccountMgr instance
 138  * @data: a ModestAccountData instance
 139  *
 140  * free the account data structure
 141  */
 142 void       modest_account_mgr_free_account_data     (ModestAccountMgr *self,
 143                                                      ModestAccountData *data);
 144
 145 /**
 146  * modest_account_mgr_set_enabled
 147  * @self: a ModestAccountMgr instance
 148  * @name: the account name
 149  * @enabled: if TRUE, the account will be enabled, if FALSE, it will be disabled
 150  *
 151  * enable/disabled an account
 152  *
 153  * Returns: TRUE if it worked, FALSE otherwise
 154  */
 155 gboolean modest_account_mgr_set_enabled (ModestAccountMgr *self, const gchar* name,
 156                                          gboolean enabled);
 157
 158 /**
 159  * modest_account_mgr_get_enabled:
 160  * @self: a ModestAccountMgr instance
 161  * @name: the account name to check
 162  *
 163  * check whether a certain account is enabled
 164  *
 165  * Returns: TRUE if it is enabled, FALSE otherwise
 166  */
 167 gboolean modest_account_mgr_get_enabled (ModestAccountMgr *self, const gchar* name);
 168
 169 /**
 170  * modest_account_mgr_get_display_name:
 171  * @self: a ModestAccountMgr instance
 172  * @name: the account name to check
 173  *
 174  * Return the human-readable account title for this account, or NULL.
 175  */
 176 gchar* modest_account_mgr_get_display_name (ModestAccountMgr *self,
 177         const gchar* name);
 178
 179
 180 /**
 181  * modest_account_mgr_set_signature
 182  * @self: a ModestAccountMgr instance
 183  * @name: the account name to check
 184  * @signature: the signature text
 185  * @use_signature: Whether the signature should be used.
 186  *
 187  * Sets the signature text for the account.
 188  *
 189  * Returns: TRUE if it worked, FALSE otherwise
 190  */
 191 gboolean modest_account_mgr_set_signature (ModestAccountMgr *self, const gchar* name,
 192         const gchar* signature, gboolean use_signature);
 193
 194 /**
 195  * modest_account_mgr_get_signature:
 196  * @self: a ModestAccountMgr instance
 197  * @name: the account name
 198  * @use_signature: Pointer to a gboolean taht will be set to TRUE if the signature should be used.
 199  *
 200  * Gets the signature text for this account.
 201  *
 202  * Returns: The signature text, which should be freed with g_free().
 203  */
 204 gchar* modest_account_mgr_get_signature (ModestAccountMgr *self, const gchar* name,
 205         gboolean* use_signature);
 206
 207 /**
 208  * modest_account_mgr_get_store_protocol:
 209  * @self: a ModestAccountMgr instance
 210  * @name: the account name
 211  *
 212  * Gets the protocol type (For instance, POP or IMAP) used for the store server account.
 213  *
 214  * Returns: The protocol type.
 215  */
 216 ModestTransportStoreProtocol modest_account_mgr_get_store_protocol (ModestAccountMgr *self, const gchar* name);
 217
 218 /**
 219  * modest_account_mgr_set_connection_specific_smtp
 220  * @self: a ModestAccountMgr instance
 221  * @name: the account name
 222  * @connection_name: A libconic IAP connection name
 223  * @server_account_name: a server account name to use for this connection.
 224  *
 225  * Specify a server account to use with the specific connection for this account.
 226  *
 227  * Returns: TRUE if it worked, FALSE otherwise
 228  */
 229 gboolean modest_account_mgr_set_connection_specific_smtp (ModestAccountMgr *self, const gchar* name,
 230                                          const gchar* connection_name, const gchar* server_account_name);
 231
 232 /**
 233  * modest_account_mgr_remove_connection_specific_smtp
 234  * @self: a ModestAccountMgr instance
 235  * @name: the account name
 236  * @connection_name: A libconic IAP connection name
 237  *
 238  * Disassacoiate a server account to use with the specific connection for this account.
 239  *
 240  * Returns: TRUE if it worked, FALSE otherwise
 241  */
 242 gboolean modest_account_mgr_remove_connection_specific_smtp (ModestAccountMgr *self, const gchar* name,
 243                                          const gchar* connection_name);
 244
 245 /**
 246  * modest_account_mgr_get_has_connection_specific_smtp
 247  * @self: a ModestAccountMgr instance
 248  * @name: the account name
 249  * @result: Whether this account uses any connection-specific smtp server accounts.
 250  */
 251 gboolean modest_account_mgr_get_has_connection_specific_smtp (ModestAccountMgr *self, const gchar* account_name);
 252
 253 /**
 254  * modest_account_mgr_get_connection_specific_smtp
 255  * @self: a ModestAccountMgr instance
 256  * @name: the account name
 257  * @connection_name: A libconic IAP connection name
 258  *
 259  * Retrieve a server account to use with this specific connection for this account.
 260  *
 261  * Returns: a server account name to use for this connection, or NULL if none is specified.
 262  */
 263 gchar* modest_account_mgr_get_connection_specific_smtp (ModestAccountMgr *self, const gchar* name,
 264                                          const gchar* connection_name);
 265
 266
 267 /**
 268  * modest_server_account_get_username:
 269  * @self: a ModestAccountMgr instance
 270  * @account_name: The name of a server account.
 271  *
 272  * Gets the username this server account.
 273  *
 274  * Returns: The username.
 275  */
 276 gchar*
 277 modest_server_account_get_username (ModestAccountMgr *self, const gchar* account_name);
 278
 279 /**
 280  * modest_server_account_set_username:
 281  * @self: a ModestAccountMgr instance
 282  * @account_name: The name of a server account.
 283  * @username: The new username.
 284  *
 285  * Sets the username this server account.
 286  */
 287 void
 288 modest_server_account_set_username (ModestAccountMgr *self, const gchar* account_name,
 289         const gchar* username);
 290
 291 /**
 292  * modest_server_account_get_username_has_succeeded:
 293  * @self: a ModestAccountMgr instance
 294  * @account_name: The name of a server account.
 295  *
 296  * Whether a connection has ever been successfully made to this account with
 297  * the current username. This can be used to avoid asking again for the username
 298  * when asking a second time for a non-stored password.
 299  *
 300  * Returns: TRUE if the username is known to be correct.
 301  */
 302 gboolean
 303 modest_server_account_get_username_has_succeeded (ModestAccountMgr *self, const gchar* account_name);
 304
 305 /**
 306  * modest_server_account_set_username_has_succeeded:
 307  * @self: a ModestAccountMgr instance
 308  * @account_name: The name of a server account.
 309  * @succeeded: Whether the username has succeeded
 310  *
 311  * Sets whether the username is known to be correct.
 312  */
 313 void
 314 modest_server_account_set_username_has_succeeded (ModestAccountMgr *self, const gchar* account_name,
 315         gboolean succeeded);
 316
 317 /**
 318  * modest_server_account_set_password:
 319  * @self: a ModestAccountMgr instance
 320  * @account_name: The name of a server account.
 321  * @password: The new password.
 322  *
 323  * Sets the password for this server account.
 324  */
 325 void
 326 modest_server_account_set_password (ModestAccountMgr *self, const gchar* account_name,
 327         const gchar* password);
 328
 329 /**
 330  * modest_server_account_get_password:
 331  * @self: a ModestAccountMgr instance
 332  * @account_name: The name of a server account.
 333  *
 334  * Gets the password for this server account from the account settings.
 335  */
 336 gchar*
 337 modest_server_account_get_password (ModestAccountMgr *self, const gchar* account_name);
 338
 339 /**
 340  * modest_server_account_get_has_password:
 341  * @self: a ModestAccountMgr instance
 342  * @account_name: The name of a server account.
 343  *
 344  * Gets whether a password has been set for this server account in the account settings.
 345  */
 346 gboolean
 347 modest_server_account_get_has_password (ModestAccountMgr *self, const gchar* account_name);
 348
 349 /**
 350  * modest_server_account_modest_server_account_get_hostnameget_username:
 351  * @self: a ModestAccountMgr instance
 352  * @account_name: The name of a server account.
 353  *
 354  * Gets the hostname this server account.
 355  *
 356  * Returns: The hostname.
 357  */
 358 gchar*
 359 modest_server_account_get_hostname (ModestAccountMgr *self, const gchar* account_name);
 360
 361
 362 /**
 363  * modest_server_account_get_secure_auth:
 364  * @self: a ModestAccountMgr instance
 365  * @account_name: The name of a server account.
 366  *
 367  * Gets the secure authentication method for this server account.
 368  *
 369  * Returns: The secure authentication enum value.
 370  */
 371 ModestAuthProtocol
 372 modest_server_account_get_secure_auth (ModestAccountMgr *self, const gchar* account_name);
 373
 374 /**
 375  * modest_server_account_data_get_secure_auth:
 376  * @self: a ModestAccountMgr instance
 377  * @account_name: The name of a server account.
 378  * @secure_auth: The secure authentication enum value.
 379  *
 380  * Gets the secure authentication method for this server account.
 381  */
 382 void
 383 modest_server_account_set_secure_auth (ModestAccountMgr *self, const gchar* account_name,
 384                                        ModestAuthProtocol secure_auth);
 385
 386 /**
 387  * modest_server_account_data_get_security:
 388  * @self: a ModestAccountMgr instance
 389  * @account_name: The name of a server account.
 390  *
 391  * Gets the security method for this server account.
 392  *
 393  * Returns: The security enum value.
 394  */
 395 ModestConnectionProtocol
 396 modest_server_account_get_security (ModestAccountMgr *self, const gchar* account_name);
 397
 398 /**
 399  * modest_server_account_set_security:
 400  * @self: a ModestAccountMgr instance
 401  * @secure_auth: The security enum value.
 402  *
 403  * Gets the security method for this server account.
 404  */
 405 void
 406 modest_server_account_set_security (ModestAccountMgr *self, const gchar* account_name,
 407                                     ModestConnectionProtocol security);
 408
 409 ModestServerAccountData*
 410 modest_account_mgr_get_server_account_data (ModestAccountMgr *self, const gchar* name);
 411
 412 void
 413 modest_account_mgr_free_server_account_data (ModestAccountMgr *self,
 414                                              ModestServerAccountData* data);
 415
 416 /**
 417  * modest_account_mgr_get_from_string
 418  * @self: a #ModestAccountMgr instance
 419  * @name: the account name
 420  *
 421  * get the From: string for some account; ie. "Foo Bar" <foo.bar@cuux.yy>"
 422  *
 423  * Returns: the newly allocated from-string, or NULL in case of error
 424  */
 425 gchar * modest_account_mgr_get_from_string (ModestAccountMgr *self, const gchar* name);
 426
 427
 428 /**
 429  * modest_account_mgr_get_unused_account_name
 430  * @self: a #ModestAccountMgr instance
 431  * @name: The initial account name
 432  *
 433  * get an unused account name, based on a starting string.
 434  *
 435  * Returns: the newly allocated name.
 436  */
 437 gchar*
 438 modest_account_mgr_get_unused_account_name (ModestAccountMgr *self, const gchar* starting_name,
 439         gboolean server_account);
 440
 441 /**
 442  * modest_account_mgr_get_unused_account_display name
 443  * @self: a #ModestAccountMgr instance
 444  * @name: The initial account display name
 445  *
 446  * get an unused account display name, based on a starting string.
 447  *
 448  * Returns: the newly allocated name.
 449  */
 450 gchar*
 451 modest_account_mgr_get_unused_account_display_name (ModestAccountMgr *self, const gchar* starting_name);
 452
 453 G_END_DECLS
 454
 455 #endif /* __MODEST_ACCOUNT_MGR_H__ */