include/email.h

   1 /*
   2  * Copyright (c) 2012 - 2013 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17  #ifndef __MESSAGING_EMAIL_H__
  18  #define __MESSAGING_EMAIL_H__
  19
  20 /**
  21  * @addtogroup CAPI_MESSAGING_EMAIL_MODULE
  22  * @{
  23  */
  24
  25 /**
  26  * @file        email.h
  27  * @ingroup     CAPI_MESSAGING_EMAIL_MODULE
  28  * @brief       Messaging API file, support for sending email messages.
  29  */
  30
  31
  32 #include <stdlib.h>
  33 #include <stdio.h>
  34 #include <email_types.h>
  35 #include <email_error.h>
  36 #ifdef __cplusplus
  37 extern "C"
  38 {
  39 #endif /* __cplusplus */
  40
  41 /**
  42  * @brief   Creates an email message handle for sending an email message.
  43  * @since_tizen 2.3
  44  * @privlevel public
  45  * @privilege %http://tizen.org/privilege/email
  46  *
  47  * @remarks  You must release @a email using email_destroy_message().
  48  *
  49  * @param[out]  email  A handle to the email message
  50  *
  51  * @return  @c 0 on success,
  52  *          otherwise a negative error value
  53  *
  54  * @retval  #EMAILS_ERROR_NONE                  Successful
  55  * @retval  #EMAILS_ERROR_OUT_OF_MEMORY         Out of memory
  56  * @retval  #EMAILS_ERROR_ACCOUNT_NOT_FOUND     Email account not found
  57  *
  58  * @pre      At least one email account should be set up on the device.
  59  *
  60  * @see email_destroy_message()
  61  */
  62 int email_create_message(email_h *email);
  63
  64 /**
  65  * @brief   Destroys the email message handle and releases all its resources.
  66  * @since_tizen 2.3
  67  *
  68  * @param[in]  email  The handle to the email message
  69  *
  70  * @return  @c 0 on success,
  71  *          otherwise a negative error value
  72  *
  73  * @retval  #EMAILS_ERROR_NONE               Successful
  74  * @retval  #EMAILS_ERROR_INVALID_PARAMETER  Invalid parameter
  75  * @retval  #EMAILS_ERROR_OPERATION_FAILED   Operation failed
  76  *
  77  * @see email_create_message()
  78  */
  79 int email_destroy_message(email_h email);
  80
  81 /**
  82  * @brief   Sets a subject of the email message.
  83  * @since_tizen 2.3
  84  *
  85  * @privlevel public
  86  * @privilege %http://tizen.org/privilege/email
  87
  88  * @param[in]   email    The handle to the email message
  89  * @param[in]   subject  The subject of the email message
  90  *
  91  * @return  @c 0 on success,
  92  *          otherwise a negative error value
  93  *
  94  * @retval  #EMAILS_ERROR_NONE               Successful
  95  * @retval  #EMAILS_ERROR_INVALID_PARAMETER  Invalid parameter
  96  * @retval  #EMAILS_ERROR_OUT_OF_MEMORY      Out of memory
  97  *
  98  * @pre     An email message handle is created using email_create_message().
  99  *
 100  * @see  email_create_message()
 101  */
 102 int email_set_subject(email_h email, const char *subject);
 103
 104 /**
 105  * @brief   Populates a body of the email message.
 106  * @details Email message body means the text data to be delivered.
 107  *
 108  * @since_tizen 2.3
 109  *
 110  * @privlevel public
 111  * @privilege %http://tizen.org/privilege/mediastorage
 112  *
 113  * @param[in]   email   The handle to the email message
 114  * @param[in]   body    The message body
 115  *
 116  * @return  @c 0 on success,
 117  *          otherwise a negative error value
 118  *
 119  * @retval  #EMAILS_ERROR_NONE              Successful
 120  * @retval  #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 121  * @retval  #EMAILS_ERROR_OPERATION_FAILED  Operation failed
 122  *
 123  * @pre     An email message handle is created using email_create_message().
 124  *
 125  * @see  email_create_message()
 126  */
 127 int email_set_body(email_h email, const char *body);
 128
 129 /**
 130  * @brief   Adds a recipient to the email message.
 131  * @details The email API supports sending an email message to multiple recipients.
 132  *
 133  * @since_tizen 2.3
 134  *
 135  * @remarks Email address should be in standard format (as described in
 136  *          Internet standards RFC 5321 and RFC 5322).
 137  *
 138  * @param[in]   email   The handle to the email message
 139  * @param[in]   type    The recipient type
 140  * @param[in]   address The recipient email address
 141  *
 142  * @return  @c 0 on success,
 143  *          otherwise a negative error value
 144  *
 145  * @retval  #EMAILS_ERROR_NONE              Successful
 146  * @retval  #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 147  * @retval  #EMAILS_ERROR_OUT_OF_MEMORY     Out of memory
 148  *
 149  * @pre     An email message handle is created using email_create_message().
 150  *
 151  * @see email_create_message()
 152  * @see email_remove_all_recipients()
 153  */
 154 int email_add_recipient(email_h email, email_recipient_type_e type, const char *address);
 155
 156 /**
 157  * @brief   Removes all recipients for the email message.
 158  * @since_tizen 2.3
 159  *
 160  * @param[in]  email  The handle to the email message
 161  *
 162  * @return  @c 0 on success,
 163  *          otherwise a negative error value
 164  *
 165  * @retval  #EMAILS_ERROR_NONE              Successful
 166  * @retval  #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 167  *
 168  * @pre     An email message handle is created using email_create_message().
 169  *
 170  * @see email_add_recipient()
 171  */
 172 int email_remove_all_recipients(email_h email);
 173
 174 /**
 175  * @brief   Adds a file as an attachment to the email message.
 176  * @details It should be used to add a file to the attachment list
 177  *          of the email message.
 178  *
 179  * @since_tizen 2.3
 180  *
 181  * @remarks  The maximum attachment file size is 10MB.
 182  *
 183  * @param[in]   email       The handle to the email message
 184  * @param[in]   filepath    The absolute full path of the file to be attached
 185  *
 186  * @return  @c 0 on success,
 187  *          otherwise a negative error value
 188  *
 189  * @retval  #EMAILS_ERROR_NONE              Successful
 190  * @retval  #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 191  * @retval  #EMAILS_ERROR_OUT_OF_MEMORY     Out of memory
 192  *
 193  * @pre     An email message handle is created using email_create_message().
 194  *
 195  * @see email_remove_all_attachments()
 196  *
 197  */
 198 int email_add_attach(email_h email, const char *filepath);
 199
 200 /**
 201  * @brief   Clears all attachments of the email message.
 202  * @since_tizen 2.3
 203  *
 204  * @param[in]  email  The handle to the email message
 205  *
 206  * @return  @c 0 on success,
 207  *          otherwise a negative error value
 208  *
 209  * @retval  #EMAILS_ERROR_NONE              Successful
 210  * @retval  #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 211  *
 212  * @pre     An email message handle is created using email_create_message().
 213  *
 214  * @see email_create_message()
 215  * @see email_add_attach()
 216  */
 217 int email_remove_all_attachments(email_h email);
 218
 219 /**
 220  * @brief   Saves the email message at outbox.
 221  * @since_tizen 2.3
 222  *
 223  * @privlevel public
 224  * @privilege %http://tizen.org/privilege/email
 225  *
 226  * @remarks Get the ID of mail.
 227  *
 228  * @param[in]  email  The handle to the email message
 229  *
 230  * @return  @c 0 on success,
 231  *          otherwise a negative error value
 232  *
 233  * @retval  #EMAILS_ERROR_NONE                             Successful
 234  * @retval  #EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed.
 235  * @retval  #EMAILS_ERROR_INVALID_PARAMETER                Invalid parameter
 236  *
 237  * @pre     An email message handle is created using email_create_message().
 238  *
 239  * @see email_create_message()
 240  * @see email_add_recipient()
 241  * @see email_set_body()
 242  * @see email_save_message
 243  */
 244 int email_save_message(email_h email);
 245
 246
 247 /**
 248  * @brief   Sends the email message.
 249  * @since_tizen 2.3
 250  *
 251  *
 252  * @remarks In order to check whether sending a message succeeds,
 253  *          you should register email_message_sent_cb() using email_set_message_sent_cb().
 254  *
 255  * @param[in]   email            The handle to the email message
 256  * @param[in]   save_to_sentbox  Set to @c true to save the message in the sentbox,
 257  *                               otherwise set to @c false to not save the message in the sentbox
 258  *
 259  * @return  @c 0 on success,
 260  *          otherwise a negative error value
 261  *
 262  * @retval  #EMAILS_ERROR_NONE                              Successful
 263  * @retval  #EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILED  Communication with server failed
 264  * @retval  #EMAILS_ERROR_INVALID_PARAMETER                 Invalid parameter
 265  *
 266  * @pre     An email message is stored using email_save_message().
 267  *
 268  * @see email_save_message()
 269  * @see email_set_message_sent_cb()
 270  */
 271 int email_send_message(email_h email, bool save_to_sentbox);
 272
 273
 274 /**
 275  * @brief   Called when the process of sending an email finishes.
 276  * @details You can check whether sending an email succeeds using this function.
 277  *
 278  * @since_tizen 2.3
 279  *
 280  * @param[in]   email       The handle to the email message
 281  * @param[in]   result      The result of email message sending \n
 282  *                          #EMAIL_SENDING_FAILED or #EMAIL_SENDING_SUCCEEDED
 283  * @param[in]   user_data   The user data passed from the callback registration function
 284  *
 285  * @pre email_send_message() will invoke this callback if you register this callback using email_set_message_sent_cb().
 286  *
 287  * @see email_send_message()
 288  * @see email_set_message_sent_cb()
 289  * @see email_unset_message_sent_cb()
 290  */
 291 typedef void (*email_message_sent_cb)(email_h email, email_sending_e result, void *user_data);
 292
 293 /**
 294  * @brief   Registers a callback function to be invoked when an email message is sent.
 295  * @details You will be notified when sending a message finishes and check whether it succeeds using this function.
 296  *
 297  * @since_tizen 2.3
 298  *
 299  * @param[in]  email      The handle to the email message
 300  * @param[in]  callback   The callback function to register
 301  * @param[in]  user_data  The user data to be passed to the callback function
 302  *
 303  * @return  @c 0 on success,
 304  *          otherwise a negative error value
 305  *
 306  * @retval  #EMAILS_ERROR_NONE               Successful
 307  * @retval  #EMAILS_ERROR_INVALID_PARAMETER  Invalid parameter
 308  *
 309  * @post  It will invoke email_message_sent_cb().
 310  *
 311  * @see email_message_sent_cb()
 312  * @see email_unset_message_sent_cb()
 313  * @see email_send_message()
 314  */
 315 int email_set_message_sent_cb(email_h email, email_message_sent_cb callback, void *user_data);
 316
 317 /**
 318  * @brief   Unregisters the callback function.
 319  * @since_tizen 2.3
 320  *
 321  * @param[in]  msg  The handle to the email message
 322  *
 323  * @return  @c 0 on success,
 324  *          otherwise a negative error value
 325  *
 326  * @retval  #EMAILS_ERROR_NONE              Successful
 327  * @retval  #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 328  *
 329  * @see email_message_sent_cb()
 330  * @see email_set_message_sent_cb()
 331  * @see email_send_message()
 332  */
 333 int email_unset_message_sent_cb(email_h msg);
 334
 335 #ifdef __cplusplus
 336 }
 337 #endif
 338
 339 /**
 340 * @}
 341 */
 342
 343 #endif /* __MESSAGING_EMAIL_H__ */
 344