Just update api description

[platform/core/api/media-content.git] / include_product / media_info.h

diff --git a/include_product/media_info.h b/include_product/media_info.h
index 6fb10f8..8918fa3 100755 (executable)
--- a/include_product/media_info.h
+++ b/include_product/media_info.h
@@ -56,10 +56,11 @@ extern "C" {
  *                   You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path. \n
  *                   If you want to access only internal storage by using this function, you should add privilege http://tizen.org/privilege/mediastorage. \n
  *                   Or if you want to access only external storage by using this function, you should add privilege http://tizen.org/privilege/externalstorage. \n
- *                   If you can access both storage, you must add all privilege.
+ *                   If you can access both storage, you must add all privilege. \n
+ *                   Since 4.0, This function does not allow a symbolic link. \n
  * @remarks Since 4.0, this function is related to the following feature:\n
  *              %http://tizen.org/feature/content.scanning.others\n
- *              If this feature is not suppported on the device, MEDIA_CONTENT_TYPE_OTHERS type file is not scanned.
+ *              If this feature is not supported on the device, MEDIA_CONTENT_TYPE_OTHERS type file is not scanned.
  *
  * @param[in] path The path of the content file to add
  * @param[out] info The handle of the inserted content file
@@ -99,10 +100,11 @@ int media_info_insert_to_db(const char *path, media_info_h *info);
  * @remarks You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path. \n
  *                   If you want to access only internal storage by using this function, you should add privilege http://tizen.org/privilege/mediastorage. \n
  *                   Or if you want to access only external storage by using this function, you should add privilege http://tizen.org/privilege/externalstorage. \n
- *                   If you can access both storage, you must add all privilege.
+ *                   If you can access both storage, you must add all privilege. \n
+ *                   Since 4.0, This function does not allow a symbolic link. \n
  * @remarks Since 4.0, this function is related to the following feature:\n
  *              %http://tizen.org/feature/content.scanning.others\n
- *              If this feature is not suppported on the device, MEDIA_CONTENT_TYPE_OTHERS type file is not scanned.
+ *              If this feature is not supported on the device, MEDIA_CONTENT_TYPE_OTHERS type file is not scanned.
  *
  * @param[in] path_array The path array of the content files to add
  * @param[in] array_length The length of the array
@@ -145,7 +147,8 @@ int media_info_insert_batch_to_db(const char **path_array, unsigned int array_le
  * @remarks You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path. \n
  *                   If you want to access only internal storage with this function, you should add privilege http://tizen.org/privilege/mediastorage. \n
  *                   Or if you want to access only external storage with this function, you should add privilege http://tizen.org/privilege/externalstorage. \n
- *                   If you can access both storage, you must add all privilege.
+ *                   If you can access both storage, you must add all privilege. \n
+ *                   Since 4.0, This function does not allow a symbolic link. \n
  *
  * @param[in] path_array The path array of the burst shot images to add
  * @param[in] array_length The length of the array
@@ -172,9 +175,10 @@ int media_info_insert_batch_to_db(const char **path_array, unsigned int array_le
 int media_info_insert_burst_shot_to_db(const char **path_array, unsigned int array_length, media_insert_burst_shot_completed_cb callback, void *user_data) TIZEN_DEPRECATED_API;
 
 /**
+ * @deprecated Deprecated since 5.0. Use media_content_scan_file() instead.
  * @brief Deletes the media information from the media database.
  * @details This function only remove media information in the media database. \n
- *               You can use media_content_scan_file()/media_content_scan_folder() function instead of this function if file is removed from the file system.
+ *               You can use media_content_scan_file()/media_content_scan_folder() function instead of this function if a file is removed from the file system.
  *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  *
@@ -200,7 +204,7 @@ int media_info_insert_burst_shot_to_db(const char **path_array, unsigned int arr
  * @see media_content_scan_file()
  * @see media_content_scan_folder()
  */
-int media_info_delete_from_db(const char *media_id);
+int media_info_delete_from_db(const char *media_id) TIZEN_DEPRECATED_API;
 
 /**
  * @deprecated Deprecated since 4.0.
@@ -236,7 +240,7 @@ int media_info_delete_batch_from_db(filter_h filter) TIZEN_DEPRECATED_API;
 /**
  * @brief Destroys media info.
  * @details The function frees all resources related to the media info handle. This handle
- *          can no longer be used to perform any operation. New media info handle has to
+ *          can no longer be used to perform any operations. New media info handle has to
  *          be created before the next usage.
  *
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
@@ -731,8 +735,9 @@ int media_info_get_timeline(media_info_h media, time_t *time);
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  *
  * @remarks The @a path should be released using free(). \n
- *                   If the thumbnail extraction for the given media has not been requested yet, this function returns NULL. To create a thumbnail, you should use media_info_create_thumbnail() function. \n
- *                   Since 3.0, this function returns an empty string if media_info_create_thumbnail() has failed to create a thumbnail for the given media.
+ *                   If the thumbnail extraction for the given media has not been requested yet, this function returns NULL. \n
+ *                   To create a thumbnail, you should use media_info_generate_thumbnail() function. \n
+ *                   This function returns an empty string if media_info_generate_thumbnail() has failed to create a thumbnail for the given media.
  *
  * @param[in] media The handle to the media info
  * @param[out] path The thumbnail path
@@ -1324,7 +1329,7 @@ int media_info_set_rating(media_info_h media, int rating) TIZEN_DEPRECATED_API;
 
 /**
  * @brief Sets the favorite of media info.
- * @details This function can mark favorite of the media. If set to @c true, this fuction record the time of the change moment. \n
+ * @details This function can mark favorite of the media. If set to @c true, this function record the time of the change moment. \n
  *                So, If you use it in order parameter, you can sort the order of the time was a favorite. \n
  *                Or, if you use it in condition parameter, you can get the result of the favorite media.
  *
@@ -1577,7 +1582,9 @@ int media_info_set_added_time(media_info_h media, time_t added_time) TIZEN_DEPRE
  *                   If you want to access only internal storage by using this function, you should add privilege http://tizen.org/privilege/mediastorage. \n
  *                   Or if you want to access only external storage by using this function, you should add privilege http://tizen.org/privilege/externalstorage. \n
  *                   If you can access both storage, you should add all privilege. \n
- *                   This function does not support USB storage.
+ *                   Since 4.0, this function does not allow symbolic links. \n
+ *                   This function does not support USB storage before 5.0. Since 5.0, USB storage is supported. \n
+ *                   Since 5.0, the thumbnail is removed if it exists.
  *
  * @param[in] media The handle to the media info
  * @param[in] dst_path The path of destination
@@ -1598,10 +1605,12 @@ int media_info_set_added_time(media_info_h media, time_t added_time) TIZEN_DEPRE
  *
  * @see media_content_connect()
  * @see media_content_scan_folder()
+ * @see media_info_generate_thumbnail()
  */
 int media_info_move_to_db(media_info_h media, const char* dst_path);
 
 /**
+ * @deprecated Deprecated since 5.0. Use media_info_generate_thumbnail() instead.
  * @brief Creates a thumbnail file for the given media, asynchronously.
  * @details This function creates an thumbnail file for given media item and calls @a callback for completion of creating the thumbnail.
  *          If a thumbnail already exists for the given media, then the path of thumbnail will be returned in callback function. \n
@@ -1639,9 +1648,10 @@ int media_info_move_to_db(media_info_h media, const char* dst_path);
  *
  * @see media_content_connect()
  */
-int media_info_create_thumbnail(media_info_h media, media_thumbnail_completed_cb callback, void *user_data);
+int media_info_create_thumbnail(media_info_h media, media_thumbnail_completed_cb callback, void *user_data) TIZEN_DEPRECATED_API;
 
 /**
+ * @deprecated Deprecated since 5.0.
  * @brief Cancels the creation of thumbnail file for the given media.
  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  *
@@ -1663,7 +1673,40 @@ int media_info_create_thumbnail(media_info_h media, media_thumbnail_completed_cb
  * @pre This function requires opened connection to content service by media_content_connect().
  * @see media_content_connect()
  */
-int media_info_cancel_thumbnail(media_info_h media);
+int media_info_cancel_thumbnail(media_info_h media) TIZEN_DEPRECATED_API;
+
+/**
+ * @brief Generates a thumbnail file for the given media, synchronously.
+ *
+ * @since_tizen 5.0
+ *
+ * @privlevel public
+ * @privilege %http://tizen.org/privilege/content.write
+ *
+ * @remarks http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage. \n
+ *          http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage. \n
+ *          Items in external storage are not supported, with the exception of MMC.
+ *
+ * @param[in] media The handle to the media info
+ *
+ * @return @c 0 on success,
+ *         otherwise a negative error value
+ *
+ * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
+ * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
+ * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
+ * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
+ * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
+ * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
+ * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
+ *
+ * @pre This function requires opened connection to content service by media_content_connect().
+ *
+ * @see media_content_connect()
+ * @see media_info_get_thumbnail_path()
+ */
+int media_info_generate_thumbnail(media_info_h media);
 
 /**
  * @ingroup CAPI_CONTENT_MEDIA_FACE_DETECTION_MODULE
@@ -1680,7 +1723,7 @@ int media_info_cancel_thumbnail(media_info_h media);
  *                   %http://tizen.org/privilege/externalstorage
  *
  * @remarks If you want to destroy the media handle before callback invoked, you must cancel the face detection request by using media_info_cancel_face_detection(). \n
- *          If face detection fails, the @a face_count argument in media_face_detection_completed_cb() will be set to 0.
+ *          If face detection fails, the face_count argument in media_face_detection_completed_cb() will be set to 0.
  *          Media items in external storage are not supported, with the exception of MMC items.
  *
  * @param[in] media The handle to the media info