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  * @connection_name: A libconic IAP connection name
 222  * @server_account_name: a server account name to use for this connection.
 223  *
 224  * Specify a server account to use with the specific connection for this account.
 225  *
 226  * Returns: TRUE if it worked, FALSE otherwise
 227  */
 228 gboolean modest_account_mgr_set_connection_specific_smtp (ModestAccountMgr *self,
 229                                          const gchar* connection_name, const gchar* server_account_name);
 230
 231 /**
 232  * modest_account_mgr_remove_connection_specific_smtp
 233  * @self: a ModestAccountMgr instance
 234  * @connection_name: A libconic IAP connection name
 235  *
 236  * Disassociate a server account to use with the specific connection for this account.
 237  *
 238  * Returns: TRUE if it worked, FALSE otherwise
 239  */
 240 gboolean modest_account_mgr_remove_connection_specific_smtp (ModestAccountMgr *self,
 241         const gchar* connection_name);
 242
 243 /**
 244  * modest_account_mgr_get_use_connection_specific_smtp
 245  * @self: a ModestAccountMgr instance
 246  * @account_name: the account name
 247  * @result: Whether this account should use connection-specific smtp server accounts.
 248  */
 249 gboolean modest_account_mgr_get_use_connection_specific_smtp (ModestAccountMgr *self, const gchar* account_name);
 250
 251 /**
 252  * modest_account_mgr_set_use_connection_specific_smtp
 253  * @self: a ModestAccountMgr instance
 254  * @account_name: the account name
 255  * @new_value: New value that indicates if if this account should use connection-specific smtp server accounts.
 256  * @result: TRUE if it succeeded, FALSE otherwise
 257  */
 258 gboolean modest_account_mgr_set_use_connection_specific_smtp (ModestAccountMgr *self, const gchar* account_name,
 259         gboolean new_value);
 260
 261 /**
 262  * modest_account_mgr_get_connection_specific_smtp
 263  * @self: a ModestAccountMgr instance
 264  * @connection_name: A libconic IAP connection name
 265  *
 266  * Retrieve a server account to use with this specific connection for this account.
 267  *
 268  * Returns: a server account name to use for this connection, or NULL if none is specified.
 269  */
 270 gchar* modest_account_mgr_get_connection_specific_smtp (ModestAccountMgr *self,
 271                                          const gchar* connection_name);
 272
 273
 274 /**
 275  * modest_server_account_get_username:
 276  * @self: a ModestAccountMgr instance
 277  * @account_name: The name of a server account.
 278  *
 279  * Gets the username this server account.
 280  *
 281  * Returns: The username.
 282  */
 283 gchar*
 284 modest_server_account_get_username (ModestAccountMgr *self, const gchar* account_name);
 285
 286 /**
 287  * modest_server_account_set_username:
 288  * @self: a ModestAccountMgr instance
 289  * @account_name: The name of a server account.
 290  * @username: The new username.
 291  *
 292  * Sets the username this server account.
 293  */
 294 void
 295 modest_server_account_set_username (ModestAccountMgr *self, const gchar* account_name,
 296         const gchar* username);
 297
 298 /**
 299  * modest_server_account_get_username_has_succeeded:
 300  * @self: a ModestAccountMgr instance
 301  * @account_name: The name of a server account.
 302  *
 303  * Whether a connection has ever been successfully made to this account with
 304  * the current username. This can be used to avoid asking again for the username
 305  * when asking a second time for a non-stored password.
 306  *
 307  * Returns: TRUE if the username is known to be correct.
 308  */
 309 gboolean
 310 modest_server_account_get_username_has_succeeded (ModestAccountMgr *self, const gchar* account_name);
 311
 312 /**
 313  * modest_server_account_set_username_has_succeeded:
 314  * @self: a ModestAccountMgr instance
 315  * @account_name: The name of a server account.
 316  * @succeeded: Whether the username has succeeded
 317  *
 318  * Sets whether the username is known to be correct.
 319  */
 320 void
 321 modest_server_account_set_username_has_succeeded (ModestAccountMgr *self, const gchar* account_name,
 322         gboolean succeeded);
 323
 324 /**
 325  * modest_server_account_set_password:
 326  * @self: a ModestAccountMgr instance
 327  * @account_name: The name of a server account.
 328  * @password: The new password.
 329  *
 330  * Sets the password for this server account.
 331  */
 332 void
 333 modest_server_account_set_password (ModestAccountMgr *self, const gchar* account_name,
 334         const gchar* password);
 335
 336 /**
 337  * modest_server_account_get_password:
 338  * @self: a ModestAccountMgr instance
 339  * @account_name: The name of a server account.
 340  *
 341  * Gets the password for this server account from the account settings.
 342  */
 343 gchar*
 344 modest_server_account_get_password (ModestAccountMgr *self, const gchar* account_name);
 345
 346 /**
 347  * modest_server_account_get_has_password:
 348  * @self: a ModestAccountMgr instance
 349  * @account_name: The name of a server account.
 350  *
 351  * Gets whether a password has been set for this server account in the account settings.
 352  */
 353 gboolean
 354 modest_server_account_get_has_password (ModestAccountMgr *self, const gchar* account_name);
 355
 356 /**
 357  * modest_server_account_modest_server_account_get_hostnameget_username:
 358  * @self: a ModestAccountMgr instance
 359  * @account_name: The name of a server account.
 360  *
 361  * Gets the hostname this server account.
 362  *
 363  * Returns: The hostname.
 364  */
 365 gchar*
 366 modest_server_account_get_hostname (ModestAccountMgr *self, const gchar* account_name);
 367
 368
 369 /**
 370  * modest_server_account_get_secure_auth:
 371  * @self: a ModestAccountMgr instance
 372  * @account_name: The name of a server account.
 373  *
 374  * Gets the secure authentication method for this server account.
 375  *
 376  * Returns: The secure authentication enum value.
 377  */
 378 ModestAuthProtocol
 379 modest_server_account_get_secure_auth (ModestAccountMgr *self, const gchar* account_name);
 380
 381 /**
 382  * modest_server_account_data_get_secure_auth:
 383  * @self: a ModestAccountMgr instance
 384  * @account_name: The name of a server account.
 385  * @secure_auth: The secure authentication enum value.
 386  *
 387  * Gets the secure authentication method for this server account.
 388  */
 389 void
 390 modest_server_account_set_secure_auth (ModestAccountMgr *self, const gchar* account_name,
 391                                        ModestAuthProtocol secure_auth);
 392
 393 /**
 394  * modest_server_account_data_get_security:
 395  * @self: a ModestAccountMgr instance
 396  * @account_name: The name of a server account.
 397  *
 398  * Gets the security method for this server account.
 399  *
 400  * Returns: The security enum value.
 401  */
 402 ModestConnectionProtocol
 403 modest_server_account_get_security (ModestAccountMgr *self, const gchar* account_name);
 404
 405 /**
 406  * modest_server_account_set_security:
 407  * @self: a ModestAccountMgr instance
 408  * @secure_auth: The security enum value.
 409  *
 410  * Gets the security method for this server account.
 411  */
 412 void
 413 modest_server_account_set_security (ModestAccountMgr *self, const gchar* account_name,
 414                                     ModestConnectionProtocol security);
 415
 416 ModestServerAccountData*
 417 modest_account_mgr_get_server_account_data (ModestAccountMgr *self, const gchar* name);
 418
 419 void
 420 modest_account_mgr_free_server_account_data (ModestAccountMgr *self,
 421                                              ModestServerAccountData* data);
 422
 423 /**
 424  * modest_account_mgr_get_from_string
 425  * @self: a #ModestAccountMgr instance
 426  * @name: the account name
 427  *
 428  * get the From: string for some account; ie. "Foo Bar" <foo.bar@cuux.yy>"
 429  *
 430  * Returns: the newly allocated from-string, or NULL in case of error
 431  */
 432 gchar * modest_account_mgr_get_from_string (ModestAccountMgr *self, const gchar* name);
 433
 434
 435 /**
 436  * modest_account_mgr_get_unused_account_name
 437  * @self: a #ModestAccountMgr instance
 438  * @name: The initial account name
 439  *
 440  * get an unused account name, based on a starting string.
 441  *
 442  * Returns: the newly allocated name.
 443  */
 444 gchar*
 445 modest_account_mgr_get_unused_account_name (ModestAccountMgr *self, const gchar* starting_name,
 446         gboolean server_account);
 447
 448 /**
 449  * modest_account_mgr_get_unused_account_display name
 450  * @self: a #ModestAccountMgr instance
 451  * @name: The initial account display name
 452  *
 453  * get an unused account display name, based on a starting string.
 454  *
 455  * Returns: the newly allocated name.
 456  */
 457 gchar*
 458 modest_account_mgr_get_unused_account_display_name (ModestAccountMgr *self, const gchar* starting_name);
 459
 460 G_END_DECLS
 461
 462 #endif /* __MODEST_ACCOUNT_MGR_H__ */