doc/media_content_doc.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
  18 #ifndef __TIZEN_MEDIA_CONTENT_DOC_H__
  19 #define __TIZEN_MEDIA_CONTENT_DOC_H__
  20
  21 /**
  22  * @defgroup CAPI_MEDIA_CONTENT_MODULE Media Content
  23  * @brief The Media Content API provides functions, enumerations used in the entire Content Service.
  24  *
  25  * @ingroup CAPI_CONTENT_FRAMEWORK
  26  *
  27  * @section CAPI_MEDIA_CONTENT_MODULE_HEADER Required Header
  28  *   \#include <media_content.h>
  29  *
  30  * @section CAPI_MEDIA_CONTENT_MODULE_OVERVIEW Overview
  31  * The Media Content API provides functions and enumerations used in the entire Content Service.\n
  32  * The information about media items i.e. image, audio, video and ebook, are managed in the content database and
  33  * operations that involve database requires an active connection with the media content service.\n
  34  * During media scanning, Media Service extract media information automatically. media information include basic file info like
  35  * path, size, modified time etc and some metadata like ID3tag, EXIF, thumbnail, etc. (thumbnail extracted only in Internal and SD card storage.) \n
  36  * Since 3.0, a thumbnail is not automatically extracted during media scanning. A thumbnail will be created only when media_info_generate_thumbnail() is called by any application. \n
  37  * Media content services do not manage hidden files. \n
  38  * The API provides functions for connecting (#media_content_connect()) and disconnecting (#media_content_disconnect()) from the media content service.
  39  *
  40  * The API consists of @ref CAPI_CONTENT_MEDIA_ALBUM_MODULE, @ref CAPI_CONTENT_MEDIA_BOOKMARK_MODULE, @ref CAPI_CONTENT_MEDIA_FACE_MODULE,
  41  * @ref CAPI_CONTENT_MEDIA_FILTER_MODULE, @ref CAPI_CONTENT_MEDIA_FOLDER_MODULE, @ref CAPI_CONTENT_MEDIA_GROUP_MODULE,
  42  * @ref CAPI_CONTENT_MEDIA_INFO_MODULE, @ref CAPI_CONTENT_MEDIA_PLAYLIST_MODULE, @ref CAPI_CONTENT_MEDIA_TAG_MODULE API.
  43  *
  44  * <table>
  45  * <tr>
  46  *    <th>API</th>
  47  *    <th>Description</th>
  48  * </tr>
  49  * <tr>
  50  *    <td>@ref CAPI_CONTENT_MEDIA_ALBUM_MODULE </td>
  51  *    <td> Provide information about the media album. </td>
  52  * </tr>
  53  * <tr>
  54  *    <td>@ref CAPI_CONTENT_MEDIA_BOOKMARK_MODULE </td>
  55  *    <td> Provide information about the media bookmark. </td>
  56  * </tr>
  57  * <tr>
  58  *    <td>@ref CAPI_CONTENT_MEDIA_FACE_MODULE </td>
  59  *    <td> Provide information about the detected faces from image. </td>
  60  * </tr>
  61  * <tr>
  62  *    <td>@ref CAPI_CONTENT_MEDIA_FILTER_MODULE </td>
  63  *    <td> Provide functions for creating and destroying media filters.\n
  64  * Provide functions to get filter properties</td>
  65  * </tr>
  66  * <tr>
  67  *    <td>@ref CAPI_CONTENT_MEDIA_FOLDER_MODULE </td>
  68  *    <td> Provide information about folders (e.g. path, name, modification date) stored on the device.\n
  69  * Provide information about the media items present in the folders.</td>
  70  * </tr>
  71  * <tr>
  72  *    <td>@ref CAPI_CONTENT_MEDIA_GROUP_MODULE </td>
  73  *    <td> Provide information about the media group(e.g. media artist, album, genre, year). </td>
  74  * </tr>
  75  * <tr>
  76  *    <td>@ref CAPI_CONTENT_MEDIA_INFO_MODULE </td>
  77  *    <td> Provide generic information about media content items (i.e. image, audio, video, ebook and others).\n
  78  *  Provide details about audio files (e.g. name, genre etc) present in the device.\n
  79  *  Provide details about image files (e.g. width, height, orientation etc) present in the device.\n
  80  *  Provide details about video files (e.g. width, height, duration etc) present in the device.\n
  81  *  Provide details about ebook files (e.g. subject, author etc) present in the device.</td>
  82  * </tr>
  83  * <tr>
  84  *    <td>@ref CAPI_CONTENT_MEDIA_PLAYLIST_MODULE </td>
  85  *    <td> Provide information about the media playlist. </td>
  86  * </tr>
  87  * <tr>
  88  *    <td>@ref CAPI_CONTENT_MEDIA_TAG_MODULE </td>
  89  *    <td> Provide information about media tags.\n
  90  * Provide functions to insert or delete tag from database.\n
  91  * Provide functions to add and remove media item from tags in the database. </td>
  92  * </tr>
  93  * </table>
  94  *
  95  */
  96
  97 /**
  98  * @defgroup CAPI_CONTENT_MEDIA_FOLDER_MODULE Media Folder
  99  * @brief The Media folder API provides functions to get information about folders.
 100  *
 101  * @ingroup CAPI_MEDIA_CONTENT_MODULE
 102  *
 103  * @section CAPI_CONTENT_MEDIA_FOLDER_MODULE_HEADER Required Header
 104  *   \#include <media_content.h>
 105  *
 106  * @section CAPI_CONTENT_MEDIA_FOLDER_MODULE_OVERVIEW Overview
 107  * A Folder is used to organize media content files i.e. image, audio, video, ebook files, in the physical storage of the device.
 108  * The Media Folder API provides functions to get basic information about existing folders e.g. folder name, path and modified time.
 109  * It also provides functions to get information related to media items present in the folder.
 110  *
 111  * For getting information about folder call the respective get functions e.g. to get path and name of a given folder call #media_folder_get_path() and #media_folder_get_name() function respectively and so on.\n
 112  * Similarly call media_folder_get_media_count_from_db() to get count of media items present in a given folder.
 113  * @subsection CAPI_CONTENT_MEDIA_FOLDER_FOREACH_OPERATIONS Foreach Operations
 114  * <div><table class="doxtable">
 115  *     <tr>
 116  *        <th><b>FOREACH</b></th>
 117  *        <th><b>CALLBACK</b></th>
 118  *        <th><b>DESCRIPTION</b></th>
 119  *     </tr>
 120  *     <tr>
 121  *        <td>media_folder_foreach_folder_from_db()</td>
 122  *        <td>media_folder_cb()</td>
 123  *        <td>Iterates over a folder information list</td>
 124  *     </tr>
 125  *     <tr>
 126  *        <td>media_folder_foreach_media_from_db()</td>
 127  *        <td>media_info_cb()</td>
 128  *        <td>Iterates media information trough the folder</td>
 129  *     </tr>
 130  * </table></div>
 131  *
 132  *
 133  */
 134
 135
 136 /**
 137  * @defgroup CAPI_CONTENT_MEDIA_TAG_MODULE Media Tag (Deprecated)
 138  * @brief  The Media Tag API provides functions to manage media content tags.
 139  *
 140  * @ingroup CAPI_MEDIA_CONTENT_MODULE
 141  *
 142  * @section CAPI_CONTENT_MEDIA_TAG_MODULE_HEADER Required Header
 143  *   \#include <media_content.h>
 144  *
 145  * @section CAPI_CONTENT_MEDIA_TAG_MODULE_OVERVIEW Overview
 146  * A Tag is a special piece of information that may be associated with media content items.
 147  * Tagging allows a user to organize large number of items into logical groups providing a simplified
 148  * and faster way of accessing media content items.\n\n
 149  * Media Tag API provides functions to get basic information about existing tags and manage tags
 150  * associated with Media Information (#media_info_h).
 151  * For inserting a new tag to the database call #media_tag_insert_to_db() function and for deleting existing tag from database
 152  * call media_tag_delete_from_db() function.\n
 153  * A Media item can be associated and dissociated from tags by calling #media_tag_add_media() and #media_tag_remove_media() function respectively.
 154  * Finally, #media_tag_update_to_db function should be called so as to update the given item in the media database.
 155  *
 156  * @subsection CAPI_CONTENT_MEDIA_TAG_FOREACH_OPERATIONS Foreach Operations
 157  * <div><table class="doxtable">
 158  *     <tr>
 159  *        <th><b>FOREACH</b></th>
 160  *        <th><b>CALLBACK</b></th>
 161  *        <th><b>DESCRIPTION</b></th>
 162  *     </tr>
 163  *     <tr>
 164  *        <td>media_tag_foreach_tag_from_db()</td>
 165  *        <td> media_tag_cb()</td>
 166  *        <td>Iterates through tags</td>
 167  *     </tr>
 168  *     <tr>
 169  *        <td>media_tag_foreach_media_from_db()</td>
 170  *        <td>media_info_cb()</td>
 171  *        <td> Iterates through the media items for a given tag
 172  </td>
 173  *     </tr>
 174  * </table></div>
 175  *
 176  *
 177  *
 178  */
 179
 180
 181 /**
 182  * @defgroup CAPI_CONTENT_MEDIA_FILTER_MODULE Media Filter
 183  * @brief The Media Filter API provides functions to manage media filters.
 184  *
 185  * @ingroup CAPI_MEDIA_CONTENT_MODULE
 186  *
 187  * @section CAPI_CONTENT_MEDIA_FILTER_MODULE_HEADER Required Header
 188  *   \#include <media_content.h>
 189  *
 190  * @section CAPI_CONTENT_MEDIA_FILTER_MODULE_OVERVIEW Overview
 191  * A Media filter is required for filtering information associated with media Folder, Tag, Audio, Bookmark and Media Information on basis of details like offset, count, order and condition for searching.\n
 192  * @ref CAPI_CONTENT_MEDIA_FILTER_MODULE API provides functions for creating and destroying media filters. \n
 193  * It provide functions to set properties and also provide functions for getting filter properties associated with a given media filter.
 194  *
 195  *\n
 196  * Setting media filter properties helps to limit the number of filtered items as following:
 197  * - Offset - Used to set starting position of the filter's search
 198  * - Count - Used to set number of items to be searched from offset
 199  * - Condition - Used to set keyword which user want to search
 200  * - Order - Used to set type of media to be ordered by the filter
 201  *
 202  *\n
 203  * The Media Filter API provides functions for creating and destroying media filters.\n
 204  * It provide functions to set and get properties of the filter associated with a given media filter. \n
 205  * For creating a media filter (@ref filter_h), call #media_filter_create() function and call #media_filter_destroy() function for destroying an existing filter. \n
 206  * For setting filter properties call the respective set functions e.g. to set offset position, call #media_filter_set_offset() function and
 207  * call #media_filter_set_condition() function to set the condition like an sql "where" clause. \n
 208  * Searchable expression can use one of the following forms:
 209  *
 210  *
 211  * - column = value
 212  * - column > value
 213  * - column >= value
 214  * - column < value
 215  * - column <= value
 216  * - value = column
 217  * -  * - value > column
 218  * - value >= column
 219  * - value < column
 220  * - value <= column
 221  * - column IN (value)
 222  * - column IN (value-list)
 223  * - column NOT IN (value)
 224  * - column NOT IN (value-list)
 225  * - column LIKE value
 226  * - expression1 AND expression2 OR expression3
 227  *
 228  *\n
 229  *
 230  * Note that if you want to set qoutation(" ' " or " " ") as value of LIKE operator, you should use two times.(" '' " or " "" ") \n
 231  * And the optional ESCAPE clause is supported. Both percent symbol("%") and underscore symbol("_") are used in the LIKE pattern.\n
 232  * If these characters are used as value of LIKE operation, then the expression following the ESCAPE clause of sqlite will be ignored. \n
 233  *
 234  * For example,
 235  * - column LIKE ('#%') ESCAPE('#') - "#" is escape character, it will be ignored.
 236  *\n
 237  *
 238  *
 239  * Similarly, call respective get function to get filter properties e.g. call #media_filter_get_condition() function
 240  * to get condition of the media filter and call #media_filter_get_order() function to get order (#media_content_order_e) of the filtered items and so on.
 241  *
 242  * @section CAPI_CONTENT_MEDIA_FILTER_MODULE_EXAMPLE Example
 243  * You can set the filter as follows.
 244  * @code
 245  *
 246  * #include <stdio.h>
 247  * #include <string.h>
 248  * #include <media_content.h>
 249  *
 250  * #define MAX_QUERY_LEN 512
 251  * #define DLOG_TAG "media-content-test"
 252  *
 253  * filter_h g_filter = NULL;
 254  *
 255  * int create_filter()
 256  * {
 257  *     int ret = MEDIA_CONTENT_ERROR_NONE;
 258  *     char condition[MAX_QUERY_LEN] = {0,};
 259  *
 260  *     snprintf(condition,sizeof(condition),"%s = 0",MEDIA_TYPE);
 261  *
 262  *     ret = media_filter_create(&g_filter);
 263  *     ret = media_filter_set_condition(g_filter, condition, MEDIA_CONTENT_COLLATE_DEFAULT);
 264  *     ret = media_filter_set_order(g_filter, MEDIA_CONTENT_ORDER_DESC, MEDIA_ARTIST, MEDIA_CONTENT_COLLATE_DEFAULT);
 265  *
 266  *     return ret;
 267  * }
 268  *
 269  * @endcode
 270  * And you can use the created filter as follows.
 271  * @code
 272  *
 273  * int get_media_count()
 274  * {
 275  *     int ret = MEDIA_CONTENT_ERROR_NONE;
 276  *     int media_cnt = 0;
 277  *
 278  *     ret = media_info_get_media_count_from_db(g_filter, &media_cnt);
 279  *     dlog_print(DLOG_DEBUG, DLOG_TAG, "media count [%d]\n", media_cnt);
 280  *
 281  *     return ret;
 282  * }
 283  *
 284  * @endcode
 285  */
 286
 287
 288 /**
 289  * @defgroup CAPI_CONTENT_MEDIA_AUDIO_META_MODULE Audio Metadata
 290  * @brief The Audio Metadata API provides functions to get information about audio items.
 291  *
 292  * @ingroup CAPI_CONTENT_MEDIA_INFO_MODULE
 293  *
 294  * @section CAPI_CONTENT_MEDIA_AUDIO_META_MODULE_HEADER Required Header
 295  *   \#include <media_content.h>
 296  *
 297  * @section CAPI_CONTENT_MEDIA_AUDIO_META_MODULE_OVERVIEW Overview
 298  * The Audio Metadata API provides functions to get information about stored audio files.
 299  * Its purpose is twofold:
 300  * - to provide information about audio content
 301  * - to organize audio content logically (grouping)
 302  *
 303  * API provides functions that allow to check attributes of audio files. Following information about audio content is provided:
 304  *
 305  * <table>
 306  * <tr>
 307  * <th>Attribute</th>
 308  * <th>Filter Keyword</th>
 309  * <th>Comments</th>
 310  * </tr>
 311  * <tr>
 312  * <td>album</td>
 313  * <td>#MEDIA_ALBUM</td>
 314  * <td>Get from metadata if exist.</td>
 315  * </tr>
 316  * <tr>
 317  * <td>artist</td>
 318  * <td>#MEDIA_ARTIST</td>
 319  * <td>Get from metadata if exist.</td>
 320  * </tr>
 321  * <tr>
 322  * <td>album_artist</td>
 323  * <td>#MEDIA_ALBUM_ARTIST</td>
 324  * <td>Get from metadata if exist.</td>
 325  * </tr>
 326  * <tr>
 327  * <td>genre</td>
 328  * <td>#MEDIA_GENRE</td>
 329  * <td>Get from metadata if exist.</td>
 330  * </tr>
 331  * <tr>
 332  * <td>composer</td>
 333  * <td>#MEDIA_COMPOSER</td>
 334  * <td>Get from metadata if exist.</td>
 335  * </tr>
 336  * <tr>
 337  * <td>year</td>
 338  * <td>#MEDIA_YEAR</td>
 339  * <td>Get from metadata if exist.</td>
 340  * </tr>
 341  * <tr>
 342  * <td>recorded_date</td>
 343  * <td>#MEDIA_RECORDED_DATE</td>
 344  * <td>Get from metadata if exist. if not, same as modified time.</td>
 345  * </tr>
 346  * <tr>
 347  * <td>copyright</td>
 348  * <td></td>
 349  * <td>Get from metadata if exist.</td>
 350  * </tr>
 351  * <tr>
 352  * <td>track_num</td>
 353  * <td>#MEDIA_TRACK_NUM</td>
 354  * <td>Get from metadata if exist.</td>
 355  * </tr>
 356  * <tr>
 357  * <td>bit_rate</td>
 358  * <td></td>
 359  * <td>Bitrate</td>
 360  * </tr>
 361  * <tr>
 362  * <td>bitpersample</td>
 363  * <td></td>
 364  * <td>Bit per sample</td>
 365  * </tr>
 366  * <tr>
 367  * <td>sample_rate</td>
 368  * <td></td>
 369  * <td>Samplerate</td>
 370  * </tr>
 371  * <tr>
 372  * <td>channel</td>
 373  * <td></td>
 374  * <td>Channel</td>
 375  * </tr>
 376  * <tr>
 377  * <td>duration</td>
 378  * <td>#MEDIA_DURATION</td>
 379  * <td>Duration</td>
 380  * </tr>
 381  * <tr>
 382  * <td>rating</td>
 383  * <td></td>
 384  * <td>Get from metadata if exist.</td>
 385  * </tr>
 386  * </table>
 387  * \n
 388  *
 389  * <p>
 390  * For getting the audio handle (#audio_meta_h) from the media information (#media_info_h), call #media_info_get_audio() function.\n
 391  * For getting the information related to audio files stored in the device, call the respective get functions e.g. to get the artist of a audio, call #audio_meta_get_artist() function and
 392  * to get bitrate of a audio, call #audio_meta_get_bit_rate() function and so on.\n
 393  * When the audio handle is no longer needed, it should be destroyed by calling #audio_meta_destroy() function.\n
 394  *
 395  *
 396  *
 397  */
 398
 399
 400 /**
 401  * @defgroup CAPI_CONTENT_MEDIA_PLAYLIST_MODULE Media Playlist
 402  * @brief The Media Playlist API provides functions to manage media playlists.
 403  *
 404  * @ingroup CAPI_MEDIA_CONTENT_MODULE
 405  *
 406  * @section CAPI_CONTENT_MEDIA_PLAYLIST_MODULE_HEADER Required Header
 407  *   \#include <media_content.h>
 408  *
 409  * @section CAPI_CONTENT_MEDIA_PLAYLIST_MODULE_OVERVIEW Overview
 410  * A Playlist is a list of songs which can be played in some sequence i.e. sequential or shuffled order.
 411  * The Media Playlist API provides functions to insert, delete or updates a media playlist in the database.
 412  *
 413  * For inserting new playlist (#media_playlist_h) in the database, call  #media_playlist_insert_to_db() function and call #media_playlist_delete_from_db() function
 414  * to delete a playlist from the database.\n
 415  * For adding a media item to the playlist, call #media_playlist_add_media() function, for removing a media item from the playlist, call
 416  * #media_playlist_remove_media() function.\n
 417  * Finally, #media_playlist_update_to_db() function should be called so as to update the given item in the media database.
 418  *
 419  * @subsection CAPI_CONTENT_MEDIA_PLAYLIST_FOREACH_OPERATIONS Foreach Operations
 420  * <div><table class="doxtable">
 421  *     <tr>
 422  *        <th><b>FOREACH</b></th>
 423  *        <th><b>CALLBACK</b></th>
 424  *        <th><b>DESCRIPTION</b></th>
 425  *     </tr>
 426  *     <tr>
 427  *        <td>media_playlist_foreach_playlist_from_db()</td>
 428  *        <td>media_playlist_cb()</td>
 429  *        <td>Iterates through playlist</td>
 430  *     </tr>
 431  *     <tr>
 432  *        <td>media_playlist_foreach_media_from_db()</td>
 433  *        <td>media_info_cb()</td>
 434  *        <td>Iterates through playlist's items</td>
 435  *     </tr>
 436  * </table></div>
 437  *
 438  *
 439  */
 440
 441
 442 /**
 443  * @defgroup CAPI_CONTENT_MEDIA_ALBUM_MODULE Media Album
 444  * @brief The Media Album API provides information related to album of media items.
 445  *
 446  * @ingroup CAPI_MEDIA_CONTENT_MODULE
 447  *
 448  * @section CAPI_CONTENT_MEDIA_ALBUM_MODULE_HEADER Required Header
 449  *   \#include <media_content.h>
 450  *
 451  * @section CAPI_CONTENT_MEDIA_ALBUM_MODULE_OVERVIEW Overview
 452  * An album is a logical collection or grouping of related audio files. It is also used for filtering media items.\n
 453  * The Media Album API allows to manage media albums which contains all video and audio items from
 454  * the same album.
 455  *
 456  * The API provides functions to get and search media items in album group.
 457  * For getting the count of media items associated with a given album, call #media_album_get_media_count_from_db() function.
 458  *
 459  * @subsection CAPI_CONTENT_MEDIA_ALBUM_FOREACH_OPERATIONS Foreach Operations
 460  * <div><table class="doxtable">
 461  *     <tr>
 462  *        <th><b>FOREACH</b></th>
 463  *        <th><b>CALLBACK</b></th>
 464  *        <th><b>DESCRIPTION</b></th>
 465  *     </tr>
 466  *     <tr>
 467  *        <td>media_album_foreach_album_from_db()</td>
 468  *        <td>media_album_cb()</td>
 469  *        <td>Iterates through albums</td>
 470  *     </tr>
 471  *     <tr>
 472  *        <td>media_album_foreach_media_from_db()</td>
 473  *        <td>media_info_cb()</td>
 474  *        <td>Iterates through album's items</td>
 475  *     </tr>
 476  * </table></div>
 477  *
 478  *
 479  */
 480
 481
 482 /**
 483  * @defgroup CAPI_CONTENT_MEDIA_GROUP_MODULE Media Group
 484  * @brief The Media Group API provides information related to artist of media group.
 485  *
 486  * @ingroup CAPI_MEDIA_CONTENT_MODULE
 487  *
 488  * @section CAPI_CONTENT_MEDIA_GROUP_MODULE_HEADER Required Header
 489  *   \#include <media_content.h>
 490  *
 491  * @section CAPI_CONTENT_MEDIA_GROUP_MODULE_OVERVIEW Overview
 492  * A Media Group represents logical grouping of media files with respect to their group name. It is also used for filtering media items.\n
 493  *
 494  * The API provides functions to get and search image, video and audio items in media group.
 495  * For getting the count of media items associated with a given group, call #media_group_get_media_count_from_db() function.
 496  *
 497  *
 498  * @subsection CAPI_CONTENT_MEDIA_GROUP_FOREACH_OPERATIONS Foreach Operations
 499  * <div><table class="doxtable">
 500  *      <tr>
 501  *         <th><b>FOREACH</b></th>
 502  *         <th><b>CALLBACK</b></th>
 503  *         <th><b>DESCRIPTION</b></th>
 504  *      </tr>
 505  *      <tr>
 506  *         <td>media_group_foreach_group_from_db()</td>
 507  *         <td> media_group_cb()</td>
 508  *         <td>Iterates through group</td>
 509  *      </tr>
 510  *      <tr>
 511  *         <td>media_group_foreach_media_from_db()</td>
 512  *         <td>media_info_cb()</td>
 513  *         <td>Iterates through group's items</td>
 514  *      </tr>
 515  * </table></div>
 516  *
 517  *
 518  */
 519
 520
 521 /**
 522  * @defgroup CAPI_CONTENT_MEDIA_IMAGE_META_MODULE Image Metadata
 523  * @brief The Image Metadata API provides functions that allow to get information about
 524  * stored image files.
 525  *
 526  * @ingroup CAPI_CONTENT_MEDIA_INFO_MODULE
 527  *
 528  * @section CAPI_CONTENT_MEDIA_IMAGE_META_MODULE_HEADER Required Header
 529  *   \#include <media_content.h>
 530  *
 531  * @section CAPI_CONTENT_MEDIA_IMAGE_META_MODULE_OVERVIEW Overview
 532  * The Image Metadata API provides functions to get basic information associated with image files:
 533  * <table>
 534  * <tr>
 535  * <th>Attribute</th>
 536  * <th>Filter Keyword</th>
 537  * <th>Comments</th>
 538  * </tr>
 539  * <tr>
 540  * <td>width</td>
 541  * <td>#MEDIA_WIDTH</td>
 542  * <td>Width</td>
 543  * </tr>
 544  * <tr>
 545  * <td>height</td>
 546  * <td>#MEDIA_HEIGHT</td>
 547  * <td>Height</td>
 548  * </tr>
 549  * <tr>
 550  * <td>longitude</td>
 551  * <td>#MEDIA_LONGITUDE</td>
 552  * <td>Get from metadata if exist.</td>
 553  * </tr>
 554  * <tr>
 555  * <td>latitude</td>
 556  * <td>#MEDIA_LATITUDE</td>
 557  * <td>Get from metadata if exist.</td>
 558  * </tr>
 559  * <tr>
 560  * <td>altitude</td>
 561  * <td>#MEDIA_ALTITUDE</td>
 562  * <td>Get from metadata if exist.</td>
 563  * </tr>
 564  * <tr>
 565  * <td>exposure_time</td>
 566  * <td></td>
 567  * <td>Get from EXIF if exist.</td>
 568  * </tr>
 569  * <tr>
 570  * <td>fnumber</td>
 571  * <td></td>
 572  * <td>Get from EXIF if exist.</td>
 573  * </tr>
 574  * <tr>
 575  * <td>iso</td>
 576  * <td></td>
 577  * <td>Get from EXIF if exist.</td>
 578  * </tr>
 579  * <tr>
 580  * <td>model</td>
 581  * <td></td>
 582  * <td>Get from EXIF if exist.</td>
 583  * </tr>
 584  * <tr>
 585  * <td>date_taken</td>
 586  * <td>#MEDIA_DATETAKEN</td>
 587  * <td>Get from EXIF if exist.</td>
 588  * </tr>
 589  * <tr>
 590  * <td>orientation</td>
 591  * <td></td>
 592  * <td>Get from EXIF if exist.</td>
 593  * </tr>
 594  * <tr>
 595  * <td>is_360_content</td>
 596  * <td>#MEDIA_360</td>
 597  * <td>Whether 360 content or not.</td>
 598  * </tr>
 599  * </table>
 600  *
 601  * \n
 602  *
 603  *<p>
 604  * For getting the image handle (#image_meta_h) from the media information (#media_info_h), call #media_info_get_image() function.\n
 605  * For getting the information related to image files stored in the device call the respective get functions e.g. to get the width of a image, call #image_meta_get_width() function and
 606  * to get orientation (#media_content_orientation_e) of a image, call #image_meta_get_orientation() function and so on.\n
 607  * When the image handle is no longer needed, it should be destroyed by calling #image_meta_destroy() function.\n
 608  *
 609  */
 610
 611
 612
 613
 614 /**
 615  * @defgroup CAPI_CONTENT_MEDIA_VIDEO_META_MODULE Video Metadata (Deprecated)
 616  * @brief The Video Metadata API provides functions to get information about video files present in the device.
 617  *
 618  * @ingroup CAPI_CONTENT_MEDIA_INFO_MODULE
 619  *
 620  * @section CAPI_CONTENT_MEDIA_VIDEO_META_MODULE_HEADER Required Header
 621  *   \#include <media_content.h>
 622  *
 623  * @section CAPI_CONTENT_MEDIA_VIDEO_META_MODULE_OVERVIEW Overview
 624  * The Video Metadata API provides functions to get information about video files present in the device.
 625  * Following information about video content (#video_meta_h) is provided:
 626  * <table>
 627  * <tr>
 628  * <th>Attribute</th>
 629  * <th>Filter Keyword</th>
 630  * <th>Comments</th>
 631  * </tr>
 632  * <tr>
 633  * <td>album</td>
 634  * <td>#MEDIA_ALBUM</td>
 635  * <td>Get from metadata if exist.</td>
 636  * </tr>
 637  * <tr>
 638  * <td>artist</td>
 639  * <td>#MEDIA_ARTIST</td>
 640  * <td>Get from metadata if exist.</td>
 641  * </tr>
 642  * <tr>
 643  * <td>album_artist</td>
 644  * <td>#MEDIA_ALBUM_ARTIST</td>
 645  * <td>Get from metadata if exist.</td>
 646  * </tr>
 647  * <tr>
 648  * <td>genre</td>
 649  * <td>#MEDIA_GENRE</td>
 650  * <td>Get from metadata if exist.</td>
 651  * </tr>
 652  * <tr>
 653  * <td>composer</td>
 654  * <td>#MEDIA_COMPOSER</td>
 655  * <td>Get from metadata if exist.</td>
 656  * </tr>
 657  * <tr>
 658  * <td>year</td>
 659  * <td>#MEDIA_YEAR</td>
 660  * <td>Get from metadata if exist.</td>
 661  * </tr>
 662  * <tr>
 663  * <td>recorded_date</td>
 664  * <td>#MEDIA_RECORDED_DATE</td>
 665  * <td>Get from metadata if exist. if not, same as modified time.</td>
 666  * </tr>
 667  * <tr>
 668  * <td>copyright</td>
 669  * <td></td>
 670  * <td>Get from metadata if exist.</td>
 671  * </tr>
 672  * <tr>
 673  * <td>track_num</td>
 674  * <td>#MEDIA_TRACK_NUM</td>
 675  * <td>Get from metadata if exist.</td>
 676  * </tr>
 677  * <tr>
 678  * <td>bit_rate</td>
 679  * <td></td>
 680  * <td>Bitrate</td>
 681  * </tr>
 682  * <tr>
 683  * <td>bitpersample</td>
 684  * <td></td>
 685  * <td>Bit per sample</td>
 686  * </tr>
 687  * <tr>
 688  * <td>sample_rate</td>
 689  * <td></td>
 690  * <td>Samplerate</td>
 691  * </tr>
 692  * <tr>
 693  * <td>channel</td>
 694  * <td></td>
 695  * <td>Channel</td>
 696  * </tr>
 697  * <tr>
 698  * <td>duration</td>
 699  * <td>#MEDIA_DURATION</td>
 700  * <td>Duration</td>
 701  * </tr>
 702  * <tr>
 703  * <td>rating</td>
 704  * <td></td>
 705  * <td>Get from metadata if exist.</td>
 706  * </tr>
 707  * <tr>
 708  * <td>rotation</td>
 709  * <td></td>
 710  * <td>Video rotation</td>
 711  * </tr>
 712  * <tr>
 713  * <td>width</td>
 714  * <td>#MEDIA_WIDTH</td>
 715  * <td>Width</td>
 716  * </tr>
 717  * <tr>
 718  * <td>height</td>
 719  * <td>#MEDIA_HEIGHT</td>
 720  * <td>Height</td>
 721  * </tr>
 722  * <tr>
 723  * <td>longitude</td>
 724  * <td>#MEDIA_LONGITUDE</td>
 725  * <td>Get from metadata if exist.</td>
 726  * </tr>
 727  * <tr>
 728  * <td>latitude</td>
 729  * <td>#MEDIA_LATITUDE</td>
 730  * <td>Get from metadata if exist.</td>
 731  * </tr>
 732  * <tr>
 733  * <td>altitude</td>
 734  * <td>#MEDIA_ALTITUDE</td>
 735  * <td>Get from metadata if exist.</td>
 736  * </tr>
 737  * <tr>
 738  * <td>is_360_content</td>
 739  * <td>#MEDIA_360</td>
 740  * <td>Whether 360 content or not.</td>
 741  * </tr>
 742  * </table>
 743  * \n
 744  *<p>
 745  * For getting the video handle (#video_meta_h) from the media information (#media_info_h), call the media_info_get_video() function.\n
 746  * For getting the information related to video files stored in the device call the respective get functions e.g. to get duration of the video file
 747  * call #video_meta_get_duration() function  and so on.\n
 748  * When the video handle is no longer needed, it should be destroyed by calling #video_meta_destroy() function.
 749  *
 750  *
 751  *
 752  */
 753
 754
 755 /**
 756  * @defgroup CAPI_CONTENT_MEDIA_BOOK_META_MODULE Book Metadata
 757  * @brief The Book Metadata API provides functions to get information about ebook files present in the device.
 758  *
 759  * @ingroup CAPI_CONTENT_MEDIA_INFO_MODULE
 760  *
 761  * @section CAPI_CONTENT_MEDIA_BOOK_META_MODULE_HEADER Required Header
 762  *   \#include <media_content.h>
 763  *
 764  * @section CAPI_CONTENT_MEDIA_BOOK_META_MODULE_OVERVIEW Overview
 765  * The Book Metadata API provides functions to get information about book files present in the device.
 766  * Following information about book content (#book_meta_h) is provided:
 767  * <table>
 768  * <tr>
 769  * <th>Attribute</th>
 770  * <th>Filter Keyword</th>
 771  * <th>Comments</th>
 772  * </tr>
 773  * <tr>
 774  * <td>subject</td>
 775  * <td>#MEDIA_GENRE</td>
 776  * <td>Get from metadata if exist.</td>
 777  * </tr>
 778  * <tr>
 779  * <td>author</td>
 780  * <td>#MEDIA_COMPOSER</td>
 781  * <td>Get from metadata if exist.</td>
 782  * </tr>
 783  * <tr>
 784  * <td>date</td>
 785  * <td>#MEDIA_RECORDED_DATE</td>
 786  * <td>Get from metadata if exist.</td>
 787  * </tr>
 788  * <tr>
 789  * <td>publisher</td>
 790  * <td></td>
 791  * <td>Get from metadata if exist.</td>
 792  * </tr>
 793  * </table>
 794  * \n
 795  *<p>
 796  * For getting the book handle (#book_meta_h) from the media information (#media_info_h), call the media_info_get_book() function.\n
 797  * For getting the information related to book files stored in the device call the respective get functions e.g. to get author of the ebook file
 798  * call #book_meta_get_author() function  and so on.\n
 799  * When the book handle is no longer needed, it should be destroyed by calling #book_meta_destroy() function.
 800  */
 801
 802 /**
 803  * @defgroup CAPI_CONTENT_MEDIA_FACE_DETECTION_MODULE Face Detection(Deprecated)
 804  * @brief The Face Detection API provides functions to detect face information about stored image files.
 805  *
 806  * @ingroup CAPI_CONTENT_MEDIA_INFO_MODULE
 807  *
 808  * @section CAPI_CONTENT_MEDIA_FACE_DETECTION_MODULE_HEADER Required Header
 809  *   \#include <media_content.h>
 810  *
 811  * @section CAPI_CONTENT_MEDIA_FACE_DETECTION_MODULE_FEATURE Related Features
 812  * This API is related with the following feature: \n
 813  * - %http://tizen.org/feature/vision.face_recognition
 814  * It is recommended to create applications with regard to features, to increase reliability. \n
 815  *
 816  * You can check if a device supports the related features for this API by using @ref CAPI_SYSTEM_SYSTEM_INFO_MODULE, thereby controlling the procedure of your application. \n
 817  *
 818  * To ensure your application is only running on a device with specific features, please define the features in your manifest file using the manifest editor in the SDK. \n
 819  *
 820  * More details on featuring your application can be found from <a href="https://docs.tizen.org/application/tizen-studio/native-tools/manifest-text-editor#feature-element"><b>Feature Element</b>.</a>
 821  *
 822  * @section CAPI_CONTENT_MEDIA_FACE_DETECTION_MODULE_OVERVIEW Overview
 823  * The Face Detection API provides functions to detect face information associated with image files. \n
 824  * Face information detected by mediavision API. To detect faces, you should use media_info_start_face_detection() API. \n
 825  *
 826  * API allows to:
 827  * - start and cancel face detection with image files
 828  *
 829  *<p>
 830  * To start face detection, call the #media_info_start_face_detection() function.\n
 831  * To cancel face detection after it's been started, call the #media_info_cancel_face_detection() function.\n
 832  *
 833  */
 834
 835 /**
 836  * @defgroup CAPI_CONTENT_MEDIA_BOOKMARK_MODULE Media Bookmark
 837  * @brief The Media Bookmark Information API provides functions to manage bookmark information on the media items.
 838  *
 839  * @ingroup CAPI_MEDIA_CONTENT_MODULE
 840  *
 841  * @section CAPI_CONTENT_MEDIA_BOOKMARKINFO_MODULE_HEADER Required Header
 842  *   \#include <media_content.h>
 843  *
 844  * @section CAPI_CONTENT_MEDIA_BOOKMARKINFO_MODULE_OVERVIEW Overview
 845  * A Bookmark allows you to mark interesting moment in a media(video and audio) to enable fast searching.
 846  * The Bookmark Information API  provides functions to get information about bookmarks associated with video and audio items.
 847  *
 848  * API allows to:
 849  * - get and filter existing bookmarks
 850  * - insert new bookmarks
 851  * - delete bookmarks
 852  *
 853  * For inserting a bookmark to media item, call media_bookmark_insert_to_db() function and for deleting already set bookmark from a media, call
 854  * #media_bookmark_delete_from_db() function.
 855  * For retrieving time where the bookmark is placed on the media, call #media_bookmark_get_marked_time() function.
 856  *
 857  * @subsection CAPI_CONTENT_MEDIA_BOOKMARKINFO_FOREACH_OPERATIONS Foreach Operations
 858  * <div><table class="doxtable" >
 859  *     <tr>
 860  *        <th><b>FOREACH</b></th>
 861  *        <th><b>CALLBACK</b></th>
 862  *        <th><b>DESCRIPTION</b></th>
 863  *     </tr>
 864  *     <tr>
 865  *        <td>media_info_foreach_bookmark_from_db()</td>
 866  *        <td>media_bookmark_cb()</td>
 867  *        <td>Iterates through bookmarks</td>
 868  *     </tr>
 869  *</table></div>
 870  *
 871  *
 872  */
 873
 874 /**
 875  * @defgroup CAPI_CONTENT_MEDIA_INFO_MODULE Media Information
 876  * @brief The Media Information API provides functions to get information about media items
 877  * stored on an internal and external storage.
 878  *
 879  * @ingroup CAPI_MEDIA_CONTENT_MODULE
 880  *
 881  * @section CAPI_CONTENT_MEDIA_INFO_MODULE_HEADER Required Header
 882  *   \#include <media_content.h>
 883  *
 884  * @section CAPI_CONTENT_MEDIA_INFO_MODULE_OVERVIEW Overview
 885  *
 886  * The Media Information API provides functions to get basic information e.g. path, date, type etc about media items (#media_info_h) present in the device.
 887  * Media Information (#media_info_h) is a generalization of media content of any type (audio, image, video and others).
 888  *
 889  * Received information about media items can be the processed using dedicated APIs:
 890  * <table>
 891  * <tr>
 892  *    <th>API</th>
 893  *    <th>Description</th>
 894  * </tr>
 895  * <tr>
 896  *    <td>@ref CAPI_CONTENT_MEDIA_INFO_MODULE </td>
 897  *    <td> Provides details about all items present in the device.\n
 898  * Provide functions to get information (e.g. title, size, mime type etc) about the files.</td>
 899  * </tr>
 900  * <tr>
 901  *    <td>@ref CAPI_CONTENT_MEDIA_AUDIO_META_MODULE </td>
 902  *    <td> Provides details about audio items present in the device.\n
 903  * Provide functions to get information (e.g. genre, album, year, bitrate etc) about the audio files.</td>
 904  * </tr>
 905  * <tr>
 906  *    <td>@ref CAPI_CONTENT_MEDIA_FACE_DETECTION_MODULE </td>
 907  *    <td> Provide functions to detect faces from image. </td>
 908  * </tr>
 909  * <tr>
 910  *    <td>@ref CAPI_CONTENT_MEDIA_IMAGE_META_MODULE </td>
 911  *    <td> Provides details about image items present in the device.\n
 912  * Provide functions to get information (e.g. longitude, description, date etc) about the image files.</td>
 913  * </tr>
 914  * <tr>
 915  *    <td>@ref CAPI_CONTENT_MEDIA_VIDEO_META_MODULE (Deprecated)</td>
 916  *    <td> Provides details about video items present in the device.\n
 917  * Provide functions to get information (e.g. duration, date etc) about the video files.</td>
 918  * </tr>
 919  * </table>
 920  * \n
 921  * The media information API provides the following information. Regarding the information of each media type (audio, video, or image), please refer to the type-specific metadata page.
 922  *
 923  * <table>
 924  * <tr>
 925  * <th>Attribute</th>
 926  * <th>Filter Keyword</th>
 927  * <th>Comments</th>
 928  * </tr>
 929  * <tr>
 930  * <td>media_id</td>
 931  * <td>#MEDIA_ID</td>
 932  * <td>UUID</td>
 933  * </tr>
 934  * <tr>
 935  * <td>file_path</td>
 936  * <td>#MEDIA_PATH</td>
 937  * <td>Full path of the file</td>
 938  * </tr>
 939  * <tr>
 940  * <td>display_name</td>
 941  * <td>#MEDIA_DISPLAY_NAME</td>
 942  * <td>Base name of the file</td>
 943  * </tr>
 944  * <tr>
 945  * <td>media_type</td>
 946  * <td>#MEDIA_TYPE</td>
 947  * <td>Type (media_content_type_e)</td>
 948  * </tr>
 949  * <tr>
 950  * <td>mime_type</td>
 951  * <td>#MEDIA_MIME_TYPE</td>
 952  * <td>MIME type</td>
 953  * </tr>
 954  * <tr>
 955  * <td>size</td>
 956  * <td>#MEDIA_SIZE</td>
 957  * <td>File size</td>
 958  * </tr>
 959  * <tr>
 960  * <td>added_time</td>
 961  * <td>#MEDIA_ADDED_TIME</td>
 962  * <td>Added time to Media DB</td>
 963  * </tr>
 964  * <tr>
 965  * <td>modified_time</td>
 966  * <td>#MEDIA_MODIFIED_TIME</td>
 967  * <td>Time of last modification</td>
 968  * </tr>
 969  * <tr>
 970  * <td>timeline</td>
 971  * <td>#MEDIA_TIMELINE</td>
 972  * <td>Same as date taken time(for image) or recorded time(for Audio/Video) if exit. if not, same as modified time.</td>
 973  * </tr>
 974  * <tr>
 975  * <td>is_drm</td>
 976  * <td>#MEDIA_IS_DRM</td>
 977  * <td>Whether DRM content or not</td>
 978  * </tr>
 979  * <tr>
 980  * <td>favorite</td>
 981  * <td>#MEDIA_FAVOURITE</td>
 982  * <td>User data. Not guarantee independence between applications.</td>
 983  * </tr>
 984  * <tr>
 985  * <td>thumbnail_path</td>
 986  * <td>#MEDIA_THUMBNAIL_PATH</td>
 987  * <td>Thumbnail path(album art for Audio) if exist.</td>
 988  * </tr>
 989  * <tr>
 990  * <td>description</td>
 991  * <td></td>
 992  * <td>Get from metadata if exist.</td>
 993  * </tr>
 994  * </table>
 995  * \n
 996  *
 997  * Video and Audio information can be further processed with respect to its properties i.e. playlist, album, using their respective APIs.
 998  * - @ref CAPI_CONTENT_MEDIA_PLAYLIST_MODULE
 999  * - @ref CAPI_CONTENT_MEDIA_ALBUM_MODULE
1000  * - @ref CAPI_CONTENT_MEDIA_BOOKMARK_MODULE
1001  *
1002  *
1003  * @subsection CAPI_CONTENT_MEDIA_INFO_FOREACH_OPERATIONS Foreach Operations
1004  * <div><table class="doxtable">
1005  *     <tr>
1006  *        <th><b>FOREACH</b></th>
1007  *        <th><b>CALLBACK</b></th>
1008  *        <th><b>DESCRIPTION</b></th>
1009  *     </tr>
1010  *     <tr>
1011  *        <td>media_info_foreach_media_from_db()</td>
1012  *        <td>media_info_cb()</td>
1013  *        <td>Iterates through items</td>
1014  *     </tr>
1015  *     <tr>
1016  *        <td>media_info_foreach_tag_from_db()</td>
1017  *        <td>media_tag_cb()</td>
1018  *        <td>Iterate through tags</td>
1019  *     </tr>
1020  *     <tr>
1021  *        <td>media_info_foreach_bookmark_from_db()</td>
1022  *        <td>media_bookmark_cb()</td>
1023  *        <td>Iterate through bookmark</td>
1024  *     </tr>
1025  * </table></div>
1026  *
1027  *
1028  *
1029  */
1030
1031 /**
1032  * @defgroup CAPI_CONTENT_MEDIA_FACE_MODULE Media Face(Deprecated)
1033  * @brief The Media Face Information API provides functions to manage the face information in the image files.
1034  *
1035  * @ingroup CAPI_MEDIA_CONTENT_MODULE
1036  *
1037  * @section CAPI_CONTENT_MEDIA_FACE_MODULE_HEADER Required Header
1038  *   \#include <media_content.h>
1039  *
1040  * @section CAPI_CONTENT_MEDIA_FACE_MODULE_OVERVIEW Overview
1041  * The Face Information API provides functions to manage the face information such as face id, face coordinates in the image files.\n
1042  *
1043  *
1044  */
1045
1046
1047 #endif /* __TIZEN_MEDIA_CONTENT_DOC_H__ */