email-api/include/email-api-network.h

   1 /*\r
   2 *  email-service\r
   3 *\r
   4 * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.\r
   5 *\r
   6 * Contact: Kyuho Jo <kyuho.jo@samsung.com>, Sunghyun Kwon <sh0701.kwon@samsung.com>\r
   7 *\r
   8 * Licensed under the Apache License, Version 2.0 (the "License");\r
   9 * you may not use this file except in compliance with the License.\r
  10 * You may obtain a copy of the License at\r
  11 *\r
  12 * http://www.apache.org/licenses/LICENSE-2.0\r
  13 *\r
  14 * Unless required by applicable law or agreed to in writing, software\r
  15 * distributed under the License is distributed on an "AS IS" BASIS,\r
  16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  17 * See the License for the specific language governing permissions and\r
  18 * limitations under the License.\r
  19 *\r
  20 */\r
  21 \r
  22 \r
  23 #ifndef __EMAIL_API_NETWORK_H__\r
  24 #define __EMAIL_API_NETWORK_H__\r
  25 \r
  26 #include "email-types.h"\r
  27 \r
  28 /**\r
  29 * @defgroup EMAIL_SERVICE Email Service\r
  30 * @{\r
  31 */\r
  32 \r
  33 /**\r
  34 * @ingroup EMAIL_SERVICE\r
  35 * @defgroup EMAIL_API_NETWORK Email Network API\r
  36 * @{\r
  37 */\r
  38 \r
  39 /**\r
  40  *\r
  41  * This file contains the data structures and interfaces needed for application,\r
  42  * to interact with email-service.\r
  43  * @file                email-api-network.h\r
  44  * @author      Kyuho Jo <kyuho.jo@samsung.com>\r
  45  * @author      Sunghyun Kwon <sh0701.kwon@samsung.com>\r
  46  * @version     0.1\r
  47  * @brief               This file contains the data structures and interfaces of Network related Functionality provided by\r
  48  *                      email-service .\r
  49  *\r
  50  * @{\r
  51 \r
  52  * @code\r
  53 \r
  54  *      #include "email-api.h"\r
  55  *\r
  56  *      bool\r
  57  *      other_app_invoke_uniform_api_sample(int* error_code)\r
  58  *      {\r
  59  *\r
  60  *              // Send a mail\r
  61  *              emf_mailbox_t mbox;\r
  62  *              emf_attachment_info_t attachment;\r
  63  *              emf_option_t option;\r
  64  *              int account_id = 1;\r
  65  *              int err = EMF_ERROR_NONE;\r
  66  *              int mail_id = 0;\r
  67  *              char arg[50]; //Input attachment number need to be download\r
  68  *              emf_event_status_type_t  status;\r
  69  *              int action = -1;\r
  70  *              int on_sending = 0;\r
  71  *          int on_receiving = 0;\r
  72  *\r
  73 *               printf("Enter mailbox name\n");\r
  74  *              scanf("%s",&mbox.mailbox_name);\r
  75  *              printf("Enter mail id\n");\r
  76  *              scanf("%d",&mail_id);\r
  77  *              option.keep_local_copy = 1;\r
  78  *\r
  79  *              if(EMF_ERROR_NONE == email_send_mail(&mbox, mail_id, &option, &handle))\r
  80  *                      //success\r
  81  *              else\r
  82  *                      //failure\r
  83  *\r
  84  *              // Download header of new emails from mail server\r
  85  *              unsigned handle = 0;\r
  86  *\r
  87  *              memset(&mbox, 0x00, sizeof(emf_mailbox_t));\r
  88  *\r
  89  *              mbox.account_id = account_id;\r
  90  *              mbox.name = strdup("INBOX");\r
  91  *              if(EMF_ERROR_NONE == email_sync_header (&mbox,&handle))\r
  92  *                      //success\r
  93  *              else\r
  94  *                      //failure\r
  95  *\r
  96  *              //Sync mail header for all accounts\r
  97  *              if(EMF_ERROR_NONE == email_sync_header_for_all_account(&handle))\r
  98  *                      //success\r
  99  *              else\r
 100  *                      //failure\r
 101  *\r
 102  *              //Download email body from server\r
 103  *\r
 104  *              memset(&mbox, 0x00, sizeof(emf_mailbox_t));\r
 105  *              mbox.account_id = account_id;\r
 106  *              mbox.name = strdup("INBOX");\r
 107  *              if(EMF_ERROR_NONE == email_download_body (&mbox,mail_id,0,&handle))\r
 108  *                      //success\r
 109  *              else\r
 110  *                      //failure\r
 111  *\r
 112  *              //Download a email nth-attachment from server\r
 113  *              prinf("Enter attachment number\n");\r
 114  *              scanf("%s",arg);\r
 115  *              memset(&mbox, 0x00, sizeof(emf_mailbox_t));\r
 116  *              mbox.name = strdup("INBOX");\r
 117  *              mbox.account_id = account_id;\r
 118  *              if(EMF_ERROR_NONE == email_download_attachment(&mailbox,mail_id,arg,&handle))\r
 119  *                      //success\r
 120  *              else\r
 121  *                      //failure\r
 122  *\r
 123  *              //Cancel job\r
 124  *              if(EMF_ERROR_NONE == email_cancel_job(account_id,handle))//canceling download email nth attachment from server job.\r
 125  *                                                                      //so this handle contains the value return by the email_download_attachment()\r
 126  *                      //success\r
 127  *              else\r
 128  *                      //failure\r
 129  *              //Get pending job listfor an account\r
 130  *\r
 131  *              printf( " Enter Action \n SEND_MAIL = 0 \n SYNC_HEADER = 1 \n" \\r
 132  *                          " DOWNLOAD_BODY,= 2 \n DOWNLOAD_ATTACHMENT = 3 \n" \\r
 133  *                          " DELETE_MAIL = 4 \n SEARCH_MAIL = 5 \n SAVE_MAIL = 6 \n" \\r
 134  *                          " NUM = 7 \n");\r
 135  *              scanf("%d",&action);\r
 136  *              if(EMF_ERROR_NONE == email_get_pending_job(action,account_id,mail_id,&status))\r
 137  *                      //success\r
 138  *              else\r
 139  *                      //error\r
 140  *\r
 141  *              //Get Network status\r
 142  *              if(EMF_ERROR_NONE == email_get_network_status(&sending,&receiving))\r
 143  *                      //success\r
 144  *              else\r
 145  *                      //failure\r
 146  *\r
 147  *              //Send read report\r
 148  *              if(EMF_ERROR_NONE == email_send_report(mail ,&handle))\r
 149  *                      //success\r
 150  *              else\r
 151  *                      //failure\r
 152  *              //Save and send\r
 153  *\r
 154  *              mbox.account_id = account_id;\r
 155  *              mbox.name = strdup("DRAFTBOX");\r
 156  *\r
 157  *              if(EMF_ERROR_NONE  == email_add_message(mail,&mbox,1))\r
 158  *              {\r
 159  *                      if(EMF_ERROR_NONE == email_send_saved(account_id,&option,&handle))\r
 160  *                              //success\r
 161  *                      else\r
 162  *                              //failure\r
 163  *              }\r
 164  *              //Get Imap mailbox list\r
 165  *              printf("\n > Enter server name:\n");\r
 166  *              scanf("%s",arg);\r
 167  *              if(EMF_ERROR_NONE == email_get_imap_mailbox_list(account_id , arg , &handle))\r
 168  *                      //success\r
 169  *              else\r
 170  *                      //failure\r
 171  *\r
 172  *              //sync local activity\r
 173  *              if(EMF_ERROR_NONE == email_sync_local_activity(account_id))\r
 174  *                      //success\r
 175  *              else\r
 176  *                      //failure\r
 177  * }\r
 178  *\r
 179  * @endcode\r
 180  * @}\r
 181 \r
 182  */\r
 183 \r
 184 \r
 185 \r
 186 #ifdef __cplusplus\r
 187 extern "C" {\r
 188 #endif /* __cplusplus */\r
 189 \r
 190 /**\r
 191  * @open\r
 192  * @fn email_send_mail( emf_mailbox_t* mailbox, int mail_id, emf_option_t* sending_option, unsigned* handle)\r
 193  * @brief       Send a mail.This function is invoked when user wants to send a composed mail.\r
 194  *\r
 195  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 196  * @param[in] mailbox                   Specifies the mailbox to consist a sending email.\r
 197  * @param[in] mail_id                   Specifies the mail ID.\r
 198  * @param[in] sending_option            Specifies the sending option.\r
 199  * @param[out] handle           Specifies the sending handle.\r
 200  * @exception   none\r
 201  * @see         emf_mailbox_t and emf_option_t\r
 202  * @remarks N/A\r
 203  */\r
 204 EXPORT_API int email_send_mail( emf_mailbox_t* mailbox,\r
 205                                 int mail_id,\r
 206                                 emf_option_t* sending_option,\r
 207                                 unsigned* handle);\r
 208 \r
 209 \r
 210 /**\r
 211  * @open\r
 212  * @fn email_sync_header(emf_mailbox_t* mailbox, unsigned* handle)\r
 213  * @brief       Download header of new emails from mail server.This function is invoked when user wants to download only header of new mails.\r
 214  *\r
 215  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 216  * @param[in] mailbox           Specifies the structure of mailbox.\r
 217  * @param[out] handle           Specifies the handle for stopping downloading.\r
 218  * @exception   none\r
 219  * @see         emf_mailbox_t\r
 220  * @remarks N/A\r
 221  */\r
 222 EXPORT_API int email_sync_header(emf_mailbox_t* mailbox, unsigned* handle);\r
 223 \r
 224 \r
 225 /**\r
 226  * @open\r
 227  * @fn email_sync_header_for_all_account(unsigned* handle)\r
 228  * @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.\r
 229  *\r
 230  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 231  * @param[out] handle           Specifies the handle for stopping downloading.\r
 232  * @exception none\r
 233  * @see         none\r
 234  * @remarks N/A\r
 235  */\r
 236 EXPORT_API int email_sync_header_for_all_account(unsigned* handle);\r
 237 \r
 238 \r
 239 /**\r
 240  * @open\r
 241  * @fn email_download_body(emf_mailbox_t* mailbox, int mail_id, int with_attachment, unsigned* handle)\r
 242  * @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\r
 243  *              from the server.\r
 244  *\r
 245  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 246  * @param[in] mailbox                   Specifies the structure of mailbox.\r
 247  * @param[in] mail_id                   Specifies the mail ID.\r
 248  * @param[in] with_attachment   Specifies the whether attachment is there or not.\r
 249  * @param[out] handle           Specifies the handle for stopping downloading.\r
 250  * @exception none\r
 251  * @see emf_mailbox_t\r
 252  * @remarks N/A\r
 253  */\r
 254 EXPORT_API int email_download_body(emf_mailbox_t* mailbox, int mail_id, int with_attachment, unsigned* handle);\r
 255 \r
 256 \r
 257 \r
 258 \r
 259 \r
 260 \r
 261 /**\r
 262  * @open\r
 263  * @fn email_download_attachment(emf_mailbox_t* mailbox, int mail_id, char* nth, unsigned* handle);\r
 264  * @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.\r
 265  *\r
 266  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 267  * @param[in] mailbox           Reserved.\r
 268  * @param[in] mail_id           Specifies the mail ID.\r
 269  * @param[in] nth                       Specifies the buffer that a attachment number been saved. the minimum number is "1".\r
 270  * @param[out] handle           Specifies the handle for stopping downloading.\r
 271  * @exception none\r
 272  * @see         emf_mailbox_t\r
 273  * @remarks N/A\r
 274  */\r
 275 EXPORT_API int email_download_attachment(emf_mailbox_t* mailbox,\r
 276                                                         int mail_id,\r
 277                                                         const char* nth,\r
 278                                                         unsigned* handle);\r
 279 \r
 280 \r
 281 /**\r
 282  * @open\r
 283  * @fn email_cancel_job(int account_id, int handle);\r
 284  * @brief       cancel the ongoing job.This function is invoked if user wants to cancel any ongoing job of a specified account.\r
 285  *\r
 286  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 287  * @param[in] account_id        Specifies the account ID.\r
 288  * @param[in] handle            Specifies the handle for stopping the operation.\r
 289  * @exception    none\r
 290  * @see         none\r
 291  * @remarks N/A\r
 292  */\r
 293 \r
 294 EXPORT_API int email_cancel_job(int account_id, int handle);\r
 295 \r
 296 \r
 297 /**\r
 298  * @open\r
 299  * @fn email_get_pending_job(emf_action_t action, int account_id, int mail_id, emf_event_status_type_t * status);\r
 300  * @brief       get pending job list.This function is invoked if user wants to get the pending job list with status information .\r
 301  *              Based on action item of a mail is for a specific account this will give all pending job list.\r
 302  *\r
 303  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 304  * @param[in] account_id        Specifies the action of the job.\r
 305  * @param[in] account_id        Specifies the account ID.\r
 306  * @param[in] mail_id           Specifies the mail ID.\r
 307  * @param[out]status            Specifies the status of the job.\r
 308  * @exception    none\r
 309  * @see         emf_action_t and emf_event_status_type_t\r
 310  * @remarks N/A\r
 311  */\r
 312 EXPORT_API int email_get_pending_job(emf_action_t action, int account_id, int mail_id, emf_event_status_type_t * status);\r
 313 \r
 314 \r
 315 /**\r
 316  * @open\r
 317  * @fn email_get_network_status(int* on_sending, int* on_receiving)\r
 318  * @brief       This function gives the  current network status.This gives the information to the user whether sending operation is in progress or receiving operation.\r
 319  *\r
 320  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 321  * @param[out] on_sending               True if sending is in progress.\r
 322  * @param[out] on_receiving             True if receivng is in progress.\r
 323  * @exception   none\r
 324  * @see         none\r
 325  * @remarks N/A\r
 326  */\r
 327 EXPORT_API int email_get_network_status(int* on_sending, int* on_receiving);\r
 328 \r
 329 /**\r
 330  * @open\r
 331  * @fn email_send_saved(int account_id, emf_option_t* sending_option, unsigned* handle)\r
 332  * @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.\r
 333  *              This will save the email in draft mailbox and then sends.\r
 334  *\r
 335  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 336  * @param[in] account_id                        Specifies the account ID.\r
 337  * @param[in] sending_option            Specifies the sending option.\r
 338  * @param[out] handle                           Specifies the handle for stopping sending.\r
 339  * @exception none\r
 340  * @see emf_option_t\r
 341  * @remarks N/A\r
 342  */\r
 343 EXPORT_API int email_send_saved(int account_id, emf_option_t* sending_option, unsigned* handle);\r
 344 \r
 345 /**\r
 346  * @open\r
 347  * @fn email_get_imap_mailbox_list(int account_id, char* mailbox, unsigned* handle)\r
 348  *  @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\r
 349  *\r
 350  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 351  * @param[in] account_id                        Specifies the account ID.\r
 352  * @param[in] mailbox                   Specifies the mailbox name.\r
 353  * @param[out] handle                   Specifies the handle for stopping Network operation.\r
 354  * @exception   none\r
 355  * @see         none\r
 356  * @remarks N/A\r
 357  */\r
 358 EXPORT_API int email_get_imap_mailbox_list(int account_id, const char* mailbox, unsigned* handle);\r
 359 \r
 360 \r
 361 \r
 362 /**\r
 363  * @open\r
 364  * @fn email_sync_local_activity(int account_id)\r
 365  *  @brief      sync local activity\r
 366  *\r
 367  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 368  * @param[in] account_id                        Specifies the account ID.\r
 369  * @exception   none\r
 370  * @see         none\r
 371  * @remarks N/A\r
 372  */\r
 373 EXPORT_API int email_sync_local_activity(int account_id);\r
 374 \r
 375 \r
 376 /**\r
 377  * @open\r
 378  * @fn email_search_mail_on_server(int account_id, const char *mailbox_name, int search_type, char *search_value)\r
 379  * @brief       Search the mails on server.\r
 380  *\r
 381  * @return This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.\r
 382  * @param[in] account_id        Specifies the Account ID\r
 383  * @param[in] mailbox_name      Specifies the Mailbox Name\r
 384  * @param[in] search_type       Specifies the searching type(EMF_SEARCH_FILTER_SUBJECT,  EMF_SEARCH_FILTER_SENDER, EMF_SEARCH_FILTER_RECIPIENT, EMF_SEARCH_FILTER_ALL)\r
 385  * @param[in] search_value      Specifies the value to use for searching. (ex : Subject, email address, display name)\r
 386  * @exception           none\r
 387  * @see\r
 388  * @code\r
 389  * @endcode\r
 390  * @remarks N/A\r
 391  */\r
 392 EXPORT_API int email_search_mail_on_server(int input_account_id, const char *input_mailbox_name, email_search_filter_t *input_search_filter_list, int input_search_filter_count, unsigned *output_handle);\r
 393 \r
 394 #ifdef __cplusplus\r
 395 }\r
 396 #endif /* __cplusplus */\r
 397 \r
 398 /**\r
 399 * @}\r
 400 */\r
 401 \r
 402 \r
 403 #endif /* __EMAIL_API_NETWORK_H__ */\r