* limitations under the License.
*/
-#ifndef __TIZEN_MEDIA_METADATA_EXTRACTOR_H__
-#define __TIZEN_MEDIA_METADATA_EXTRACTOR_H__
+#ifndef __TIZEN_MULTIMEDIA_METADATA_EXTRACTOR_H__
+#define __TIZEN_MULTIMEDIA_METADATA_EXTRACTOR_H__
#include <tizen.h>
#endif /* __cplusplus */
/**
- * @addtogroup CAPI_METADATA_EXTRACTOR_MODULE
- * @{
- *
* @file metadata_extractor.h
- * @brief This file contains the multimedia content metadata extractor API and related structure and enumeration. \n
- * Description of metadata: duration, bitrate, album, artist, author, genre and description etc. \n
+ * @brief This file contains the multimedia content metadata extractor API and related structure and enumeration.
+ * It also contains the description of metadata: duration, bitrate, album, artist, author, genre, description, and so on.
*/
+/**
+ * @addtogroup CAPI_METADATA_EXTRACTOR_MODULE
+ * @{
+ */
/**
- * @brief Create metadata
+ * @brief Creates metadata.
+ * @since_tizen 2.3
+ * @remarks The @a metadata should be released using metadata_extractor_destroy().
*
- * @remarks @a metadata must be released metadata_extractor_destroy() by you
+ * @param[in] metadata The handle to metadata
*
- * @param [in] metadata The handle to metadata
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
* @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
+ * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Out of memory
+ *
* @see metadata_extractor_destroy()
*/
int metadata_extractor_create(metadata_extractor_h *metadata);
-
/**
- * @brief Set file path to extract
+ * @brief Sets the file path to extract.
+ * @since_tizen 2.3
+ *
+ * @param[in] metadata The handle to metadata
+ * @param[in] path The path to extract metadata
*
- * @param [in] metadata The handle to metadata
- * @param [in] path path to extract metadata
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
* @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #METADATA_EXTRACTOR_ERROR_FILE_EXISTS File not exist
- * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal Operation Fail
- * @pre Create metadata handle by calling metadata_extractor_create()
- * @see metadata_extractor_create(), metadata_extractor_destroy()
+ * @retval #METADATA_EXTRACTOR_ERROR_FILE_EXISTS File does not exist
+ * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
+ *
+ * @pre Create a metadata handle by calling metadata_extractor_create().
+ * @see metadata_extractor_create()
+ * @see metadata_extractor_destroy()
*/
int metadata_extractor_set_path(metadata_extractor_h metadata, const char *path);
+/**
+ * @brief Sets the buffer to extract.
+ * @since_tizen 2.3
+ *
+ * @param[in] metadata The handle to metadata
+ * @param[in] buffer The buffer to extract metadata
+ * @param[in] size The buffer size
+ *
+ * @return @c 0 on success, otherwise a negative error value
+ * @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
+ * @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
+ * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
+ *
+ * @pre Create a metadata handle by calling metadata_extractor_create().
+ * @see metadata_extractor_create()
+ * @see metadata_extractor_destroy()
+ */
+int metadata_extractor_set_buffer(metadata_extractor_h metadata, const void *buffer, int size);
/**
- * @brief Destroy metadata
+ * @brief Destroys metadata.
+ * @since_tizen 2.3
+ *
+ * @param[in] metadata The handle to metadata
*
- * @param [in] metadata The handle to metadata
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
* @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal Operation Fail
- * @pre Create metadata handle by calling metadata_extractor_create()
+ * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
+*
+ * @pre Create a metadata handle by calling metadata_extractor_create().
* @see metadata_extractor_create()
*/
int metadata_extractor_destroy(metadata_extractor_h metadata);
-
/**
- * @brief Get metadata
+ * @brief Gets metadata.
+ * @since_tizen 2.3
+ *
+ * @remarks The @a value should be released using free(). \n
+ * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
+ * For example, if you get the specific path by using storage_get_directory(). you should add privilege %http://tizen.org/privilege/mediastorage or %http://tizen.org/privilege/externalstorage.
*
- * @remarks @a value must be released with @c free() by you
+ * @param[in] metadata The handle to metadata
+ * @param[in] attribute The key attribute name to get
+ * @param[out] value The value of the attribute
*
- * @param [in] metadata The handle to metadata
- * @param [in] attribute key attribute name to get
- * @param [out] value The value of the attribute
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
* @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
- * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal Operation Fail
- * @pre Set path to extract by calling metadata_extractor_set_path()
- * @see metadata_extractor_create(), metadata_extractor_destroy()
+ * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
+ * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
+ *
+ * @pre Set the path to extract by calling metadata_extractor_set_path().
+ * @see metadata_extractor_create()
+ * @see metadata_extractor_destroy()
*/
int metadata_extractor_get_metadata(metadata_extractor_h metadata, metadata_extractor_attr_e attribute, char **value);
-
/**
- * @brief Get artwork image in media file
+ * @brief Gets the artwork image in a media file.
+ * @since_tizen 2.3
*
- * @remarks @a artwork and @a artwork_mime must be released with @c free() by you
+ * @remarks The @a artwork and @a mime_type should be released using free(). \n
+ * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
+ * For example, if you get the specific path by using storage_get_directory(). you should add privilege %http://tizen.org/privilege/mediastorage or %http://tizen.org/privilege/externalstorage.
+ *
+ * @param[in] metadata The handle to metadata
+ * @param[out] artwork The encoded artwork image
+ * @param[out] size The encoded artwork size
+ * @param[out] mime_type The MIME of the artwork
+ * @return @c 0 on success, otherwise a negative error value
*
- * @param [in] metadata The handle to metadata
- * @param [out] artwork encoded artwork image
- * @param [out] size encoded artwork size
- * @param [out] mime_type mime type of artwork
- * @return 0 on success, otherwise a negative error value
* @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
* @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
- * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal Operation Fail
- * @pre Set path to extract by calling metadata_extractor_set_path()
- * @see metadata_extractor_create(), metadata_extractor_destroy()
+ * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
+ * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
+ *
+ * @pre Set the path to extract by calling metadata_extractor_set_path().
+ * @see metadata_extractor_create()
+ * @see metadata_extractor_destroy()
*/
int metadata_extractor_get_artwork(metadata_extractor_h metadata, void **artwork, int *size, char **mime_type);
-
/**
- * @brief Get frame of video media file
+ * @brief Gets the frame of a video media file.
+ * @since_tizen 2.3
+ *
+ * @remarks The @a frame should be released using free().
+ * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
+ * For example, if you get the specific path by using storage_get_directory(). you should add privilege %http://tizen.org/privilege/mediastorage or %http://tizen.org/privilege/externalstorage.
*
- * @remarks @a frame must be released with @c free() by you
+ * @param[in] metadata The handle to metadata
+ * @param[out] frame The raw frame data in RGB888
+ * @param[out] size The frame data size
*
- * @param [in] metadata The handle to metadata
- * @param [out] frame raw frame data in RGB888
- * @param [out] size The frame data size
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
* @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
- * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal Operation Fail
- * @pre Set path to extract by calling metadata_extractor_set_path()
- * @see metadata_extractor_create(), metadata_extractor_destroy()
+ * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
+ * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
+ *
+ * @pre Set the path to extract by calling metadata_extractor_set_path().
+ * @see metadata_extractor_create()
+ * @see metadata_extractor_destroy()
*/
int metadata_extractor_get_frame(metadata_extractor_h metadata, void **frame, int *size);
-
/**
- * @brief Get synclyric of media file
+ * @brief Gets the synclyrics of a media file.
+ * @since_tizen 2.3
+ *
+ * @remarks The @a lyrics should be released using free().
+ * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
+ * For example, if you get the specific path by using storage_get_directory(). you should add privilege %http://tizen.org/privilege/mediastorage or %http://tizen.org/privilege/externalstorage.
*
- * @remarks @a lyrics must be released with @c free() by you
+ * @param[in] metadata The handle to metadata
+ * @param[in] index The index of time/lyrics to set
+ * @param[out] time_stamp The time information of the index
+ * @param[out] lyrics The lyrics of the index
*
- * @param [in] metadata The handle to metadata
- * @param [in] index Index of time/lyrics set
- * @param [out] time_info Time information of index
- * @param [out] lyrics Lyric of index
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
* @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal Operation Fail
- * @pre Set path to extract by calling metadata_extractor_set_path()
- * @pre Get time/lyrics set number by calling metadata_extractor_get_metadata(METADATA_SYNCLYRICS_NUM)
- * @see metadata_extractor_create(), metadata_extractor_destroy()
+ * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
+ * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
+ *
+ * @pre Set the path to extract by calling metadata_extractor_set_path().
+ * @pre Get the time/lyrics set number by calling metadata_extractor_get_metadata(METADATA_SYNCLYRICS_NUM).
+ * @see metadata_extractor_create()
+ * @see metadata_extractor_destroy()
*/
int metadata_extractor_get_synclyrics(metadata_extractor_h metadata, int index, unsigned long *time_stamp, char **lyrics);
/**
- * @brief Get a frame of video media
+ * @brief Gets the frame of a video media.
+ * @since_tizen 2.3
+ *
+ * @remarks The @a frame should be released using free().
+ * In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
+ * For example, if you get the specific path by using storage_get_directory(). you should add privilege %http://tizen.org/privilege/mediastorage or %http://tizen.org/privilege/externalstorage.
*
- * @remarks @a frame must be released with @c free() by you
+ * @param[in] metadata The handle to metadata
+ * @param[in] timestamp The timestamp in milliseconds
+ * @param[in] is_accurate If @c true the user can get an accurate frame for the given timestamp,\n
+ * otherwise @c false if the user can only get the nearest i-frame of the video rapidly
+ * @param[out] frame The raw frame data in RGB888
+ * @param[out] size The frame data size
*
- * @param [in] metadata The handle to metadata
- * @param [in] timestamp The timestamp in milliseconds
- * @param [in] is_accurate @a true, user can get an accurated frame for given the timestamp.\n
- * @a false, user can only get the nearest i-frame of video rapidly.
- * @param [out] frame raw frame data in RGB888
- * @param [out] size The frame data size
- * @return 0 on success, otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
* @retval #METADATA_EXTRACTOR_ERROR_NONE Successful
* @retval #METADATA_EXTRACTOR_ERROR_INVALID_PARAMETER Invalid parameter
- * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Not enough memory is available
- * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal Operation Fail
- * @pre Set path to extract by calling metadata_extractor_set_path()
- * @see metadata_extractor_create(), metadata_extractor_destroy()
+ * @retval #METADATA_EXTRACTOR_ERROR_OUT_OF_MEMORY Out of memory
+ * @retval #METADATA_EXTRACTOR_ERROR_OPERATION_FAILED Internal operation failed
+ * @retval #METADATA_EXTRACTOR_ERROR_PERMISSION_DENIED Permission denied
+ *
+ * @pre Set the path to extract by calling metadata_extractor_set_path().
+ * @see metadata_extractor_create()
+ * @see metadata_extractor_destroy()
*/
-
int metadata_extractor_get_frame_at_time(metadata_extractor_h metadata, unsigned long timestamp, bool is_accurate, void **frame, int *size);
/**
}
#endif /* __cplusplus */
-#endif /* __TIZEN_MEDIA_METADATA_EXTRACTOR_H__ */
-
-
+#endif /* __TIZEN_MULTIMEDIA_METADATA_EXTRACTOR_H__ */
projects / platform / core / api / metadata-extractor.git / blobdiff