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_FRAMEWORK
  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  *
  44  * @remarks  a email must be released with email_destroy_message() by you.
  45  *
  46  * @param[out]  email   A handle to the email message
  47  *
  48  * @return  0 on success, otherwise a negative error value.
  49  * @retval      #EMAIL_ERROR_NONE Successful
  50  * @retval      #EMAIL_ERROR_OUT_OF_MEMORY Out of memory
  51  * @retval      #EMAIL_ERROR_ACCOUNT_NOT_FOUND           Email account not found
  52  *
  53  * @see email_destroy_message()
  54  */
  55 int email_create_message(email_h *email);
  56
  57 /**
  58  * @brief   Destroys the email message handle and releases all its resources.
  59  *
  60  * @param[in]   email   The handle to the email message
  61  *
  62  * @return  0 on success, otherwise a negative error value.
  63  * @retval      #EMAIL_ERROR_NONE Successful
  64  * @retval      #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
  65  * @retval      #EMAIL_ERROR_OPERATION_FAILED Operation failed
  66  *
  67  * @see email_create_message()
  68  */
  69 int email_destroy_message(email_h email);
  70
  71 /**
  72  * @brief   Sets a subject of the email message.
  73  *
  74  * @param[in]   email   The handle to the email message
  75  * @param[in]   subject The subject of the email message
  76  * @return      0 on success, otherwise a negative error value.
  77  * @retval      #EMAIL_ERROR_NONE Successful
  78  * @retval      #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
  79  * @retval      #EMAIL_ERROR_OUT_OF_MEMORY Out of memory
  80  *
  81  * @see email_create_message()
  82  */
  83 int email_set_subject(email_h email, const char *subject);
  84
  85 /**
  86  * @brief   Populates a body of the email message.
  87  * @details Email message body means the text data to be delivered.
  88  *
  89  * @param[in]   email   The handle to the email message
  90  * @param[in]   body    The message body
  91  * @return      0 on success, otherwise a negative error value.
  92  * @retval      #EMAIL_ERROR_NONE Successful
  93  * @retval      #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
  94  * @retval      # EMAIL_ERROR_OPERATION_FAILED Operation failed
  95  * @pre     An email message handle is created using #email_create_message().
  96  * @see email_create_message()
  97  */
  98 int email_set_body(email_h email, const char *body);
  99
 100 /**
 101  * @brief   Adds a recipient to the email message.
 102  * @details The email API supports sending an email message to multiple recipients.
 103  *
 104  * @remarks Email address should be in standard format (as described in
 105  * Internet standards RFC 5321 and RFC 5322).\n
 106  *
 107  * @param[in]   email   The handle to the email message
 108  * @param[in]   type    The recipient type
 109  * @param[in]   address The recipient email address
 110  *
 111  * @return  0 on success, otherwise a negative error value.
 112  * @retval  #EMAIL_ERROR_NONE Successful
 113  * @retval  #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
 114  * @retval  #EMAIL_ERROR_OUT_OF_MEMORY Out of memory
 115  *
 116  * @see email_create_message()
 117  * @see email_remove_all_recipients()
 118  */
 119 int email_add_recipient(email_h email, email_recipient_type_e type, const char *address);
 120
 121 /**
 122  * @brief   Removes all recipients for the email message.
 123  *
 124  * @param[in]   email   The handle to the email message
 125  *
 126  * @return  0 on success, otherwise a negative error value.
 127  * @retval  #EMAIL_ERROR_NONE Successful
 128  * @retval  #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
 129  *
 130  * @see email_add_recipient()
 131  */
 132 int email_remove_all_recipients(email_h email);
 133
 134 /**
 135  * @brief   Adds a file as an attachment to the email message.
 136  * @details It should be used to add a file to the attachment list
 137  * of the email message.
 138  *
 139  * @remarks  The maximum attachment file size is 10MB.
 140  *
 141  * @param[in]   email   The handle to the email message
 142  * @param[in]   filepath    The absolute full path of the file to be attached
 143  *
 144  * @return  0 on success, otherwise a negative error value.
 145  * @retval  #EMAIL_ERROR_NONE Successful
 146  * @retval  #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
 147  * @retval  #EMAIL_ERROR_OUT_OF_MEMORY Out of memory
 148  *
 149  * @see email_remove_all_attachments()
 150  *
 151  */
 152 int email_add_attach(email_h email, const char *filepath);
 153
 154 /**
 155  * @brief   Clears all attachments of the email message.
 156  *
 157  * @param[in]   email   The handle to the email message
 158  *
 159  * @return  0 on success, otherwise a negative error value.
 160  * @retval  #EMAIL_ERROR_NONE Successful
 161  * @retval  #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
 162  *
 163  * @see email_create_message()
 164  * @see email_add_attach()
 165  */
 166 int email_remove_all_attachments(email_h email);
 167
 168 /**
 169  * @brief   Save the email message at outbox.
 170  *
 171  * @remarks Get the id of mail.
 172  *
 173  *
 174  * @param[in]   email   The handle to the email message
 175  * @return  0 on success, otherwise a negative error value.
 176  * @retval  #EMAIL_ERROR_NONE Successful
 177  * @retval  #EMAIL_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed.
 178  * @retval  #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
 179  *
 180  * @see email_create_message()
 181  * @see email_add_recipient()
 182  * @see email_set_body()
 183  * @see email_save_message
 184  */
 185 int email_save_message(email_h email);
 186
 187
 188 /**
 189  * @brief   Sends the email message.
 190  *
 191  * @remarks In order to check whether sending a message succeeds, \n you should register email_message_sent_cb() using #email_set_message_sent_cb().
 192  *
 193  *
 194  * @param[in]   email   The handle to the email message
 195  * @param[in]   save_to_sentbox Set to true to save the message in the sentbox, else false
 196  * @return  0 on success, otherwise a negative error value.
 197  * @retval  #EMAIL_ERROR_NONE Successful
 198  * @retval  #EMAIL_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed.
 199  * @retval  #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
 200  *
 201  * @see email_save_message()
 202  * @see email_set_message_sent_cb()
 203  */
 204 int email_send_message(email_h email, bool save_to_sentbox);
 205
 206
 207 /**
 208  * @brief   Called when the process of sending an email finishes.
 209  * @details You can check whether sending an email succeeds using this function.
 210  *
 211  *
 212  * @param[in]   email   The handle to the email message
 213  * @param[in]   result          The result of email message sending\n
 214  *                                              #EMAIL_SENDING_FAILED or #EMAIL_SENDING_SUCCEEDED
 215  * @param[in]   user_data  The user data passed from the callback registration function
 216  *
 217  * @pre email_send_message() will invoke this callback if you register this callback using email_set_message_sent_cb().
 218  *
 219  * @see email_send_message()
 220  * @see email_set_message_sent_cb()
 221  * @see email_unset_message_sent_cb()
 222  */
 223 typedef void (* email_message_sent_cb)(email_h email, email_sending_e result, void *user_data);
 224
 225 /**
 226  * @brief   Registers a callback function to be invoked when an email message is sent.
 227  * @details You will be notified when sending a message finishes and check whether it succeeds using this function.
 228  *
 229  * @param[in]   email   The handle to the email message
 230  * @param[in]   callback        The callback function to register
 231  * @param[in]   user_data       The user data to be passed to the callback function
 232  *
 233  * @return  0 on success, otherwise a negative error value.
 234  * @retval  #EMAIL_ERROR_NONE   Successful
 235  * @retval  #EMAIL_ERROR_INVALID_PARAMETER      Invalid parameter
 236  * @post        It will invoke email_message_sent_cb().
 237  * @see email_message_sent_cb()
 238  * @see email_unset_message_sent_cb()
 239  * @see email_send_message()
 240  */
 241 int email_set_message_sent_cb(email_h email, email_message_sent_cb callback, void *user_data);
 242
 243 /**
 244  * @brief   Unregisters the callback function.
 245  *
 246  * @param[in]   email   The handle to the email message
 247  *
 248  * @return  0 on success, otherwise a negative error value.
 249  * @retval  #EMAIL_ERROR_NONE Successful
 250  * @retval  #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
 251  *
 252  * @see email_message_sent_cb()
 253  * @see email_set_message_sent_cb()
 254  * @see email_send_message()
 255  */
 256 int email_unset_message_sent_cb(email_h msg);
 257
 258 #ifdef __cplusplus
 259 }
 260 #endif
 261
 262 /**
 263 * @}
 264 */
 265
 266 #endif /* __MESSAGING_EMAIL_H__ */