email-service_PG.h

   1 /**\r
   2  *\r
   3  * @ingroup   PG\r
   4  * @defgroup   EMAILSVC Email Service\r
   5 @{\r
   6 <h1 class="pg">Introduction</h1>\r
   7         <h2 class="pg">Overview </h2>\r
   8 Electronic mail, most commonly abbreviated email or e-mail, is a method of exchanging digital messages. E-mail systems are based on a store-and-forward model in which e-mail server computer systems accept, forward, deliver and store messages on behalf of users, who only need to connect to the e-mail infrastructure, typically an e-mail server, with a network-enabled device for the duration of message submission or retrieval.\r
   9 \r
  10         <h2 class="pg">Purpose of Programming Guide</h2>\r
  11 This document is mainly aimed at the core functionality of the Email Service.  The EMail Service component is implemented by Samsung to provide EMail service to applications that make use of EMail Engine. Email Engine provides functionality for the user like composing mail, saving mail, sending mail, and creating user mailbox according to the settings. Mobile subscribers can use the Email Engine to perform storage opearations such as save, update, get, delete and transport operations such as send, download and other email operations.\r
  12 \r
  13 This programming guide is prepared for application developers who will use the email-service. It contains: \r
  14 - List of features offered by email-service\r
  15 - Information on How to use APIs provided by the email-service\r
  16 - Examples \r
  17 \r
  18         <h2 class="pg">Target Domain / Application</h2>\r
  19 The Email Service Layer can be utilized by any component in the application layer which allow the end user to perform the email related operations such as save, send, download email message and others.\r
  20 \r
  21 For Example, the Email Service APIs shall be invoked by \r
  22 @li Multimedia application when user opts to send media file through email \r
  23 @li Email application when user tries to send an email message \r
  24 \r
  25         <h2 class="pg">Terminology & Acronyms</h2>\r
  26 <table>\r
  27 <tr><th>Terminology</th><th>Description</th></tr>\r
  28 <tr><td>Email </td><td>Electronic mail</td></tr>\r
  29 <tr><td>IMAP</td><td>Internet Message Access Protocol</td></tr>\r
  30 <tr><td>SMTP</td><td>Simple mail transfer protocol for sending mails</td></tr>\r
  31 <tr><td>POP3</td><td>Post office protocol for receiving mails</td></tr>\r
  32 <tr><td>RFC822</td><td>Describes mail header, to address, cc, bcc etc. formats and decoding and encoding standards. </td></tr>\r
  33 <tr><td>OMA </td><td>Open Moblie Alliance</td></tr>\r
  34 </table> \r
  35 \r
  36 \r
  37 @}\r
  38 \r
  39 @defgroup Email_Architecture 1. Email Service Architecture\r
  40 @ingroup EMAILSVC\r
  41 @{\r
  42 <h1 class="pg">Email-service Architecture</h1>\r
  43         <h2 class="pg">System Architecture</h2>\r
  44 @image html email_image001.png\r
  45  \r
  46         <h2 class="pg">Process Architecture</h2>\r
  47 @image html email_image002.png email-service Process view\r
  48 \r
  49 @image html email_image003.png email-service Process architecture\r
  50 \r
  51 Whenever an application wants to use email-service, it will call APIs from Email MAPI layer. Email MAPI layer APIs will internally call APIs provided by email framework module.\r
  52 @}\r
  53 \r
  54 @defgroup Email_Feature 2. Email Service Feature\r
  55 @ingroup EMAILSVC\r
  56 @{\r
  57 <h1 class="pg">Email-service Features</h1>\r
  58 <table>\r
  59 <tr><th>Feature </th><th>API Reference</th></tr>\r
  60 <tr><td>Account Operation</td>\r
  61 <td>\r
  62 @n email_add_account()\r
  63 @n email_delete_account() \r
  64 @n email_update_account() \r
  65 @n email_get_account() \r
  66 @n email_get_account_list() \r
  67 @n email_free_account() \r
  68 @n email_validate_account()\r
  69 </td></tr>\r
  70  \r
  71 <tr><td>mailbox Operation </td>\r
  72 <td>\r
  73 @n email_add_mailbox()\r
  74 @n email_delete_mailbox()\r
  75 @n email_update_mailbox()\r
  76 @n email_get_mailbox_list()\r
  77 @n email_get_mailbox_by_name()\r
  78 @n email_get_child_mailbox_list()\r
  79 @n email_get_mailbox_by_mailbox_type()\r
  80 </td></tr>\r
  81  \r
  82 <tr><td>Message Operation </td>\r
  83 <td>\r
  84 @n email_add_message()  \r
  85 @n email_update_message()\r
  86 @n email_count_message()  \r
  87 @n email_delete_message()  \r
  88 @n email_delete_all_message_in_mailbox()\r
  89 @n email_clear_mail_data()\r
  90 @n email_add_attachment()\r
  91 @n email_delete_attachment() \r
  92 @n email_get_info()\r
  93 @n email_free_mail_info()\r
  94 @n email_get_header_info()  \r
  95 @n email_free_header_info()  \r
  96 @n email_get_body_info()\r
  97 @n email_free_body_info()\r
  98 @n email_get_attachment_info() \r
  99 @n email_free_attachment_info()  \r
 100 @n email_get_mail() \r
 101 @n email_modify_mail_flag()\r
 102 @n email_modify_seen_flag()\r
 103 @n email_modify_extra_mail_flag()\r
 104 @n email_move_mail_to_mailbox()\r
 105 @n email_move_all_mails_to_mailbox()\r
 106 @n email_count_message_with_draft_flag()\r
 107 @n email_count_message_on_sending()\r
 108 @n email_get_mailbox_list()\r
 109 @n email_free_mailbox()\r
 110 @n email_free_mail()\r
 111 @n email_get_mail_flag()\r
 112 @n email_free_mail_list()\r
 113 @n email_release_mail()\r
 114 @n email_retry_send_mail()\r
 115 @n email_create_db_full()\r
 116 @n email_get_mailbox_name_by_mail_id()\r
 117 @n email_cancel_send_mail()\r
 118 @n email_count_message_all_mailboxes()\r
 119 @n email_get_latest_unread_mail_id()\r
 120 @n email_get_max_mail_count()\r
 121 @n email_get_disk_space_usage()\r
 122 </td></tr>\r
 123  \r
 124 <tr><td>Network Operation </td>\r
 125 <td>\r
 126 @n email_send_mail()\r
 127 @n email_sync_header()\r
 128 @n email_download_body()\r
 129 @n email_download_attachment()\r
 130 @n email_cancel_job()\r
 131 @n email_get_pending_job()\r
 132 @n email_get_network_status()\r
 133 @n email_send_report()\r
 134 @n email_send_saved()\r
 135 @n email_get_imap_mailbox_list()\r
 136 @n email_sync_local_activity()\r
 137 </td></tr>\r
 138  \r
 139 <tr><td>Rule Operation </td>\r
 140 <td>\r
 141 @n email_get_rule()\r
 142 @n email_get_rule_list()\r
 143 @n email_add_rule()\r
 144 @n email_update_rule()\r
 145 @n email_delete_rule()\r
 146 @n email_free_rule()\r
 147 </td></tr>\r
 148  \r
 149 <tr><td>Control Operation </td>\r
 150 <td>\r
 151 @n email_init_storage()\r
 152 @n email_open_db()\r
 153 @n email_close_db()\r
 154 @n email_service_begin()\r
 155 @n email_service_end()\r
 156 </td></tr>\r
 157 </table>\r
 158 @}\r
 159 \r
 160 \r
 161 \r
 162 @defgroup Use_Case1_account Account Operation\r
 163 @ingroup EMAIL_USECASES\r
 164 @{\r
 165         <h2 class="pg">Account Operation </h2>\r
 166 Account Operations are a set of operations to manage email accounts like add, update, delete or get account related details.\r
 167 \r
 168 Structure:\r
 169 emf_account_t \r
 170 <table>\r
 171 <tr><td>API</td>\r
 172 <td>Return Value / Exceptions</td></tr>\r
 173 \r
 174 <tr><td>int email_add_account(emf_account_t* account)</td>\r
 175 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for param emf_account_t* account should be allocated and deallocated by Application</td></tr>\r
 176 \r
 177 <tr><td>int email_delete_account(int account_id) </td>\r
 178 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 179   \r
 180 <tr><td>int email_update_account(int account_id , emf_account_t* new_account) </td>\r
 181 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks:  - Memory for param emf_account_t* new_account should be allocated and deallocated by Application</td></tr>\r
 182   \r
 183 <tr><td>int email_get_account(int account_id, int pulloption, emf_account_t** account) </td>\r
 184 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory allocation for param account will happen in email_get_account (). To free this memory, application should call email_free_account ()</td></tr>\r
 185   \r
 186 <tr><td>int email_get_account_list(emf_account_t** account_list, int* count) </td>\r
 187 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: Memory allocation for param ccount_list will happen in email_get_account_list (). To free this memory, application should call email_free_account () </td></tr>\r
 188   \r
 189 <tr><td>int email_free_account(emf_account_t** account_list, int count) </td>\r
 190 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 191   \r
 192 <tr><td>int email_validate_account(int account_id, unsigned* handle)</td>\r
 193 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 194 </table> \r
 195 \r
 196 <b>Sample Code</b>\r
 197 @li Add account\r
 198 @code\r
 199 /* Add account */       \r
 200 \r
 201 /*  Assign values for new account */\r
 202 emf_account_t *account = NULL;\r
 203  \r
 204 account = malloc(sizeof(emf_account_t));\r
 205 memset(account, 0x00, sizeof(emf_account_t));\r
 206  \r
 207 account->account_bind_type      = 1;                           \r
 208 account->retrieval_mode         = 1;                                                   \r
 209 account->use_security           = 1;                                                   \r
 210 account->sending_server_type    = EMF_SERVER_TYPE_SMTP; \r
 211 account->sending_port_num       = EMF_SMTP_PORT;                          \r
 212 account->sending_auth           = 1;   \r
 213 account->flag1 = 2;\r
 214 account->account_bind_type      = 1;                           \r
 215 account->account_name           = strdup("gmail"); \r
 216 account->display_name           = strdup("Tom"); \r
 217 account->email_addr             = strdup("tom@gmail.com"); \r
 218 account->reply_to_addr          = strdup("tom@gmail.com"); \r
 219 account->return_addr            = strdup("tom@gmail.com"); \r
 220 account->receiving_server_type  = EMF_SERVER_TYPE_POP3; \r
 221 account->receiving_server_addr  = strdup("pop3.gmail.com"); \r
 222 account->port_num               = 995;        \r
 223 account->use_security           = 1;                                                   \r
 224 account->retrieval_mode         = EMF_IMAP4_RETRIEVAL_MODE_ALL;\r
 225 account->user_name              = strdup("tom"); \r
 226 account->password               = strdup("tioimi"); \r
 227 account->sending_server_type    = EMF_SERVER_TYPE_SMTP;                               \r
 228 account->sending_server_addr    = strdup("smtp.gmail.com"); \r
 229 account->sending_port_num       = 587;                                                        \r
 230 account->sending_security       = 0x02;  \r
 231 account->sending_auth           = 1;   \r
 232 account->sending_user           = strdup("tom@gmail.com"); \r
 233 account->sending_password       = strdup("tioimi");\r
 234 account->pop_before_smtp        = 0;\r
 235 account->apop                   = 0;\r
 236 account->flag1                  = 2;                \r
 237 account->flag2                  = 1; \r
 238 account->preset_account         = 1;       \r
 239 account->logo_icon_path         = strdup("Logo Icon Path"); \r
 240 account->target_storage         = 0;                            \r
 241 account->options.priority = 3;   \r
 242 account->options.keep_local_copy = 0;   \r
 243 account->options.req_delivery_receipt = 0;   \r
 244 account->options.req_read_receipt = 0;   \r
 245 account->options.download_limit = 0;   \r
 246 account->options.block_address = 0;   \r
 247 account->options.block_subject = 0;   \r
 248 account->options.display_name_from = strdup("Display name from"); \r
 249 account->options.reply_with_body = 0;   \r
 250 account->options.forward_with_files = 0;   \r
 251 account->options.add_myname_card = 0;   \r
 252 account->options.add_signature = 0;   \r
 253 account->options.signature= strdup("Signature");    \r
 254 account->check_interval = 0;  \r
 255       \r
 256 if(EMF_ERROR_NONE != email_add_account(account))\r
 257         /* failure */\r
 258 else\r
 259 {\r
 260         /* success     */\r
 261         if(account_id)\r
 262                 *account_id = account->account_id;              /*  Use this returned account id when calling APIs which need it */\r
 263 }\r
 264 \r
 265 /* free account */\r
 266 email_free_account(&account, 1);\r
 267  \r
 268 @endcode \r
 269 \r
 270 @li Get account\r
 271 @code\r
 272 /* Get account */\r
 273  \r
 274 emf_account_t *account = NULL;\r
 275 int account_id = 1;             /*  account id to be gotten */\r
 276  \r
 277 if(EMF_ERROR_NONE != email_get_account(account_id,GET_FULL_DATA,&account))\r
 278         /* failure */\r
 279 else\r
 280         /* success */\r
 281  \r
 282 /* free account */\r
 283 email_free_account(&account, 1);\r
 284  \r
 285 @endcode\r
 286 \r
 287 @li Update account\r
 288 @code\r
 289 /* Update account */               \r
 290 \r
 291 emf_account_t *new_account = NULL;\r
 292 int account_id = 1;             /*  account id to be updated */\r
 293  \r
 294 /*  Get account to be updated */\r
 295 if(EMF_ERROR_NONE != email_get_account(account_id,GET_FULL_DATA,&new_account))\r
 296         /* failure */\r
 297 else\r
 298         /* success */\r
 299  \r
 300 /*  Set the new values */\r
 301 new_account->flag1 = 1;\r
 302 new_account->account_name           = strdup("gmail"); \r
 303 new_account->display_name           = strdup("Tom001");             \r
 304 new_account->options.keep_local_copy = 1;   \r
 305 new_account->check_interval = 55;  \r
 306  \r
 307 if(EMF_ERROR_NONE != email_update_account(account_id,new_account))\r
 308         /* failure */\r
 309 else\r
 310         /* success */\r
 311  \r
 312 /* free account */\r
 313 email_free_account(&new_account, 1);\r
 314 \r
 315 @endcode\r
 316 \r
 317 @li Delete account\r
 318 @code \r
 319 /* Delete account */\r
 320 \r
 321 int account_id = 1;             /*  account id to be deleted */\r
 322  \r
 323 if(EMF_ERROR_NONE != email_delete_account(account_id))\r
 324       /* failure */\r
 325 else\r
 326       /* success */\r
 327  \r
 328 @endcode\r
 329 \r
 330 \r
 331 @li Get list of accounts\r
 332 @code\r
 333 /* Get list of accounts */\r
 334 \r
 335 emf_account_t *account_list = NULL;\r
 336 int count = 0;          \r
 337 int i;\r
 338  \r
 339 if(EMF_ERROR_NONE != email_get_account_list(&account_list,&count))\r
 340         /* failure */\r
 341 else\r
 342 {\r
 343         /* success */\r
 344         for ( i = 0; i < count; i++ )\r
 345         {\r
 346                 /*  Do something with each account */\r
 347                 printf("account id : %d\n", account_list[i].account_id);\r
 348         }\r
 349 }       \r
 350  \r
 351 /* free account */\r
 352 email_free_account(&account_list,count);\r
 353 \r
 354 @endcode\r
 355 \r
 356 @li Validate account - try to connect to server\r
 357 @code\r
 358 /* Validate account - try to connect to server */\r
 359 unsigned account_handle = 0;\r
 360 int account_id = 1;\r
 361  \r
 362 if(EMF_ERROR_NONE != email_validate_account(account_id,&account_handle))\r
 363         /* failure */\r
 364 else\r
 365         /* success */\r
 366 @endcode\r
 367  \r
 368 <b>Flow Diagram</b>\r
 369 @image html email_image004.png\r
 370 @}\r
 371 \r
 372 @defgroup Use_Case2_folder mailbox Operation\r
 373 @ingroup EMAIL_USECASES\r
 374 @{\r
 375         <h2 class="pg">mailbox Operation </h2>\r
 376 mailbox Operations are a set of operations to manage email mailboxes like add, update, delete or get mailbox related details.\r
 377 \r
 378 Structure:\r
 379 emf_mailbox_t \r
 380 \r
 381 <table>\r
 382 <tr><td>API</td><td>Return Value / Exceptions</td></tr>\r
 383  \r
 384 <tr><td>int email_add_mailbox(emf_mailbox_t* new_mailbox, int on_server, unsigned* handle) </td>\r
 385 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: -  Memory for param emf_mailbox_t* new_mailbox should be allocated and deallocated by Application </td></tr>\r
 386  \r
 387 <tr><td>int email_delete_mailbox(emf_mailbox_t* mailbox, int on_server,  unsigned* handle) </td>\r
 388 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for param emf_mailbox_t* mailbox should be allocated and deallocated by Application</td></tr>\r
 389 \r
 390 <tr><td>int email_update_mailbox(emf_mailbox_t*old_mailbox, emf_mailbox_t* new_mailbox)</td>\r
 391 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for params emf_mailbox_t* old_mailbox and  emf_mailbox_t* new_mailbox should be allocated and deallocated by Application</td></tr>\r
 392 \r
 393 <tr><td>int email_get_mailbox_list(int account_id, int local_yn, emf_mailbox_t** mailbox_list, int* count)</td>\r
 394 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory allocation for param mailbox_list will happen in email_get_mailbox_list (). To free this memory application should call email_free_mailbox</td></tr>\r
 395  \r
 396 <tr><td>int email_get_mailbox_by_name(int account_id, const char *pMailboxName, emf_mailbox_t **pMailbox)</td>\r
 397 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory allocation for param pMailbox will happen in email_get_mailbox_by_name (). To free this memory application should call email_free_mailbox</td></tr>\r
 398  \r
 399 <tr><td>int email_get_child_mailbox_list(int account_id, const char *parent_mailbox,  emf_mailbox_t** mailbox_list, int* count)</td>\r
 400 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory allocation for param mailbox_list will happen in email_get_child_mailbox_list (). To free this memory application should call email_free_mailbox</td></tr>\r
 401  \r
 402 <tr><td>int email_get_mailbox_by_mailbox_type(int account_id, emf_mailbox_type_e mailbox_type,  emf_mailbox_t** mailbox)</td>\r
 403 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory allocation for param mailbox_list will happen in email_get_mailbox_by_mailbox_type (). To free this memory application should call email_free_mailbox</td></tr>\r
 404 </table>\r
 405  \r
 406 <b>Sample Code</b>\r
 407 \r
 408 @li Create new mailbox\r
 409 @code\r
 410 emf_mailbox_t *mailbox = NULL, *new_mailbox = NULL;\r
 411 unsigned handle = 0;\r
 412 int on_server = 0;\r
 413  \r
 414 mailbox = malloc(sizeof(emf_mailbox_t));\r
 415 memset(mailbox, 0x00, sizeof(emf_mailbox_t));\r
 416  \r
 417 mailbox->name           = strdup("Personal"); \r
 418 mailbox->alias          = strdup("selfuse");            \r
 419 mailbox->account_id     = 1; \r
 420 mailbox->local          = on_server; \r
 421 mailbox->mailbox_type    = 7;  \r
 422       \r
 423 /* create new mailbox */           \r
 424 if(EMF_ERROR_NONE != email_add_mailbox(mailbox,on_server,&handle))\r
 425       /* failure */\r
 426 else\r
 427       /* success   */\r
 428 \r
 429 @endcode\r
 430 \r
 431 \r
 432 @li Update and Delete mailbox\r
 433 @code\r
 434 emf_mailbox_t *mailbox = NULL, *new_mailbox = NULL;\r
 435 int on_server = 0;\r
 436 unsigned handle = 0;\r
 437 \r
 438 new_mailbox = malloc(sizeof(emf_mailbox_t));\r
 439 memset(new_mailbox, 0x00, sizeof(emf_mailbox_t));\r
 440  \r
 441 new_mailbox->name =  strdup("Personal001");\r
 442  \r
 443 /* update mailbox */\r
 444 if(EMF_ERROR_NONE != email_update_mailbox(mailbox,new_mailbox))\r
 445       /* failure */\r
 446 else\r
 447       /* success   */\r
 448  \r
 449 /* delete mailbox */\r
 450 if(EMF_ERROR_NONE != email_delete_mailbox(mailbox,on_server,&handle))\r
 451       /* failure */\r
 452 else\r
 453       /* success   */\r
 454  \r
 455 email_free_mailbox(&mailbox, 1);\r
 456 email_free_mailbox(&new_mailbox, 1);\r
 457  \r
 458 @endcode\r
 459 \r
 460 @li Get list of mailboxes\r
 461 @code\r
 462 int account_id = 1;\r
 463 int local_yn = 0;\r
 464 emf_mailbox_t* mailbox_list = NULL;\r
 465 int count = 0;\r
 466  \r
 467 /*get list of mailboxes */\r
 468 if(EMF_ERROR_NONE != email_get_mailbox_list(account_id, local_yn, &mailbox_list, &count))\r
 469       /* failure */\r
 470 else\r
 471 {\r
 472       /* success   */\r
 473       email_free_mailbox(&mailbox_list,count);\r
 474 }\r
 475 @endcode\r
 476 \r
 477 <b>Flow Diagram</b>\r
 478 @image html email_image005.png\r
 479 @}\r
 480 \r
 481 @defgroup Use_Case3_message Message Operation\r
 482 @ingroup EMAIL_USECASES\r
 483 @{\r
 484         <h2 class="pg">Message Operation </h2>\r
 485 Message Operations are a set of operations to manage email messages like add, update, delete or get message related details.\r
 486 \r
 487 Structure:\r
 488 emf_mail_t \r
 489 <table>\r
 490 <tr><td>API</td>\r
 491 <td>Return Value / Exceptions</td></tr>\r
 492  \r
 493 <tr><td>int email_add_mail(emf_mail_data_t *input_mail_data, emf_attachment_data_t *input_attachment_data_list, int input_attachment_count, emf_meeting_request_t* input_meeting_request, int input_from_eas)  </td>\r
 494 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: -  Memory for params emf_mail_data_t* input_mail_data and emf_attachment_data_t *input_attachment_data_list and emf_meeting_request_t* input_meeting_request should be allocated and deallocated by Application</td></tr>\r
 495  \r
 496 <tr><td>int email_update_mail(emf_mail_data_t *input_mail_data, emf_attachment_data_t *input_attachment_data_list, int input_attachment_count, emf_meeting_request_t* input_meeting_request, int input_from_eas)  </td>\r
 497 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: -  Memory for params emf_mail_data_t* input_mail_data and emf_attachment_data_t *input_attachment_data_list and emf_meeting_request_t* input_meeting_request should be allocated and deallocated by Application</td></tr>\r
 498  \r
 499 <tr><td>int email_count_message(emf_mailbox_t* mailbox, int* total, int* unseen)  </td>\r
 500 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for param emf_mailbox_t* mailbox should be allocated and deallocated by Application</td></tr>\r
 501 \r
 502 <tr><td>int email_delete_message(emf_mailbox_t* mailbox, int *mail_ids, int num, int from_server)  </td>\r
 503 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for params int *mail_ids and mf_mailbox_t* mailbox should be allocated and deallocated by Application</td></tr>\r
 504  \r
 505 <tr><td>int email_delete_all_message_in_mailbox(emf_mailbox_t* mailbox, int from_server)  </td>\r
 506 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for param mf_mailbox_t* mailbox should be allocated and deallocated by Application</td></tr>\r
 507  \r
 508 <tr><td>int email_clear_mail_data()  </td>\r
 509 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 510 \r
 511 <tr><td>int email_add_attachment(emf_mailbox_t* mailbox, int mail_id, emf_attachment_info_t* attachment)</td>\r
 512 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for param mf_mailbox_t* mailbox and mf_attachment_info_t* attachment hould be allocated and deallocated by Application</td></tr>\r
 513  \r
 514 <tr><td>int email_delete_attachment(emf_mailbox_t * mailbox, int mail_id, const char * attachment_id)</td>\r
 515 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for param emf_mailbox_t* mailbox should be allocated and deallocated by Application</td></tr>\r
 516  \r
 517 <tr><td>int email_get_attachment_info(emf_mailbox_t* mailbox, int mail_id, const char* attachment_id, emf_attachment_info_t** attachment)</td>\r
 518 <td>Returns EMF_ERROR_NONE on success or negative value on failure.@n Remarks:\r
 519 -# Memory for param emf_mailbox_t* mailbox should be allocated and deallocated by Application \r
 520 -# Memory allocation for param emf_attachment_info_t** attachment will happen in email_get_attachment_info (). To free this memory, application should call email_free_attachment_info () </td></tr>\r
 521  \r
 522 <tr><td>int email_free_attachment_info(emf_attachment_info_t** atch_info)  </td>\r
 523 <td>Returns EMF_ERROR_NONE on success or negative value on failure.</td></tr>\r
 524  \r
 525 <tr><td>int email_modify_mail_flag(int mail_id, emf_mail_flag_t new_flag, int onserver)  </td>\r
 526 <td>Returns EMF_ERROR_NONE on success or negative value on failure.</td></tr>\r
 527  \r
 528 <tr><td>int email_modify_seen_flag(int *mail_ids, int num, int seen_flag, int onserver)  </td>\r
 529 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for param int *mail_ids should be allocated and deallocated by Application</td></tr>\r
 530 \r
 531 <tr><td>int email_modify_extra_mail_flag(int mail_id, emf_extra_flag_t new_flag)  </td>\r
 532 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 533  \r
 534 <tr><td>int email_move_mail_to_mailbox(int *mail_ids, int num, emf_mailbox_t* new_mailbox)  </td>\r
 535 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for params int *mail_ids and emf_mailbox_t* new_mailbox should be allocated and deallocated by Application</td></tr>\r
 536  \r
 537 <tr><td>int email_move_all_mails_to_mailbox(emf_mailbox_t* src_mailbox, emf_mailbox_t* new_mailbox)  </td>\r
 538 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for params emf_mailbox_t* src_mailbox and emf_mailbox_t* new_mailbox should be allocated and deallocated by Application</td></tr>\r
 539  \r
 540 <tr><td>int email_count_message_with_draft_flag(emf_mailbox_t* mailbox, int* total)  </td>\r
 541 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for param emf_mailbox_t* mailbox should be allocated and deallocated by Application</td></tr>\r
 542  \r
 543 <tr><td>int email_count_message_on_sending(emf_mailbox_t* mailbox, int* total)  </td>\r
 544 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory for param emf_mailbox_t* mailbox should be allocated and deallocated by Application</td></tr>\r
 545   \r
 546 <tr><td>int email_get_mailbox_list(int account_id, emf_mailbox_t** mailbox_list, int* count ) </td>\r
 547 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: - Memory allocation for param emf_mailbox_t** mailbox_list will happen in email_get_mailbox_list (). To free this memory, application should call email_free_mailbox ()</td></tr>\r
 548  \r
 549 <tr><td>int email_free_mailbox(emf_mailbox_t** mailbox_list, int count)  </td>\r
 550 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 551    \r
 552 <tr><td>int email_get_mail_flag(int account_id, int mail_id, emf_mail_flag_t* mail_flag)  </td>\r
 553 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 554  \r
 555 <tr><td>int email_retry_send_mail( int mail_id, int timeout_in_sec)  </td>\r
 556 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 557  \r
 558 <tr><td>int email_create_db_full()</td>\r
 559 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 560  \r
 561 <tr><td>int email_get_mailbox_name_by_mail_id(int mail_id, char **pMailbox_name)</td>\r
 562 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 563  \r
 564 <tr><td>int email_cancel_send_mail( int mail_id)  </td>\r
 565 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 566  \r
 567 <tr><td>int email_count_message_all_mailboxes(emf_mailbox_t* mailbox, int* total, int* unseen) </td>\r
 568 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 569  \r
 570 <tr><td>int email_get_latest_unread_mail_id(int account_id, int *pMailID) </td>\r
 571 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 572  \r
 573 <tr><td>int email_get_max_mail_count(int *Count) </td>\r
 574 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 575  \r
 576 <tr><td>int email_get_disk_space_usage(unsigned long *total_size)</td>\r
 577 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 578 </table>\r
 579  \r
 580 <b>Sample Code</b>\r
 581 \r
 582 @li Add, Update, Count and Delete message\r
 583 @code\r
 584 emf_mailbox_t *mailbox = NULL;\r
 585 int on_server = 0, account_id = 0, mail_id = 0;\r
 586 char *pFilePath = "/tmp/mail.txt";\r
 587 int                    i = 0;\r
 588 int                    account_id = 0;\r
 589 int                    from_eas = 0;\r
 590 int                    attachment_count = 0;\r
 591 int                    err = EMF_ERROR_NONE;\r
 592 char                   arg[50] = { 0 , };\r
 593 char                  *body_file_path = "/opt/data/email/.emfdata/tmp/mail.txt";\r
 594 emf_mailbox_t         *mailbox_data = NULL;\r
 595 emf_mail_data_t       *test_mail_data = NULL;\r
 596 emf_attachment_data_t *attachment_data = NULL;\r
 597 emf_meeting_request_t *meeting_req = NULL;\r
 598 FILE                  *body_file;\r
 599 \r
 600 printf("\n > Enter account id : ");\r
 601 scanf("%d", &account_id);\r
 602 \r
 603 memset(arg, 0x00, 50);\r
 604 printf("\n > Enter mailbox name : ");\r
 605 scanf("%s", arg);\r
 606 \r
 607 email_get_mailbox_by_name(account_id, arg, &mailbox_data);\r
 608 \r
 609 test_mail_data = malloc(sizeof(emf_mail_data_t));\r
 610 memset(test_mail_data, 0x00, sizeof(emf_mail_data_t));\r
 611 \r
 612 printf("\n From EAS? [0/1]> ");\r
 613 scanf("%d", &from_eas);\r
 614 \r
 615 test_mail_data->account_id        = account_id;\r
 616 test_mail_data->save_status       = 1;\r
 617 test_mail_data->flags_seen_field  = 1;\r
 618 test_mail_data->file_path_plain   = strdup(body_file_path);\r
 619 test_mail_data->mailbox_name      = strdup(mailbox_data->name);\r
 620 test_mail_data->mailbox_type      = mailbox_data->mailbox_type;\r
 621 test_mail_data->full_address_from = strdup("<test1@test.com>");\r
 622 test_mail_data->full_address_to   = strdup("<test2@test.com>");\r
 623 test_mail_data->full_address_cc   = strdup("<test3@test.com>");\r
 624 test_mail_data->full_address_bcc  = strdup("<test4@test.com>");\r
 625 test_mail_data->subject           = strdup("Meeting request mail");\r
 626 \r
 627 body_file = fopen(body_file_path, "w");\r
 628 \r
 629 for(i = 0; i < 500; i++)\r
 630         fprintf(body_file, "X2 X2 X2 X2 X2 X2 X2");\r
 631 fflush(body_file);\r
 632  fclose(body_file);\r
 633 \r
 634 \r
 635 if((err = email_add_mail(test_mail_data, attachment_data, attachment_count, meeting_req, from_eas)) != EMF_ERROR_NONE)\r
 636         printf("email_add_mail failed. [%d]\n", err);\r
 637 else\r
 638         printf("email_add_mail success.\n");\r
 639  \r
 640 /* Update message */\r
 641 /*  variable 'mail' should be filled with data on DB. */\r
 642 /*  And change values you want to update. */\r
 643 mail->head->subject = strdup("save.mailbox again...");\r
 644  \r
 645 if(EMF_ERROR_NONE != email_update_message(mail_id,mail))\r
 646         /* failure */\r
 647 else\r
 648         /* success   */\r
 649  \r
 650 /* Count message */\r
 651 int total = 0, unseen = 0;\r
 652  \r
 653 /*  Get the total number of mails and the number of unseen mails */\r
 654 if(EMF_ERROR_NONE != email_count_message(mailbox,&total,&unseen))\r
 655         /* failure */\r
 656 else\r
 657         /* success   */\r
 658  \r
 659 /* Delete message */\r
 660 int *mail_ids, num = 0;\r
 661  \r
 662 if(EMF_ERROR_NONE != email_delete_message(mailbox,mail_ids,num,on_server))\r
 663         /* failure */\r
 664 else\r
 665         /* success   */\r
 666 @endcode \r
 667  \r
 668 @li Delete all message in a specific mailbox\r
 669 @code \r
 670 /* Delete all message in mailbox */\r
 671 emf_mailbox_t *mailbox = NULL;\r
 672 int on_server = 0;\r
 673 \r
 674 mailbox = malloc(sizeof(emf_mailbox_t));\r
 675 memset(mailbox, 0x00, sizeof(emf_mailbox_t));\r
 676 \r
 677 mailbox->account_id = 1;\r
 678 mailbox->name = strdup("INBOX");                \r
 679 \r
 680 if( EMF_ERROR_NONE != email_delete_all_message_in_mailbox(mailbox, on_server))\r
 681       /* failure */\r
 682 else\r
 683 \r
 684       /* success   */\r
 685 @endcode\r
 686 \r
 687 \r
 688 @li Clear all messages\r
 689 @code\r
 690 /* clear mail data */\r
 691 if(EMF_ERROR_NONE !=  email_clear_mail_data())\r
 692       /* failure */\r
 693 else\r
 694       /* success   */\r
 695 @endcode\r
 696 \r
 697 @li Modify flag\r
 698 @code\r
 699 emf_mail_flag_t newflag = {0};\r
 700 int mail_id = 0;\r
 701 int on_server = 0;\r
 702  \r
 703 /* Modify mail flag*/\r
 704 if(EMF_ERROR_NONE != email_modify_mail_flag(mail_id,newflag,on_server))\r
 705        /* failure */\r
 706 else\r
 707        /* success   */\r
 708 \r
 709 int mail_ids[] = {1, 2}; \r
 710 int num = 2;\r
 711 int seen_flag = 0; \r
 712 int on_server = 0;\r
 713  \r
 714 /* Modify seen flag*/\r
 715 if(EMF_ERROR_NONE != email_modify_seen_flag(mail_ids, num, seen_flag,on_server))\r
 716        /* failure */\r
 717 else\r
 718        /* success   */\r
 719  \r
 720 /* Modify extra flag*/\r
 721 int mail_id = 1;\r
 722 if(EMF_ERROR_NONE != email_modify_extra_mail_flag(mail_id, newflag))\r
 723        /* failure */\r
 724 else\r
 725        /* success   */\r
 726 @endcode\r
 727 \r
 728 \r
 729 @li Move mail\r
 730 @code \r
 731 int mail_id[],account_id = 1;\r
 732 emf_mailbox_t *mailbox = NULL;\r
 733 char *mailbox_name = "INBOX";\r
 734  \r
 735 mailbox = malloc(sizeof(emf_mailbox_t));\r
 736 memset(mailbox, 0x00, sizeof(emf_mailbox_t));\r
 737  \r
 738 mailbox->account_id = account_id;\r
 739 mailbox->name = mailbox_name;\r
 740  \r
 741 /* Move mail to given mailbox*/\r
 742 if(EMF_ERROR_NONE !=  email_move_mail_to_mailbox(/*mail_id*/,/*num*/,mailbox))\r
 743       /* failure */\r
 744 else\r
 745       /* success   */\r
 746  \r
 747 /* free mailbox*/\r
 748 email_free_mailbox(&mailbox,1);\r
 749  \r
 750 emf_mailbox_t *src_mailbox = NULL,*dest_mailbox = NULL;\r
 751 int src_account_id = 0, dest_account_id = 0;\r
 752 char * src_mailbox_name = NULL, *dest_mailbox_name = NULL;\r
 753  \r
 754 src_mailbox = malloc(sizeof(emf_mailbox_t));\r
 755 memset(src_mailbox, 0x00, sizeof(emf_mailbox_t));\r
 756  \r
 757 dest_mailbox = malloc(sizeof(emf_mailbox_t));\r
 758 memset(dest_mailbox, 0x00, sizeof(emf_mailbox_t));\r
 759  \r
 760 src_mailbox->account_id = /*src_account_id*/;\r
 761 src_mailbox->name = /*src_mailbox_name*/\r
 762  \r
 763 dest_mailbox->account_id = /*dest_account_id*/;\r
 764 dest_mailbox->name = /*dest_mailbox_name*/\r
 765  \r
 766 /*move all mails to given mailbox*/\r
 767 if(EMF_ERROR_NONE !=  email_move_all_mails_to_mailbox(src_mailbox,dest_mailbox))\r
 768       /* failure */\r
 769 else\r
 770       /* success   */\r
 771  \r
 772 /* free mailbox*/\r
 773 email_free_mailbox(&src_mailbox,1);\r
 774 email_free_mailbox(&dest_mailbox,1);\r
 775  \r
 776 int account_id = 0, total = 0;\r
 777 emf_mailbox_t *mailbox = NULL;\r
 778 char *mailbox_name = NULL;\r
 779  \r
 780 mailbox = malloc(sizeof(emf_mailbox_t));\r
 781 memset(mailbox, 0x00, sizeof(emf_mailbox_t));\r
 782  \r
 783 mailbox->account_id = /*account_id*/;\r
 784 mailbox->name = /*mailbox_name*/\r
 785  \r
 786 /*count of draft msgs*/\r
 787 if(EMF_ERROR_NONE !=  email_count_message_with_draft_flag(mailbox,&total))\r
 788       /* failure */\r
 789 else\r
 790       /* success   */\r
 791  \r
 792 /* free mailbox*/\r
 793 email_free_mailbox(&mailbox,1);\r
 794 @endcode\r
 795  \r
 796 @li Count of msgs sent from given folde\r
 797 @code\r
 798 int account_id = 0, total = 0;\r
 799 emf_mailbox_t *mailbox = NULL;\r
 800 char *mailbox_name = NULL;\r
 801  \r
 802 mailbox = malloc(sizeof(emf_mailbox_t));\r
 803 memset(mailbox, 0x00, sizeof(emf_mailbox_t));\r
 804  \r
 805 mailbox->account_id = /*account_id*/;\r
 806 mailbox->name = /*mailbox_name*/\r
 807  \r
 808 /*count of msgs sent from given mailbox*/\r
 809 if(EMF_ERROR_NONE != email_count_message_on_sending(mailbox,&total))\r
 810       /* failure */\r
 811 else\r
 812       /* success   */\r
 813  \r
 814 /* free mailbox*/\r
 815 email_free_mailbox(&mailbox,1);\r
 816 \r
 817 @endcode\r
 818 \r
 819 \r
 820 @li Get mailbox list \r
 821 @code\r
 822  \r
 823 emf_mailbox_t* mailbox_list = NULL;\r
 824 int account_id = 1, count = 0;\r
 825  \r
 826 /* Get mailbox list*/\r
 827 if(EMF_ERROR_NONE != email_get_mailbox_list(account_id,&mailbox_list,&count))\r
 828       /* failure */\r
 829 else\r
 830       /* success   */\r
 831  \r
 832 /* free mailbox list*/\r
 833 email_free_mailbox(&mailbox,count);\r
 834 @endcode\r
 835 \r
 836 \r
 837 @li Get mailBox name by mailID\r
 838 @code\r
 839 /* Get mailBox name by mailID*/\r
 840 int mail_id = 1;\r
 841 char *pMailbox_name=strdup("INBOX");\r
 842 err = email_get_mailbox_name_by_mail_id(mail_id,&pMailbox_name);\r
 843 \r
 844 free(pMailbox_name);\r
 845 \r
 846 @endcode\r
 847 \r
 848 \r
 849 @li Cancel sending mail\r
 850 @code \r
 851  \r
 852 /* email_cancel_send_mail*/\r
 853 int mail_id = 1;        /*  mail id of a mail which is on sending */\r
 854 err = email_cancel_send_mail(mail_id);\r
 855  \r
 856 @endcode\r
 857 \r
 858 \r
 859 \r
 860 @li Get the Total count and Unread count of all mailboxes\r
 861 @code \r
 862 /* Get the Total count and Unread count of all mailboxes */\r
 863 emf_mailbox_t* mailbox = NULL;\r
 864 int account_id = 1, total = 0, unseen = 0;\r
 865 char *mailbox_name = NULL;\r
 866  \r
 867 mailbox = malloc(sizeof(emf_mailbox_t));\r
 868 memset(mailbox, 0x00, sizeof(emf_mailbox_t));\r
 869  \r
 870 mailbox->account_id = /*account_id*/;\r
 871 mailbox->name = /*mailbox_name*/\r
 872  \r
 873 err = email_count_message_all_mailboxes(mailbox,&total,&unseen);\r
 874  \r
 875 @endcode\r
 876 \r
 877 <b>Flow Diagram</b>s\r
 878 @image html email_image006.png\r
 879 \r
 880 @image html email_image007.png\r
 881  \r
 882 @image html email_image008.png \r
 883 @}\r
 884 \r
 885 @defgroup Use_Case4_network Network Operation\r
 886 @ingroup EMAIL_USECASES\r
 887 @{\r
 888         <h2 class="pg">Network Operation </h2>\r
 889 Network Operations are a set of operations to manage email send, receive and cancel related details.\r
 890 \r
 891 Structure:\r
 892 emf_option_t \r
 893 <table>\r
 894 <tr><td>API</td>\r
 895 <td>Return Value / Exceptions</td></tr>\r
 896  \r
 897 <tr><td>int email_send_mail( emf_mailbox_t* mailbox, int mail_id, emf_option_t* sending_option, unsigned* handle)</td>\r
 898 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: \r
 899 -# Memory allocation and de-allocation for input param is to be done by application.</td></tr>\r
 900  \r
 901 <tr><td>int email_sync_header(emf_mailbox_t* mailbox, unsigned* handle)</td>\r
 902 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks:\r
 903 -# Memory allocation and de-allocation for input param is to be done by application.</td></tr>\r
 904  \r
 905 <tr><td>int email_download_body(emf_mailbox_t* mailbox, int mail_id, int with_attachment, unsigned* handle) </td>\r
 906 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks:\r
 907 -# Memory allocation and de-allocation for input param is to be done by application.</td></tr>\r
 908  \r
 909 <tr><td>int email_download_attachment(emf_mailbox_t* mailbox, int mail_id, const char* nth,  unsigned* handle)</td>\r
 910 <td>Returns EMF_ERROR_NONE on success or negative value on failure.</td></tr>\r
 911 \r
 912 <tr><td>int email_cancel_job(int account_id, int handle)</td>\r
 913 <td>Returns EMF_ERROR_NONE on success or negative value on failure.</td></tr>\r
 914  \r
 915 <tr><td>int email_get_pending_job(emf_action_t action, int account_id, int mail_id, emf_event_status_type_t * status)</td>\r
 916 <td>Returns EMF_ERROR_NONE on success or negative value on failure.</td></tr>\r
 917  \r
 918 <tr><td>void email_get_network_status(int* on_sending, int* on_receiving) </td>\r
 919 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
 920  \r
 921 <tr><td>int email_send_saved(int account_id, emf_option_t* sending_option, unsigned* handle)</td>\r
 922 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks:\r
 923 -# Memory allocation and de-allocation for input param is to be done by application.</td></tr>\r
 924  \r
 925 <tr><td>int email_get_imap_mailbox_list(int account_id, const char* mailbox, unsigned* handle)</td>\r
 926 <td>Returns EMF_ERROR_NONE on success or negative value on failure.</td></tr>\r
 927  \r
 928 <tr><td>int email_sync_local_activity(int account_id)</td>\r
 929 <td>Returns EMF_ERROR_NONE on success or negative value on failure.</td></tr>\r
 930 </table>\r
 931 \r
 932 <b>Sample Code</b>\r
 933 @li Send a mail\r
 934 @code\r
 935 /* TODO : Write sample to send a mail. */\r
 936 @endcode\r
 937 \r
 938 @li Download header of new emails from mail server\r
 939 @code\r
 940 /* Download header of new emails from mail server*/\r
 941 emf_mailbox_t mbox;\r
 942 int account_id = 1;\r
 943 int err = EMF_ERROR_NONE;\r
 944 unsigned handle = 0;\r
 945  \r
 946 memset(&mbox, 0x00, sizeof(emf_mailbox_t));\r
 947  \r
 948 mbox.account_id = account_id;\r
 949 mbox.name = strdup("INBOX");\r
 950 err = email_sync_header (&mbox,&handle);\r
 951 @endcode\r
 952 \r
 953 \r
 954 @li Download email body from server\r
 955 @code\r
 956  \r
 957 /*Download email body from server*/\r
 958 emf_mailbox_t mbox;\r
 959 int mail_id = 1;\r
 960 int account_id = 1;\r
 961 int handle = 0;\r
 962 int err = EMF_ERROR_NONE;\r
 963  \r
 964 memset(&mailbox, 0x00, sizeof(emf_mailbox_t));\r
 965 mbox.account_id = account_id;\r
 966 mbox.name = strdup("INBOX");\r
 967 err= email_download_body (&mbox,mail_id,0,&handle);\r
 968  \r
 969 @li Download a email nth-attachment from server\r
 970 @code\r
 971 /*Download a email nth-attachment from server*/\r
 972 emf_mailbox_t mailbox;\r
 973 int mail_id = 1;\r
 974 int account_id = 1;     \r
 975 char arg[50]; /* Input attachment number need to be download */\r
 976 unsigned handle = 0;\r
 977 int err = EMF_ERROR_NONE;\r
 978  \r
 979 memset(&mailbox, 0x00, sizeof(emf_mailbox_t));\r
 980 mailbox.name = "INBOX";\r
 981 mailbox.account_id = account_id;\r
 982 err=email_download_attachment(&mailbox,mail_id,arg,&handle);\r
 983 @endcode\r
 984 \r
 985 <b>Flow Diagram</b>\r
 986 @image html email_image009.png\r
 987 @}\r
 988 \r
 989 @defgroup Use_Case5_rule Rule Operation\r
 990 @ingroup EMAIL_USECASES\r
 991 @{\r
 992         <h2 class="pg">Rule Operation</h2>\r
 993 Rule Operations are a set of operations to manage email rules like add, get, delete or update rule related details.\r
 994 \r
 995 Structure:\r
 996 emf_rule_t\r
 997 <table>\r
 998 <tr><td>API</td>\r
 999 <td>Return Value / Exceptions</td></tr>\r
1000  \r
1001 <tr><td>int email_get_rule(int filter_id, emf_rule_t** filtering_set)</td>\r
1002 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks: \r
1003 -# Memory allocation for the param emf_rule_t** filtering_set will be done in this api.\r
1004 -# De-allocation is to be done by application.</td></tr>\r
1005  \r
1006 <tr><td>int email_get_rule_list(emf_rule_t** filtering_set, int* count)</td>\r
1007 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks:\r
1008 -# Memory allocation for the param emf_rule_t** filtering_set will be done in this api.\r
1009 -# De-allocation is to be done by application.</td></tr>\r
1010  \r
1011 <tr><td>int email_add_rule(emf_rule_t* filtering_set) </td>\r
1012 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks:\r
1013 -# Memory allocation and de-allocation is to be done by application.\r
1014 -# Use email_free_rule to free allocated memory.</td></tr>\r
1015  \r
1016 <tr><td>int email_update_rule(int filter_id, emf_rule_t* new_set) </td>\r
1017 <td>Returns EMF_ERROR_NONE on success or negative value on failure@n Remarks:\r
1018 -# Memory allocation and de-allocation is to be done by application.</td></tr>\r
1019 -# Use email_free_rule to free allocated memory.\r
1020  \r
1021 <tr><td>int email_delete_rule(int filter_id)</td>\r
1022 <td>Returns EMF_ERROR_NONE on success or negative value on failure.</td></tr>\r
1023  \r
1024 <tr><td>int email_free_rule(emf_rule_t** filtering_set, int count)</td>\r
1025 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
1026 </table>\r
1027 \r
1028 <b>Sample Code</b>\r
1029 @li Filter Operation\r
1030 @code\r
1031 int err = EMF_ERROR_NONE;\r
1032 emf_rule_t*  rule = NULL;\r
1033 int filter_id = 1;\r
1034  \r
1035 /* Get a information of filtering*/\r
1036 err = email_get_rule (filter_id,&rule);\r
1037 err = email_free_rule (&rule,1);\r
1038  \r
1039 /* Get all filterings */\r
1040 int count = 0;\r
1041 err = email_get_rule_list(&rule,&count);\r
1042  \r
1043  \r
1044 /* Add a filter information */\r
1045 err = email_add_rule (rule);\r
1046 err = email_free_rule (&rule,1);\r
1047  \r
1048 /* Change a filter information */\r
1049 err = email_update_rule (filter_id,rule);\r
1050 err = email_free_rule (&rule,1);\r
1051  \r
1052 /* Delete a filter information*/\r
1053 err = email_delete_rule (filter_id);\r
1054  \r
1055 /* Free allocated memory */\r
1056 err = email_free_rule (&rule,1);\r
1057 @endcode\r
1058 \r
1059 <b>Flow Diagram</b>\r
1060 @image html email_image010.png\r
1061 @}\r
1062 \r
1063 @defgroup Use_Case6_control Control Operation\r
1064 @ingroup EMAIL_USECASES\r
1065 @{\r
1066         <h2 class="pg">Control Operation</h2>\r
1067 Control Operations are a set of operations to manage Email MAPI Layer  initialization.\r
1068 The Application which will use the MAPIs MUST initialize IPC proxy and conntect to Email FW database before calling other APIs.\r
1069 And it MUST finalize IPC proxy and disconnect to the DB if the application doesn't use APIs.\r
1070 \r
1071 <table>\r
1072 <tr><td>API</td>\r
1073 <td>Return Value / Exceptions</td></tr>\r
1074  \r
1075 <tr><td>int email_init_storage(void)</td>\r
1076 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
1077  \r
1078 <tr><td>int email_open_db(void)</td>\r
1079 <td>Returns EMF_ERROR_NONE on success or negative value on failure\r
1080 @n Remarks:\r
1081 @n Application should call email_close_db once db operation is over</td></tr>\r
1082  \r
1083 <tr><td>int email_close_db(void)</td>\r
1084 <td>Returns EMF_ERROR_NONE on success or negative value on failure\r
1085 @n Remarks: - \r
1086 @n This API should be called only if email_open_db () is called.</td></tr>\r
1087  \r
1088 <tr><td>int email_service_begin(void)</td>\r
1089 <td>Returns EMF_ERROR_NONE on success or negative value on failure</td></tr>\r
1090  \r
1091 <tr><td>int email_service_end(void)</td>\r
1092 <td>Returns EMF_ERROR_NONE on success or negative value on failure\r
1093 @n Remarks:\r
1094 @n This API should be called only if email_service_begin () is called.</td></tr>\r
1095 </table>\r
1096  \r
1097 <b>Sample Code</b>\r
1098 @li Initialize and Finalize Email MAPI Layer\r
1099 @code\r
1100 int err = EMF_ERROR_NONE;\r
1101  \r
1102 /*  Initialize Email MAPI Layer before calling other MAPIs */\r
1103 if(EMF_ERROR_NONE == email_service_begin())\r
1104 {\r
1105         if(EMF_ERROR_NONE != email_open_db())\r
1106         {\r
1107                 return false;\r
1108         }\r
1109         if(EMF_ERROR_NONE != email_init_storage())      \r
1110         {\r
1111                 return false;\r
1112         }\r
1113 }\r
1114 \r
1115 /*  Call other MAPIs */\r
1116 \r
1117 ......\r
1118 \r
1119 /*  Finalize Email MAPI Layer when finishing application */\r
1120 err = email_close_db();\r
1121 err = email_service_end();\r
1122 @endcode\r
1123 \r
1124 <b>Flow Diagram</b>\r
1125 @image html email_image011.png\r
1126 @}\r
1127 \r
1128 @addtogroup Email_Feature\r
1129 @{\r
1130 <h1 class="pg">System Configuration</h1>\r
1131         <h2 class="pg">Files to be included</h2>\r
1132 email-api.h\r
1133 @n Emf_Mapi_Types.h\r
1134 \r
1135         <h2 class="pg">System Initialization and De-Initialization</h2>\r
1136 email_service_begin is used to initialize email-service at boot time.\r
1137 @n email_service_end is used to deinitialize email-service at shutdown. \r
1138 @n These two are separate executables.\r
1139 \r
1140         <h2 class="pg">Variable Configuration</h2>\r
1141 NA\r
1142 \r
1143         <h2 class="pg">Build Environment</h2>\r
1144 If the Application wants to use email-service Module, make sure that the following package should be included in the Makefile.\r
1145 \r
1146 email-service-dev\r
1147 \r
1148         <h2 class="pg">Runtime Environment</h2>\r
1149 NA\r
1150 @}\r
1151 \r
1152 @defgroup EMAL_Appendix 4. Reference\r
1153 @ingroup EMAILSVC\r
1154 @{\r
1155 <h1 class="pg">Appendix</h1>\r
1156         <h2 class="pg">Email</h2>\r
1157 @image html email_image012.png\r
1158 \r
1159 - Alice composed a message using MUA (Mail User Agent). Alice enters the e-mail address of her correspondent, and hits the "send" button.\r
1160 - MUA format the message using MIME and uses Simple mail Transfer Protocol to send the message to local MTA (Mail Transfer Agent) i,e smtp.a.org run by Alices ISP (Internet Service provider).\r
1161 - The MTA looks at the destination address provided in the SMTP protocol i,e bob@b.org. An Internet e-mail address is a string of the form localpart@exampledomain. The part before the @ sign is the local part of the address, often the username of the recipient, and the part after the @ sign is a domain name. The MTA resolves a domain name to determine the fully qualified domain name of the mail exchange server in the Domain Name System (DNS).\r
1162 - The DNS Server for the b.org domain, ns.b.org, responds with an MX Records listing the mail exchange servers for that domain, in this case mx.b.org, a server run by Bob's ISP. \r
1163 - smtp.a.org sends the message to mx.b.org using SMTP, which delivers it to the mailbox of the user bob. \r
1164 - Bob presses the "get mail" button in his MUA, which picks up the message using the Post Office Protocol (POP3).\r
1165 \r
1166         <h2 class="pg">RFC</h2>\r
1167 -# RFC 2821-SMTP(Simple Mail Transfer Protocol)\r
1168 -# RFC 1939-POP3(Post Office Protocol)\r
1169 -# RFC 3501-IMAP4(Internate message protocol)\r
1170 @}\r
1171 \r
1172 */\r
1173 \r
1174 /**\r
1175 * @defgroup  EMAILSVC\r
1176  @{\r
1177 *       @defgroup EMAIL_USECASES 3. API Description\r
1178 *\r
1179 @{\r
1180 <h1 class="pg">API Description</h1>\r
1181 This section describes APIs and shows the example of using them.\r
1182 @}\r
1183  @}\r
1184 */\r
1185 \r