tizen 2.3.1 releasetizen_2.3.1_releasesubmit/tizen_2.3.1/20150915.075731tizen_2.3.1

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__*/
 
+