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