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