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 the API for metadata of several popular audio formats and related structure and enumeration. \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 Not enough memory is available
  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 previlege 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(), metadata_editor_destroy()
  72  */
  73 int metadata_editor_set_path(metadata_editor_h metadata, const char *path);
  74
  75
  76 /**
  77  * @brief Gets the metadata corresponding to the attribute.
  78  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
  79  *
  80  * @remarks The @a value should be released using free(). \n
  81  *                   If the attribute value of the metadata is empty, return value is NULL. \n
  82  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
  83  *                   For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
  84  *
  85  * @param[in] metadata The handle to metadata
  86  * @param[in] attribute key attribute name to get
  87  * @param[out] value The value of the attribute
  88  * @return 0 on success, otherwise a negative error value
  89  * @retval #METADATA_EDITOR_ERROR_NONE Successful
  90  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
  91  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Not enough memory is available
  92  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
  93  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
  94  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
  95  * @see metadata_editor_create(), metadata_editor_destroy()
  96  */
  97 int metadata_editor_get_metadata(metadata_editor_h metadata, metadata_editor_attr_e attribute, char **value);
  98
  99
 100 /**
 101  * @brief Sets the attribute of the metadata.
 102  * @details This function set the attribute of the metadata for updating the metadata. \n
 103  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 104  *
 105  * @remarks The @a value should be released using free(). \n
 106  *                  You must call metadata_editor_update_metadata() for applying to the metadata of the media file. if not, you will see the existing metadata when you call metadata_editor_get_metadata().
 107  *
 108  * @param[in] metadata The handle to metadata
 109  * @param[in] attribute key attribute name to get
 110  * @param[in] value The value of the attribute
 111  * @return 0 on success, otherwise a negative error value
 112  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 113  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 114  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Not enough memory is available
 115  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 116  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 117  * @see metadata_editor_create(), metadata_editor_update_metadata(), metadata_editor_destroy()
 118  */
 119 int metadata_editor_set_metadata(metadata_editor_h metadata, metadata_editor_attr_e attribute, const char *value);
 120
 121
 122 /**
 123  * @brief Updates the modified metadata.
 124  * @details This function update the metadata in the media file that is modified by metadata_editor_set_metadata().
 125  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 126  *
 127  * @remarks In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
 128  *                   For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
 129  *
 130  * @param[in] metadata The handle to metadata
 131  * @return 0 on success, otherwise a negative error value
 132  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 133  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 134  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Not enough memory is available
 135  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
 136  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 137  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 138  * @see metadata_editor_create(), metadata_editor_destroy()
 139  */
 140 int metadata_editor_update_metadata(metadata_editor_h metadata);
 141
 142 /**
 143  * @brief Gets the picture in the media file.
 144  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 145  *
 146  * @remarks The @a picture abd @a mime_type should be released using free(). \n
 147  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
 148  *                   For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
 149  *
 150  * @param[in] metadata The handle to metadata
 151  * @param[in] index picture order
 152  * @param[out] picture encoded picture
 153  * @param[out] size encoded picture size
 154  * @param[out] mime_type the MIME of the picture
 155  * @return 0 on success, otherwise a negative error value
 156  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 157  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 158  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Not enough memory is available
 159  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 160  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
 161  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 162  * @see metadata_editor_create(), metadata_editor_destroy()
 163  */
 164 int metadata_editor_get_picture(metadata_editor_h metadata, int index, void **picture, int *size, char **mime_type);
 165
 166 /**
 167  * @brief Appends the picture to the media file.
 168  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 169  *
 170  * @remarks You must call metadata_editor_update_metadata() for applying to the metadata of the media file. if not, you will see the existing metadata when you call metadata_editor_get_metadata(). \n
 171  *                   Image type of the metadata supports jpeg and png. \n
 172  *                   In case of accessing specific path in internal storage or external storage, you may add the privilege for accessing the path. \n
 173  *                   For example, if you get the specific path by using storage_get_directory(). you should add previlege http://tizen.org/privilege/mediastorage or http://tizen.org/privilege/externalstorage.
 174  *
 175  * @param[in] metadata The handle to metadata
 176  * @param[in] picture_path The path of picture for adding to the metadata
 177  * @return 0 on success, otherwise a negative error value
 178  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 179  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 180  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Not enough memory is available
 181  * @retval #METADATA_EDITOR_ERROR_NOT_SUPPORTED unsupported file type
 182  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 183  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
 184  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 185  * @see metadata_editor_create(), metadata_editor_destroy()
 186  */
 187 int metadata_editor_append_picture(metadata_editor_h metadata, const char *picture_path);
 188
 189 /**
 190  * @brief Removes artwork image from media file.
 191  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 192  *
 193  * @remarks You must call metadata_editor_update_metadata() for applying to the metadata of the media file. if not, you will see the existing metadata when you call metadata_editor_get_metadata(). \n
 194  *
 195  * @param[in] metadata The handle to metadata
 196  * @param[in] index artwork image order
 197  * @return 0 on success, otherwise a negative error value
 198  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 199  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 200  * @retval #METADATA_EDITOR_ERROR_OUT_OF_MEMORY Not enough memory is available
 201  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 202  * @retval #METADATA_EDITOR_ERROR_PERMISSION_DENIED Permission denied
 203  * @pre Set path to read or write metadata by calling metadata_editor_set_path()
 204  * @see metadata_editor_create(), metadata_editor_destroy()
 205  */
 206 int metadata_editor_remove_picture(metadata_editor_h metadata, int index);
 207
 208 /**
 209  * @brief Destroys metadata.
 210  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 211  *
 212  * @param[in] metadata The handle to metadata
 213  * @return 0 on success, otherwise a negative error value
 214  * @retval #METADATA_EDITOR_ERROR_NONE Successful
 215  * @retval #METADATA_EDITOR_ERROR_INVALID_PARAMETER Invalid parameter
 216  * @retval #METADATA_EDITOR_ERROR_OPERATION_FAILED Internal Operation Fail
 217  * @pre Create metadata handle by calling metadata_editor_create()
 218  * @see metadata_editor_create()
 219  */
 220 int metadata_editor_destroy(metadata_editor_h metadata);
 221
 222 /**
 223  * @}
 224  */
 225
 226
 227 #ifdef __cplusplus
 228 }
 229 #endif /* __cplusplus */
 230
 231 #endif /* __TIZEN_MULTIMEDIA_METADATA_EDITOR_H__ */