email-service_PG.h

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