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.
18 #ifndef __MESSAGING_EMAIL_H__
19 #define __MESSAGING_EMAIL_H__
23 * @addtogroup CAPI_MESSAGING_EMAIL_MODULE
30 * @ingroup CAPI_MESSAGING_EMAIL_MODULE
31 * @brief Messaging API file, support for sending email messages.
37 #include <email_types.h>
38 #include <email_error.h>
42 #endif /* __cplusplus */
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
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()
63 int email_create_message(email_h *email) TIZEN_DEPRECATED_API;
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()
79 int email_destroy_message(email_h email) TIZEN_DEPRECATED_API;
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
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()
100 int email_set_subject(email_h email, const char *subject) TIZEN_DEPRECATED_API;
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
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()
122 int email_set_body(email_h email, const char *body) TIZEN_DEPRECATED_API;
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()
145 int email_add_recipient(email_h email, email_recipient_type_e type, const char *address) TIZEN_DEPRECATED_API;
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()
161 int email_remove_all_recipients(email_h email) TIZEN_DEPRECATED_API;
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()
185 int email_add_attach(email_h email, const char *filepath) TIZEN_DEPRECATED_API;
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()
202 int email_remove_all_attachments(email_h email) TIZEN_DEPRECATED_API;
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
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()
224 int email_save_message(email_h email) TIZEN_DEPRECATED_API;
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()
246 int email_send_message(email_h email, bool save_to_sentbox) TIZEN_DEPRECATED_API;
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()
263 typedef void (*email_message_sent_cb)(email_h email, email_sending_e result, void *user_data);
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()
284 int email_set_message_sent_cb(email_h email, email_message_sent_cb callback, void *user_data) TIZEN_DEPRECATED_API;
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()
301 int email_unset_message_sent_cb(email_h msg) TIZEN_DEPRECATED_API;
314 #endif /* __MESSAGING_EMAIL_H__ */