2 * Copyright (c) 2012 - 2013 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __MESSAGING_EMAIL_H__
18 #define __MESSAGING_EMAIL_H__
21 * @addtogroup CAPI_MESSAGING_EMAIL_MODULE
27 * @ingroup CAPI_MESSAGING_EMAIL_MODULE
28 * @brief Messaging API file, support for sending email messages.
34 #include <email_types.h>
35 #include <email_error.h>
39 #endif /* __cplusplus */
42 * @brief Creates an email message handle for sending an email message.
45 * @privilege %http://tizen.org/privilege/email
47 * @remarks You must release @a email using email_destroy_message().
49 * @param[out] email A handle to the email message
51 * @return @c 0 on success,
52 * 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
58 * @pre At least one email account should be set up on the device.
60 * @see email_destroy_message()
62 int email_create_message(email_h *email);
65 * @brief Destroys the email message handle and releases all its resources.
68 * @param[in] email The handle to the email message
70 * @return @c 0 on success,
71 * 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
77 * @see email_create_message()
79 int email_destroy_message(email_h email);
82 * @brief Sets a subject of the email message.
86 * @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
91 * @return @c 0 on success,
92 * otherwise a negative error value
94 * @retval #EMAILS_ERROR_NONE Successful
95 * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
96 * @retval #EMAILS_ERROR_OUT_OF_MEMORY Out of memory
98 * @pre An email message handle is created using email_create_message().
100 * @see email_create_message()
102 int email_set_subject(email_h email, const char *subject);
105 * @brief Populates a body of the email message.
106 * @details Email message body means the text data to be delivered.
111 * @privilege %http://tizen.org/privilege/mediastorage
113 * @param[in] email The handle to the email message
114 * @param[in] body The message body
116 * @return @c 0 on success,
117 * otherwise a negative error value
119 * @retval #EMAILS_ERROR_NONE Successful
120 * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
121 * @retval #EMAILS_ERROR_OPERATION_FAILED Operation failed
123 * @pre An email message handle is created using email_create_message().
125 * @see email_create_message()
127 int email_set_body(email_h email, const char *body);
130 * @brief Adds a recipient to the email message.
131 * @details The email API supports sending an email message to multiple recipients.
135 * @remarks Email address should be in standard format (as described in
136 * Internet standards RFC 5321 and RFC 5322).
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
142 * @return @c 0 on success,
143 * otherwise a negative error value
145 * @retval #EMAILS_ERROR_NONE Successful
146 * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
147 * @retval #EMAILS_ERROR_OUT_OF_MEMORY Out of memory
149 * @pre An email message handle is created using email_create_message().
151 * @see email_create_message()
152 * @see email_remove_all_recipients()
154 int email_add_recipient(email_h email, email_recipient_type_e type, const char *address);
157 * @brief Removes all recipients for the email message.
160 * @param[in] email The handle to the email message
162 * @return @c 0 on success,
163 * otherwise a negative error value
165 * @retval #EMAILS_ERROR_NONE Successful
166 * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
168 * @pre An email message handle is created using email_create_message().
170 * @see email_add_recipient()
172 int email_remove_all_recipients(email_h email);
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.
181 * @remarks The maximum attachment file size is 10MB.
183 * @param[in] email The handle to the email message
184 * @param[in] filepath The absolute full path of the file to be attached
186 * @return @c 0 on success,
187 * otherwise a negative error value
189 * @retval #EMAILS_ERROR_NONE Successful
190 * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
191 * @retval #EMAILS_ERROR_OUT_OF_MEMORY Out of memory
193 * @pre An email message handle is created using email_create_message().
195 * @see email_remove_all_attachments()
198 int email_add_attach(email_h email, const char *filepath);
201 * @brief Clears all attachments of the email message.
204 * @param[in] email The handle to the email message
206 * @return @c 0 on success,
207 * otherwise a negative error value
209 * @retval #EMAILS_ERROR_NONE Successful
210 * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
212 * @pre An email message handle is created using email_create_message().
214 * @see email_create_message()
215 * @see email_add_attach()
217 int email_remove_all_attachments(email_h email);
220 * @brief Saves the email message at outbox.
224 * @privilege %http://tizen.org/privilege/email
226 * @remarks Get the ID of mail.
228 * @param[in] email The handle to the email message
230 * @return @c 0 on success,
231 * otherwise a negative error value
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
237 * @pre An email message handle is created using email_create_message().
239 * @see email_create_message()
240 * @see email_add_recipient()
241 * @see email_set_body()
242 * @see email_save_message
244 int email_save_message(email_h email);
248 * @brief Sends the email message.
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().
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
259 * @return @c 0 on success,
260 * otherwise a negative error value
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
266 * @pre An email message is stored using email_save_message().
268 * @see email_save_message()
269 * @see email_set_message_sent_cb()
271 int email_send_message(email_h email, bool save_to_sentbox);
275 * @brief Called when the process of sending an email finishes.
276 * @details You can check whether sending an email succeeds using this function.
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
285 * @pre email_send_message() will invoke this callback if you register this callback using email_set_message_sent_cb().
287 * @see email_send_message()
288 * @see email_set_message_sent_cb()
289 * @see email_unset_message_sent_cb()
291 typedef void (* email_message_sent_cb)(email_h email, email_sending_e result, void *user_data);
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.
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
303 * @return @c 0 on success,
304 * otherwise a negative error value
306 * @retval #EMAILS_ERROR_NONE Successful
307 * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
309 * @post It will invoke email_message_sent_cb().
311 * @see email_message_sent_cb()
312 * @see email_unset_message_sent_cb()
313 * @see email_send_message()
315 int email_set_message_sent_cb(email_h email, email_message_sent_cb callback, void *user_data);
318 * @brief Unregisters the callback function.
321 * @param[in] msg The handle to the email message
323 * @return @c 0 on success,
324 * otherwise a negative error value
326 * @retval #EMAILS_ERROR_NONE Successful
327 * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
329 * @see email_message_sent_cb()
330 * @see email_set_message_sent_cb()
331 * @see email_send_message()
333 int email_unset_message_sent_cb(email_h msg);
343 #endif /* __MESSAGING_EMAIL_H__ */