include/media_content.h

   1 /*
   2 * Copyright (c) 2011 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_MEDIA_CONTENT_H__
  18 #define __TIZEN_MEDIA_CONTENT_H__
  19
  20 #include <media_audio.h>
  21 #include <media_content_type.h>
  22 #include <media_filter.h>
  23 #include <media_folder.h>
  24 #include <media_image.h>
  25 #include <media_info.h>
  26 #include <media_tag.h>
  27 #include <media_video.h>
  28 #include <media_group.h>
  29 #include <media_playlist.h>
  30 #include <media_bookmark.h>
  31 #include <media_storage.h>
  32 #include <media_face.h>
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif /* __cplusplus */
  37
  38 /**
  39  * @file media_content.h
  40  * @brief This file contains API providing functions for media content in DB. \n
  41  *        Operations include connect and disconnect the media content service, scanning media file and folder with subfolders, \n
  42  *        subscribing and unsubscribing notifications of media DB change.
  43  */
  44
  45 /**
  46  * @addtogroup CAPI_MEDIA_CONTENT_MODULE
  47  * @{
  48  */
  49
  50 /**
  51  * @brief Connects to the media content service.
  52  * @details Any media content related function call should be invoked after this function call.
  53  *
  54  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  55  *
  56  * @return @c 0 on success,
  57  *         otherwise a negative error value
  58  *
  59  * @retval #MEDIA_CONTENT_ERROR_NONE      Successful
  60  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
  61  *
  62  * @post media_content_disconnect()
  63  *
  64  * @see media_content_disconnect()
  65  */
  66 int media_content_connect(void);
  67
  68 /**
  69  * @brief Disconnects from the media content service.
  70  * @details This function closes connection to the media content service. Any further media content related operation
  71  *          cannot be performed after this function is called.
  72  *
  73  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  74  *
  75  * @return @c 0 on success,
  76  *         otherwise a negative error value
  77  *
  78  * @retval #MEDIA_CONTENT_ERROR_NONE      Successful
  79  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
  80  *
  81  * @pre media_content_connect()
  82  *
  83  * @see media_content_connect()
  84  *
  85  */
  86 int media_content_disconnect(void);
  87
  88 /**
  89  * @brief Requests to scan a media file.
  90  * @details This function requests to scan a media file to the media server.
  91  *          If media file is not registered to DB yet, that media file information will be added to the media DB. If it is already registered to the DB, then this tries to refresh information. \n
  92  *          If requested file does not exist on file system, information of the media file will be removed from the media DB. \n
  93  *          If file information does not exist in DB, this API will be return #MEDIA_CONTENT_ERROR_INVALID_PARAMETER.
  94  *
  95  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  96  *
  97  * @privlevel public
  98  * @privilege %http://tizen.org/privilege/content.write \n
  99  *                   %http://tizen.org/privilege/mediastorage \n
 100  *                   %http://tizen.org/privilege/externalstorage
 101  *
 102  * @remarks You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path. \n
 103  *                   If you want to access only internal storage by using  this API, you should add privilege http://tizen.org/privilege/mediastorage. \n
 104  *                   Or if you want to access only external storage by using  this API, you should add privilege http://tizen.org/privilege/externalstorage. \n
 105  *                   If you can access both storage, you must add all privilege.
 106  *
 107  * @param[in] path The file path
 108  *
 109  * @return @c 0 on success,
 110  *         otherwise a negative error value
 111  *
 112  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 113  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 114  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 115  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 116  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED    DB Operation failed
 117  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY    DB Operation busy
 118  *
 119  * @pre This function requires opened connection to content service by media_content_connect().
 120  * @see media_content_connect()
 121  */
 122 int media_content_scan_file(const char *path);
 123
 124 /**
 125  * @brief Requests to scan a media folder, asynchronously.
 126  * @details This function requests to scan a media folder to the media server with given completed callback function.
 127  *          media_scan_completed_cb() function will be called when the scanning is finished.
 128  *          The sub folders are also scanned, if there are sub folders in that folder. \n
 129  *          If any folder must not be scanned, a blank file ".scan_ignore" has to be created in that folder.
 130  *          After adding or removing a folder from the filesystem, call this function on its source location
 131  *          (this will add or remove an entry from the database). \n
 132  *          After moving or renaming a folder in the filesystem, call this function on its source location
 133  *          (this will remove an entry from the database) and call this function again on its destination location
 134  *          (this will add a new entry to the database).\n
 135  *          Alternatively, you can call this API on any parent of source location and on any parent of destination location.\n
 136  *          You can also call the function once, on a folder which is a parent of both source and destination.\n
 137  *
 138  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 139  *
 140  * @privlevel public
 141  * @privilege %http://tizen.org/privilege/content.write \n
 142  *                   %http://tizen.org/privilege/mediastorage \n
 143  *                   %http://tizen.org/privilege/externalstorage
 144  *
 145  * @remarks You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path. \n
 146  *                   If you want to access only internal storage by using  this API, you should add privilege http://tizen.org/privilege/mediastorage. \n
 147  *                   Or if you want to access only external storage by using  this API, you should add privilege http://tizen.org/privilege/externalstorage. \n
 148  *                   If you can access both storage, you must add all privilege.
 149  *
 150  * @param[in] path         The folder path
 151  * @param[in] is_recursive Set @c true to scan recursively subdirectories,
 152  *                         otherwise @c false to scan only the current directory
 153  * @param[in] callback     The callback to be invoked when the scanning is finished
 154  * @param[in] user_data    The user data to be passed to the callback function
 155  *
 156  * @return @c 0 on success,
 157  *         otherwise a negative error value
 158  *
 159  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 160  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 161  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 162  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 163  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 164  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED    DB Operation failed
 165  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY    DB Operation busy
 166  *
 167  * @pre This function requires opened connection to content service by media_content_connect().
 168  * @see media_scan_completed_cb()
 169  * @see media_content_connect()
 170  */
 171 int media_content_scan_folder(const char *path, bool is_recursive, media_scan_completed_cb callback, void *user_data);
 172
 173 /**
 174  * @brief Requests to cancel the media folder scanning.
 175  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 176  *
 177  * @param[in] path         The folder path
 178  *
 179  * @return @c 0 on success,
 180  *         otherwise a negative error value
 181  *
 182  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 183  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 184  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 185  *
 186  * @pre media_content_scan_folder()
 187  */
 188 int media_content_cancel_scan_folder(const char *path);
 189
 190 /**
 191  * @deprecated Deprecated since 3.0. Use media_content_add_db_updated_cb() instead.
 192  * @brief Subscribes notifications of the media DB change.
 193  * @details This function subscribes notifications of the media DB change which are published by the media server or other apps.
 194  *          media_content_db_update_cb() function will be called when notification of the media DB change is subscribed.
 195  *
 196  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 197  *
 198  * @param[in] callback  The callback to be invoked when the scanning is finished
 199  * @param[in] user_data The user data to be passed to the callback function
 200  *
 201  * @return @c 0 on success,
 202  *         otherwise a negative error value
 203  *
 204  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 205  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 206  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 207  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 208  *
 209  * @see media_content_db_update_cb()
 210  * @see media_content_unset_db_updated_cb()
 211  */
 212 int media_content_set_db_updated_cb(media_content_db_update_cb callback, void *user_data) TIZEN_DEPRECATED_API;
 213
 214 /**
 215  * @deprecated Deprecated since 3.0. Use media_content_remove_db_updated_cb() instead.
 216  * @brief Unsubscribes notifications of the media DB change.
 217  * @details This function unsubscribes notifications of the media DB change which are published by the media server or other apps.
 218  *
 219  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 220  *
 221  * @return @c 0 on success,
 222  *         otherwise a negative error value
 223  *
 224  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 225  *
 226  * @pre media_content_set_db_updated_cb()
 227  *
 228  * @see media_content_set_db_updated_cb()
 229  */
 230 int media_content_unset_db_updated_cb(void) TIZEN_DEPRECATED_API;
 231
 232 /**
 233  * @brief Subscribes notifications of the media DB change.
 234  * @details This function subscribes notifications of the media DB change which are published by the media server or other apps. \n
 235  *          media_content_db_update_cb() function will be called when notification of the media DB change is subscribed. \n
 236  *          Using this API, multiple callback is possible to register in one process.
 237  *
 238  * @since_tizen 3.0
 239  *
 240  * @remarks  To release the registered callback, you must use media_content_remove_db_updated_cb() API. \n
 241  *                    media_content_unset_db_updated_cb() API can not release the callbacks added by this API. \n
 242  *                    If you set the same callback that you previously added, this API returns MEDIA_CONTENT_ERROR_INVALID_OPERATION error. \n
 243  *
 244  * @param[in] callback  The callback to be invoked when the scanning is finished
 245  * @param[in] user_data The user data to be passed to the callback function
 246  * @param[out] noti_handle The handle to db updated notification
 247  *
 248  * @return @c 0 on success,
 249  *         otherwise a negative error value
 250  *
 251  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 252  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 253  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 254  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 255  *
 256  * @see media_content_db_update_cb()
 257  * @see media_content_remove_db_updated_cb()
 258  */
 259 int media_content_add_db_updated_cb(media_content_db_update_cb callback, void *user_data, media_content_noti_h *noti_handle);
 260
 261
 262 /**
 263  * @brief Unsubscribes notifications of the media DB change.
 264  * @details This function unsubscribes notifications of the media DB change which are published by the media server or other apps.
 265  *
 266  * @since_tizen 3.0
 267  *
 268  * @param[in] noti_handle The handle to db updated notification
 269  *
 270  * @return @c 0 on success,
 271  *         otherwise a negative error value
 272  *
 273  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 274  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 275  *
 276  * @pre media_content_add_db_updated_cb()
 277  *
 278  * @see media_content_add_db_updated_cb()
 279  */
 280 int media_content_remove_db_updated_cb(media_content_noti_h noti_handle);
 281
 282 /**
 283  * @}
 284  */
 285
 286 #ifdef __cplusplus
 287 }
 288 #endif /* __cplusplus */
 289
 290 #endif /* __TIZEN_MEDIA_CONTENT_H__ */