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