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  * @param[in]   email    The handle to the email message
  86  * @param[in]   subject  The subject of the email message
  87  *
  88  * @return  @c 0 on success,
  89  *          otherwise a negative error value
  90  *
  91  * @retval  #EMAILS_ERROR_NONE               Successful
  92  * @retval  #EMAILS_ERROR_INVALID_PARAMETER  Invalid parameter
  93  * @retval  #EMAILS_ERROR_OUT_OF_MEMORY      Out of memory
  94  *
  95  * @pre     An email message handle is created using email_create_message().
  96  *
  97  * @see  email_create_message()
  98  */
  99 int email_set_subject(email_h email, const char *subject);
 100
 101 /**
 102  * @brief   Populates a body of the email message.
 103  * @details Email message body means the text data to be delivered.
 104  *
 105  * @since_tizen 2.3
 106  *
 107  * @param[in]   email   The handle to the email message
 108  * @param[in]   body    The message body
 109  *
 110  * @return  @c 0 on success,
 111  *          otherwise a negative error value
 112  *
 113  * @retval  #EMAILS_ERROR_NONE              Successful
 114  * @retval  #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 115  * @retval  #EMAILS_ERROR_OPERATION_FAILED  Operation failed
 116  *
 117  * @pre     An email message handle is created using email_create_message().
 118  *
 119  * @see  email_create_message()
 120  */
 121 int email_set_body(email_h email, const char *body);
 122
 123 /**
 124  * @brief   Adds a recipient to the email message.
 125  * @details The email API supports sending an email message to multiple recipients.
 126  *
 127  * @since_tizen 2.3
 128  *
 129  * @remarks Email address should be in standard format (as described in
 130  *          Internet standards RFC 5321 and RFC 5322).
 131  *
 132  * @param[in]   email   The handle to the email message
 133  * @param[in]   type    The recipient type
 134  * @param[in]   address The recipient email address
 135  *
 136  * @return  @c 0 on success,
 137  *          otherwise a negative error value
 138  *
 139  * @retval  #EMAILS_ERROR_NONE              Successful
 140  * @retval  #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 141  * @retval  #EMAILS_ERROR_OUT_OF_MEMORY     Out of memory
 142  *
 143  * @pre     An email message handle is created using email_create_message().
 144  *
 145  * @see email_create_message()
 146  * @see email_remove_all_recipients()
 147  */
 148 int email_add_recipient(email_h email, email_recipient_type_e type, const char *address);
 149
 150 /**
 151  * @brief   Removes all recipients for the email message.
 152  * @since_tizen 2.3
 153  *
 154  * @param[in]  email  The handle to the email message
 155  *
 156  * @return  @c 0 on success,
 157  *          otherwise a negative error value
 158  *
 159  * @retval  #EMAILS_ERROR_NONE              Successful
 160  * @retval  #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 161  *
 162  * @pre     An email message handle is created using email_create_message().
 163  *
 164  * @see email_add_recipient()
 165  */
 166 int email_remove_all_recipients(email_h email);
 167
 168 /**
 169  * @brief   Adds a file as an attachment to the email message.
 170  * @details It should be used to add a file to the attachment list
 171  *          of the email message.
 172  *
 173  * @since_tizen 2.3
 174  *
 175  * @remarks  The maximum attachment file size is 10MB.
 176  *
 177  * @param[in]   email       The handle to the email message
 178  * @param[in]   filepath    The absolute full path of the file to be attached
 179  *
 180  * @return  @c 0 on success,
 181  *          otherwise a negative error value
 182  *
 183  * @retval  #EMAILS_ERROR_NONE              Successful
 184  * @retval  #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 185  * @retval  #EMAILS_ERROR_OUT_OF_MEMORY     Out of memory
 186  *
 187  * @pre     An email message handle is created using email_create_message().
 188  *
 189  * @see email_remove_all_attachments()
 190  *
 191  */
 192 int email_add_attach(email_h email, const char *filepath);
 193
 194 /**
 195  * @brief   Clears all attachments of the email message.
 196  * @since_tizen 2.3
 197  *
 198  * @param[in]  email  The handle to the email message
 199  *
 200  * @return  @c 0 on success,
 201  *          otherwise a negative error value
 202  *
 203  * @retval  #EMAILS_ERROR_NONE              Successful
 204  * @retval  #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 205  *
 206  * @pre     An email message handle is created using email_create_message().
 207  *
 208  * @see email_create_message()
 209  * @see email_add_attach()
 210  */
 211 int email_remove_all_attachments(email_h email);
 212
 213 /**
 214  * @brief   Saves the email message at outbox.
 215  * @since_tizen 2.3
 216  *
 217  * @privlevel public
 218  * @privilege %http://tizen.org/privilege/email
 219  *
 220  * @remarks Get the ID of mail.
 221  *
 222  * @param[in]  email  The handle to the email message
 223  *
 224  * @return  @c 0 on success,
 225  *          otherwise a negative error value
 226  *
 227  * @retval  #EMAILS_ERROR_NONE                             Successful
 228  * @retval  #EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed.
 229  * @retval  #EMAILS_ERROR_INVALID_PARAMETER                Invalid parameter
 230  *
 231  * @pre     An email message handle is created using email_create_message().
 232  *
 233  * @see email_create_message()
 234  * @see email_add_recipient()
 235  * @see email_set_body()
 236  * @see email_save_message
 237  */
 238 int email_save_message(email_h email);
 239
 240
 241 /**
 242  * @brief   Sends the email message.
 243  * @since_tizen 2.3
 244  *
 245  * @privlevel public
 246  * @privilege %http://tizen.org/privilege/email
 247  *
 248  * @remarks In order to check whether sending a message succeeds,
 249  *          you should register email_message_sent_cb() using email_set_message_sent_cb().
 250  *
 251  * @param[in]   email            The handle to the email message
 252  * @param[in]   save_to_sentbox  Set to @c true to save the message in the sentbox,
 253  *                               otherwise set to @c false to not save the message in the sentbox
 254  *
 255  * @return  @c 0 on success,
 256  *          otherwise a negative error value
 257  *
 258  * @retval  #EMAILS_ERROR_NONE                              Successful
 259  * @retval  #EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILED  Communication with server failed
 260  * @retval  #EMAILS_ERROR_INVALID_PARAMETER                 Invalid parameter
 261  *
 262  * @pre     An email message is stored using email_save_message().
 263  *
 264  * @see email_save_message()
 265  * @see email_set_message_sent_cb()
 266  */
 267 int email_send_message(email_h email, bool save_to_sentbox);
 268
 269
 270 /**
 271  * @brief   Called when the process of sending an email finishes.
 272  * @details You can check whether sending an email succeeds using this function.
 273  *
 274  * @since_tizen 2.3
 275  *
 276  * @param[in]   email       The handle to the email message
 277  * @param[in]   result      The result of email message sending \n
 278  *                          #EMAIL_SENDING_FAILED or #EMAIL_SENDING_SUCCEEDED
 279  * @param[in]   user_data   The user data passed from the callback registration function
 280  *
 281  * @pre email_send_message() will invoke this callback if you register this callback using email_set_message_sent_cb().
 282  *
 283  * @see email_send_message()
 284  * @see email_set_message_sent_cb()
 285  * @see email_unset_message_sent_cb()
 286  */
 287 typedef void (* email_message_sent_cb)(email_h email, email_sending_e result, void *user_data);
 288
 289 /**
 290  * @brief   Registers a callback function to be invoked when an email message is sent.
 291  * @details You will be notified when sending a message finishes and check whether it succeeds using this function.
 292  *
 293  * @since_tizen 2.3
 294  *
 295  * @param[in]  email      The handle to the email message
 296  * @param[in]  callback   The callback function to register
 297  * @param[in]  user_data  The user data to be passed to the callback function
 298  *
 299  * @return  @c 0 on success,
 300  *          otherwise a negative error value
 301  *
 302  * @retval  #EMAILS_ERROR_NONE               Successful
 303  * @retval  #EMAILS_ERROR_INVALID_PARAMETER  Invalid parameter
 304  *
 305  * @post  It will invoke email_message_sent_cb().
 306  *
 307  * @see email_message_sent_cb()
 308  * @see email_unset_message_sent_cb()
 309  * @see email_send_message()
 310  */
 311 int email_set_message_sent_cb(email_h email, email_message_sent_cb callback, void *user_data);
 312
 313 /**
 314  * @brief   Unregisters the callback function.
 315  * @since_tizen 2.3
 316  *
 317  * @param[in]  msg  The handle to the email message
 318  *
 319  * @return  @c 0 on success,
 320  *          otherwise a negative error value
 321  *
 322  * @retval  #EMAILS_ERROR_NONE              Successful
 323  * @retval  #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 324  *
 325  * @see email_message_sent_cb()
 326  * @see email_set_message_sent_cb()
 327  * @see email_send_message()
 328  */
 329 int email_unset_message_sent_cb(email_h msg);
 330
 331 #ifdef __cplusplus
 332 }
 333 #endif
 334
 335 /**
 336 * @}
 337 */
 338
 339 #endif /* __MESSAGING_EMAIL_H__ */
 340