include/media_folder.h

   1 /*\r
   2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved\r
   3 *\r
   4 * Licensed under the Apache License, Version 2.0 (the "License");\r
   5 * you may not use this file except in compliance with the License.\r
   6 * You may obtain a copy of the License at\r
   7 *\r
   8 * http://www.apache.org/licenses/LICENSE-2.0\r
   9 *\r
  10 * Unless required by applicable law or agreed to in writing, software\r
  11 * distributed under the License is distributed on an "AS IS" BASIS,\r
  12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  13 * See the License for the specific language governing permissions and\r
  14 * limitations under the License. \r
  15 */\r
  16 \r
  17 \r
  18 #ifndef __TIZEN_MEDIA_FOLDER_H__\r
  19 #define __TIZEN_MEDIA_FOLDER_H__\r
  20 \r
  21 \r
  22 #include <media_content_type.h>\r
  23 \r
  24 \r
  25 #ifdef __cplusplus\r
  26 extern "C" {\r
  27 #endif /* __cplusplus */\r
  28 \r
  29 /**\r
  30  * @addtogroup CAPI_CONTENT_MEDIA_FOLDER_MODULE\r
  31  * @{\r
  32  */\r
  33 \r
  34 /**\r
  35  * @brief Iterates through all available media folders from the media database.\r
  36  * @details This function gets all media folder handles meeting the given \r
  37  * @a filter. The @a callback function will be invoked for every retrieved\r
  38  * folder. If NULL is passed to the @a filter, no filtering is applied. \r
  39  *\r
  40  * @param[in] filter The handle to media folder filter\r
  41  * @param[in] callback  The callback function to invoke\r
  42  * @param[in] user_data The user data to be passed to the callback function \r
  43  * @return return 0 on success, otherwise a negative error value.\r
  44  * @retval #MEDIA_CONTENT_ERROR_NONE Successful\r
  45  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter\r
  46  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory\r
  47  * @pre This function requires opened connection to content service by media_content_connect().\r
  48  * @pre A filter handle has to be created by calling media_folder_filter_create()\r
  49  * @post This function invokes media_folder_cb()\r
  50  * @see media_content_connect()\r
  51  * @see #media_folder_cb\r
  52  * @see media_folder_filter_create()\r
  53  */\r
  54 int media_folder_foreach_folder_from_db(media_folder_filter_h filter, media_folder_cb callback, void *user_data);\r
  55 \r
  56 /**\r
  57  * @brief Iterates through the media files with optional @a filter in the given @a folder from the media database.\r
  58  * @details This function gets all media files associated with the given folder and\r
  59  * meeting desired filter option and calls registered callback function for\r
  60  * every retrieved media item. If NULL is passed to the @a filter, no filtering is applied. \r
  61  *\r
  62  * @param[in] folder The handle to media folder\r
  63  * @param[in] filter The handle to media info filter\r
  64  * @param[in] callback The callback function to invoke\r
  65  * @param[in] user_data The user data to be passed to the callback function \r
  66  * @return 0 on success, otherwise a negative error value.\r
  67  * @retval #MEDIA_CONTENT_ERROR_NONE Successful\r
  68  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter\r
  69  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory\r
  70  * @pre This function requires opened connection to content service by media_content_connect().\r
  71  * @post This function invokes media_info_cb()\r
  72  * @see #media_info_cb\r
  73  * @see media_content_connect()\r
  74  * @see media_folder_filter_create()\r
  75  */\r
  76 int media_folder_foreach_media_from_db(media_folder_h folder, media_info_filter_h filter, media_info_cb callback, void *user_data);\r
  77 \r
  78 \r
  79 /**\r
  80  * @brief Gets the number of media files for the passed @a type  in the given @a folder from the media database.\r
  81  *\r
  82  * @param[in] folder The handle to media folder\r
  83  * @param[in] type The type of media content. \n To allow searching over different content types, you should use bitwise 'OR' operator to compose @a type.\r
  84  * @param[out] count The count of media folder items\r
  85  * @return 0 on success, otherwise a negative error value.\r
  86  * @retval #MEDIA_CONTENT_ERROR_NONE Successful\r
  87  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter\r
  88  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed \r
  89  * @pre This function requires opened connection to content service by media_content_connect().\r
  90  * @see media_content_connect()\r
  91  *\r
  92  */\r
  93 int media_folder_get_media_count_from_db(media_folder_h folder, media_content_type_e type, int *count);\r
  94 \r
  95 /**\r
  96  * @brief Clones the media folder.\r
  97  * @details This function copies the media folder handle from a source to\r
  98  * destination. There is no media_folder_create() function. The media_folder_h is created internally and available through \r
  99  * media folder foreach function such as media_folder_foreach_folder_from_db(). To  use this handle outside of these foreach functions, \r
 100  * use this function. \r
 101  * @remark The destination handle must be released with media_folder_destroy() by you. \r
 102  * @param[out] dst A destination handle to media folder\r
 103  * @param[in] src  The  source handle to media folder\r
 104  * @return 0 on success, otherwise a negative error value.\r
 105  * @retval #MEDIA_CONTENT_ERROR_NONE Successful\r
 106  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter\r
 107  * @see media_folder_destroy()\r
 108  * @see media_folder_foreach_folder_from_db() \r
 109  */\r
 110 int media_folder_clone(media_folder_h* dst, media_folder_h src);\r
 111 \r
 112 \r
 113 /**\r
 114  * @brief Destroys the media folder.\r
 115  * @details The function frees all resources related to the folder handle. This handle\r
 116  * no longer can be used to perform any operation. A new handle has to\r
 117  * be created before the next use.\r
 118  *\r
 119  * @param[in] folder The handle to media folder\r
 120  * @return 0 on success, otherwise a negative error value.\r
 121  * @retval #MEDIA_CONTENT_ERROR_NONE Successful\r
 122  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter\r
 123  * @pre A copy of the media folder handle created by calling media_folder_clone()\r
 124  * @see media_folder_clone()\r
 125  */\r
 126 int media_folder_destroy(media_folder_h folder);\r
 127 \r
 128 \r
 129 /**\r
 130  * @brief Gets the absolute path to the folder.\r
 131  *\r
 132  * @remarks @a path must be released with free() by you.\r
 133  *\r
 134  * @param[in] folder The handle to media folder\r
 135  * @param[out] path The path of the media folder\r
 136  * @return 0 on success, otherwise a negative error value.\r
 137  * @retval #MEDIA_CONTENT_ERROR_NONE Successful\r
 138  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter\r
 139  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory\r
 140  *\r
 141  */\r
 142 int media_folder_get_path(media_folder_h folder, char **path);\r
 143 \r
 144 /**\r
 145  * @brief Gets the folder name.\r
 146  *\r
 147  * @remarks @a folder_name must be released with free() by you.\r
 148  *\r
 149  * @param[in] folder The handle to media folder\r
 150  * @param[out] folder_name The name of the media folder\r
 151  * @return 0 on success, otherwise a negative error value.\r
 152  * @retval #MEDIA_CONTENT_ERROR_NONE Successful\r
 153  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter\r
 154  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory\r
 155  *\r
 156  */\r
 157 int media_folder_get_name(media_folder_h folder, char **folder_name);\r
 158 \r
 159 /**\r
 160  * @brief Gets the folder storage type.\r
 161  *\r
 162  * @param[in] folder The handle to media folder\r
 163  * @param[out] storage_type The storage type of the media folder\r
 164  * @return 0 on success, otherwise a negative error value.\r
 165  * @retval #MEDIA_CONTENT_ERROR_NONE Successful\r
 166  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter\r
 167  *\r
 168  */\r
 169 int media_folder_get_storage_type(media_folder_h folder, media_content_storage_e *storage_type);\r
 170 \r
 171 /**\r
 172  * @brief Gets the modifed date of the folder.\r
 173  *\r
 174  * @param[in] folder The handle to media folder\r
 175  * @param[out] date The modifed date of folder \r
 176  * @return 0 on success, otherwise a negative error value.\r
 177  * @retval #MEDIA_CONTENT_ERROR_NONE Successful\r
 178  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter\r
 179  *\r
 180  */\r
 181 int media_folder_get_date_modified(media_folder_h folder, time_t *date);\r
 182 \r
 183 /**\r
 184  * @}\r
 185  */\r
 186 \r
 187 #ifdef __cplusplus\r
 188 }\r
 189 #endif /* __cplusplus */\r
 190 \r
 191 #endif /* __TIZEN_MEDIA_FOLDER_H__ */\r
 192 \r