include/metadata_editor.h

   1 /*
   2 * Copyright (c) 2013 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   4 * Licensed under the Apache License, Version 2.0 (the "License");
   5 * you may not use this file except in compliance with the License.
   6 * You may obtain a copy of the License at
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  10 * Unless required by applicable law or agreed to in writing, software
  11 * distributed under the License is distributed on an "AS IS" BASIS,
  12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 * See the License for the specific language governing permissions and
  14 * limitations under the License.
  15 */
  16
  17 #ifndef __TIZEN_MULTIMEDIA_METADATA_EDITOR_H__
  18 #define __TIZEN_MULTIMEDIA_METADATA_EDITOR_H__
  19
  20
  21 #include <metadata_editor_type.h>
  22
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif /* __cplusplus */
  27
  28 /**
  29  * @addtogroup CAPI_MEDIA_METADATA_EDITOR_MODULE
  30  * @{
  31  *
  32  * @file metadata_editor.h
  33  * @brief This file contains functions for editing metadata of MP3 and MP4 files. \n
  34  *        Description of metadata: title, album, artist, author, genre and description etc. \n
  35  */
  36
  37
  38 /**
  39  * @brief Creates metadata.
  40  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  41  *
  42  * @remarks The @a metadata should be released using metadata_editor_destroy().
  43  *
  44  * @param[in] metadata The handle to metadata
  45  * @return 0 on success, otherwise a negative error value
  46  * @retval #METADATA_EDITOR_ERROR_NONE Successful
  47  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
  48  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
  49  * @see metadata_editor_destroy()
  50  */
  51 int metadata_editor_create(metadata_editor_h *metadata);
  52
  53
  54 /**
  55  * @brief Sets file path to read or write metadata.
  56  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  57  *
  58  * @remarks In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
  59  *                   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.
  60  *
  61  * @param[in] metadata The handle to metadata
  62  * @param[in] path path to read or write metadata
  63  * @return 0 on success, otherwise a negative error value
  64  * @retval #METADATA_EDITOR_ERROR_NONE Successful
  65  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
  66  * @retval #METADATA_EDITOR_ERROR_FILE_EXISTS File not exist
  67  * @retval #METADATA_EDITOR_ERROR_NOT_SUPPORTED unsupported file type
  68  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
  69  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
  70  * @pre Create metadata handle by calling metadata_editor_create()
  71  * @see metadata_editor_create()
  72  * @see metadata_editor_destroy()
  73  */
  74 int metadata_editor_set_path(metadata_editor_h metadata, const char *path);
  75
  76
  77 /**
  78  * @brief Gets the metadata corresponding to the attribute.
  79  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  80  *
  81  * @remarks The @a value should be released using free(). \n
  82  *                   If the attribute value of the metadata is empty, return value is NULL. \n
  83  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
  84  *                   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.
  85  *
  86  * @param[in] metadata The handle to metadata
  87  * @param[in] attribute key attribute name to get
  88  * @param[out] value The value of the attribute
  89  * @return 0 on success, otherwise a negative error value
  90  * @retval #METADATA_EDITOR_ERROR_NONE Successful
  91  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
  92  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
  93  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
  94  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
  95  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
  96  * @see metadata_editor_create()
  97  * @see metadata_editor_set_path()
  98  * @see metadata_editor_destroy()
  99  */
 100 int metadata_editor_get_metadata(metadata_editor_h metadata, metadata_editor_attr_e attribute, char **value);
 101
 102
 103 /**
 104  * @brief Sets the attribute of the metadata.
 105  * @details This function set the attribute of the metadata for updating the metadata. \n
 106  *            If @a attribute is #METADATA_EDITOR_ATTR_PICTURE_NUM, this function returns #METADATA_EDITOR_ERROR_INVALID_PARAMETER.
 107  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 108  *
 109  * @remarks The @a value should be released using free(). \n
 110  *                  You must call metadata_editor_update_metadata() to apply metadata changes to the media file. Otherwise, the previous metadata will be returned when you call metadata_editor_get_metadata().
 111  *
 112  * @param[in] metadata The handle to metadata
 113  * @param[in] attribute key attribute name to get
 114  * @param[in] value The value of the attribute
 115  * @return 0 on success, otherwise a negative error value
 116  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 117  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 118  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
 119  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 120  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 121  * @see metadata_editor_create()
 122  * @see metadata_editor_set_path()
 123  * @see metadata_editor_update_metadata()
 124  * @see metadata_editor_destroy()
 125  */
 126 int metadata_editor_set_metadata(metadata_editor_h metadata, metadata_editor_attr_e attribute, const char *value);
 127
 128
 129 /**
 130  * @brief Updates the modified metadata.
 131  * @details This function update the metadata in the media file that is modified by metadata_editor_set_metadata().
 132  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 133  *
 134  * @remarks In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
 135  *                   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.
 136  *
 137  * @param[in] metadata The handle to metadata
 138  * @return 0 on success, otherwise a negative error value
 139  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 140  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 141  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
 142  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
 143  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 144  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 145  * @see metadata_editor_create()
 146  * @see metadata_editor_set_path()
 147  * @see metadata_editor_destroy()
 148  */
 149 int metadata_editor_update_metadata(metadata_editor_h metadata);
 150
 151 /**
 152  * @brief Gets the picture in the media file.
 153  * @details If there is no picture or if the @a index is invalid, this function returns #METADATA_EDITOR_ERROR_INVALID_PARAMETER.\n
 154  *            You can get picture number by using metadata_editor_get_metadata() and index starts with 0.
 155  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 156  *
 157  * @remarks The @a picture and @a mime_type should be released using free(). \n
 158  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
 159  *                   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.
 160  *
 161  * @param[in] metadata The handle to metadata
 162  * @param[in] index picture order (starts with 0)
 163  * @param[out] picture encoded picture
 164  * @param[out] size encoded picture size
 165  * @param[out] mime_type the MIME of the picture
 166  * @return 0 on success, otherwise a negative error value
 167  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 168  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 169  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
 170  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 171  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
 172  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 173  * @see metadata_editor_create()
 174  * @see metadata_editor_set_path()
 175  * @see metadata_editor_destroy()
 176  */
 177 int metadata_editor_get_picture(metadata_editor_h metadata, int index, void **picture, int *size, char **mime_type);
 178
 179 /**
 180  * @brief Appends the picture to the media file.
 181  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 182  *
 183  * @remarks You must call metadata_editor_update_metadata() to apply metadata changes to the media file. Otherwise, the previous metadata will be returned when you call metadata_editor_get_metadata(). \n
 184  *                   Image type of the metadata supports jpeg and png. \n
 185  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
 186  *                   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.
 187  *
 188  * @param[in] metadata The handle to metadata
 189  * @param[in] picture_path The path of picture for adding to the metadata
 190  * @return 0 on success, otherwise a negative error value
 191  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 192  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 193  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
 194  * @retval #METADATA_EDITOR_ERROR_NOT_SUPPORTED unsupported file type
 195  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 196  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
 197  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 198  * @see metadata_editor_create()
 199  * @see metadata_editor_set_path()
 200  * @see metadata_editor_update_metadata()
 201  * @see metadata_editor_destroy()
 202  */
 203 int metadata_editor_append_picture(metadata_editor_h metadata, const char *picture_path);
 204
 205 /**
 206  * @brief Removes artwork image from media file.
 207  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 208  *
 209  * @remarks You must call metadata_editor_update_metadata() to apply metadata changes to the media file. Otherwise, the previous metadata will be returned when you call metadata_editor_get_metadata(). \n
 210  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
 211  *                   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.
 212  *
 213  * @param[in] metadata The handle to metadata
 214  * @param[in] index artwork image order
 215  * @return 0 on success, otherwise a negative error value
 216  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 217  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 218  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
 219  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 220  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
 221  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 222  * @see metadata_editor_create()
 223  * @see metadata_editor_set_path()
 224  * @see metadata_editor_update_metadata()
 225  * @see metadata_editor_destroy()
 226  */
 227 int metadata_editor_remove_picture(metadata_editor_h metadata, int index);
 228
 229 /**
 230  * @brief Destroys metadata.
 231  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 232  *
 233  * @param[in] metadata The handle to metadata
 234  * @return 0 on success, otherwise a negative error value
 235  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 236  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 237  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 238  * @pre Create metadata handle by calling metadata_editor_create()
 239  * @see metadata_editor_create()
 240  */
 241 int metadata_editor_destroy(metadata_editor_h metadata);
 242
 243 /**
 244  * @}
 245  */
 246
 247
 248 #ifdef __cplusplus
 249 }
 250 #endif /* __cplusplus */
 251
 252 #endif /* __TIZEN_MULTIMEDIA_METADATA_EDITOR_H__ */