MAPI/include/Emf_Mapi_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 __EMF_MAPI_NETWORK_H__
  24 #define __EMF_MAPI_NETWORK_H__
  25
  26 #include "emf-types.h"
  27
  28 /**
  29 * @defgroup EMAIL_FRAMEWORK Email Service
  30 * @{
  31 */
  32
  33 /**
  34 * @ingroup EMAIL_FRAMEWORK
  35 * @defgroup EMAIL_MAPI_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 Engine.
  43  * @file                Emf_Mapi_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 Engine .
  49  *
  50  * @{
  51
  52  * @code
  53
  54  *      #include "Emf_Mapi_Network.h"
  55  *
  56  *      bool
  57  *      other_app_invoke_uniform_api_sample(int* error_code)
  58  *      {
  59  *
  60  *              // Send a mail
  61  *              emf_mailbox_t mbox;
  62  *              emf_mail_t *mail = NULL;
  63  *              emf_mail_head_t *head =NULL;
  64  *              emf_mail_body_t *body =NULL;
  65  *              emf_attachment_info_t attachment;
  66  *              emf_option_t option;
  67  *              int account_id = 1;
  68  *              int err = EMF_ERROR_NONE;
  69  *              int mail_id = 1;
  70  *              char arg[50]; //Input attachment number need to be download
  71  *              emf_event_status_type_t  status;
  72  *              int action = -1;
  73  *              int on_sending = 0;
  74  *              int on_receiving = 0;
  75  *
  76  *              mail =( emf_mail_t *)malloc(sizeof(emf_mail_t));
  77  *              head =( emf_mail_head_t *)malloc(sizeof(emf_mail_head_t));
  78  *              body =( emf_mail_body_t *)malloc(sizeof(emf_mail_body_t));
  79  *              mail->info =( emf_mail_info_t*) malloc(sizeof(emf_mail_info_t));
  80  *              memset(mail->info, 0x00, sizeof(emf_mail_info_t));
  81  *
  82  *              memset(&mbox, 0x00, sizeof(emf_mailbox_t));
  83  *              memset(&option, 0x00, sizeof(emf_option_t));
  84  *              memset(mail, 0x00, sizeof(emf_mail_t));
  85  *              memset(head, 0x00, sizeof(emf_mail_head_t));
  86  *              memset(body, 0x00, sizeof(emf_mail_body_t));
  87  *              memset(&attachment, 0x00, sizeof(emf_attachment_info_t));
  88  *
  89  *              option.keep_local_copy = 1;
  90  *
  91  *              mbox.account_id = account_id;
  92  *              mbox.name = strdup("OUTBOX");
  93  *              head->to=strdup("test@test.com");
  94  *              head->subject =strdup("test");
  95  *              body->plain = strdup("/tmp/mail.txt");
  96  *
  97  *              mail->info->account_id = account_id;
  98  *              mail->info->flags.draft = 1;
  99  *              mail->body = body;
 100  *              mail->head = head;
 101  *
 102  *              attachment.name = strdup("attach");
 103  *              attachment.savename = strdup("/tmp/mail.txt");
 104  *              attachment.next = NULL;
 105  *              mail->body->attachment = &attachment;
 106  *              mail->body->attachment_num = 1;
 107  *              if(EMF_ERROR_NONE  == email_add_message(mail,&mbox,1))
 108  *              {
 109  *                      if(EMF_ERROR_NONE == email_send_mail(&mbox, mail->info->uid,&option,&handle))
 110  *                              //success
 111  *                      else
 112  *                              //failure
 113  *              }
 114  *
 115  *              // Download header of new emails from mail server
 116  *              unsigned handle = 0;
 117  *
 118  *              memset(&mbox, 0x00, sizeof(emf_mailbox_t));
 119  *
 120  *              mbox.account_id = account_id;
 121  *              mbox.name = strdup("INBOX");
 122  *              if(EMF_ERROR_NONE == email_sync_header (&mbox,&handle))
 123  *                      //success
 124  *              else
 125  *                      //failure
 126  *
 127  *              //Sync mail header for all accounts
 128  *              if(EMF_ERROR_NONE == email_sync_header_for_all_account(&handle))
 129  *                      //success
 130  *              else
 131  *                      //failure
 132  *
 133  *              //Download email body from server
 134  *
 135  *              memset(&mbox, 0x00, sizeof(emf_mailbox_t));
 136  *              mbox.account_id = account_id;
 137  *              mbox.name = strdup("INBOX");
 138  *              if(EMF_ERROR_NONE == email_download_body (&mbox,mail_id,0,&handle))
 139  *                      //success
 140  *              else
 141  *                      //failure
 142  *
 143  *              //Download a email nth-attachment from server
 144  *              prinf("Enter attachment number\n");
 145  *              scanf("%s",arg);
 146  *              memset(&mbox, 0x00, sizeof(emf_mailbox_t));
 147  *              mbox.name = strdup("INBOX");
 148  *              mbox.account_id = account_id;
 149  *              if(EMF_ERROR_NONE == email_download_attachment(&mailbox,mail_id,arg,&handle))
 150  *                      //success
 151  *              else
 152  *                      //failure
 153  *
 154  *              //Cancel job
 155  *              if(EMF_ERROR_NONE == email_cancel_job(account_id,handle))//canceling download email nth attachment from server job.
 156  *                                                                      //so this handle contains the value return by the email_download_attachment()
 157  *                      //success
 158  *              else
 159  *                      //failure
 160  *              //Get pending job listfor an account
 161  *
 162  *              printf( " Enter Action \n SEND_MAIL = 0 \n SYNC_HEADER = 1 \n" \
 163  *                          " DOWNLOAD_BODY,= 2 \n DOWNLOAD_ATTACHMENT = 3 \n" \
 164  *                          " DELETE_MAIL = 4 \n SEARCH_MAIL = 5 \n SAVE_MAIL = 6 \n" \
 165  *                          " NUM = 7 \n");
 166  *              scanf("%d",&action);
 167  *              if(EMF_ERROR_NONE == email_get_pending_job(action,account_id,mail_id,&status))
 168  *                      //success
 169  *              else
 170  *                      //error
 171  *
 172  *              //Get Network status
 173  *              if(EMF_ERROR_NONE == email_get_network_status(&sending,&receiving))
 174  *                      //success
 175  *              else
 176  *                      //failure
 177  *
 178  *              //Send read report
 179  *              if(EMF_ERROR_NONE == email_send_report(mail ,&handle))
 180  *                      //success
 181  *              else
 182  *                      //failure
 183  *              //Save and send
 184  *
 185  *              mbox.account_id = account_id;
 186  *              mbox.name = strdup("DRAFTBOX");
 187  *
 188  *              if(EMF_ERROR_NONE  == email_add_message(mail,&mbox,1))
 189  *              {
 190  *                      if(EMF_ERROR_NONE == email_send_saved(account_id,&option,&handle))
 191  *                              //success
 192  *                      else
 193  *                              //failure
 194  *              }
 195  *              //Get Imap mailbox list
 196  *              printf("\n > Enter server name:\n");
 197  *              scanf("%s",arg);
 198  *              if(EMF_ERROR_NONE == email_get_imap_mailbox_list(account_id , arg , &handle))
 199  *                      //success
 200  *              else
 201  *                      //failure
 202  *
 203  *              //sync local activity
 204  *              if(EMF_ERROR_NONE == email_sync_local_activity(account_id))
 205  *                      //success
 206  *              else
 207  *                      //failure
 208  * }
 209  *
 210  * @endcode
 211  * @}
 212
 213  */
 214
 215
 216
 217 #ifdef __cplusplus
 218 extern "C" {
 219 #endif /* __cplusplus */
 220
 221 /**
 222  * @open
 223  * @fn email_send_mail( emf_mailbox_t* mailbox, int mail_id, emf_option_t* sending_option, unsigned* handle)
 224  * @brief       Send a mail.This function is invoked when user wants to send a composed mail.
 225  *
 226  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 227  * @param[in] mailbox                   Specifies the mailbox to consist a sending email.
 228  * @param[in] mail_id                   Specifies the mail ID.
 229  * @param[in] sending_option            Specifies the sending option.
 230  * @param[out] handle           Specifies the sending handle.
 231  * @exception   none
 232  * @see         emf_mailbox_t and emf_option_t
 233  * @remarks N/A
 234  */
 235 EXPORT_API int email_send_mail( emf_mailbox_t* mailbox,
 236                                 int mail_id,
 237                                 emf_option_t* sending_option,
 238                                 unsigned* handle);
 239
 240
 241 /**
 242  * @open
 243  * @fn email_sync_header(emf_mailbox_t* mailbox, unsigned* handle)
 244  * @brief       Download header of new emails from mail server.This function is invoked when user wants to download only header of new mails.
 245  *
 246  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 247  * @param[in] mailbox           Specifies the structure of mailbox.
 248  * @param[out] handle           Specifies the handle for stopping downloading.
 249  * @exception   none
 250  * @see         emf_mailbox_t
 251  * @remarks N/A
 252  */
 253 EXPORT_API int email_sync_header(emf_mailbox_t* mailbox, unsigned* handle);
 254
 255
 256 /**
 257  * @open
 258  * @fn email_sync_header_for_all_account(unsigned* handle)
 259  * @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.
 260  *
 261  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 262  * @param[out] handle           Specifies the handle for stopping downloading.
 263  * @exception none
 264  * @see         none
 265  * @remarks N/A
 266  */
 267 EXPORT_API int email_sync_header_for_all_account(unsigned* handle);
 268
 269
 270 /**
 271  * @open
 272  * @fn email_download_body(emf_mailbox_t* mailbox, int mail_id, int with_attachment, unsigned* handle)
 273  * @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
 274  *              from the server.
 275  *
 276  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 277  * @param[in] mailbox                   Specifies the structure of mailbox.
 278  * @param[in] mail_id                   Specifies the mail ID.
 279  * @param[in] with_attachment   Specifies the whether attachment is there or not.
 280  * @param[out] handle           Specifies the handle for stopping downloading.
 281  * @exception none
 282  * @see emf_mailbox_t
 283  * @remarks N/A
 284  */
 285 EXPORT_API int email_download_body(emf_mailbox_t* mailbox, int mail_id, int with_attachment, unsigned* handle);
 286
 287
 288
 289
 290
 291
 292 /**
 293  * @open
 294  * @fn email_download_attachment(emf_mailbox_t* mailbox, int mail_id, char* nth, unsigned* handle);
 295  * @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.
 296  *
 297  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 298  * @param[in] mailbox           Reserved.
 299  * @param[in] mail_id           Specifies the mail ID.
 300  * @param[in] nth                       Specifies the buffer that a attachment number been saved. the minimum number is "1".
 301  * @param[out] handle           Specifies the handle for stopping downloading.
 302  * @exception none
 303  * @see         emf_mailbox_t
 304  * @remarks N/A
 305  */
 306 EXPORT_API int email_download_attachment(emf_mailbox_t* mailbox,
 307                                                         int mail_id,
 308                                                         const char* nth,
 309                                                         unsigned* handle);
 310
 311
 312 /**
 313  * @open
 314  * @fn email_cancel_job(int account_id, int handle);
 315  * @brief       cancel the ongoing job.This function is invoked if user wants to cancel any ongoing job of a specified account.
 316  *
 317  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 318  * @param[in] account_id        Specifies the account ID.
 319  * @param[in] handle            Specifies the handle for stopping the operation.
 320  * @exception    none
 321  * @see         none
 322  * @remarks N/A
 323  */
 324
 325 EXPORT_API int email_cancel_job(int account_id, int handle);
 326
 327
 328 /**
 329  * @open
 330  * @fn email_get_pending_job(emf_action_t action, int account_id, int mail_id, emf_event_status_type_t * status);
 331  * @brief       get pending job list.This function is invoked if user wants to get the pending job list with status information .
 332  *              Based on action item of a mail is for a specific account this will give all pending job list.
 333  *
 334  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 335  * @param[in] account_id        Specifies the action of the job.
 336  * @param[in] account_id        Specifies the account ID.
 337  * @param[in] mail_id           Specifies the mail ID.
 338  * @param[out]status            Specifies the status of the job.
 339  * @exception    none
 340  * @see         emf_action_t and emf_event_status_type_t
 341  * @remarks N/A
 342  */
 343 EXPORT_API int email_get_pending_job(emf_action_t action, int account_id, int mail_id, emf_event_status_type_t * status);
 344
 345
 346 /**
 347  * @open
 348  * @fn email_get_network_status(int* on_sending, int* on_receiving)
 349  * @brief       This function gives the  current network status.This gives the information to the user whether sending operation is in progress or receiving operation.
 350  *
 351  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 352  * @param[out] on_sending               True if sending is in progress.
 353  * @param[out] on_receiving             True if receivng is in progress.
 354  * @exception   none
 355  * @see         none
 356  * @remarks N/A
 357  */
 358 EXPORT_API int email_get_network_status(int* on_sending, int* on_receiving);
 359
 360
 361 /**
 362  * @open
 363  * @fn email_send_report(emf_mail_t* mail, unsigned* handle)
 364  * @brief       Send 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.
 365  *
 366  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 367  * @param[in] mail                              Specifies the mail to been read.
 368  * @param[out] handle                   Specifies the handle for stopping sending.
 369  * @exception none
 370  * @see         emf_mail_t
 371  * @remarks N/A
 372  */
 373 EXPORT_API int email_send_report(emf_mail_t* mail,  unsigned* handle);
 374
 375
 376 /**
 377  * @open
 378  * @fn email_send_saved(int account_id, emf_option_t* sending_option, unsigned* handle)
 379  * @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.
 380  *              This will save the email in draft mailbox and then sends.
 381  *
 382  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 383  * @param[in] account_id                        Specifies the account ID.
 384  * @param[in] sending_option            Specifies the sending option.
 385  * @param[out] handle                           Specifies the handle for stopping sending.
 386  * @exception none
 387  * @see emf_option_t
 388  * @remarks N/A
 389  */
 390 EXPORT_API int email_send_saved(int account_id, emf_option_t* sending_option, unsigned* handle);
 391
 392
 393 EXPORT_API int email_download_mail_from_server(emf_mailbox_t * mailbox, const char * server_mail_id, unsigned* handle) DEPRECATED;
 394
 395
 396 /**
 397  * @open
 398  * @fn email_get_imap_mailbox_list(int account_id, char* mailbox, unsigned* handle)
 399  *  @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
 400  *
 401  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 402  * @param[in] account_id                        Specifies the account ID.
 403  * @param[in] mailbox                   Specifies the mailbox name.
 404  * @param[out] handle                   Specifies the handle for stopping Network operation.
 405  * @exception   none
 406  * @see         none
 407  * @remarks N/A
 408  */
 409 EXPORT_API int email_get_imap_mailbox_list(int account_id, const char* mailbox, unsigned* handle);
 410
 411
 412
 413 /**
 414  * @open
 415  * @fn email_sync_local_activity(int account_id)
 416  *  @brief      sync local activity
 417  *
 418  * @return      This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 419  * @param[in] account_id                        Specifies the account ID.
 420  * @exception   none
 421  * @see         none
 422  * @remarks N/A
 423  */
 424 EXPORT_API int email_sync_local_activity(int account_id);
 425
 426
 427 /**
 428  * @open
 429  * @fn email_find_mail_on_server(int account_id, const char *mailbox_name, int search_type, char *search_value)
 430  * @brief       Search the mails on server.
 431  *
 432  * @return This function returns EMF_ERROR_NONE on success or error code (refer to EMF_ERROR_XXX) on failure.
 433  * @param[in] account_id        Specifies the Account ID
 434  * @param[in] mailbox_name      Specifies the Mailbox Name
 435  * @param[in] search_type       Specifies the searching type(EMF_SEARCH_FILTER_SUBJECT,  EMF_SEARCH_FILTER_SENDER, EMF_SEARCH_FILTER_RECIPIENT, EMF_SEARCH_FILTER_ALL)
 436  * @param[in] search_value      Specifies the value to use for searching. (ex : Subject, email address, display name)
 437  * @exception           none
 438  * @see
 439  * @code
 440  * @endcode
 441  * @remarks N/A
 442  */
 443 EXPORT_API int email_find_mail_on_server(int input_account_id, const char *input_mailbox_name, int input_search_type, char *input_search_value, unsigned *output_handle);
 444
 445 #ifdef __cplusplus
 446 }
 447 #endif /* __cplusplus */
 448
 449 /**
 450 * @}
 451 */
 452
 453
 454 #endif /* __EMF_MAPI_NETWORK_H__ */