* distributed under the License is distributed on an AS IS BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
- * limitations under the License.
+ * limitations under the License.
*/
#ifndef __MESSAGING_EMAIL_H__
/**
* @file email.h
- * @ingroup CAPI_MESSAGING_FRAMEWORK
+ * @ingroup CAPI_MESSAGING_EMAIL_MODULE
* @brief Messaging API file, support for sending email messages.
*/
/**
* @brief Creates an email message handle for sending an email message.
+ * @since_tizen 2.3
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/email
*
- * @remarks a email must be released with email_destroy_message() by you.
+ * @remarks You must release @a email using email_destroy_message().
*
- * @param[out] email A handle to the email message
+ * @param[out] email A handle to the email message
*
- * @return 0 on success, otherwise a negative error value.
- * @retval #EMAIL_ERROR_NONE Successful
- * @retval #EMAIL_ERROR_OUT_OF_MEMORY Out of memory
- * @retval #EMAIL_ERROR_ACCOUNT_NOT_FOUND Email account not found
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #EMAILS_ERROR_NONE Successful
+ * @retval #EMAILS_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #EMAILS_ERROR_ACCOUNT_NOT_FOUND Email account not found
+ *
+ * @pre At least one email account should be set up on the device.
*
* @see email_destroy_message()
*/
/**
* @brief Destroys the email message handle and releases all its resources.
+ * @since_tizen 2.3
+ *
+ * @param[in] email The handle to the email message
*
- * @param[in] email The handle to the email message
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @return 0 on success, otherwise a negative error value.
- * @retval #EMAIL_ERROR_NONE Successful
- * @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #EMAIL_ERROR_OPERATION_FAILED Operation failed
+ * @retval #EMAILS_ERROR_NONE Successful
+ * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #EMAILS_ERROR_OPERATION_FAILED Operation failed
*
* @see email_create_message()
*/
/**
* @brief Sets a subject of the email message.
+ * @since_tizen 2.3
+ *
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/email
+
+ * @param[in] email The handle to the email message
+ * @param[in] subject The subject of the email message
*
- * @param[in] email The handle to the email message
- * @param[in] subject The subject of the email message
- * @return 0 on success, otherwise a negative error value.
- * @retval #EMAIL_ERROR_NONE Successful
- * @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #EMAIL_ERROR_OUT_OF_MEMORY Out of memory
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @see email_create_message()
+ * @retval #EMAILS_ERROR_NONE Successful
+ * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #EMAILS_ERROR_OUT_OF_MEMORY Out of memory
+ *
+ * @pre An email message handle is created using email_create_message().
+ *
+ * @see email_create_message()
*/
int email_set_subject(email_h email, const char *subject);
* @brief Populates a body of the email message.
* @details Email message body means the text data to be delivered.
*
- * @param[in] email The handle to the email message
+ * @since_tizen 2.3
+ *
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/mediastorage
+ *
+ * @param[in] email The handle to the email message
* @param[in] body The message body
- * @return 0 on success, otherwise a negative error value.
- * @retval #EMAIL_ERROR_NONE Successful
- * @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval # EMAIL_ERROR_OPERATION_FAILED Operation failed
- * @pre An email message handle is created using #email_create_message().
- * @see email_create_message()
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #EMAILS_ERROR_NONE Successful
+ * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #EMAILS_ERROR_OPERATION_FAILED Operation failed
+ *
+ * @pre An email message handle is created using email_create_message().
+ *
+ * @see email_create_message()
*/
int email_set_body(email_h email, const char *body);
/**
* @brief Adds a recipient to the email message.
- * @details The email API supports sending an email message to multiple recipients.
+ * @details The email API supports sending an email message to multiple recipients.
+ *
+ * @since_tizen 2.3
*
* @remarks Email address should be in standard format (as described in
- * Internet standards RFC 5321 and RFC 5322).\n
+ * Internet standards RFC 5321 and RFC 5322).
*
- * @param[in] email The handle to the email message
+ * @param[in] email The handle to the email message
* @param[in] type The recipient type
* @param[in] address The recipient email address
*
- * @return 0 on success, otherwise a negative error value.
- * @retval #EMAIL_ERROR_NONE Successful
- * @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #EMAIL_ERROR_OUT_OF_MEMORY Out of memory
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #EMAILS_ERROR_NONE Successful
+ * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #EMAILS_ERROR_OUT_OF_MEMORY Out of memory
+ *
+ * @pre An email message handle is created using email_create_message().
*
* @see email_create_message()
* @see email_remove_all_recipients()
/**
* @brief Removes all recipients for the email message.
+ * @since_tizen 2.3
+ *
+ * @param[in] email The handle to the email message
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @param[in] email The handle to the email message
+ * @retval #EMAILS_ERROR_NONE Successful
+ * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
*
- * @return 0 on success, otherwise a negative error value.
- * @retval #EMAIL_ERROR_NONE Successful
- * @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
+ * @pre An email message handle is created using email_create_message().
*
* @see email_add_recipient()
*/
/**
* @brief Adds a file as an attachment to the email message.
* @details It should be used to add a file to the attachment list
- * of the email message.
+ * of the email message.
+ *
+ * @since_tizen 2.3
*
* @remarks The maximum attachment file size is 10MB.
*
- * @param[in] email The handle to the email message
+ * @param[in] email The handle to the email message
* @param[in] filepath The absolute full path of the file to be attached
*
- * @return 0 on success, otherwise a negative error value.
- * @retval #EMAIL_ERROR_NONE Successful
- * @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #EMAIL_ERROR_OUT_OF_MEMORY Out of memory
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #EMAILS_ERROR_NONE Successful
+ * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #EMAILS_ERROR_OUT_OF_MEMORY Out of memory
+ *
+ * @pre An email message handle is created using email_create_message().
*
* @see email_remove_all_attachments()
*
/**
* @brief Clears all attachments of the email message.
+ * @since_tizen 2.3
+ *
+ * @param[in] email The handle to the email message
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
*
- * @param[in] email The handle to the email message
+ * @retval #EMAILS_ERROR_NONE Successful
+ * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
*
- * @return 0 on success, otherwise a negative error value.
- * @retval #EMAIL_ERROR_NONE Successful
- * @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
+ * @pre An email message handle is created using email_create_message().
*
* @see email_create_message()
* @see email_add_attach()
int email_remove_all_attachments(email_h email);
/**
- * @brief Save the email message at outbox.
+ * @brief Saves the email message at outbox.
+ * @since_tizen 2.3
*
- * @remarks Get the id of mail.
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/email
*
+ * @remarks Get the ID of mail.
*
- * @param[in] email The handle to the email message
- * @return 0 on success, otherwise a negative error value.
- * @retval #EMAIL_ERROR_NONE Successful
- * @retval #EMAIL_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed.
- * @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
+ * @param[in] email The handle to the email message
+ *
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #EMAILS_ERROR_NONE Successful
+ * @retval #EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed.
+ * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @pre An email message handle is created using email_create_message().
*
* @see email_create_message()
* @see email_add_recipient()
/**
* @brief Sends the email message.
+ * @since_tizen 2.3
+ *
*
- * @remarks In order to check whether sending a message succeeds, \n you should register email_message_sent_cb() using #email_set_message_sent_cb().
+ * @remarks In order to check whether sending a message succeeds,
+ * you should register email_message_sent_cb() using email_set_message_sent_cb().
*
+ * @param[in] email The handle to the email message
+ * @param[in] save_to_sentbox Set to @c true to save the message in the sentbox,
+ * otherwise set to @c false to not save the message in the sentbox
*
- * @param[in] email The handle to the email message
- * @param[in] save_to_sentbox Set to true to save the message in the sentbox, else false
- * @return 0 on success, otherwise a negative error value.
- * @retval #EMAIL_ERROR_NONE Successful
- * @retval #EMAIL_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed.
- * @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #EMAILS_ERROR_NONE Successful
+ * @retval #EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILED Communication with server failed
+ * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @pre An email message is stored using email_save_message().
*
* @see email_save_message()
* @see email_set_message_sent_cb()
/**
* @brief Called when the process of sending an email finishes.
* @details You can check whether sending an email succeeds using this function.
- *
*
- * @param[in] email The handle to the email message
- * @param[in] result The result of email message sending\n
- * #EMAIL_SENDING_FAILED or #EMAIL_SENDING_SUCCEEDED
- * @param[in] user_data The user data passed from the callback registration function
+ * @since_tizen 2.3
+ *
+ * @param[in] email The handle to the email message
+ * @param[in] result The result of email message sending \n
+ * #EMAIL_SENDING_FAILED or #EMAIL_SENDING_SUCCEEDED
+ * @param[in] user_data The user data passed from the callback registration function
*
* @pre email_send_message() will invoke this callback if you register this callback using email_set_message_sent_cb().
*
* @see email_set_message_sent_cb()
* @see email_unset_message_sent_cb()
*/
-typedef void (* email_message_sent_cb)(email_h email, email_sending_e result, void *user_data);
+typedef void (*email_message_sent_cb)(email_h email, email_sending_e result, void *user_data);
/**
- * @brief Registers a callback function to be invoked when an email message is sent.
- * @details You will be notified when sending a message finishes and check whether it succeeds using this function.
+ * @brief Registers a callback function to be invoked when an email message is sent.
+ * @details You will be notified when sending a message finishes and check whether it succeeds using this function.
+ *
+ * @since_tizen 2.3
+ *
+ * @param[in] email The handle to the email message
+ * @param[in] callback The callback function to register
+ * @param[in] user_data The user data to be passed to the callback function
*
- * @param[in] email The handle to the email message
- * @param[in] callback The callback function to register
- * @param[in] user_data The user data to be passed to the callback function
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #EMAILS_ERROR_NONE Successful
+ * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
+ *
+ * @post It will invoke email_message_sent_cb().
*
- * @return 0 on success, otherwise a negative error value.
- * @retval #EMAIL_ERROR_NONE Successful
- * @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
- * @post It will invoke email_message_sent_cb().
* @see email_message_sent_cb()
* @see email_unset_message_sent_cb()
* @see email_send_message()
/**
* @brief Unregisters the callback function.
+ * @since_tizen 2.3
*
- * @param[in] email The handle to the email message
+ * @param[in] msg The handle to the email message
*
- * @return 0 on success, otherwise a negative error value.
- * @retval #EMAIL_ERROR_NONE Successful
- * @retval #EMAIL_ERROR_INVALID_PARAMETER Invalid parameter
+ * @return @c 0 on success,
+ * otherwise a negative error value
+ *
+ * @retval #EMAILS_ERROR_NONE Successful
+ * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter
*
* @see email_message_sent_cb()
* @see email_set_message_sent_cb()
*/
#endif /* __MESSAGING_EMAIL_H__ */
+
projects / platform / core / api / email.git / blobdiff