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