diff options
author | jk7744.park <jk7744.park@samsung.com> | 2015-09-08 22:09:23 +0900 |
---|---|---|
committer | jk7744.park <jk7744.park@samsung.com> | 2015-09-08 22:09:23 +0900 |
commit | be65e40bf1e0825e2fd36e76f21e2e0100e7129c (patch) | |
tree | ba76c4d745d161ed090ba29dd506c8a89e2888dc /include | |
parent | 936b87081ce4285c8825c08a7b009ab5b0559c2c (diff) | |
download | email-be65e40bf1e0825e2fd36e76f21e2e0100e7129c.tar.gz email-be65e40bf1e0825e2fd36e76f21e2e0100e7129c.tar.bz2 email-be65e40bf1e0825e2fd36e76f21e2e0100e7129c.zip |
tizen 2.3.1 releasetizen_2.3.1_releasesubmit/tizen_2.3.1/20150915.075731tizen_2.3.1
Diffstat (limited to 'include')
-rwxr-xr-x | include/email.h | 237 | ||||
-rwxr-xr-x | include/email_error.h | 26 | ||||
-rwxr-xr-x | include/email_private.h | 2 | ||||
-rwxr-xr-x | include/email_types.h | 22 |
4 files changed, 193 insertions, 94 deletions
diff --git a/include/email.h b/include/email.h index 96d35a3..fa6164d 100755 --- a/include/email.h +++ b/include/email.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved + * Copyright (c) 2012 - 2013 Samsung Electronics Co., Ltd All Rights Reserved * * Licensed under the Apache License, Version 2.0 (the License); * you may not use this file except in compliance with the License. @@ -24,7 +24,7 @@ /** * @file email.h - * @ingroup CAPI_MESSAGING_FRAMEWORK + * @ingroup CAPI_MESSAGING_EMAIL_MODULE * @brief Messaging API file, support for sending email messages. */ @@ -40,15 +40,22 @@ extern "C" /** * @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() */ @@ -56,13 +63,16 @@ int email_create_message(email_h *email); /** * @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() */ @@ -70,15 +80,21 @@ int email_destroy_message(email_h email); /** * @brief Sets a subject of the email message. + * @since_tizen 2.3 + * + * @param[in] email The handle to the email message + * @param[in] subject The subject of the email 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_OUT_OF_MEMORY Out of memory * - * @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 + * @pre An email message handle is created using email_create_message(). * - * @see email_create_message() + * @see email_create_message() */ int email_set_subject(email_h email, const char *subject); @@ -86,14 +102,21 @@ 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 + * + * @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); @@ -101,17 +124,23 @@ 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. * + * @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() @@ -120,12 +149,17 @@ int email_add_recipient(email_h email, email_recipient_type_e type, const char * /** * @brief Removes all recipients for the email message. + * @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 #EMAILS_ERROR_NONE Successful + * @retval #EMAILS_ERROR_INVALID_PARAMETER Invalid parameter + * + * @pre An email message handle is created using email_create_message(). * * @see email_add_recipient() */ @@ -134,17 +168,23 @@ int email_remove_all_recipients(email_h email); /** * @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() * @@ -153,12 +193,17 @@ int email_add_attach(email_h email, const char *filepath); /** * @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() @@ -166,21 +211,58 @@ int email_add_attach(email_h email, const char *filepath); int email_remove_all_attachments(email_h email); /** - * @brief Sends the email message. + * @brief Saves the email message at outbox. + * @since_tizen 2.3 + * + * @privlevel public + * @privilege %http://tizen.org/privilege/email * - * @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 Get the ID of mail. * + * @param[in] email The handle to the email message * - * @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 handle is created using email_create_message(). * * @see email_create_message() - * @see email_set_message_sent_cb() * @see email_add_recipient() + * @see email_set_body() + * @see email_save_message + */ +int email_save_message(email_h email); + + +/** + * @brief Sends the email message. + * @since_tizen 2.3 + * + * @privlevel public + * @privilege %http://tizen.org/privilege/email + * + * @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 + * + * @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() */ int email_send_message(email_h email, bool save_to_sentbox); @@ -188,12 +270,13 @@ int email_send_message(email_h email, bool save_to_sentbox); /** * @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(). * @@ -207,14 +290,20 @@ typedef void (* email_message_sent_cb)(email_h email, email_sending_e result, vo * @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. * - * @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 + * @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 + * + * @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() @@ -223,12 +312,15 @@ int email_set_message_sent_cb(email_h email, email_message_sent_cb callback, voi /** * @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() @@ -245,3 +337,4 @@ int email_unset_message_sent_cb(email_h msg); */ #endif /* __MESSAGING_EMAIL_H__ */ + diff --git a/include/email_error.h b/include/email_error.h index 157886d..88a5fea 100755 --- a/include/email_error.h +++ b/include/email_error.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved + * Copyright (c) 2012 - 2013 Samsung Electronics Co., Ltd All Rights Reserved * * Licensed under the Apache License, Version 2.0 (the License); * you may not use this file except in compliance with the License. @@ -35,21 +35,22 @@ extern "C" * @brief Email error definitions. */ - /** - * @brief Enumerations of error codes for email API. + * @brief Enumeration for error codes for email API. + * @since_tizen 2.3 */ typedef enum { - EMAIL_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ - EMAIL_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Memory cannot be allocated */ - EMAIL_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ - - EMAIL_ERROR_SERVER_NOT_READY = TIZEN_ERROR_MESSAGING_CLASS|0x200, /**< Server not ready */ - EMAIL_ERROR_COMMUNICATION_WITH_SERVER_FAILED = TIZEN_ERROR_MESSAGING_CLASS|0x201, /**< Communication with server failed */ - EMAIL_ERROR_OPERATION_FAILED = TIZEN_ERROR_MESSAGING_CLASS|0x202, /**< Operation failed */ - EMAIL_ERROR_ACCOUNT_NOT_FOUND = TIZEN_ERROR_MESSAGING_CLASS|0x203, /**< Email account not found */ - EMAIL_ERROR_DB_FAILED = TIZEN_ERROR_MESSAGING_CLASS|0x204, /**< Email database failed */ + EMAILS_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ + EMAILS_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Memory cannot be allocated */ + EMAILS_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ + + EMAILS_ERROR_SERVER_NOT_READY = TIZEN_ERROR_EMAIL_SERVICE|0x200, /**< Server not ready */ + EMAILS_ERROR_COMMUNICATION_WITH_SERVER_FAILED = TIZEN_ERROR_EMAIL_SERVICE|0x201, /**< Communication with server failed */ + EMAILS_ERROR_OPERATION_FAILED = TIZEN_ERROR_EMAIL_SERVICE|0x202, /**< Operation failed */ + EMAILS_ERROR_ACCOUNT_NOT_FOUND = TIZEN_ERROR_EMAIL_SERVICE|0x203, /**< Email account not found */ + EMAILS_ERROR_DB_FAILED = TIZEN_ERROR_EMAIL_SERVICE|0x204, /**< Email database failed */ + EMAILS_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */ } email_error_e; /** @@ -61,3 +62,4 @@ typedef enum #endif #endif /* __EMAILAPI_ERROR_H__*/ + diff --git a/include/email_private.h b/include/email_private.h index ae22bd8..c4bd56b 100755 --- a/include/email_private.h +++ b/include/email_private.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved + * Copyright (c) 2012 - 2013 Samsung Electronics Co., Ltd All Rights Reserved * * Licensed under the Apache License, Version 2.0 (the License); * you may not use this file except in compliance with the License. diff --git a/include/email_types.h b/include/email_types.h index 95f79d7..337ac34 100755 --- a/include/email_types.h +++ b/include/email_types.h @@ -1,5 +1,5 @@ /* - * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved + * Copyright (c) 2012 - 2013 Samsung Electronics Co., Ltd All Rights Reserved * * Licensed under the Apache License, Version 2.0 (the License); * you may not use this file except in compliance with the License. @@ -31,35 +31,38 @@ extern "C" /** * @file email_types.h - * @ingroup CAPI_MESSAGING_FRAMEWORK + * @ingroup CAPI_MESSAGING_EMAIL_MODULE * @brief This file defines common types and enums of EMAIL. */ /** - * @brief Email message handle type. + * @brief The email message handle. + * @since_tizen 2.3 */ typedef struct email_s *email_h; /** - * @brief Enumerations for the result values of email transport. + * @brief Enumeration for the result values of email transport. + * @since_tizen 2.3 */ typedef enum { - EMAIL_SENDING_FAILED = -1, /**< Email sending failed */ - EMAIL_SENDING_SUCCEEDED = 0, /**< Email sending succeeded */ + EMAIL_SENDING_FAILED = -1, /**< Email sending failed */ + EMAIL_SENDING_SUCCEEDED = 0, /**< Email sending succeeded */ } email_sending_e; /** - * @brief Enumerations of the email recipient types. + * @brief Enumeration for the email recipient types. + * @since_tizen 2.3 */ typedef enum { EMAIL_RECIPIENT_TYPE_TO = 1, /**< Normal recipient */ - EMAIL_RECIPIENT_TYPE_CC , /**< CC(carbon copy) recipient */ - EMAIL_RECIPIENT_TYPE_BCC , /**< BCC(blind carbon copy) recipient */ + EMAIL_RECIPIENT_TYPE_CC , /**< CC(carbon copy) recipient */ + EMAIL_RECIPIENT_TYPE_BCC , /**< BCC(blind carbon copy) recipient */ } email_recipient_type_e; @@ -72,3 +75,4 @@ typedef enum #endif /* __TIZEN_EMAIL_TYPES_H__*/ + |