email-api/include/email-api-mail.h

   1 /*
   2 *  email-service
   3 *
   4 * Copyright (c) 2000 - 2011 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_MAIL_H__
  24 #define __EMAIL_API_MAIL_H__
  25
  26 #include "email-types.h"
  27
  28 #include <time.h>
  29
  30 #include <sys/types.h>
  31 #include <sys/stat.h>
  32 #include <unistd.h>
  33
  34 /**
  35 * @defgroup EMAIL_SERVICE Email Service
  36 * @{
  37 */
  38
  39
  40 /**
  41 * @ingroup EMAIL_SERVICE
  42 * @defgroup EMAIL_API_MAIL Email Mail API
  43 * @{
  44 */
  45
  46 /**
  47  *
  48  * This file contains the data structures and interfaces needed for application,
  49  * to interact with email-service.
  50  * @file                email-api-mail.h
  51  * @author      Kyuho Jo <kyuho.jo@samsung.com>
  52  * @author      Sunghyun Kwon <sh0701.kwon@samsung.com>
  53  * @version     0.1
  54  * @brief               This file contains the data structures and interfaces of Messages provided by
  55  *                      email-service .
  56  */
  57
  58
  59
  60 #ifdef __cplusplus
  61 extern "C" {
  62 #endif /* __cplusplus */
  63
  64 /**
  65  * @open
  66  * @fn email_add_mail(email_mail_data_t *input_mail_data, email_attachment_data_t *input_attachment_data_list, int input_attachment_count, email_meeting_request_t* input_meeting_request, int input_from_eas)
  67  * @brief       Save a mail. This function is invoked when user wants to add a mail.
  68  *              If the option from_eas is 1 then this will save the message on server as well as on locally.
  69  *              If the incoming_server_type is EMAIL_SERVER_TYPE_POP3 then from_eas value will be 0
  70  *              If the incoming_server_type is EMAIL_SERVER_TYPE_IMAP4 then from_eas value will be 1/0
  71  *
  72  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
  73  * @param[in] input_mail_data   Specifies the saving mail.
  74  * @param[in] input_attachment_data_list        Specifies the mailbox structure for saving email.
  75  * @param[in] input_attachment_count    Specifies if the mail comes from composer.
  76  * @param[in] input_meeting_request     Specifies if the mail comes from composer.
  77  * @param[in] input_from_eas    Specifies if the mail will be saved on server.
  78
  79  * @exception   none
  80  * @see email_mail_data_t and email_mailbox_t
  81  * @remarks N/A
  82  * @code
  83  * #include "email-api-mail.h"
  84  * int _test_add_mail ()
  85  * {
  86  *      int                    i = 0;
  87  *      int                    account_id = 0;
  88  *      int                    from_eas = 0;
  89  *      int                    attachment_count = 0;
  90  *      int                    err = EMAIL_ERROR_NONE;
  91  *      char                   arg[50] = { 0 , };
  92  *      char                  *body_file_path = "/opt/data/email/.emfdata/tmp/mail.txt";
  93  *      email_mailbox_t         *mailbox_data = NULL;
  94  *      email_mail_data_t       *test_mail_data = NULL;
  95  *      email_attachment_data_t *attachment_data = NULL;
  96  *      email_meeting_request_t *meeting_req = NULL;
  97  *      FILE                  *body_file;
  98  *
  99  *      printf("\n > Enter account id : ");
 100  *      scanf("%d", &account_id);
 101  *
 102  *
 103  *      memset(arg, 0x00, 50);
 104  *      printf("\n > Enter mailbox name : ");
 105  *      scanf("%s", arg);
 106  *
 107  *      email_get_mailbox_by_name(account_id, arg, &mailbox_data);
 108  *
 109  *      test_mail_data = malloc(sizeof(email_mail_data_t));
 110  *      memset(test_mail_data, 0x00, sizeof(email_mail_data_t));
 111  *
 112  *      printf("\n From EAS? [0/1]> ");
 113  *      scanf("%d", &from_eas);
 114  *
 115  *      test_mail_data->account_id        = account_id;
 116  *      test_mail_data->save_status       = 1;
 117  *      test_mail_data->flags_seen_field  = 1;
 118  *      test_mail_data->file_path_plain   = strdup(body_file_path);
 119  *      test_mail_data->mailbox_id        = mailbox_data->mailbox_id;
 120  *      test_mail_data->mailbox_type      = mailbox_data->mailbox_type;
 121  *      test_mail_data->full_address_from = strdup("<test1@test.com>");
 122  *      test_mail_data->full_address_to   = strdup("<test2@test.com>");
 123  *      test_mail_data->full_address_cc   = strdup("<test3@test.com>");
 124  *      test_mail_data->full_address_bcc  = strdup("<test4@test.com>");
 125  *      test_mail_data->subject           = strdup("Meeting request mail");
 126  *
 127  *      body_file = fopen(body_file_path, "w");
 128  *
 129  *      for(i = 0; i < 500; i++)
 130  *              fprintf(body_file, "X2 X2 X2 X2 X2 X2 X2");
 131  *      fflush(body_file);
 132  *   fclose(body_file);
 133  *
 134  *      printf(" > Attach file? [0/1] : ");
 135  *      scanf("%d",&attachment_count);
 136  *
 137  *      if ( attachment_count )  {
 138  *              memset(arg, 0x00, 50);
 139  *              printf("\n > Enter attachment name : ");
 140  *              scanf("%s", arg);
 141  *
 142  *              attachment_data = malloc(sizeof(email_attachment_data_t));
 143  *
 144  *              attachment_data->attachment_name  = strdup(arg);
 145  *
 146  *              memset(arg, 0x00, 50);
 147  *              printf("\n > Enter attachment absolute path : ");
 148  *              scanf("%s",arg);
 149  *
 150  *              attachment_data->attachment_path  = strdup(arg);
 151  *              attachment_data->save_status      = 1;
 152  *              test_mail_data->attachment_count  = attachment_count;
 153  *      }
 154  *
 155  *      printf("\n > Meeting Request? [0: no, 1: yes (request from server), 2: yes (response from local)]");
 156  *      scanf("%d", &(test_mail_data->meeting_request_status));
 157  *
 158  *      if ( test_mail_data->meeting_request_status == 1
 159  *              || test_mail_data->meeting_request_status == 2 ) {
 160  *              time_t current_time;
 161  *              meeting_req = malloc(sizeof(email_meeting_request_t));
 162  *              memset(meeting_req, 0x00, sizeof(email_meeting_request_t));
 163  *
 164  *              meeting_req->meeting_response     = 1;
 165  *              current_time = time(NULL);
 166  *              gmtime_r(&current_time, &(meeting_req->start_time));
 167  *              gmtime_r(&current_time, &(meeting_req->end_time));
 168  *              meeting_req->location = malloc(strlen("Seoul") + 1);
 169  *              memset(meeting_req->location, 0x00, strlen("Seoul") + 1);
 170  *              strcpy(meeting_req->location, "Seoul");
 171  *              strcpy(meeting_req->global_object_id, "abcdef12345");
 172  *
 173  *              meeting_req->time_zone.offset_from_GMT = 9;
 174  *              strcpy(meeting_req->time_zone.standard_name, "STANDARD_NAME");
 175  *              gmtime_r(&current_time, &(meeting_req->time_zone.standard_time_start_date));
 176  *              meeting_req->time_zone.standard_bias = 3;
 177  *
 178  *              strcpy(meeting_req->time_zone.daylight_name, "DAYLIGHT_NAME");
 179  *              gmtime_r(&current_time, &(meeting_req->time_zone.daylight_time_start_date));
 180  *              meeting_req->time_zone.daylight_bias = 7;
 181  *
 182  *      }
 183  *
 184  *      if((err = email_add_mail(test_mail_data, attachment_data, attachment_count, meeting_req, from_eas)) != EMAIL_ERROR_NONE)
 185  *              printf("email_add_mail failed. [%d]\n", err);
 186  *      else
 187  *              printf("email_add_mail success.\n");
 188  *
 189  *      if(attachment_data)
 190  *              email_free_attachment_data(&attachment_data, attachment_count);
 191  *
 192  *      if(meeting_req)
 193  *              email_free_meeting_request(&meeting_req, 1);
 194  *
 195  *      email_free_mail_data(&test_mail_data, 1);
 196  *      email_free_mailbox(&mailbox_data, 1);
 197  *
 198  *      printf("saved mail id = [%d]\n", test_mail_data->mail_id);
 199  *
 200  *      return 0;
 201  * }
 202  * @endcode
 203  */
 204 EXPORT_API int email_add_mail(email_mail_data_t *input_mail_data, email_attachment_data_t *input_attachment_data_list, int input_attachment_count, email_meeting_request_t* input_meeting_request, int input_from_eas);
 205
 206  /**
 207   * @open
 208   * @fn email_add_read_receipt(int input_read_mail_id,  unsigned *output_handle)
 209   * @brief      Add a read receipt mail. This function is invoked when user receives a mail with read report enable and wants to send a read report for the same.
 210   *
 211   * @return     This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 212   * @param[in]  input_read_mail_id      Specifies the id of mail which has been read.
 213   * @param[out] output_receipt_mail_id  Specifies the receipt mail id .
 214   * @exception none
 215   * @see
 216   * @remarks N/A
 217   */
 218 EXPORT_API int email_add_read_receipt(int input_read_mail_id, int *output_receipt_mail_id);
 219
 220 /**
 221  * @open
 222  * @fn email_update_mail(email_mail_data_t *input_mail_data, email_attachment_data_t *input_attachment_data_list, int input_attachment_count, email_meeting_request_t* input_meeting_request, int input_from_composer)
 223  * @brief       Update a existing email information. This function is invoked when user wants to change some existing email information with new email information.
 224  *
 225  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 226  * @param[in] input_mail_data           Specifies the mail ID.
 227  * @param[in] input_attachment_data_list        Specifies the pointer of attachment data.
 228  * @param[in] input_attachment_count    Specifies the number of attachment data.
 229  * @param[in] input_meeting_request     Specifies the meeting request data.
 230  * @param[in] input_from_eas Specifies whether sync server.
 231
 232  * @exception   none
 233  * @see         email_mail_data_t
 234  * @code
 235  * #include "email-api-account.h"
 236  * int email_test_update_mail()
 237  * {
 238  *      int                    mail_id = 0;
 239  *      int                    err = EMAIL_ERROR_NONE;
 240  *      int                    test_attachment_data_count = 0;
 241  *      char                   arg[50];
 242  *      email_mail_data_t       *test_mail_data = NULL;
 243  *      email_attachment_data_t *test_attachment_data_list = NULL;
 244  *      email_meeting_request_t *meeting_req = NULL;
 245  *
 246  *      printf("\n > Enter mail id : ");
 247  *      scanf("%d", &mail_id);
 248  *
 249  *      email_get_mail_data(mail_id, &test_mail_data);
 250  *
 251  *      printf("\n > Enter Subject: ");
 252  *      scanf("%s", arg);
 253  *
 254  *      test_mail_data->subject= strdup(arg);
 255  *
 256  *
 257  *
 258  *      if (test_mail_data->attachment_count > 0) {
 259  *              if ( (err = email_get_attachment_data_list(mail_id, &test_attachment_data_list, &test_attachment_data_count)) != EMAIL_ERROR_NONE ) {
 260  *                      printf("email_get_meeting_request() failed [%d]\n", err);
 261  *                      return -1;
 262  *              }
 263  *      }
 264  *
 265  *      if ( test_mail_data->meeting_request_status == EMAIL_MAIL_TYPE_MEETING_REQUEST
 266  *              || test_mail_data->meeting_request_status == EMAIL_MAIL_TYPE_MEETING_RESPONSE
 267  *              || test_mail_data->meeting_request_status == EMAIL_MAIL_TYPE_MEETING_ORIGINATINGREQUEST) {
 268  *
 269  *              if ( (err = email_get_meeting_request(mail_id, &meeting_req)) != EMAIL_ERROR_NONE ) {
 270  *                      printf("email_get_meeting_request() failed [%d]\n", err);
 271  *                      return -1;
 272  *              }
 273  *
 274  *              printf("\n > Enter meeting response: ");
 275  *              scanf("%d", (int*)&(meeting_req->meeting_response));
 276  *      }
 277  *
 278  *      if ( (err = email_update_mail(test_mail_data, test_attachment_data_list, test_attachment_data_count, meeting_req, 0)) != EMAIL_ERROR_NONE)
 279  *                      printf("email_update_mail failed.[%d]\n", err);
 280  *              else
 281  *                      printf("email_update_mail success\n");
 282  *
 283  *      if(test_mail_data)
 284  *              email_free_mail_data(&test_mail_data, 1);
 285  *
 286  *      if(test_attachment_data_list)
 287  *              email_free_attachment_data(&test_attachment_data_list, test_attachment_data_count);
 288  *
 289  *      if(meeting_req)
 290  *              email_free_meeting_request(&meeting_req, 1);
 291  *
 292  *      return 0;
 293  * }
 294
 295  * @endcode
 296  * @remarks N/A
 297  */
 298 EXPORT_API int email_update_mail(email_mail_data_t *input_mail_data, email_attachment_data_t *input_attachment_data_list, int input_attachment_count, email_meeting_request_t* input_meeting_request, int input_from_eas);
 299
 300 /**
 301  * @open
 302  * @fn email_count_mail(email_mailbox_t* mailbox, int* total, int* unseen)
 303  * @brief       Get mail count from mailbox.This function is invoked when user wants to know how many toatl mails and out of that
 304  *              how many unseen mails are there in a given mailbox.
 305  *
 306  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 307  * @param[in] mailbox   Specifies the pointer of mailbox structure.
 308  * @param[out] total    Total email count is saved here.
 309  * @param[out] unseen   Unread email count is saved here.
 310  * @exception   none
 311  * @see         email_mailbox_t
 312
 313  * @code
 314  *      #include "email-api-account.h"
 315  *      bool
 316  *      _api_sample_count_mail()
 317  *      {
 318  *              int total = 0;
 319  *              int unseen = 0;
 320  *              email_list_filter_t *filter_list = NULL;
 321  *              int err = EMAIL_ERROR_NONE;
 322  *              int i = 0;
 323  *              filter_list = malloc(sizeof(email_list_filter_t) * 3);
 324  *              memset(filter_list, 0 , sizeof(email_list_filter_t) * 3);
 325  *
 326  *              filter_list[0].list_filter_item_type                               = EMAIL_LIST_FILTER_ITEM_RULE;
 327  *              filter_list[0].list_filter_item.rule.target_attribute              = EMAIL_MAIL_ATTRIBUTE_SUBJECT;
 328  *              filter_list[0].list_filter_item.rule.rule_type                     = EMAIL_LIST_FILTER_RULE_INCLUDE;
 329  *              filter_list[0].list_filter_item.rule.key_value.string_type_value   = strdup("RE");
 330  *              filter_list[0].list_filter_item.rule.case_sensitivity              = false;
 331  *
 332  *              filter_list[1].list_filter_item_type                               = EMAIL_LIST_FILTER_ITEM_OPERATOR;
 333  *              filter_list[1].list_filter_item.operator_type                      = EMAIL_LIST_FILTER_OPERATOR_OR;
 334  *
 335  *              filter_list[2].list_filter_item_type                               = EMAIL_LIST_FILTER_ITEM_RULE;
 336  *              filter_list[2].list_filter_item.rule.target_attribute              = EMAIL_MAIL_ATTRIBUTE_TO;
 337  *              filter_list[2].list_filter_item.rule.rule_type                     = EMAIL_LIST_FILTER_RULE_INCLUDE;
 338  *              filter_list[2].list_filter_item.rule.key_value.string_type_value   = strdup("RE");
 339  *              filter_list[2].list_filter_item.rule.case_sensitivity              = false;
 340  *
 341  *              if(EMAIL_ERROR_NONE == email_count_mail(filter_list, 3, &total, &unseen))
 342  *                      printf("\n Total: %d, Unseen: %d \n", total, unseen);
 343  *      }
 344  * @endcode
 345  * @remarks N/A
 346  */
 347 EXPORT_API int email_count_mail(email_list_filter_t *input_filter_list, int input_filter_count, int *output_total_mail_count, int *output_unseen_mail_count);
 348
 349 /**
 350  * @open
 351  * @fn email_get_max_mail_count(int *Count)
 352  * @brief       Gets the max count of mails which can be supported by email-service
 353  *
 354  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 355  * @param[out] Count    max count of mails which can be supported by email-service
 356  * @exception           none
 357  * @code
 358  *      #include "email-api-account.h"
 359  *              bool
 360  *              _api_sample_get_max_mail_count()
 361  *              {
 362  *                      int max_count = -1;
 363  *
 364  *                      if(EMAIL_ERROR_NONE == email_get_max_mail_count(&max_count))
 365  *                              printf("\n\t>>>>> email_get_max_mail_count() return [%d]\n\n", max_count);
 366  *      }
 367  * @endcode
 368  * @remarks N/A
 369  */
 370 EXPORT_API int email_get_max_mail_count(int *count);
 371
 372 /**
 373  * @open
 374  * @fn  email_delete_mail(email_mailbox_t* mailbox, int *mail_ids, int num, int from_server)
 375  * @brief       Delete a mail or multiple mails.Based on from_server value this function will delte a mail or multiple mails from server or loaclly.
 376  * @param[in] mailbox                   Reserved.
 377  *              If the incoming_server_type is EMAIL_SERVER_TYPE_POP3 then from_server value will be 0
 378  *              If the incoming_server_type is EMAIL_SERVER_TYPE_IMAP4 then from_server value will be 1/0
 379  *
 380  * @param[in] mail_ids[]                                Specifies the arrary of mail id.
 381  * @param[in] num                                       Specifies the number of mail id.
 382  * @param[in] from_server       Specifies whether mails are deleted from server.
 383  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 384  * @exception           none
 385  * @see                 email_mailbox_t
 386  * @code
 387  *      #include "email-api-account.h"
 388  *      bool
 389  *      _api_sample_delete_mail()
 390  *      {
 391  *              int count, i, mail_id=0, mailbox_id =0;
 392  *
 393  *              printf("\n > Enter Mail_id: ");
 394  *              scanf("%d",&mail_id);
 395  *              printf("\n > Enter Mailbox ID: ");
 396  *              scanf("%d",&mailbox_id);
 397  *              if(EMAIL_ERROR_NONE == email_delete_mail(mailbox_id, &mail_id, 1, 1))
 398  *                      printf("\n email_delete_mail success");
 399  *              else
 400  *                      printf("\n email_delete_mail failed");
 401  *      }
 402  * @endcode
 403  * @remarks N/A
 404  */
 405 EXPORT_API int email_delete_mail(int input_mailbox_id, int *input_mail_ids, int input_num, int input_from_server);
 406
 407
 408 /**
 409  * @open
 410  * @fn email_delete_all_mails_in_mailbox(int input_mailbox_id, int input_from_server)
 411  * @brief       Delete all mail from a mailbox.
 412  *              If the incoming_server_type is EMAIL_SERVER_TYPE_POP3 then from_server value will be 0
 413  *              If the incoming_server_type is EMAIL_SERVER_TYPE_IMAP4 then from_server value will be 1/0
 414  *
 415  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 416  * @param[in] mailbox                   Specifies the structure of mailbox.
 417  * @param[in] from_server               Specifies whether mails are also deleted from server.
 418  * @exception           none
 419  * @see                 email_mailbox_t
 420
 421  * @code
 422  *      #include "email-api-account.h"
 423  *      bool
 424  *      _api_sample_delete_all_mails_in_mailbox()
 425  *      {
 426  *              int count, mailbox_id =0;
 427  *
 428  *              printf("\n > Enter mailbox_id: ");
 429  *              scanf("%d",&mailbox_id);
 430  *
 431  *              if (EMAIL_ERROR_NONE != email_delete_all_mails_in_mailbox(mailbox_id, 0))
 432  *                      printf("email_delete_all_mails_in_mailbox failed");
 433  *              else
 434  *                      printf("email_delete_all_mails_in_mailbox Success");
 435  *      }
 436  * @endcode
 437  * @remarks N/A
 438  */
 439 EXPORT_API int email_delete_all_mails_in_mailbox(int input_mailbox_id, int input_from_server);
 440
 441 /**
 442  * @open
 443  *  @fn email_clear_mail_data()
 444  * @brief       delete email data from storage. This API will be used by the Settings Application
 445  *
 446  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 447  * @exception           none
 448  * @see                 none
 449
 450  * @code
 451  *      #include "email-api-account.h"
 452  *      bool
 453  *      _api_sample_clear_mail_data()
 454  *      {
 455  *              if(EMAIL_ERROR_NONE == email_clear_mail_data())
 456  *                      //success
 457  *              else
 458  *                      //failure
 459  *
 460  *      }
 461  * @endcode
 462  * @remarks N/A
 463  */
 464 EXPORT_API int  email_clear_mail_data();
 465
 466
 467 /**
 468  * @open
 469  * @fn email_add_attachment(int mail_id, email_attachment_data_t* attachment)
 470  * @brief       Append a attachment to email.This function is invoked when user wants to add attachment to existing mail.
 471  *
 472  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 473  * @param[in] mail_id           Specifies the mail ID.
 474  * @param[in] attachment        Specifies the structure of attachment.
 475  * @exception           none
 476  * @see email_attachment_data_t
 477
 478  * @code
 479  *      #include "email-api-account.h"
 480  *      bool
 481  *      _api_sample_mail_add_attachment()
 482  *      {
 483  *              int mail_id = 0;
 484  *              email_attachment_data_t attachment;
 485  *
 486  *              printf("\n > Enter Mail Id: ");
 487  *              scanf("%d", &mail_id);
 488  *              memset(&attachment, 0x00, sizeof(email_attachment_data_t));
 489  *              printf("\n > Enter attachment name: ");
 490  *              attachment.name = strdup("Test");
 491  *              printf("\n > Enter attachment absolute path: ");
 492  *              attachment.savename = strdup("/tmp/test.txt");
 493  *              attachment.next = NULL;
 494  *              if(EMAIL_ERROR_NONE != email_add_attachment(mail_id, &attachment))
 495  *                      printf("email_add_attachment failed\n");
 496  *              else
 497  *                      printf(email_add_attachment success\n");
 498  *      }
 499  * @endcode
 500  * @remarks N/A
 501  */
 502 EXPORT_API int email_add_attachment(int mail_id, email_attachment_data_t* attachment);
 503
 504
 505 /**
 506  * @open
 507  * @fn email_delete_attachment(int mail_id, const char * attachment_id)
 508  * @brief       delete a attachment from email.This function is invoked when user wants to delete a attachment from existing mailbased on mail Id and attachment Id
 509  *
 510  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 511  * @param[in] mail_id                   Specifies the mail ID.
 512  * @param[in] attachment_id             Specifies the attachment id.
 513  * @exception           none
 514  * @see                 email_mailbox_t
 515  * @code
 516  *      #include "email-api-account.h"
 517  *      bool
 518  *      _api_sample_mail_delete_attachment()
 519  *      {
 520  *
 521  *              if(EMAIL_ERROR_NONE != email_delete_attachment(1))
 522  *                      //failure
 523  *              else
 524  *                      //success
 525  *      }
 526  * @endcode
 527  * @remarks N/A
 528  */
 529 EXPORT_API int email_delete_attachment(int attachment_id);
 530
 531 /**
 532  * @open
 533  * @fn  email_get_attachment_data(int mail_id, const char* attachment_id, email_attachment_data_t** attachment)
 534  * @brief       Get a mail attachment.This function is invoked when user wants to get the attachment information based on attachment id for the specified mail Id.
 535  *
 536  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 537  * @param[in] mail_id           Specifies the mail ID.
 538  * @param[in] attachment_id     Specifies the buffer that a attachment ID been saved.
 539  * @param[out] attachment       The returned attachment is save here.
 540  * @exception           none
 541  * @see                 email_mailbox_t and email_mail_attachment_info_t
 542
 543  * @code
 544  *      #include "email-api-account.h"
 545  *      bool
 546  *      _api_sample_mail_get_attachment_info()
 547  *      {
 548  *              email_mail_attachment_info_t *mail_attach_info = NULL;
 549  *              int mail_id = 0;
 550  *              char arg[10];
 551  *              int err = EMAIL_ERROR_NONE;
 552  *
 553  *
 554  *              printf("\n > Enter Mail Id: ");
 555  *              scanf("%d", &mail_id);
 556  *              printf("> attachment Id\n");
 557  *              scanf("%s",arg);
 558  *              if (EMAIL_ERROR_NONE != email_get_attachment_data(mail_id, &mail_attach_info))
 559  *                      printf("email_get_attachment_data failed\n");
 560  *              else
 561  *              {
 562  *                      printf("email_get_attachment_data SUCCESS\n");
 563  *                      //do something
 564  *                      email_free_attachment_data(&mail_attach_info,1);
 565  *              }
 566  *      }
 567  * @endcode
 568  * @remarks N/A
 569  */
 570 EXPORT_API int email_get_attachment_data(int attachment_id, email_attachment_data_t** attachment);
 571
 572 EXPORT_API int email_get_attachment_data_list(int input_mail_id, email_attachment_data_t **output_attachment_data, int *output_attachment_count);
 573
 574 /**
 575  * @open
 576  * @fn email_free_attachment_data(email_attachment_data_t **attachment_data_list, int attachment_data_count)
 577  * @brief       Free allocated memroy for email attachment.
 578  *
 579  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 580  * @param[in] atch_info Specifies the pointer of mail attachment structure pointer.
 581  * @exception           none
 582  * @see                 email_mail_attachment_info_t
 583
 584  * @code
 585  *      #include "email-api-account.h"
 586  *      bool
 587  *      _api_sample_mail_free_attachment_info()
 588  *      {
 589  *              email_mailbox_t mailbox;
 590  *              email_mail_attachment_info_t *mail_attach_info = NULL;
 591  *              int mail_id = 0,account_id = 0;
 592  *              char arg[10];
 593  *              int err = EMAIL_ERROR_NONE;
 594  *
 595  *              memset(&mailbox, 0x00, sizeof(email_mailbox_t));
 596  *
 597  *              printf("\n > Enter Mail Id: ");
 598  *              scanf("%d", &mail_id);
 599  *              printf("\n > Enter account Id: ");
 600  *              scanf("%d", &account_id);
 601  *              printf("> attachment Id\n");
 602  *              scanf("%s",arg);
 603  *              mailbox.account_id = account_id;
 604  *              if (EMAIL_ERROR_NONE != email_get_attachment_data(&mailbox, mail_id, &mail_attach_info))
 605  *                      printf("email_get_attachment_data failed\n");
 606  *              else
 607  *              {
 608  *                      printf("email_get_attachment_data SUCCESS\n");
 609  *                      //do something
 610  *                      email_free_attachment_info(&mail_attach_info,1);
 611  *              }
 612  *      }
 613  * @endcode
 614  * @remarks N/A
 615  */
 616 EXPORT_API int email_free_attachment_data(email_attachment_data_t **attachment_data_list, int attachment_data_count);
 617
 618 /* -----------------------------------------------------------
 619                                               Mail Information API
 620     -----------------------------------------------------------*/
 621
 622
 623 /**
 624  * @open
 625  * @fn email_query_mails(char *conditional_clause_string, email_mail_data_t** mail_list,  int *result_count)
 626  * @brief                          Query the mail list information from DB based on the mailbox name.
 627  *
 628  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 629  * @param[in] conditional_clause_string  Specifies the where clause string.
 630  * @param[in/out] mail_list        Specifies the pointer to the structure email_mail_data_t.
 631  * @param[in/out] result_count     Specifies the number of mails returned.
 632  * @exception                      None
 633  * @see                            email_mail_list_item_t
 634
 635  * @code
 636  *      #include "email-api-account.h"
 637  *      bool
 638  *      _api_sample_query_mail()
 639  *      {
 640  *              email_mail_data_t *mail_list = NULL;
 641  *              char conditional_clause_string[500];
 642  *              int result_count = 0;
 643  *
 644  *              memset(conditional_clause_string, 0x00, 10);
 645  *              printf("\n > Enter where clause: ");
 646  *              scanf("%s", conditional_clause_string);
 647  *
 648  *
 649  *              if (EMAIL_ERROR_NONE != email_query_mails(conditional_clause_string, &mail_list, &result_count))
 650  *                      printf("email_query_mails failed \n");
 651  *              else {
 652  *                      printf("Success\n");
 653  *                      //do something
 654  *                      free(mail_list);
 655  *              }
 656  *
 657  *      }
 658  * @endcode
 659  * @remarks N/A
 660  */
 661 EXPORT_API int email_query_mails(char *conditional_clause_string, email_mail_data_t** mail_list,  int *result_count);
 662
 663 /**
 664  * @open
 665  * @fn email_query_mail_list(char *input_conditional_clause_string, email_mail_list_item_t** output_mail_list,  int *output_result_count)
 666  * @brief Query the mail list information from DB.
 667  *
 668  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 669  * @param[in] input_conditional_clause_string   Specifies the where clause string.
 670  * @param[in/out] output_mail_list                              Specifies the pointer to the structure email_mail_list_item_t.
 671  * @param[in/out] output_result_count                   Specifies the number of mails returned.
 672  * @exception   None
 673  * @see                 email_mail_list_item_t
 674
 675  * @code
 676  *      #include "email-api-account.h"
 677  *      bool
 678  *      _api_sample_query_mail_list()
 679  *      {
 680  *              email_mail_list_item_t *mail_list = NULL;
 681  *              char conditional_clause_string[500];
 682  *              int result_count = 0;
 683  *
 684  *              memset(conditional_clause_string, 0x00, 10);
 685  *              printf("\n > Enter where clause: ");
 686  *              scanf("%s", conditional_clause_string);
 687  *
 688  *
 689  *              if (EMAIL_ERROR_NONE != email_query_mail_list(conditional_clause_string, &mail_list, &result_count))
 690  *                      printf("email_query_mail_list failed \n");
 691  *              else {
 692  *                      printf("Success\n");
 693  *                      //do something
 694  *                      free(mail_list);
 695  *              }
 696  *
 697  *      }
 698  * @endcode
 699  * @remarks N/A
 700  */
 701 EXPORT_API int email_query_mail_list(char *input_conditional_clause_string, email_mail_list_item_t** output_mail_list,  int *output_result_count);
 702
 703 /**
 704  * @open
 705  * @fn email_get_mail_data(int input_mail_id, email_mail_data_t **output_mail_data)
 706  * @brief       Get a mail by its mail id. This function is invoked when user wants to get a mail based on mail id existing in DB.
 707  *
 708  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 709  * @param[in] input_mail_id     specifies the mail id.
 710  * @param[out] output_mail_data         The returned mail is save here.
 711  * @exception           none
 712  * @see email_mail_data_t
 713
 714  * @code
 715  *    #include "email-api-account.h"
 716  *      bool
 717  *      _api_sample_get_mail_data()
 718  *      {
 719  *              email_mail_data_t *mail = NULL;
 720  *              int mail_id = 0 ;
 721  *              int err = EMAIL_ERROR_NONE;
 722  *
 723  *              printf("\n > Enter mail id: ");
 724  *              scanf("%d", &mail_id);
 725  *
 726  *              if (EMAIL_ERROR_NONE != email_get_mail_data(mail_id, &mail))
 727  *                      printf("email_get_mail_data failed\n");
 728  *              else
 729  *              {
 730  *                      printf("email_get_mail_data SUCCESS\n");
 731  *                      //do something
 732  *                      email_free_mail_data(&mail,1);
 733  *              }
 734  *      }
 735  * @endcode
 736  * @remarks N/A
 737  */
 738
 739 EXPORT_API int email_get_mail_data(int input_mail_id, email_mail_data_t **output_mail_data);
 740
 741
 742 /**
 743  * @open
 744  * @fn email_free_mail_data(email_mail_data_t** mail_list, int count)
 745  * @brief       Free allocated memroy for emails.
 746  *
 747  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 748  * @param[in] mail_list Specifies the pointer of mail structure pointer.
 749  * @param[in] count             Specifies the count of mails.
 750  * @exception           none
 751  * @see                 email_mail_data_t
 752
 753  * @code
 754  *      #include "email-api-account.h"
 755  *      bool
 756  *      _api_sample_free_mail()
 757  *      {
 758  *              email_mail_data_t *mail;
 759  *
 760  *              //fill the mail structure
 761  *              //count - number of mail structure user want to free
 762  *               if(EMAIL_ERROR_NONE == email_free_mail_data(&mail,count))
 763  *                      //success
 764  *               else
 765  *                      //failure
 766  *
 767  *      }
 768  * @endcode
 769  * @remarks N/A
 770  */
 771 EXPORT_API int email_free_mail_data(email_mail_data_t** mail_list, int count);
 772
 773 /* -----------------------------------------------------------
 774                                               Mail Flag API
 775     -----------------------------------------------------------*/
 776
 777 /**
 778  * @open
 779  * @fn email_set_flags_field(int *mail_ids, int num, email_flags_field_type field_type, int value, int onserver)
 780  * @brief       Change email flags field.
 781  *              If the incoming_server_type is EMAIL_SERVER_TYPE_POP3 then from_server value will be 0
 782  *              If the incoming_server_type is EMAIL_SERVER_TYPE_IMAP4 then from_server value will be 1/0
 783  *
 784  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 785  * @param[in] account_id  Specifies account ID.
 786  * @param[in] mail_ids          Specifies the array of mail ID.
 787  * @param[in] num               Specifies the number of mail ID.
 788  * @param[in] field_type  Specifies the field type what you want to set. Refer email_flags_field_type.
 789  * @param[in] value           Specifies the value what you want to set.
 790  * @param[in] onserver          Specifies whether mail Flag updation in server
 791  * @exception           none
 792  * @see                 none
 793  * @code
 794  *      #include "email-api-account.h"
 795  *      bool
 796  *      _api_sample_set_flags_field()
 797  *      {
 798  *              int account_id = 0;
 799  *                      int mail_id = 0;
 800  *                      int err = EMAIL_ERROR_NONE;
 801  *
 802  *                      printf("\n > Enter account id: ");
 803  *                      scanf("%d", &account_id);
 804  *
 805  *                      printf("\n > Enter mail id: ");
 806  *                      scanf("%d", &mail_id);
 807  *                      if (EMAIL_ERROR_NONE != email_set_flags_field(&account_id, &mail_id, EMAIL_FLAGS_SEEN_FIELD, 1, 0))
 808  *                              printf("email_set_flags_field failed\n");
 809  *                      else
 810  *                      {
 811  *                              printf("email_set_flags_field succeed\n");
 812  *                              //do something
 813  *                      }
 814  *      }
 815  * @endcode
 816  * @remarks N/A
 817  */
 818
 819 EXPORT_API int email_set_flags_field(int account_id, int *mail_ids, int num, email_flags_field_type field_type, int value, int onserver);
 820
 821 /* -----------------------------------------------------------
 822                                               Mail Move API
 823     -----------------------------------------------------------*/
 824
 825 /**
 826  * @open
 827  * @fn email_move_mail_to_mailbox(int *mail_ids, int num, int input_target_mailbox_id)
 828  * @brief       Move a email to another mailbox.
 829  *
 830  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 831  * @param[in] mail_id                                   Specifies the array of mail ID.
 832  * @param[in] num                                               Specifies the count of mail IDs.
 833  * @param[in] input_target_mailbox_id   Specifies the mailbox ID for moving email.
 834  * @exception           none
 835  * @see                 email_mailbox_t
 836
 837  * @code
 838  *      #include "email-api-account.h"
 839  *      bool
 840  *      _api_sample_move_mail_to_mailbox()
 841  *      {
 842  *              int mail_id = 0;
 843  *      int mailbox_id = 0;
 844  *              int err = EMAIL_ERROR_NONE;
 845
 846  *              printf("\n > Enter mail_id: ");
 847  *              scanf("%d",&mail_id);
 848  *
 849  *              printf("\n > Enter target mailbox_id: ");
 850  *              scanf("%d",&mailbox_id);
 851  *
 852  *              if(EMAIL_ERROR_NONE == email_move_mail_to_mailbox(&mail_id,     1, mailbox_id))
 853  *                      printf("Success\n");
 854  *
 855  *      }
 856  * @endcode
 857  * @remarks N/A
 858  */
 859 EXPORT_API int email_move_mail_to_mailbox(int *mail_ids, int num, int input_target_mailbox_id);
 860
 861
 862 /**
 863  * @open
 864  * @fn email_move_all_mails_to_mailbox(int input_source_mailbox_id, int input_target_mailbox_id)
 865  * @brief       Move all email to another mailbox.
 866  *
 867  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 868  * @param[in] input_source_mailbox_id   Specifies the source mailbox ID for moving email.
 869  * @param[in] input_target_mailbox_id   Specifies the destination mailbox ID for moving email.
 870  * @exception           none
 871  * @see                 email_mailbox_t
 872
 873  * @code
 874  *      #include "email-api-account.h"
 875  *      bool
 876  *      _api_sample_move_all_mails_to_mailbox()
 877  *      {
 878  *      int src_mailbox_id;
 879  *      int dst_mailbox_id;
 880  *              int total_count;
 881  *              int err = EMAIL_ERROR_NONE;
 882  *              char temp[128];
 883  *
 884  *
 885  *              // input mailbox information : need  account_id and name (src & dest)
 886  *              printf("src mail maibox id> ");
 887  *              scanf("%d", &src_mailbox_id);
 888  *
 889  *              // Destination mailbox
 890  *              printf("dest mailbox id> ");
 891  *              scanf("%d", &dst_mailbox_id);
 892  *
 893  *              if( EMAIL_ERROR_NONE == email_move_all_mails_to_mailbox(src_mailbox_id, dst_mailbox_id))
 894  *              {
 895  *                      printf("  fail email_move_all_mails_to_mailbox: \n");
 896  *              }
 897  *              else
 898  *                      //success
 899  * }
 900  * @endcode
 901  * @remarks N/A
 902  */
 903 EXPORT_API int email_move_all_mails_to_mailbox(int input_source_mailbox_id, int input_target_mailbox_id);
 904
 905
 906 /**
 907  * @open
 908  * @fn email_get_mail_list_ex(email_list_filter_t *input_filter_list, int input_filter_count, email_list_sorting_rule_t *input_sorting_rule_list, int input_sorting_rule_count, int input_start_index, int input_limit_count, email_mail_list_item_t** output_mail_list, int *output_result_count)
 909  * @brief       Get the Mail List information from DB.
 910  *
 911  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 912  * @param[in] input_filter_list                 Specifies the filter list
 913  * @param[in] input_filter_count                Specifies the number of filter
 914  * @param[in] input_sorting_rule_list   Specifies the sorting rule list.
 915  * @param[in] input_sorting_rule_count  Specifies the number of sorting rule
 916  * @param[in] input_start_index                 Specifies start index for LIMIT clause of SQL query.
 917  * @param[in] input_limit_count                 Specifies limit count for LIMIT clause of SQL query.
 918  * @param[in/out] output_mail_list              Specifies the pointer to the structure email_mail_list_item_t.
 919  * @param[in/out] output_result_count   Specifies the number of mails returned.
 920  * @exception           none
 921  * @see             email_mail_list_item_t
 922  * @code
 923  * email_list_filter_t *filter_list = NULL;
 924  * email_list_sorting_rule_t *sorting_rule_list = NULL;
 925  * email_mail_list_item_t *result_mail_list = NULL;
 926  * int result_mail_count = 0;
 927  * int err = EMAIL_ERROR_NONE;
 928  * int i = 0;
 929  * filter_list = malloc(sizeof(email_list_filter_t) * 9);
 930  * memset(filter_list, 0 , sizeof(email_list_filter_t) * 9);
 931  *
 932  * filter_list[0].list_filter_item_type                               = EMAIL_LIST_FILTER_ITEM_RULE;
 933  * filter_list[0].list_filter_item.rule.target_attribute              = EMAIL_MAIL_ATTRIBUTE_SUBJECT;
 934  * filter_list[0].list_filter_item.rule.rule_type                     = EMAIL_LIST_FILTER_RULE_INCLUDE;
 935  * filter_list[0].list_filter_item.rule.key_value.string_type_value   = strdup("RE");
 936  * filter_list[0].list_filter_item.rule.case_sensitivity              = false;
 937  *
 938  * filter_list[1].list_filter_item_type                               = EMAIL_LIST_FILTER_ITEM_OPERATOR;
 939  * filter_list[1].list_filter_item.operator_type                      = EMAIL_LIST_FILTER_OPERATOR_OR;
 940  *
 941  * filter_list[2].list_filter_item_type                               = EMAIL_LIST_FILTER_ITEM_RULE;
 942  * filter_list[2].list_filter_item.rule.target_attribute              = EMAIL_MAIL_ATTRIBUTE_TO;
 943  * filter_list[2].list_filter_item.rule.rule_type                     = EMAIL_LIST_FILTER_RULE_INCLUDE;
 944  * filter_list[2].list_filter_item.rule.key_value.string_type_value   = strdup("RE");
 945  * filter_list[2].list_filter_item.rule.case_sensitivity              = false;
 946  *
 947  * filter_list[3].list_filter_item_type                               = EMAIL_LIST_FILTER_ITEM_OPERATOR;
 948  * filter_list[3].list_filter_item.operator_type                      = EMAIL_LIST_FILTER_OPERATOR_OR;
 949  *
 950  * filter_list[4].list_filter_item_type                               = EMAIL_LIST_FILTER_ITEM_RULE;
 951  * filter_list[4].list_filter_item.rule.target_attribute              = EMAIL_MAIL_ATTRIBUTE_CC;
 952  * filter_list[4].list_filter_item.rule.rule_type                     = EMAIL_LIST_FILTER_RULE_INCLUDE;
 953  * filter_list[4].list_filter_item.rule.key_value.string_type_value   = strdup("RE");
 954  * filter_list[4].list_filter_item.rule.case_sensitivity              = false;
 955  *
 956  * filter_list[5].list_filter_item_type                               = EMAIL_LIST_FILTER_ITEM_OPERATOR;
 957  * filter_list[5].list_filter_item.operator_type                      = EMAIL_LIST_FILTER_OPERATOR_OR;
 958  *
 959  * filter_list[6].list_filter_item_type                               = EMAIL_LIST_FILTER_ITEM_RULE;
 960  * filter_list[6].list_filter_item.rule.target_attribute              = EMAIL_MAIL_ATTRIBUTE_BCC;
 961  * filter_list[6].list_filter_item.rule.rule_type                     = EMAIL_LIST_FILTER_RULE_INCLUDE;
 962  * filter_list[6].list_filter_item.rule.key_value.string_type_value   = strdup("RE");
 963  * filter_list[6].list_filter_item.rule.case_sensitivity              = false;
 964  *
 965  * filter_list[7].list_filter_item_type                               = EMAIL_LIST_FILTER_ITEM_OPERATOR;
 966  * filter_list[7].list_filter_item.operator_type                      = EMAIL_LIST_FILTER_OPERATOR_OR;
 967  *
 968  * filter_list[8].list_filter_item_type                               = EMAIL_LIST_FILTER_ITEM_RULE;
 969  * filter_list[8].list_filter_item.rule.target_attribute              = EMAIL_MAIL_ATTRIBUTE_FROM;
 970  * filter_list[8].list_filter_item.rule.rule_type                     = EMAIL_LIST_FILTER_RULE_INCLUDE;
 971  * filter_list[8].list_filter_item.rule.key_value.string_type_value   = strdup("RE");
 972  * filter_list[8].list_filter_item.rule.case_sensitivity              = false;
 973  *
 974  * sorting_rule_list = malloc(sizeof(email_list_sorting_rule_t) * 2);
 975  * memset(sorting_rule_list, 0 , sizeof(email_list_sorting_rule_t) * 2);
 976  *
 977  * sorting_rule_list[0].target_attribute                              = EMAIL_MAIL_ATTRIBUTE_FLAGS_SEEN_FIELD;
 978  * sorting_rule_list[0].sort_order                                    = EMAIL_SORT_ORDER_ASCEND;
 979  *
 980  * sorting_rule_list[1].target_attribute                              = EMAIL_MAIL_ATTRIBUTE_DATE_TIME;
 981  * sorting_rule_list[1].sort_order                                    = EMAIL_SORT_ORDER_ASCEND;
 982  *
 983  * err = email_get_mail_list_ex(filter_list, 9, sorting_rule_list, 2, -1, -1, &result_mail_list, &result_mail_count);
 984  *
 985  * if(err == EMAIL_ERROR_NONE) {
 986  * printf("email_get_mail_list_ex succeed.\n");
 987  *
 988  * for(i = 0; i < result_mail_count; i++) {
 989  *      printf("mail_id [%d], subject [%s], from [%s]\n", result_mail_list[i].mail_id, result_mail_list[i].subject, result_mail_list[i].from);
 990  *      }
 991  * }
 992  * else {
 993  *      printf("email_get_mail_list_ex failed.\n");
 994  * }
 995  *
 996  * email_free_list_filter(&filter_list, 9);
 997  *
 998  * return FALSE;
 999  * @endcode
1000  * @remarks N/A
1001  */
1002 EXPORT_API int email_get_mail_list_ex(email_list_filter_t *input_filter_list, int input_filter_count, email_list_sorting_rule_t *input_sorting_rule_list, int input_sorting_rule_count, int input_start_index, int input_limit_count, email_mail_list_item_t** output_mail_list, int *output_result_count);
1003
1004 EXPORT_API int email_free_list_filter(email_list_filter_t **input_filter_list, int input_filter_count);
1005
1006 /**
1007  * @open
1008  * @fn email_get_mails(int account_id , int mailbox_id, int thread_id, int start_index, int limit_count, email_sort_type_t sorting, email_mail_data_t** mail_list,  int* result_count)
1009  * @brief       Get the Mail List information from DB based on the mailbox name.
1010  *
1011  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
1012  * @param[in] account_id                Specifies the account ID
1013  * @param[in] mailbox_id                Specifies the mailbox id
1014  * @param[in] thread_id                 Specifies the thread id. It can be EMAIL_LIST_TYPE_THREAD, EMAIL_LIST_TYPE_NORMAL or thread id.
1015  * @param[in] start_index       Specifies start index for LIMIT clause of SQL query.
1016  * @param[in] limit_count       Specifies limit count for LIMIT clause of SQL query.
1017  * @param[in] sorting           Specifies the sorting type.
1018  * @param[in/out] mail_list             Specifies the pointer to the structure email_mail_data_t.
1019  * @param[in/out] result_count  Specifies the number of mails returned.
1020  * @exception           none
1021  * @see                 email_mail_data_t
1022
1023  * @code
1024  *    #include "email-api-account.h"
1025  *      bool
1026  *      _api_sample_get_mail()
1027  *      {
1028  *              email_mail_data_t *mail_list = NULL;
1029  *              int mailbox_id;
1030  *              int result_count = 0;
1031  *              int account_id = 0;
1032  *              int err_code = EMAIL_ERROR_NONE;
1033  *
1034  *              printf("\n > Enter Mailbox id: ");
1035  *              scanf("%d", mailbox_id);
1036  *
1037  *              printf("\n > Enter Account_id: ");
1038  *              scanf("%d",&account_id);
1039  *
1040  *              if (EMAIL_ERROR_NONE != email_get_mails(account_id, mailbox_id, EMAIL_LIST_TYPE_NORMAL, 0, 100, EMAIL_SORT_DATETIME_HIGH,  &mail_list, &result_count)) {
1041  *                      printf("email_get_mails failed \n");
1042  *              }
1043  *              else {
1044  *                      printf("Success\n");
1045  *                      //do something
1046  *                      free(mail_list);
1047  *              }
1048  *
1049  *      }
1050  * @endcode
1051  * @remarks N/A
1052  */
1053
1054 EXPORT_API int email_get_mails(int account_id , int mailbox_id, int thread_id, int start_index, int limit_count, email_sort_type_t sorting, email_mail_data_t** mail_list,  int* result_count);
1055
1056 /**
1057  * @open
1058  * @fn email_get_mail_list(int account_id, int mailbox_id, int thread_id, int start_index, int limit_count, email_sort_type_t sorting, email_mail_list_item_t** mail_list,  int* result_count)
1059  * @brief       Get the Mail List information from DB based on the mailbox name.
1060  *
1061  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
1062  * @param[in] account_id                Specifies the account id
1063  * @param[in] mailbox_id                Specifies the mailbox id
1064  * @param[in] thread_id                 Specifies the thread id. It can be EMAIL_LIST_TYPE_THREAD, EMAIL_LIST_TYPE_NORMAL or thread id.
1065  * @param[in] start_index       Specifies start index for LIMIT clause of SQL query.
1066  * @param[in] limit_count       Specifies limit count for LIMIT clause of SQL query.
1067  * @param[in] sorting           Specifies the sorting type.
1068  * @param[in/out] mail_list             Specifies the pointer to the structure email_mail_list_item_t.
1069  * @param[in/out] result_count  Specifies the number of mails returned.
1070  * @exception           none
1071  * @see                 email_mail_list_item_t
1072
1073  * @code
1074  *      #include "email-api-account.h"
1075  *      bool
1076  *      _api_sample_get_mail()
1077  *      {
1078  *              email_mail_list_item_t *mail_list = NULL;
1079  *              int mailbox_id;
1080  *              int result_count = 0;
1081  *              int account_id = 0;
1082  *              int err_code = EMAIL_ERROR_NONE;
1083  *
1084  *              printf("\n > Enter Mailbox id: ");
1085  *              scanf("%d", mailbox_id);
1086  *
1087  *              printf("\n > Enter Account_id: ");
1088  *              scanf("%d",&account_id);
1089  *
1090  *              if (EMAIL_ERROR_NONE != email_get_mail_list(account_id, mailbox_id, EMAIL_LIST_TYPE_NORMAL, 0, 100, EMAIL_SORT_DATETIME_HIGH,  &mail_list, &result_count))
1091  *              {
1092  *                      printf("email_get_mail_list_ex failed \n");
1093  *              }
1094  *              else
1095  *              {
1096  *                      printf("Success\n");
1097  *                      //do something
1098  *                      free(mail_list);
1099  *              }
1100  *
1101  *      }
1102  * @endcode
1103  * @remarks N/A
1104  */
1105 EXPORT_API int email_get_mail_list(int account_id, int mailbox_id, int thread_id, int start_index, int limit_count, email_sort_type_t sorting, email_mail_list_item_t** mail_list,  int* result_count);
1106
1107 /**
1108  * @open
1109  * @fn  email_get_mail_by_address(int account_id, int mailbox_id, email_email_address_list_t* addr_list,
1110                                                                         int start_index, int limit_count, email_sort_type_t sorting, email_mail_list_item_t** mail_list,  int* result_count)
1111  * @brief       Get the Mail List information from the DB based on the mailbox name account_id and sender address.
1112  *
1113  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
1114  * @param[in] account_id        Specifies the Account ID
1115  * @param[in] mailbox_id        Specifies the Mailbox ID
1116  * @param[in] addr_list         Specifies the addresses of senders. see email_email_address_list_t
1117  * @param[in] start_index               Specifies the first mail index of searched mail. This function will return mails whose index in the result list are from start_index to start_index + limit_count
1118  * @param[in] limit_count               Specifies the max number of returned mails.
1119  * @param[in] search_type   Specifies the search type.
1120  * @param[in] search_value  Specifies the search value.
1121  * @param[in] sorting                   Specifies the sorting order. see email_sort_type_t
1122  * @param[in/out] mail_list     Specifies the Pointer to the structure email_mail_list_item_t.
1123  * @param[in/out] result_count          Specifies the Number of searched Mails
1124  * @exception           none
1125  * @see                 email_email_address_list_t, email_sort_type_t, email_mail_list_item_t
1126  * @code
1127  * @endcode
1128  * @remarks N/A
1129  */
1130 EXPORT_API int email_get_mail_by_address(int account_id , int mailbox_id, email_email_address_list_t* addr_list,
1131                                                                         int start_index, int limit_count, int search_type, const char *search_value, email_sort_type_t sorting, email_mail_list_item_t** mail_list,  int* result_count);
1132
1133 /**
1134  * @open
1135  * @fn email_get_thread_information_by_thread_id(int thread_id, email_mail_data_t** thread_info)
1136  * @brief       Get the thread information for specific thread from DB based on the mailbox name.
1137  *
1138  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
1139  * @param[in] thread_id             Specifies the thread_id
1140  * @param[in/out] thread_info   Specifies the Pointer to the structure email_mail_data_t.
1141  * @exception           none
1142  * @see             email_mail_data_t
1143  * @code
1144  *      #include "email-api-account.h"
1145  *      bool
1146  *      _api_sample_get_thread_information()
1147  *      {
1148  *              email_mail_data_t *thread_info = NULL;
1149  *              int thread_id = 0;
1150  *              int err_code = EMAIL_ERROR_NONE;
1151  *
1152  *              printf("\n > Enter thread_id: ");
1153  *              scanf("%d",&thread_id);
1154  *
1155  *              if ( EMAIL_ERROR_NONE != email_get_thread_information_by_thread_id(thread_id, &thread_info))
1156  *              {
1157  *                      printf("email_get_thread_information_by_thread_id failed :\n"); *
1158  *              }
1159  *              else
1160  *              {
1161  *                      printf("Success\n");
1162  *                      //do something
1163  *              }
1164  *
1165  *      }
1166  * @endcode
1167  * @remarks N/A
1168  */
1169
1170
1171 EXPORT_API int email_get_thread_information_by_thread_id(int thread_id, email_mail_data_t** thread_info);
1172
1173 /**
1174  * @open
1175  * @fn email_get_thread_information_ex(int thread_id, email_mail_list_item_t** thread_info)
1176  * @brief       Get the Mail List information for specific thread from DB based on the mailbox name.
1177  *
1178  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
1179  * @param[in] thread_id             Specifies the thread_id
1180  * @param[in/out] thread_info   Specifies the Pointer to the structure email_mail_list_item_t.
1181  * @exception           none
1182  * @see             email_mail_list_item_t
1183  * @code
1184  *      #include "email-api-account.h"
1185  *      bool
1186  *      _api_sample_get_thread_information_ex()
1187  *      {
1188  *              email_mail_list_item_t *thread_info = NULL;
1189  *              int thread_id = 0;
1190  *              int err_code = EMAIL_ERROR_NONE;
1191  *
1192  *              printf("\n > Enter thread_id: ");
1193  *              scanf("%d",&thread_id);
1194  *
1195  *              if ( EMAIL_ERROR_NONE != email_get_thread_information_ex(thread_id, &thread_info))
1196  *              {
1197  *                      printf("email_get_mail_list_of_thread failed :\n"); *
1198  *              }
1199  *              else
1200  *              {
1201  *                      printf("Success\n");
1202  *                      //do something
1203  *              }
1204  *
1205  *      }
1206  * @endcode
1207  * @remarks N/A
1208  */
1209 EXPORT_API int email_get_thread_information_ex(int thread_id, email_mail_list_item_t** thread_info);
1210
1211
1212
1213 /**
1214  * @open
1215  * @fn email_retry_sending_mail( int mail_id, int timeout_in_sec)
1216  * @brief       Retry mail send
1217  *
1218  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
1219  * @param[in] mail_id                   Specifies the mail id for the mail to resend
1220  * @param[in] timeout_in_sec    Specifies the timeout value in seconds
1221  * @exception           none
1222  * @see                 none
1223
1224  * @code
1225  *      #include "email-api-account.h"
1226  *      bool
1227  *      _api_sample_retry_send_mail()
1228  *      {
1229  *              int mail_id = 1;
1230  *              int timeout_in_sec = 2;
1231  *
1232  *               if(EMAIL_ERROR_NONE == email_retry_sending_mail(mail_id,timeout_in_sec))
1233  *                      //success
1234  *               else
1235  *                      //failure
1236  *
1237  *      }
1238  * @endcode
1239  * @remarks N/A
1240  */
1241 EXPORT_API int email_retry_sending_mail(int mail_id, int timeout_in_sec);
1242
1243 EXPORT_API int email_create_db_full();
1244
1245 /**
1246  * @open
1247  * @fn email_cancel_sending_mail( int mail_id)
1248  * @brief       Callback function for cm popup. We set the status as EMAIL_MAIL_STATUS_SEND_CANCELED
1249  *
1250  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
1251  * @param[in] mail_id           Specifies the mailID
1252  * @exception           none
1253  * @see                 none
1254  * @code
1255  *      #include "email-api-account.h"
1256  *      bool
1257  *      _api_sample_cancel_send_mail()
1258  *      {
1259  *              int mail_id = 10;
1260  *
1261  *
1262  *               if(EMAIL_ERROR_NONE == email_cancel_sending_mail(mail_id,))
1263  *                      //success
1264  *               else
1265  *                      //failure
1266  *
1267  *      }
1268  * @endcode
1269  * @remarks N/A
1270  */
1271 EXPORT_API int email_cancel_sending_mail(int mail_id) ;
1272
1273  /**
1274  * @open
1275  * @fn email_get_disk_space_usage(unsigned long *total_size)
1276  * @brief       Gets the total disk usage of emails in KB.
1277  *
1278  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
1279  * @param[out] total_size       total disk usage of emails
1280  * @exception           none
1281  * @code
1282  *      #include "email-api-account.h"
1283  *              bool
1284  *              _api_sample_get_disk_space_usage()
1285  *              {
1286  *                      unsigned long total_size = 0;
1287  *
1288  *                      if ( EMAIL_ERROR_NONE  != email_get_disk_space_usage(&total_size))
1289  *                              printf("email_get_disk_space_usage failed err : %d\n",err_code);
1290  *                      else
1291  *                              printf("email_get_disk_space_usage SUCCESS, total disk usage in KB : %ld \n", total_size);
1292  *              }
1293  * @endcode
1294  * @remarks N/A
1295  */
1296 EXPORT_API int email_get_disk_space_usage(unsigned long *total_size);
1297
1298 /**
1299  * @open
1300  * @fn  email_get_address_info_list(int mail_id, email_address_info_list_t** address_info_list)
1301  * @brief       Get the address info list. The address info list contains from, to, cc, bcc addresses and their display name, contact id and etc. (see email_address_info_list_t)
1302  *                      Each GList (from, to, cc, bcc) is the list of email_address_info_t data.
1303  *                      "data" variable of GList structure contains email_address_info_t data. <br>
1304  *                      To get email_address_info_t data from GList, Use type casting from GList node.
1305  *
1306  * @return      This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
1307  * @param[in] mail_id           Specifies the mail id to get the list.
1308  * @param[out] address_info_list        Specifies the Pointer to the structure email_address_info_list_t. Memory for a new address info list will be allocated to this. Call email_free_address_info_list() to free the memory allocated to this.
1309  * @exception           none
1310  * @see                 email_address_info_list_t, email_address_info_t, email_free_address_info_list()
1311  * @code
1312  *      #include "email-api-account.h"
1313  *      bool
1314  *      _api_sample_get_address_info_list()
1315  *      {
1316  *              email_address_info_list_t *p_address_info_list= NULL;
1317  *              email_address_info_t *p_address_info = NULL;
1318  *              int mai_id;
1319  *              int err_code = EMAIL_ERROR_NONE;
1320  *
1321  *              mail_id = 1;
1322  *
1323  *              if ( EMAIL_ERROR_NONE != (err_code = email_get_address_info_list(mail_id, &p_address_info_list)) )
1324  *              {
1325  *                      printf("email_get_address_info_list failed :\n"); *
1326  *                      return false;
1327  *              }
1328  *              else
1329  *              {
1330  *                      printf("Success\n");
1331  *                      //do something with p_address_info_list
1332  *                      GList *list = p_address_info_list->from;
1333  *                      GList *node = g_list_first(list);
1334  *                      while ( node != NULL )
1335  *                      {
1336  *                              p_address_info = (email_address_info_t*)node->data;
1337  *                              printf("%d,  %s, %s, %d\n", p_address_info->address_type, p_address_info->address, p_address_info->display_name, p_address_info->contact_id);
1338  *
1339  *                              node = g_list_next(node);
1340  *                      }
1341  *              }
1342  *
1343  *              // Free sender list
1344  *              if ( p_address_info_list )
1345  *              {
1346  *                      email_free_address_info_list(&p_address_info_list);
1347  *              }
1348  *      }
1349  * @endcode
1350  * @remarks N/A
1351  */
1352 EXPORT_API int email_get_address_info_list(int mail_id, email_address_info_list_t** address_info_list);
1353
1354 /**
1355  * @open
1356  * @fn  email_free_address_info_list(email_address_info_list_t **address_info_list)
1357  * @brief       Free the address info list allocated by email_get_address_info_list(). This function will free the memory which is allocated to address_info_list itself.
1358  *
1359  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
1360  * @param[in] address_info_list Specifies the Pointer to the structure email_address_info_list_t to be freed.
1361  * @exception           none
1362  * @see                 email_address_info_list_t, email_get_address_info_list()
1363  */
1364 EXPORT_API int email_free_address_info_list(email_address_info_list_t **address_info_list);
1365
1366 /**
1367  * @open
1368  * @fn  email_get_structure(const char*encoded_string, void **struct_var, email_convert_struct_type_e type)
1369  * @brief       This function returns the structure of the type which is indicated by 'type' variable. This function will allocate new memory to 'struct_var' for structure.<br>
1370  *                      Some notifications such as NOTI_DOWNLOAD_NEW_MAIL are published with string parameter. The string contains various values that might be divided by delimiter.<br>
1371  *
1372  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
1373  * @param[in] encoded_string            Specifies the Pointer to the string from notification.
1374  * @param[out] struct_var                       Specifies the Pointer to the structure to be returned. If success, new memory for structure will be allocated.
1375  * @param[in] type                              Specifies the converting type. see email_convert_struct_type_e
1376  * @exception           none
1377  * @see                 email_convert_struct_type_e
1378  */
1379 EXPORT_API int email_get_structure(const char*encoded_string, void **struct_var, email_convert_struct_type_e type);
1380
1381 /**
1382  * @open
1383  * @fn email_get_meeting_request(int mail_id, email_meeting_request_t **meeting_req)
1384  * @brief       Get the information of meeting request.  The information of meeting request is based on Mail Id. <br>
1385  *                      The information of meeting request is corresponding to only one mail.
1386  *                      For this reason, the information of meeting request can be added by using email_add_message_with_meeting_request() with a matched mail information.
1387  *
1388  * @return This function returns EMAIL_ERROR_NONE on success. This function returns EMAIL_ERROR_DATA_NOT_FOUND if there isn't a matched mail. Otherwise it returns error code (refer to EMAIL_ERROR_XXX) on failure.
1389  * @param[in] mail_id           Specifies the Mail id for which  meeting request details need to be fetched
1390  * @param[in/out] meeting_req   Specifies the Pointer to the structure email_meeting_request_t.
1391  * @exception           none
1392  * @see                 email_meeting_request_t
1393  */
1394 EXPORT_API int email_get_meeting_request(int mail_id, email_meeting_request_t **meeting_req);
1395
1396
1397 /**
1398  * @open
1399  * @fn  email_free_meeting_request(email_meeting_request_t** meeting_req, int count)
1400  * @brief       Free the meeting request allocated by email_get_meeting_request() or alloacted to add. This function will free the memory which is allocated to meeting_req (= *meeting_req) itself.
1401  *
1402  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
1403  * @param[in] email_meeting_request_t   Specifies the Pointer to the structure email_meeting_request_t to be freed.
1404  * @param[in] count     Specifies the number of elements in meeting_req array. this is usually 1.
1405  * @exception           none
1406  * @see                 email_meeting_request_t, email_get_meeting_request()
1407  */
1408 EXPORT_API int email_free_meeting_request(email_meeting_request_t** meeting_req, int count);
1409
1410 EXPORT_API int email_move_thread_to_mailbox(int thread_id, int target_mailbox_id, int move_always_flag);
1411
1412 EXPORT_API int email_delete_thread(int thread_id, int delete_always_flag);
1413
1414 EXPORT_API int email_modify_seen_flag_of_thread(int thread_id, int seen_flag, int on_server);
1415
1416 EXPORT_API int email_expunge_mails_deleted_flagged(int input_mailbox_id, int input_on_server, unsigned *output_handle);
1417
1418 #ifdef __cplusplus
1419 }
1420 #endif /* __cplusplus */
1421
1422 /**
1423 * @} @}
1424 */
1425
1426
1427 #endif /* __EMAIL_API_MAIL_H__ */