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
  18  #ifndef __MESSAGING_EMAIL_H__
  19  #define __MESSAGING_EMAIL_H__
  20
  21
  22 /**
  23  * @addtogroup CAPI_MESSAGING_EMAIL_MODULE
  24  * @{
  25  */
  26
  27
  28 /**
  29  * @file email.h
  30  * @ingroup CAPI_MESSAGING_EMAIL_MODULE
  31  * @brief Messaging API file, support for sending email messages.
  32  */
  33
  34
  35 #include <stdlib.h>
  36 #include <stdio.h>
  37 #include <email_types.h>
  38 #include <email_error.h>
  39 #ifdef __cplusplus
  40 extern "C"
  41 {
  42 #endif /* __cplusplus */
  43
  44
  45 /**
  46  * @brief Creates an email message handle for sending an email message.
  47  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  48  * @privlevel public
  49  * @privilege %http://tizen.org/privilege/email
  50  * @remarks You must release @a email using email_destroy_message().
  51  * @param[out] email A handle to the email message
  52  * @return @c 0 on success,
  53  *         otherwise a negative error value
  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  * @retval #EMAILS_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
  58  * @retval #EMAILS_ERROR_NOT_SUPPORTED Not supported
  59  * @pre At least one email account should be set up on the device.
  60  * @see email_destroy_message()
  61  */
  62 int email_create_message(email_h *email);
  63
  64
  65 /**
  66  * @brief Destroys the email message handle and releases all its resources.
  67  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  68  * @param[in] email The handle to the email message
  69  * @return @c 0 on success,
  70  *         otherwise a negative error value
  71  * @retval #EMAILS_ERROR_NONE Successful
  72  * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
  73  * @retval #EMAILS_ERROR_OPERATION_FAILED Operation failed
  74  * @retval #EMAILS_ERROR_NOT_SUPPORTED Not supported
  75  * @see email_create_message()
  76  */
  77 int email_destroy_message(email_h email);
  78
  79
  80 /**
  81  * @brief Sets a subject of the email message.
  82  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  83  * @privlevel public
  84  * @privilege %http://tizen.org/privilege/email
  85  * @param[in] email The handle to the email message
  86  * @param[in] subject The subject of the email message
  87  * @return @c 0 on success,
  88  *         otherwise a negative error value
  89  * @retval #EMAILS_ERROR_NONE Successful
  90  * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
  91  * @retval #EMAILS_ERROR_OUT_OF_MEMORY Out of memory
  92  * @retval #EMAILS_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
  93  * @retval #EMAILS_ERROR_NOT_SUPPORTED Not supported
  94  * @pre An email message handle is created using email_create_message().
  95  * @see email_create_message()
  96  */
  97 int email_set_subject(email_h email, const char *subject);
  98
  99
 100 /**
 101  * @brief Populates a body of the email message.
 102  * @details Email message body means the text data to be delivered.
 103  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 104  * @privlevel public
 105  * @privilege %http://tizen.org/privilege/mediastorage
 106  * @param[in] email The handle to the email message
 107  * @param[in] body The message body
 108  * @return @c 0 on success,
 109  *         otherwise a negative error value
 110  * @retval #EMAILS_ERROR_NONE Successful
 111  * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 112  * @retval #EMAILS_ERROR_OPERATION_FAILED Operation failed
 113  * @retval #EMAILS_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 114  * @retval #EMAILS_ERROR_NOT_SUPPORTED Not supported
 115  * @pre An email message handle is created using email_create_message().
 116  * @see email_create_message()
 117  */
 118 int email_set_body(email_h email, const char *body);
 119
 120
 121 /**
 122  * @brief Adds a recipient to the email message.
 123  * @details The email API supports sending an email message to multiple recipients.
 124  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 125  * @remarks Email address should be in standard format (as described in
 126  *          Internet standards RFC 5321 and RFC 5322).
 127  * @param[in] email The handle to the email message
 128  * @param[in] type The recipient type
 129  * @param[in] address The recipient email address
 130  * @return @c 0 on success,
 131  *         otherwise a negative error value
 132  * @retval #EMAILS_ERROR_NONE Successful
 133  * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 134  * @retval #EMAILS_ERROR_OUT_OF_MEMORY Out of memory
 135  * @retval #EMAILS_ERROR_NOT_SUPPORTED Not supported
 136  * @pre An email message handle is created using email_create_message().
 137  * @see email_create_message()
 138  * @see email_remove_all_recipients()
 139  */
 140 int email_add_recipient(email_h email, email_recipient_type_e type, const char *address);
 141
 142
 143 /**
 144  * @brief Removes all recipients for the email message.
 145  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 146  * @param[in] email The handle to the email message
 147  * @return @c 0 on success,
 148  *         otherwise a negative error value
 149  * @retval #EMAILS_ERROR_NONE Successful
 150  * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 151  * @retval #EMAILS_ERROR_NOT_SUPPORTED Not supported
 152  * @pre An email message handle is created using email_create_message().
 153  * @see email_add_recipient()
 154  */
 155 int email_remove_all_recipients(email_h email);
 156
 157
 158 /**
 159  * @brief Adds a file as an attachment to the email message.
 160  * @details It should be used to add a file to the attachment list
 161  *          of the email message.
 162  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 163  * @remarks The maximum attachment file size is 10MB.
 164  *          %http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage
 165  *          %http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
 166  * @param[in] email The handle to the email message
 167  * @param[in] filepath The absolute full path of the file to be attached
 168  * @return @c 0 on success,
 169  *         otherwise a negative error value
 170  * @retval #EMAILS_ERROR_NONE Successful
 171  * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 172  * @retval #EMAILS_ERROR_OUT_OF_MEMORY Out of memory
 173  * @retval #EMAILS_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 174  * @retval #EMAILS_ERROR_NOT_SUPPORTED Not supported
 175  * @pre An email message handle is created using email_create_message().
 176  * @see email_remove_all_attachments()
 177  */
 178 int email_add_attach(email_h email, const char *filepath);
 179
 180
 181 /**
 182  * @brief Clears all attachments of the email message.
 183  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 184  * @param[in] email The handle to the email message
 185  * @return @c 0 on success,
 186  *         otherwise a negative error value
 187  * @retval #EMAILS_ERROR_NONE Successful
 188  * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 189  * @retval #EMAILS_ERROR_NOT_SUPPORTED Not supported
 190  * @pre An email message handle is created using email_create_message().
 191  * @see email_create_message()
 192  * @see email_add_attach()
 193  */
 194 int email_remove_all_attachments(email_h email);
 195
 196
 197 /**
 198  * @brief Saves the email message at outbox.
 199  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 200  * @privlevel public
 201  * @privilege %http://tizen.org/privilege/email
 202  * @param[in] email The handle to the email message
 203  * @return @c 0 on success,
 204  *         otherwise a negative error value
 205  * @retval #EMAILS_ERROR_NONE Successful
 206  * @retval #EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed.
 207  * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 208  * @retval #EMAILS_ERROR_PERMISSION_DENIED The application does not have the privilege to call this method
 209  * @retval #EMAILS_ERROR_NOT_SUPPORTED Not supported
 210  * @pre An email message handle is created using email_create_message().
 211  * @see email_create_message()
 212  * @see email_add_recipient()
 213  * @see email_set_body()
 214  */
 215 int email_save_message(email_h email);
 216
 217
 218 /**
 219  * @brief Sends the email message.
 220  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 221  * @remarks In order to check whether sending a message succeeds,
 222  *          you should register email_message_sent_cb() using email_set_message_sent_cb().
 223  * @param[in] email The handle to the email message
 224  * @param[in] save_to_sentbox Set to @c true to save the message in the sentbox,
 225  *                            otherwise set to @c false to not save the message in the sentbox
 226  * @return @c 0 on success,
 227  *         otherwise a negative error value
 228  * @retval #EMAILS_ERROR_NONE Successful
 229  * @retval #EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed
 230  * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 231  * @retval #EMAILS_ERROR_NOT_SUPPORTED Not supported
 232  * @pre An email message is stored using email_save_message().
 233  * @see email_save_message()
 234  * @see email_set_message_sent_cb()
 235  */
 236 int email_send_message(email_h email, bool save_to_sentbox);
 237
 238
 239 /**
 240  * @brief Called when the process of sending an email finishes.
 241  * @details You can check whether sending an email succeeds using this function.
 242  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 243  * @param[in] email The handle to the email message
 244  * @param[in] result The result of email message sending \n
 245  *                   #EMAIL_SENDING_FAILED or #EMAIL_SENDING_SUCCEEDED
 246  * @param[in] user_data The user data passed from the callback registration function
 247  * @pre email_send_message() will invoke this callback if you register this callback using email_set_message_sent_cb().
 248  * @see email_send_message()
 249  * @see email_set_message_sent_cb()
 250  * @see email_unset_message_sent_cb()
 251  */
 252 typedef void (*email_message_sent_cb)(email_h email, email_sending_e result, void *user_data);
 253
 254
 255 /**
 256  * @brief Registers a callback function to be invoked when an email message is sent.
 257  * @details You will be notified when sending a message finishes and check whether it succeeds using this function.
 258  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 259  * @param[in] email The handle to the email message
 260  * @param[in] callback The callback function to register
 261  * @param[in] user_data The user data to be passed to the callback function
 262  * @return @c 0 on success,
 263  *         otherwise a negative error value
 264  * @retval #EMAILS_ERROR_NONE Successful
 265  * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 266  * @retval #EMAILS_ERROR_NOT_SUPPORTED Not supported
 267  * @post It will invoke email_message_sent_cb().
 268  * @see email_message_sent_cb()
 269  * @see email_unset_message_sent_cb()
 270  * @see email_send_message()
 271  */
 272 int email_set_message_sent_cb(email_h email, email_message_sent_cb callback, void *user_data);
 273
 274
 275 /**
 276  * @brief Unregisters the callback function.
 277  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 278  * @param[in] msg The handle to the email message
 279  * @return @c 0 on success,
 280  *         otherwise a negative error value
 281  * @retval #EMAILS_ERROR_NONE Successful
 282  * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
 283  * @retval #EMAILS_ERROR_NOT_SUPPORTED Not supported
 284  * @see email_message_sent_cb()
 285  * @see email_set_message_sent_cb()
 286  * @see email_send_message()
 287  */
 288 int email_unset_message_sent_cb(email_h msg);
 289
 290
 291 #ifdef __cplusplus
 292 }
 293 #endif
 294
 295
 296 /**
 297 * @}
 298 */
 299
 300
 301 #endif /* __MESSAGING_EMAIL_H__ */
 302