email-api/include/email-api-account.h

   1 /*
   2 *  email-service
   3 *
   4 * Copyright (c) 2012 - 2013 Samsung Electronics Co., Ltd. All rights reserved.
   5 *
   6 * Contact: Kyuho Jo <kyuho.jo@samsung.com>, Sunghyun Kwon <sh0701.kwon@samsung.com>
   7 *
   8 * Licensed under the Apache License, Version 2.0 (the "License");
   9 * you may not use this file except in compliance with the License.
  10 * You may obtain a copy of the License at
  11 *
  12 * http://www.apache.org/licenses/LICENSE-2.0
  13 *
  14 * Unless required by applicable law or agreed to in writing, software
  15 * distributed under the License is distributed on an "AS IS" BASIS,
  16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17 * See the License for the specific language governing permissions and
  18 * limitations under the License.
  19 *
  20 */
  21
  22
  23 #ifndef __EMAIL_API_ACCOUNT_H__
  24 #define __EMAIL_API_ACCOUNT_H__
  25
  26 #include "email-types.h"
  27
  28 /**
  29 * @defgroup EMAIL_SERVICE Email Service
  30 * @{
  31 */
  32
  33
  34 /**
  35 * @ingroup EMAIL_SERVICE
  36 * @defgroup EMAIL_API_ACCOUNT Email Account API
  37 * @{
  38 */
  39
  40 /**
  41  *
  42  * This file contains the data structures and interfaces needed for application,
  43  * to interact with email-service.
  44  * @file                email-api-account.h
  45  * @author      Kyuho Jo <kyuho.jo@samsung.com>
  46  * @author      Sunghyun Kwon <sh0701.kwon@samsung.com>
  47  * @version     0.1
  48  * @brief               This file contains the data structures and interfaces of Accounts provided by
  49  *                      email-service .
  50  *
  51 * @{
  52
  53 * @code
  54 *       #include "email-api-account.h"
  55 *        bool
  56 *       other_app_invoke_uniform_api_sample(int* error_code)
  57 *       {
  58 *       email_account_t *account = NULL;
  59 *       email_account_t *new_account = NULL;
  60 *
  61 *       account = malloc(sizeof(email_account_t));
  62 *       memset(account, 0x00, sizeof(email_account_t));
  63 *
  64 *       account->retrieval_mode         = 1;
  65 *       account->incoming_server_secure_connection           = 1;
  66 *       account->outgoing_server_type    = EMAIL_SERVER_TYPE_SMTP;
  67 *       account->outgoing_server_port_number       = EMAIL_SMTP_PORT;
  68 *       account->outgoing_server_need_authentication           = 1;
  69 *       account->account_name           = strdup("gmail");
  70 *       account->display_name           = strdup("Tom");
  71 *       account->user_email_address             = strdup("tom@gmail.com");
  72 *       account->reply_to_addr          = strdup("tom@gmail.com");
  73 *       account->return_addr            = strdup("tom@gmail.com");
  74 *       account->incoming_server_type  = EMAIL_SERVER_TYPE_POP3;
  75 *       account->incoming_server_address  = strdup("pop3.gmail.com");
  76 *       account->incoming_server_port_number               = 995;
  77 *       account->incoming_server_secure_connection           = 1;
  78 *       account->retrieval_mode         = EMAIL_IMAP4_RETRIEVAL_MODE_ALL;
  79 *       account->incoming_server_user_name              = strdup("tom");
  80 *       account->password               = strdup("password");
  81 *       account->outgoing_server_type    = EMAIL_SERVER_TYPE_SMTP;
  82 *       account->outgoing_server_address    = strdup("smtp.gmail.com");
  83 *       account->outgoing_server_port_number       = 587;
  84 *       account->outgoing_server_secure_connection       = 0x02;
  85 *       account->outgoing_server_need_authentication           = 1;
  86 *       account->outgoing_server_user_name           = strdup("tom@gmail.com");
  87 *       account->sending_password       = strdup("password");
  88 *       account->pop_before_smtp        = 0;
  89 *       account->incoming_server_requires_apop                   = 0;
  90 *       account->flag1                  = 2;
  91 *       account->flag2                  = 1;
  92 *       account->is_preset_account         = 1;
  93 *       account->logo_icon_path         = strdup("Logo Icon Path");
  94 *       account->options.priority = 3;
  95 *       account->options.keep_local_copy = 0;
  96 *       account->options.req_delivery_receipt = 0;
  97 *       account->options.req_read_receipt = 0;
  98 *       account->options.download_limit = 0;
  99 *       account->options.block_address = 0;
 100 *       account->options.block_subject = 0;
 101 *       account->options.display_name_from = strdup("Display name from");
 102 *       account->options.reply_with_body = 0;
 103 *       account->options.forward_with_files = 0;
 104 *       account->options.add_myname_card = 0;
 105 *       account->options.add_signature = 0;
 106 *       account->options.signature= strdup("Signature");
 107 *       account->check_interval = 0;
 108 *       // Add account
 109 *       if(EMAIL_ERROR_NONE != email_add_account(account))
 110 *               //failure
 111 *       //else
 112 *       {
 113 *               //success
 114 *               if(account_id)
 115 *                       *account_id = account->account_id;
 116 *       }
 117 *       if(EMAIL_ERROR_NONE != email_validate_account(account_id,&account_handle))
 118 *               //failure
 119 *       else
 120 *             //success
 121 *       if(EMAIL_ERROR_NONE != email_delete_account(account_id))
 122 *               //failure
 123 *       else
 124 *               //success
 125 *       new_account = malloc(sizeof(email_account_t));
 126 *       memset(new_account, 0x00, sizeof(email_account_t));
 127 *       new_account->flag1                   = 1;
 128 *       new_account->account_name            = strdup("samsung001");
 129 *       new_account->display_name            = strdup("Tom001");
 130 *       new_account->options.keep_local_copy = 1;
 131 *       new_account->check_interval          = 55;
 132 *       // Update account
 133 *       if(EMAIL_ERROR_NONE != email_update_account(acount_id,new_account))
 134 *               //failure
 135 *       else
 136 *               //success
 137 *       // Get account
 138 *       if(EMAIL_ERROR_NONE != email_get_account(account_id,GET_FULL_DATA,&account))
 139 *               //failure
 140 *       else
 141 *               //success
 142 *       // Get list of accounts
 143 *       if(EMAIL_ERROR_NONE != email_get_account_list(&account_list,&count))
 144 *               //failure
 145 *       else
 146 *               //success
 147 *       // free account
 148 *       email_free_account(&account, 1);
 149 *       }
 150  *
 151  * @endcode
 152  * @}
 153  */
 154
 155
 156 #ifdef __cplusplus
 157 extern "C" {
 158 #endif /* __cplusplus */
 159
 160 /**
 161
 162  * @fn email_add_account(email_account_t* account)
 163  * @brief       Create a new email account.This function is invoked when user wants to add new email account
 164  *
 165  * @param[in] account   Specifies the structure pointer of account.
 166  * @exception  none
 167  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 168  * @see         email_account_t
 169  * @remarks N/A
 170  */
 171 EXPORT_API int email_add_account(email_account_t* account);
 172
 173 /**
 174
 175  * @fn email_delete_account(int account_id)
 176  * @brief        Delete a email account.This function is invoked when user wants to delete an existing email account
 177  *
 178  * @param[in] account_id        Specifies the account ID.
 179  * @exception  EMAIL_ERROR_INVALID_PARAM                -Invalid argument
 180  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 181  * @see
 182  * @remarks N/A
 183  */
 184 EXPORT_API int email_delete_account(int account_id);
 185
 186 /**
 187
 188  * @fn email_update_account(int account_id, email_account_t* new_account)
 189  * @brief       Change the information of a email account.This function is getting invoked when user wants to change some information of existing email account.
 190  *
 191  * @param[in] account_id        Specifies the orignal account ID.
 192  * @param[in] new_account       Specifies the information of new account.
 193  * @param[in] with_validation   If this is 1, email-service will validate the account before updating. If this is 0, email-service will update the account without validation.
 194  * @exception EMAIL_ERROR_INVALID_PARAM         -Invalid argument
 195  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 196  * @see email_account_t
 197  * @remarks N/A
 198  */
 199 EXPORT_API int email_update_account(int account_id, email_account_t* new_account);
 200
 201 /**
 202
 203  * @fn email_update_account_with_validation(int account_id, email_account_t* new_account)
 204  * @brief       Change the information of a email account.This function is getting invoked when user wants to change some information of existing email account.
 205  *
 206  * @param[in] account_id        Specifies the orignal account ID.
 207  * @param[in] new_account       Specifies the information of new account.
 208  * @param[in] with_validation   If this is 1, email-service will validate the account before updating. If this is 0, email-service will update the account without validation.
 209  * @exception EMAIL_ERROR_INVALID_PARAM         -Invalid argument
 210  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 211  * @see email_account_t
 212  * @remarks N/A
 213  */
 214 EXPORT_API int email_update_account_with_validation(int account_id, email_account_t* new_account);
 215
 216 /**
 217
 218  * @fn  email_get_account(int account_id, int pulloption, email_account_t** account)
 219  * @brief       Get an email account by ID. This function is getting invoked when user wants to get the account informantion based on account id and option (GET_FULL_DATA/WITHOUT_OPTION/ONLY_OPTION).<br>
 220  *                      Memory for account information will be allocated to 3rd param(account). The allocated memory should be freed by email_free_account().
 221  *
 222  * @param[in] account_id        Specifies the account ID.This function is invoked when user
 223  * @param[in] pulloption        Option to specify to get full details or partial, see definition of EMAIL_ACC_GET_OPT_XXX
 224  * @param[out] account          The returned account is saved here.
 225  * @exception EMAIL_ERROR_INVALID_PARAM         -Invalid argument
 226  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 227  * @see email_account_t
 228  * @remarks N/A
 229  */
 230
 231 EXPORT_API int email_get_account(int account_id, int pulloption, email_account_t** account);
 232
 233 /**
 234
 235  * @fn email_get_account_list(email_account_t** account_list, int* count);
 236  * @brief       Get Account List.This function is getting invoked when user wants to get all account information based on the count of accounts provided by user.<br>
 237  *                      Memory for account information will be allocated to 3rd param(account). The allocated memory should be freed by email_free_account().
 238  *
 239  * @param[in] account_list      Specifies the structure pointer of account.
 240  * @param[out] count                    Specifies the count of accounts.
 241  * @exception EMAIL_ERROR_INVALID_PARAM         -Invalid argument
 242  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 243  * @see email_account_t
 244  * @remarks N/A
 245  */
 246 EXPORT_API int email_get_account_list(email_account_t** account_list, int* count);
 247
 248  /**
 249
 250  * @fn   email_free_account(email_account_t** account_list, int count);
 251  * @brief       Free allocated memory.This function is getting invoked when user wants to delete all account information.
 252  *
 253  * @param[in] account_list      Specifies the structure pointer of account.
 254  * @param[out] count                    Specifies the count of accounts.
 255  * @exception EMAIL_ERROR_INVALID_PARAM         -Invalid argument
 256  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 257  * @see email_account_t
 258  * @remarks N/A
 259  */
 260 EXPORT_API int email_free_account(email_account_t** account_list, int count);
 261
 262
 263 /**
 264
 265  * @fn email_validate_account(int account_id, int *handle)
 266  * @brief       Validate account.This function is getting invoked  after adding one account to validate it.If account is not validated then user should retry once again to add the account .
 267  *
 268  * @param[in] account_id               Specifies the account Id to validate.
 269  * @param[out] handle           Specifies the sending handle.
 270  * @remarks N/A
 271  * @exception EMAIL_ERROR_INVALID_PARAM         -Invalid argument
 272  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 273  * @see         none
 274  * @remarks N/A
 275  */
 276 EXPORT_API int email_validate_account(int account_id, int *handle);
 277
 278 /**
 279
 280  * @fn email_add_account_with_validation(email_account_t* account, int *handle)
 281  * @brief       Add an account when the account is validated. This function is getting invoked when user want to validate an account. If account is not validated then user should retry once again to add the account.<br>
 282  *              Validation is executed without saving an account to DB
 283  *
 284  * @param[in] account       Specifies the structure pointer of account.
 285  * @param[out] handle           Specifies the sending handle.
 286  * @remarks N/A
 287  * @return This function returns true on success or false on failure.
 288  */
 289 EXPORT_API int email_add_account_with_validation(email_account_t* account, int *handle);
 290
 291
 292 /**
 293
 294  * @fn email_backup_accounts_into_secure_storage(const char *file_name)
 295  * @brief       Back up information of all accounts into secure storage.
 296  *          This function is getting invoked when user want to backup account information safely.
 297  *
 298  * @param[in] file_name     Specifies the file name in secure storage
 299  * @remarks N/A
 300  * @return This function returns true on success or false on failure.
 301  */
 302 EXPORT_API int email_backup_accounts_into_secure_storage(const char *file_name);
 303
 304 /**
 305
 306  * @fn email_restore_accounts_from_secure_storage(const char *file_name)
 307  * @brief       Restore accounts from stored file in secure storage.
 308  *          This function is getting invoked when user want to restore accounts.
 309  *
 310  * @param[in] file_name     Specifies the file name in secure storage
 311  * @remarks N/A
 312  * @return This function returns true on success or false on failure.
 313  */
 314 EXPORT_API int email_restore_accounts_from_secure_storage(const char * file_name);
 315
 316 /**
 317
 318  * @fn email_get_password_length_of_account(const int account_id, int *password_length)
 319  * @brief       Get password length of an account.
 320  *          This function is getting invoked when user want to know the length of an account.
 321  *
 322  * @param[in] account_id    Specifies the account id
 323  * @param[out] handle           Specifies the password length.
 324  * @remarks N/A
 325  * @return This function returns true on success or false on failure.
 326  */
 327 EXPORT_API int email_get_password_length_of_account(const int account_id, int *password_length);
 328
 329
 330 /**
 331
 332  * @fn email_query_server_info(const char* domain_name, email_server_info_t **result_server_info)
 333  * @brief       Query email server information.
 334  *          This function is getting invoked when user want to get email server information.
 335  *
 336  * @param[in] domain_name               Specifies the domain name of server
 337  * @param[out] result_server_info       Specifies the information of email server.
 338  * @remarks N/A
 339  * @return This function returns true on success or false on failure.
 340  */
 341 EXPORT_API int email_query_server_info(const char* domain_name, email_server_info_t **result_server_info);
 342
 343 /**
 344
 345  * @fn email_free_server_info(email_server_info_t **result_server_info)
 346  * @brief       Free email_server_info_t.
 347  *          This function is getting invoked when user want to free email_server_info_t.
 348  *
 349  * @param[in] result_server_info        Specifies the pointer of  in secure storage
 350  * @remarks N/A
 351  * @return This function returns true on success or false on failure.
 352  */
 353 EXPORT_API int email_free_server_info(email_server_info_t **result_server_info);
 354
 355 /**
 356
 357  * @fn email_update_notification_bar(int account_id)
 358  * @brief       Update notifications on notification bar.
 359  *          This function is getting invoked when user want to update notification bar.
 360  *
 361  * @param[in] account_id                Specifies the id of account.
 362  * @remarks N/A
 363  * @return This function returns true on success or false on failure.
 364  */
 365 EXPORT_API int email_update_notification_bar(int account_id);
 366
 367 /**
 368
 369  * @fn email_clear_all_notification_bar()
 370  * @brief       Clear all notification on notification bar.
 371  *          This function is getting invoked when user want to clear notification bar.
 372  *
 373  * @remarks N/A
 374  * @return This function returns true on success or false on failure.
 375  */
 376 EXPORT_API int email_clear_all_notification_bar();
 377
 378
 379 /**
 380
 381  * @fn email_save_default_account_id()
 382  * @brief       Save default account id to vconf storage.
 383  *          This function is getting invoked when user want to save default account id.
 384  *
 385  * @remarks N/A
 386  * @return This function returns true on success or false on failure.
 387  */
 388 EXPORT_API int email_save_default_account_id(int input_account_id);
 389
 390 /**
 391
 392  * @fn email_load_default_account_id()
 393  * @brief       Load default account id to vconf storage.
 394  *          This function is getting invoked when user want to load default account id.
 395  *
 396  * @remarks N/A
 397  * @return This function returns true on success or false on failure.
 398  */
 399 EXPORT_API int email_load_default_account_id(int *output_account_id);
 400
 401 #ifdef __cplusplus
 402 }
 403 #endif /* __cplusplus */
 404
 405 /**
 406 * @} @}
 407 */
 408
 409 #endif /* __EMAIL_API_ACCOUNT_H__ */
 410
 411