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  *        Since 6.0, this module supports WAV, FLAC and OGG files as well.
  35  *        Description of metadata: title, album, artist, author, genre and description etc. \n
  36  */
  37
  38
  39 /**
  40  * @brief Creates metadata.
  41  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  42  *
  43  * @remarks The @a metadata should be released using metadata_editor_destroy().
  44  *
  45  * @param[in] metadata The handle to metadata
  46  * @return 0 on success, otherwise a negative error value
  47  * @retval #METADATA_EDITOR_ERROR_NONE Successful
  48  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
  49  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
  50  * @see metadata_editor_destroy()
  51  */
  52 int metadata_editor_create(metadata_editor_h *metadata);
  53
  54
  55 /**
  56  * @brief Sets file path to read or write metadata.
  57  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  58  *
  59  * @remarks In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
  60  *                   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.
  61  *
  62  * @param[in] metadata The handle to metadata
  63  * @param[in] path path to read or write metadata
  64  * @return 0 on success, otherwise a negative error value
  65  * @retval #METADATA_EDITOR_ERROR_NONE Successful
  66  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
  67  * @retval #METADATA_EDITOR_ERROR_FILE_EXISTS File not exist
  68  * @retval #METADATA_EDITOR_ERROR_NOT_SUPPORTED unsupported file type
  69  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
  70  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
  71  * @pre Create metadata handle by calling metadata_editor_create()
  72  * @see metadata_editor_create()
  73  * @see metadata_editor_destroy()
  74  */
  75 int metadata_editor_set_path(metadata_editor_h metadata, const char *path);
  76
  77
  78 /**
  79  * @brief Gets the metadata corresponding to the attribute.
  80  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  81  *
  82  * @remarks The @a value should be released using free(). \n
  83  *                   If the attribute value of the metadata is empty, return value is NULL. \n
  84  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
  85  *                   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.
  86  *
  87  * @param[in] metadata The handle to metadata
  88  * @param[in] attribute key attribute name to get
  89  * @param[out] value The value of the attribute
  90  * @return 0 on success, otherwise a negative error value
  91  * @retval #METADATA_EDITOR_ERROR_NONE Successful
  92  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
  93  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
  94  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
  95  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
  96  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
  97  * @see metadata_editor_create()
  98  * @see metadata_editor_set_path()
  99  * @see metadata_editor_destroy()
 100  */
 101 int metadata_editor_get_metadata(metadata_editor_h metadata, metadata_editor_attr_e attribute, char **value);
 102
 103
 104 /**
 105  * @brief Sets the attribute of the metadata.
 106  * @details This function set the attribute of the metadata for updating the metadata. \n
 107  *            If @a attribute is #METADATA_EDITOR_ATTR_PICTURE_NUM, this function returns #METADATA_EDITOR_ERROR_INVALID_PARAMETER.
 108  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 109  *
 110  * @remarks The @a value should be released using free(). \n
 111  *               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().
 112  *               This function doesn't support updating metadata of an invalid media file.
 113  *               Before 6.0, this function returned #METADATA_EDITOR_ERROR_OPERATION_FAILED. Since 6.0, #METADATA_EDITOR_ERROR_METADATA_UPDATE_NOT_POSSIBLE is returned in such cases.
 114  *
 115  * @param[in] metadata The handle to metadata
 116  * @param[in] attribute key attribute name to get
 117  * @param[in] value The value of the attribute
 118  * @return 0 on success, otherwise a negative error value
 119  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 120  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 121  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
 122  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 123  * @retval #METADATA_EDITOR_ERROR_METADATA_UPDATE_NOT_POSSIBLE Update not possible
 124  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 125  * @see metadata_editor_create()
 126  * @see metadata_editor_set_path()
 127  * @see metadata_editor_update_metadata()
 128  * @see metadata_editor_destroy()
 129  */
 130 int metadata_editor_set_metadata(metadata_editor_h metadata, metadata_editor_attr_e attribute, const char *value);
 131
 132
 133 /**
 134  * @brief Updates the modified metadata.
 135  * @details This function update the metadata in the media file that is modified by metadata_editor_set_metadata().
 136  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 137  *
 138  * @remarks In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
 139  *                   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.
 140  *
 141  * @param[in] metadata The handle to metadata
 142  * @return 0 on success, otherwise a negative error value
 143  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 144  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 145  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
 146  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
 147  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 148  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 149  * @see metadata_editor_create()
 150  * @see metadata_editor_set_path()
 151  * @see metadata_editor_destroy()
 152  */
 153 int metadata_editor_update_metadata(metadata_editor_h metadata);
 154
 155 /**
 156  * @brief Gets the picture in the media file.
 157  * @details If there is no picture or if the @a index is invalid, this function returns #METADATA_EDITOR_ERROR_INVALID_PARAMETER.\n
 158  *            You can get picture number by using metadata_editor_get_metadata() and index starts with 0.
 159  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 160  *
 161  * @remarks The @a picture and @a mime_type should be released using free(). \n
 162  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
 163  *                   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.
 164  *
 165  * @param[in] metadata The handle to metadata
 166  * @param[in] index picture order (starts with 0)
 167  * @param[out] picture encoded picture
 168  * @param[out] size encoded picture size
 169  * @param[out] mime_type the MIME of the picture
 170  * @return 0 on success, otherwise a negative error value
 171  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 172  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 173  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
 174  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 175  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
 176  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 177  * @see metadata_editor_create()
 178  * @see metadata_editor_set_path()
 179  * @see metadata_editor_destroy()
 180  */
 181 int metadata_editor_get_picture(metadata_editor_h metadata, int index, void **picture, int *size, char **mime_type);
 182
 183 /**
 184  * @brief Appends the picture to the media file.
 185  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 186  *
 187  * @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
 188  *                   Image type of the metadata supports jpeg and png. \n
 189  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
 190  *                   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.
 191  *                   This function doesn't support updating metadata of an invalid media file.
 192  *                   Before 6.0, this function returned #METADATA_EDITOR_ERROR_OPERATION_FAILED. Since 6.0, #METADATA_EDITOR_ERROR_METADATA_UPDATE_NOT_POSSIBLE is returned in such cases.
 193  *
 194  * @param[in] metadata The handle to metadata
 195  * @param[in] picture_path The path of picture for adding to the metadata
 196  * @return 0 on success, otherwise a negative error value
 197  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 198  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 199  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
 200  * @retval #METADATA_EDITOR_ERROR_NOT_SUPPORTED unsupported file type
 201  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 202  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
 203  * @retval #METADATA_EDITOR_ERROR_METADATA_UPDATE_NOT_POSSIBLE Update not possible
 204  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 205  * @see metadata_editor_create()
 206  * @see metadata_editor_set_path()
 207  * @see metadata_editor_update_metadata()
 208  * @see metadata_editor_destroy()
 209  */
 210 int metadata_editor_append_picture(metadata_editor_h metadata, const char *picture_path);
 211
 212 /**
 213  * @brief Removes artwork image from media file.
 214  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 215  *
 216  * @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
 217  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
 218  *                   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.
 219  *
 220  * @param[in] metadata The handle to metadata
 221  * @param[in] index artwork image order
 222  * @return 0 on success, otherwise a negative error value
 223  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 224  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 225  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Out of memory
 226  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 227  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
 228  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 229  * @see metadata_editor_create()
 230  * @see metadata_editor_set_path()
 231  * @see metadata_editor_update_metadata()
 232  * @see metadata_editor_destroy()
 233  */
 234 int metadata_editor_remove_picture(metadata_editor_h metadata, int index);
 235
 236 /**
 237  * @brief Destroys metadata.
 238  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 239  *
 240  * @param[in] metadata The handle to metadata
 241  * @return 0 on success, otherwise a negative error value
 242  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 243  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 244  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 245  * @pre Create metadata handle by calling metadata_editor_create()
 246  * @see metadata_editor_create()
 247  */
 248 int metadata_editor_destroy(metadata_editor_h metadata);
 249
 250 /**
 251  * @}
 252  */
 253
 254
 255 #ifdef __cplusplus
 256 }
 257 #endif /* __cplusplus */
 258
 259 #endif /* __TIZEN_MULTIMEDIA_METADATA_EDITOR_H__ */