email-api/include/email-api-network.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_NETWORK_H__
  24 #define __EMAIL_API_NETWORK_H__
  25
  26 #include "email-types.h"
  27
  28 /**
  29 * @defgroup EMAIL_SERVICE Email Service
  30 * @{
  31 */
  32
  33 /**
  34 * @ingroup EMAIL_SERVICE
  35 * @defgroup EMAIL_API_NETWORK Email Network API
  36 * @{
  37 */
  38
  39 /**
  40  *
  41  * This file contains the data structures and interfaces needed for application,
  42  * to interact with email-service.
  43  * @file                email-api-network.h
  44  * @author      Kyuho Jo <kyuho.jo@samsung.com>
  45  * @author      Sunghyun Kwon <sh0701.kwon@samsung.com>
  46  * @version     0.1
  47  * @brief               This file contains the data structures and interfaces of Network related Functionality provided by
  48  *                      email-service .
  49  *
  50  * @{
  51
  52  * @code
  53
  54  *      #include "email-api.h"
  55  *
  56  *      bool
  57  *      other_app_invoke_uniform_api_sample(int* error_code)
  58  *      {
  59  *
  60  *              // Send a mail
  61  *              email_attachment_data_t attachment;
  62  *              int account_id = 1;
  63  *              int mailbox_id = 0;
  64  *              int attachment_id = 0;
  65  *              int err = EMAIL_ERROR_NONE;
  66  *              int mail_id = 0;
  67  *              int action = -1;
  68  *
  69  *              printf("Enter mail id\n");
  70  *              scanf("%d",&mail_id);
  71  *
  72  *              if(EMAIL_ERROR_NONE == email_send_mail(mail_id, &handle))
  73  *                      //success
  74  *              else
  75  *                      //failure
  76  *
  77  *              // Download header of new emails from mail server
  78  *              int handle = 0;
  79  *
  80  *              mailbox.account_id = account_id;
  81  *              printf("Enter mailbox id\n");
  82  *              scanf("%d",&mailbox_id);
  83  *              if(EMAIL_ERROR_NONE == email_sync_header (account_id, mailbox_id, &handle))
  84  *                      //success
  85  *              else
  86  *                      //failure
  87  *
  88  *              //Sync mail header for all accounts
  89  *              if(EMAIL_ERROR_NONE == email_sync_header_for_all_account(&handle))
  90  *                      //success
  91  *              else
  92  *                      //failure
  93  *
  94  *              //Download email body from server
  95  *
  96  *              if(EMAIL_ERROR_NONE == email_download_body (mail_id,0,&handle))
  97  *                      //success
  98  *              else
  99  *                      //failure
 100  *
 101  *              //Download a email nth-attachment from server
 102  *              prinf("Enter attachment number\n");
 103  *              scanf("%d",&attachment_id);
 104  *              if(EMAIL_ERROR_NONE == email_download_attachment(mail_id, attachment_id, &handle))
 105  *                      //success
 106  *              else
 107  *                      //failure
 108  *
 109  *              //Cancel job
 110  *              if(EMAIL_ERROR_NONE == email_cancel_job(account_id,handle))//canceling download email nth attachment from server job.
 111  *                                                                      //so this handle contains the value return by the email_download_attachment()
 112  *                      //success
 113  *              else
 114  *                      //failure
 115  *              //Get pending job list for an account
 116  *
 117  *              printf( " Enter Action \n SEND_MAIL = 0 \n SYNC_HEADER = 1 \n" \
 118  *                          " DOWNLOAD_BODY,= 2 \n DOWNLOAD_ATTACHMENT = 3 \n" \
 119  *                          " DELETE_MAIL = 4 \n SEARCH_MAIL = 5 \n SAVE_MAIL = 6 \n" \
 120  *                          " NUM = 7 \n");
 121  *              scanf("%d",&action);
 122  *              if(EMAIL_ERROR_NONE == email_get_pending_job(action,account_id,mail_id,&status))
 123  *                      //success
 124  *              else
 125  *                      //error
 126  *
 127  *              //Get Network status
 128  *              if(EMAIL_ERROR_NONE == email_get_network_status(&sending,&receiving))
 129  *                      //success
 130  *              else
 131  *                      //failure
 132  *
 133  *              //Send read report
 134  *              if(EMAIL_ERROR_NONE == email_send_report(mail ,&handle))
 135  *                      //success
 136  *              else
 137  *                      //failure
 138  *              //Save and send
 139  *
 140  *
 141  *              if(EMAIL_ERROR_NONE  == email_add_mail(mail,NULL,0, NULL, 0))
 142  *              {
 143  *                      if(EMAIL_ERROR_NONE == email_send_saved(account_id,&option,&handle))
 144  *                              //success
 145  *                      else
 146  *                              //failure
 147  *              }
 148  *              //Get Imap mailbox list
 149  *              if(EMAIL_ERROR_NONE == email_sync_imap_mailbox_list(account_id,  &handle))
 150  *                      //success
 151  *              else
 152  *                      //failure
 153  *
 154  * }
 155  *
 156  * @endcode
 157  * @}
 158
 159  */
 160
 161
 162
 163 #ifdef __cplusplus
 164 extern "C" {
 165 #endif /* __cplusplus */
 166
 167 /**
 168  * @fn email_send_mail(int mail_id,     int *handle)
 169  * @brief       Send a mail.This function is invoked when user wants to send a composed mail.
 170  *
 171  * @return      This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 172  * @param[in] mail_id                   Specifies the mail ID.
 173  * @param[out] handle           Specifies the sending handle.
 174  * @exception   none
 175  * @see         email_mailbox_t and email_option_t
 176  * @remarks N/A
 177  */
 178 EXPORT_API int email_send_mail(int mail_id,     int *handle);
 179
 180 EXPORT_API int email_send_mail_with_downloading_attachment_of_original_mail(int input_mail_id, int *output_handle);
 181
 182 EXPORT_API int email_schedule_sending_mail(int input_mail_id, time_t input_time);
 183
 184
 185 /**
 186  * @fn email_sync_header(int input_account_id, int input_mailbox_id, int *handle)
 187  * @brief       Download header of new emails from mail server.This function is invoked when user wants to download only header of new mails.
 188  *
 189  * @return      This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 190  * @param[in] input_account_id          Specifies the account ID.
 191  * @param[in] input_mailbox_id          Specifies the mailbox ID.
 192  * @param[out] handle           Specifies the handle for stopping downloading.
 193  * @exception   none
 194  * @see         email_mailbox_t
 195  * @remarks N/A
 196  */
 197 EXPORT_API int email_sync_header(int input_account_id, int input_mailbox_id, int *handle);
 198
 199
 200 /**
 201  * @fn email_sync_header_for_all_account(int *handle)
 202  * @brief       Download header of new emails from mail server for all emails.This function is invoked when user wants to download header of new mails for all accounts.
 203  *
 204  * @return      This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 205  * @param[out] handle           Specifies the handle for stopping downloading.
 206  * @exception none
 207  * @see         none
 208  * @remarks N/A
 209  */
 210 EXPORT_API int email_sync_header_for_all_account(int *handle);
 211
 212
 213 /**
 214
 215  * @fn email_download_body(int mail_id, int with_attachment, int *handle)
 216  * @brief       Download email body from server.This function is invoked when user wants to download email body with/without attachment based on the option with_attachment
 217  *              from the server.
 218  *
 219  * @return      This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 220  * @param[in] mail_id                   Specifies the mail ID.
 221  * @param[in] with_attachment   Specifies the whether attachment is there or not.
 222  * @param[out] handle           Specifies the handle for stopping downloading.
 223  * @exception none
 224  * @see email_mailbox_t
 225  * @remarks N/A
 226  */
 227 EXPORT_API int email_download_body(int mail_id, int with_attachment, int *handle);
 228
 229
 230
 231
 232
 233
 234 /**
 235
 236  * @fn email_download_attachment(int mail_id, const char* nth, int *handle);
 237  * @brief       Download a email nth-attachment from server.This function is invoked if user wants to download only specific attachment of a mail whose body is already downloaded.
 238  *
 239  * @return      This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 240  * @param[in] mail_id           Specifies the mail ID.
 241  * @param[in] nth                       Specifies the attachment number been saved. the minimum number is "1".
 242  * @param[out] handle           Specifies the handle for stopping downloading.
 243  * @exception none
 244  * @see         email_mailbox_t
 245  * @remarks N/A
 246  */
 247 EXPORT_API int email_download_attachment(int mail_id, int nth, int *handle);
 248
 249
 250 /**
 251
 252  * @fn email_cancel_job(int account_id, int handle);
 253  * @brief       cancel the ongoing job.This function is invoked if user wants to cancel any ongoing job of a specified account.
 254  *
 255  * @return      This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 256  * @param[in] input_account_id  Specifies the account ID.
 257  * @param[in] input_handle              Specifies the handle for stopping the operation.
 258  * @param[in] input_cancel_type Specifies the type of cancellation.
 259  * @exception    none
 260  * @see         none
 261  * @remarks N/A
 262  */
 263
 264 EXPORT_API int email_cancel_job(int input_account_id, int input_handle, email_cancelation_type input_cancel_type);
 265
 266
 267 /**
 268
 269  * @fn email_get_pending_job(email_action_t action, int account_id, int mail_id, email_event_status_type_t * status);
 270  * @brief       get pending job list.This function is invoked if user wants to get the pending job list with status information .
 271  *              Based on action item of a mail is for a specific account this will give all pending job list.
 272  *
 273  * @return      This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 274  * @param[in] account_id        Specifies the action of the job.
 275  * @param[in] account_id        Specifies the account ID.
 276  * @param[in] mail_id           Specifies the mail ID.
 277  * @param[out]status            Specifies the status of the job.
 278  * @exception    none
 279  * @see         email_action_t and email_event_status_type_t
 280  * @remarks N/A
 281  */
 282 EXPORT_API int email_get_pending_job(email_action_t action, int account_id, int mail_id, email_event_status_type_t * status);
 283
 284
 285 /**
 286
 287  * @fn email_get_network_status(int* on_sending, int* on_receiving)
 288  * @brief       This function gives the  current network status.This gives the information to the user whether sending operation is in progress or receiving operation.
 289  *
 290  * @return      This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 291  * @param[out] on_sending               True if sending is in progress.
 292  * @param[out] on_receiving             True if receivng is in progress.
 293  * @exception   none
 294  * @see         none
 295  * @remarks N/A
 296  */
 297 EXPORT_API int email_get_network_status(int* on_sending, int* on_receiving);
 298
 299 /**
 300
 301  * @fn email_send_saved(int account_id, int *handle)
 302  * @brief       Send all mails to been saved in Offline-mode.This function is invoked when user wants to send an email and after saving it.
 303  *              This will save the email in draft mailbox and then sends.
 304  *
 305  * @return      This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 306  * @param[in] account_id                        Specifies the account ID.
 307  * @param[out] handle                           Specifies the handle for stopping sending.
 308  * @exception none
 309  * @see email_option_t
 310  * @remarks N/A
 311  */
 312 EXPORT_API int email_send_saved(int account_id, int *handle);
 313
 314 /**
 315
 316  * @fn email_sync_imap_mailbox_list(int account_id, int *handle)
 317  *  @brief      fetch all the mailbox names from server and store the non-existing mailboxes in DB.This function is invoked when user wants to download all server mailboxes from IMAP server
 318  *
 319  * @return      This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 320  * @param[in] account_id                        Specifies the account ID.
 321  * @param[out] handle                   Specifies the handle for stopping Network operation.
 322  * @exception   none
 323  * @see         none
 324  * @remarks N/A
 325  */
 326 EXPORT_API int email_sync_imap_mailbox_list(int account_id, int *handle);
 327
 328 /**
 329
 330  * @fn email_search_mail_on_server(int input_account_id, int input_mailbox_id, email_search_filter_t *input_search_filter_list, int input_search_filter_count, int *output_handle)
 331  * @brief       Search the mails on server.
 332  *
 333  * @return This function returns EMAIL_ERROR_NONE on success or error code (refer to EMAIL_ERROR_XXX) on failure.
 334  * @param[in] account_id        Specifies the Account ID
 335  * @param[in] mailbox_id        Specifies the Mailbox ID
 336  * @param[in] search_type       Specifies the searching type(EMAIL_SEARCH_FILTER_SUBJECT,  EMAIL_SEARCH_FILTER_SENDER, EMAIL_SEARCH_FILTER_RECIPIENT, EMAIL_SEARCH_FILTER_ALL)
 337  * @param[in] search_value      Specifies the value to use for searching. (ex : Subject, email address, display name)
 338  * @exception           none
 339  * @see email_search_filter_t,
 340  * @code
 341  * @endcode
 342  * @remarks N/A
 343  */
 344 EXPORT_API int email_search_mail_on_server(int input_account_id, int input_mailbox_id, email_search_filter_t *input_search_filter_list, int input_search_filter_count, int *output_handle);
 345
 346 EXPORT_API int email_clear_result_of_search_mail_on_server(int input_account_id);
 347
 348 #ifdef __cplusplus
 349 }
 350 #endif /* __cplusplus */
 351
 352 /**
 353 * @}
 354 */
 355
 356
 357 #endif /* __EMAIL_API_NETWORK_H__ */