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
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif /* __cplusplus */
  35
  36 /**
  37  * @file media_content.h
  38  * @brief This file contains API providing functions for media content in DB. \n
  39  *        Operations include connect and disconnect the media content service, scanning media file and folder with subfolders, \n
  40  *        subscribing and unsubscribing notifications of media DB change.
  41  */
  42
  43 /**
  44  * @addtogroup CAPI_MEDIA_CONTENT_MODULE
  45  * @{
  46  */
  47
  48 /**
  49  * @brief Connects to the media content service.
  50  * @details Any media content related function call should be invoked after this function call.
  51  *
  52  * @since_tizen 2.3
  53  *
  54  * @return @c 0 on success,
  55  *         otherwise a negative error value
  56  *
  57  * @retval #MEDIA_CONTENT_ERROR_NONE      Successful
  58  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
  59  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
  60  *
  61  * @post media_content_disconnect()
  62  *
  63  * @see media_content_disconnect()
  64  */
  65 int media_content_connect(void);
  66
  67 /**
  68  * @brief Disconnects from the media content service.
  69  * @details This function closes connection to the media content service. Any further media content related operation
  70  *          cannot be performed after this function is called.
  71  *
  72  * @since_tizen 2.3
  73  *
  74  * @return @c 0 on success,
  75  *         otherwise a negative error value
  76  *
  77  * @retval #MEDIA_CONTENT_ERROR_NONE      Successful
  78  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
  79  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
  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.
  92  *          If requested file does not exist on file system, information of the media file will be removed from the media DB.
  93  *
  94  * @since_tizen 2.3
  95  *
  96  * @privlevel public
  97  * @privilege %http://tizen.org/privilege/content.write \n
  98  *                   %http://tizen.org/privilege/mediastorage \n
  99  *                   %http://tizen.org/privilege/externalstorage
 100  *
 101  * @remarks You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path. \n
 102  *                   If you want to access only internal storage by using  this API, you should add privilege http://tizen.org/privilege/mediastorage. \n
 103  *                   Or if you want to access only external storage by using  this API, you shold add privilege http://tizen.org/privilege/externalstorage. \n
 104  *                   If you can access both storage, you must add all privilege.
 105  *
 106  * @param[in] path The file path
 107  *
 108  * @return @c 0 on success,
 109  *         otherwise a negative error value
 110  *
 111  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 112  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 113  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 114  *
 115  * @pre This function requires opened connection to content service by media_content_connect().
 116  */
 117 int media_content_scan_file(const char *path);
 118
 119 /**
 120  * @brief Requests to scan a media folder, asynchronously.
 121  * @details This function requests to scan a media folder to the media server with given completed callback function.
 122  *          media_scan_completed_cb() function will be called when the scanning is finished.
 123  *          The sub folders are also scanned, if there are sub folders in that folder. \n
 124  *          If any folder must not be scanned, a blank file ".scan_ignore" has to be created in that folder.
 125  *
 126  * @since_tizen 2.3
 127  *
 128  * @privlevel public
 129  * @privilege %http://tizen.org/privilege/content.write \n
 130  *                   %http://tizen.org/privilege/mediastorage \n
 131  *                   %http://tizen.org/privilege/externalstorage
 132  *
 133  * @remarks You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path. \n
 134  *                   If you want to access only internal storage by using  this API, you should add privilege http://tizen.org/privilege/mediastorage. \n
 135  *                   Or if you want to access only external storage by using  this API, you shold add privilege http://tizen.org/privilege/externalstorage. \n
 136  *                   If you can access both storage, you must add all privilege.
 137  *
 138  * @param[in] path         The folder path
 139  * @param[in] is_recursive Set @c true to scan recursively subdirectories,
 140  *                         otherwise @c false to scan only the current directory
 141  * @param[in] callback     The callback to be invoked when the scanning is finished
 142  * @param[in] user_data    The user data to be passed to the callback function
 143  *
 144  * @return @c 0 on success,
 145  *         otherwise a negative error value
 146  *
 147  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 148  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 149  *
 150  * @see media_scan_completed_cb()
 151  */
 152 int media_content_scan_folder(const char *path, bool is_recursive, media_scan_completed_cb callback, void *user_data);
 153
 154 /**
 155  * @brief Requests to cancel the media folder scanning.
 156  * @since_tizen 2.4
 157  *
 158  * @param[in] path         The folder path
 159  *
 160  * @return @c 0 on success,
 161  *         otherwise a negative error value
 162  *
 163  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 164  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 165  *
 166  * @pre media_content_scan_folder()
 167  */
 168 int media_content_cancel_scan_folder(const char *path);
 169
 170 /**
 171  * @brief Subscribes notifications of the media DB change.
 172  * @details This function subscribes notifications of the media DB change which are published by the media server or other apps.
 173  *          media_content_db_update_cb() function will be called when notification of the media DB change is subscribed.
 174  *
 175  * @since_tizen 2.3
 176  *
 177  * @param[in] callback  The callback to be invoked when the scanning is finished
 178  * @param[in] user_data The user data to be passed to the callback function
 179  *
 180  * @return @c 0 on success,
 181  *         otherwise a negative error value
 182  *
 183  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 184  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 185  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 186  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 187  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 188  *
 189  * @see media_content_db_update_cb()
 190  * @see media_content_unset_db_updated_cb()
 191  */
 192 int media_content_set_db_updated_cb(media_content_db_update_cb callback, void *user_data);
 193
 194 /**
 195  * @brief Unsubscribes notifications of the media DB change.
 196  * @details This function unsubscribes notifications of the media DB change which are published by the media server or other apps.
 197  *
 198  * @since_tizen 2.3
 199  *
 200  * @return @c 0 on success,
 201  *         otherwise a negative error value
 202  *
 203  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 204  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 205  *
 206  * @pre media_content_set_db_updated_cb()
 207  *
 208  * @see media_content_set_db_updated_cb()
 209  */
 210 int media_content_unset_db_updated_cb(void);
 211
 212 /**
 213  * @}
 214  */
 215
 216 #ifdef __cplusplus
 217 }
 218 #endif /* __cplusplus */
 219
 220 #endif /* __TIZEN_MEDIA_CONTENT_H__ */