include/SLP_MediaSvc_PG.h

   1 /*
   2  * libmedia-service
   3  *
   4  * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Contact: Hyunjun Ko <zzoon.ko@samsung.com>, Haejeong Kim <backto.kim@samsung.com>
   7  *
   8  * Licensed under the Apache License, Version 2.0 (the "License");
   9  * you may not use this file except in compliance with the License.
  10  * You may obtain a copy of the License at
  11  *
  12  * http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  * Unless required by applicable law or agreed to in writing, software
  15  * distributed under the License is distributed on an "AS IS" BASIS,
  16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  * See the License for the specific language governing permissions and
  18  * limitations under the License.
  19  *
  20  */
  21
  22 /**
  23  *
  24  * @defgroup   MB_SVC_PG Media Service
  25  * @ingroup SLP_PG
  26    @{
  27
  28
  29 <h1 class="pg">Introduction</h1>
  30 <h2 class="pg">Purpose</h2>
  31
  32 The purpose of this document is to give the application developer detailed information to access  media(images and videos) database using the Media Service API's.
  33
  34
  35 <h2 class="pg">Scope</h2>
  36
  37 The scope of this document is limited to Samsung platform Media Service API usage.
  38
  39 <h2 class="pg">Abbreviations</h2>
  40
  41         <table>
  42                 <tr>
  43                         <td>
  44                           Media
  45                         </td>
  46                         <td>
  47                          In this document, Media items mean multimedia items including image and video, not music. If you want to manage music items, Please see Music Service Document
  48                         </td>
  49                 </tr>
  50                 <tr>
  51                         <td>
  52                         API
  53                         </td>
  54                         <td>
  55                         Application Programming Interface
  56                         </td>
  57                 </tr>
  58                 <tr>
  59                         <td>
  60                           Cluster
  61                         </td>
  62                         <td>
  63                          a collection of related images or videos like Album or Folder
  64                         </td>
  65                 </tr>
  66                 <tr>
  67                         <td>
  68                           extractor
  69                         </td>
  70                         <td>
  71                           Extracts metadata associated with a particular media format from a file or records in the databases.
  72                         </td>
  73                 </tr>
  74                 <tr>
  75                         <td>
  76                           File manager service
  77                         </td>
  78                         <td>
  79                           Detect and manage all of file system chagnes.
  80                         </td>
  81                 </tr>
  82         </table>
  83
  84 <h1 class="pg"> Media Service Architecture</h1>
  85
  86
  87 Media Service is designed to provide easy to use services for accessing media library database based on an embedded Linux platform.
  88 Media Service is used to maintain media content in SQLite database. The content stored in database consists of media items from both MMC and Phone flash.
  89
  90
  91 <h2 class="pg">Features</h2>
  92 You can use Media Service to organize your digital media collection.
  93 You can do a number of things with them, including playing, creating playlists.
  94
  95 - Add media items to the media database.
  96         - File manager service automatically searches certain default folders on your phone     and MMC for media files, and then adds those files to the system media database.  If you ever add or remove files from these folders, File manager service automatically updates the database accordingly.
  97
  98 - Delete media items from the media database.
  99         - You can delete a media file from the library, and it will be removed forever in your device.
 100
 101 - Find media items in the media database.
 102         - Media Service provides smart search for you to find items in the media database. To ensure that you can easily find items in the database, it is important that files have accurate and complete media information.
 103
 104 - Organizing media items in the media database.
 105         - Media Service provides a great way to organize media items in the media database as you want. You can also sort by name, date, or etc.
 106
 107 <h2 class="pg">Architecture diagram</h2>
 108
 109
 110 <b>Modules</b>
 111
 112 - User Interface
 113         - User interface is a group of api, which is open to public. User could access and control media data in the media database with using these apis. Also, user could extract thumbnail from media of image or video.
 114
 115 - List Organizer
 116         - List organizer performs querying db, organizing and returning results as a type of list. This component return a list, which is sorted by what user wants, for example, by name or date.
 117
 118 - Database Manager
 119          - Database manager is responsible for database manipulation, such as open database, close database, create table, set the storage validation, and delete the storage contents.
 120
 121 - Thumbnail Extractor
 122         - Thumbnail extractor supports for user to extract a thumbnail from media of image or video. Also, user could get the path of the produced thumbnail.
 123
 124
 125 @image html SLP_MediaSvc_PG_image001.png
 126
 127 <h1 class="pg">Database Schema Design</h1>
 128
 129 This image describes the design of the media database schema.
 130
 131 @image html SLP_MediaSvc_PG_image002.png
 132
 133 <h1 class="pg"> API descriptions </h2>
 134
 135 <h2 class="pg"> Open and close media service </h2>
 136
 137 <b> Purpose </b>
 138 - To be prepared for accessing to the media database.
 139         - Use function minfo_init().
 140 - To be finalized for accessing to the media database.
 141         - Use function minfo_finalize().
 142 - Applications should call minfo_init() before using media-svc and call minfo_finalize() after finishing jobs in related to the media-svc.
 143
 144 The following is a sample code:
 145
 146 @code
 147         #include <media-svc.h>
 148
 149         int ret = -1;
 150
 151         //open a databse file.
 152         ret = minfo_init();
 153         if(ret< 0)
 154         {
 155                 printf("minfo_init error\n");
 156                 return ret;
 157         }
 158
 159         //close database file.
 160         ret = minfo_finalize();
 161
 162         if(ret< 0)
 163         {
 164                 printf("minfo_finalize error\n");
 165                 return ret;
 166         }
 167
 168 @endcode
 169
 170 <h2 class="pg"> Get a cluster list of media </h2>
 171 <b> Purpose </b>
 172 - To get a list of clusters in the media database.
 173
 174 <b> Usage </b>
 175 - User can set the minfo_cluster_filter to get what user wants.
 176         - User can set minfo_folder_type
 177                 - MINFO_CLUSTER_TYPE_ALL : All type of media
 178                 - MINFO_CLUSTER_TYPE_LOCAL_ALL : lcoal both phone and mmc
 179                 - MINFO_CLUSTER_TYPE_LOCAL_PHONE : lcoal phone only
 180                 - MINFO_CLUSTER_TYPE_LOCAL_MMC : lcoal mmc only
 181                 - MINFO_CLUSTER_TYPE_WEB : web album
 182                 - MINFO_CLUSTER_TYPE_STREAMING : streaming album
 183         - User can set minfo_folder_sort_type
 184                 - MINFO_CLUSTER_SORT_BY_NONE : No Sort
 185                 - MINFO_CLUSTER_SORT_BY_NAME_DESC : Sort by display name descending
 186                 - MINFO_CLUSTER_SORT_BY_NAME_ASC : Sort by display name ascending
 187                 - MINFO_CLUSTER_SORT_BY_DATE_DESC : Sort by modified_date descending
 188                 - MINFO_CLUSTER_SORT_BY_DATE_ASC : Sort by modified_date ascending
 189         - User can set start position and end position.
 190                 - If user want to get all clusters in the database, set -1 to both.
 191         - User should define a iterative callback to insert clusters to user list. It makes user to be able to use specific list type user wants.
 192
 193 The following is a sample code:
 194
 195 @code
 196 #include <media-svc.h>
 197
 198 static int _cluster_ite_fn( Mcluster* cluster, void* user_data)
 199 {
 200         GList** list = (GList**) user_data;
 201         *list = g_list_append( *list, cluster );
 202
 203         return 0;
 204 }
 205
 206 int get_cluster_list_exam()
 207 {
 208         int err = -1;
 209         int img_cnt = 0;
 210         int i;
 211         Mcluster* cluster;
 212         GList* list = NULL
 213
 214         minfo_cluster_filter cluster_filter_all ={MINFO_CLUSTER_TYPE_ALL,MINFO_CLUSTER_SORT_BY_DATE_ASC,0,10};
 215         minfo_cluster_filter cluster_filter_mmc ={MINFO_CLUSTER_TYPE_LOCAL_MMC,MINFO_CLUSTER_SORT_BY_NAME_DESC, -1, -1};
 216
 217         err = minfo_get_cluster_list(cluster_filter_all, _cluster_ite_fn, &p_list);
 218
 219         if( err < 0)
 220         {
 221                  printf("minfo_get_cluster_list failed\n");
 222                  return -1;
 223         }
 224
 225         img_cnt = g_list_length(p_list);
 226
 227         for(i=0; i<img_cnt; i++)
 228         {
 229                 cluster = (Mcluster*)g_list_nth_data(p_list, i);
 230                 printf("cluster ID=%d, sns_type = %d, display_name= %s, \n", cluster->_id, cluster->sns_type,cluster->display_name);
 231         }
 232
 233         err = minfo_get_cluster_list(cluster_filter_mmc, _cluster_ite_fn, &p_list);
 234
 235         if( err < 0)
 236         {
 237                  printf("minfo_get_cluster_list failed\n");
 238                  return -1;
 239         }
 240
 241         img_cnt = g_list_length(p_list);
 242
 243         for(i=0; i<img_cnt; i++)
 244         {
 245                 cluster = (Mcluster*)g_list_nth_data(p_list, i);
 246                 printf("cluster ID=%d, sns_type = %d, display_name= %s, \n", cluster->_id, cluster->sns_type,cluster->display_name);
 247         }
 248
 249         return 0;
 250 }
 251
 252 @endcode
 253
 254 <h2 class="pg"> Get a item list of media </h2>
 255 <b> Purpose </b>
 256 - To get a list of items in a cluster in the media database.
 257
 258 <b> Usage </b>
 259 - User can set minfo_item_filter to get what user wants.
 260         - User can set minfo_file_type
 261                 - MINFO_ITEM_NONE : none
 262                 - MINFO_ITEM_IMAGE : image files
 263                 - MINFO_ITEM_VIDEO : video files
 264         - User can set minfo_media_sort_type
 265                 - MINFO_MEDIA_SORT_BY_NONE : No Sort
 266                 - MINFO_MEDIA_SORT_BY_NAME_DESC : Sort by display name descending
 267                 - MINFO_MEDIA_SORT_BY_NAME_ASC : Sort by display name ascending
 268                 - MINFO_MEDIA_SORT_BY_DATE_DESC : Sort by modified_date descending
 269                 - MINFO_MEDIA_SORT_BY_DATE_ASC : Sort by modified_date ascending
 270         - User can set minfo_media_favorite_type
 271                 - MINFO_MEDIA_FAV_ALL : Includes all favorite and unfavorite media
 272                 - MINFO_MEDIA_FAV_ONLY : Includes only favorite media
 273                 - MINFO_MEDIA_UNFAV_ONLY : Includes only unfavorite media
 274         - User can set start position and end position.
 275                 - If user want to get all items in the cluster, set -1 to both.
 276         - User should define a iterative callback to insert items to user list. It makes user to be able to use specific list type user wants.
 277
 278 The following is a sample code:
 279
 280 @code
 281
 282 static int _ite_fn( Mitem* item, void* user_data)
 283 {
 284         GList** list = (GList**) user_data;
 285         *list = g_list_append( *list, item );
 286
 287         return 0;
 288 }
 289
 290 int get_item_list_exam()
 291 {
 292         int err = -1;
 293         int img_cnt = 0;
 294         int cluster_id = 0;
 295         int i;
 296         Mcluster* cluster;
 297         Mitem* cluster;
 298         GList* list = NULL
 299
 300         minfo_item_filter item_filter_all = {MINFO_ITEM_ALL,MINFO_MEDIA_SORT_BY_NONE,-1,-1,false,MINFO_MEDIA_FAV_ALL};
 301         minfo_item_filter item_filter_image = {MINFO_ITEM_IMAGE,MINFO_MEDIA_SORT_BY_DATE_DESC,0,1,FALSE, MINFO_MEDIA_FAV_ONLY};
 302
 303         // Id of the cluster in which user want to get items
 304         cluster_id = 1;
 305         err = minfo_get_item_list(cluster_id, item_filter_all, _ite_fn, &p_list);
 306
 307         if( err < 0)
 308         {
 309                 printf("minfo_get_item_list failed\n");
 310                 return -1;
 311         }
 312
 313         img_cnt = g_list_length(p_list);
 314
 315         for(i=0; i<img_cnt; i++)
 316         {
 317                 mitem = (Mitem*)g_list_nth_data(p_list, i);
 318                 printf("mitem ID=%d, %s\n",mitem->_id, mitem->file_url);
 319         }
 320
 321         err = minfo_get_item_list(cluster_id, item_filter_image, &p_list);
 322
 323         if( err < 0)
 324         {
 325                 printf("minfo_get_item_list failed\n");
 326                 return -1;
 327         }
 328
 329         img_cnt = g_list_length(p_list);
 330
 331         for(i=0; i<img_cnt; i++)
 332         {
 333                 mitem = (Mitem*)g_list_nth_data(p_list, i);
 334                 printf("mitem ID=%d, %p\n",mitem->_id, mitem);
 335         }
 336 }
 337
 338 @endcode
 339
 340 <h2 class="pg"> Delete a user list, which is got by media-svc </h2>
 341 <b> Purpose </b>
 342 - To delete media-svc items that user get through media-svc api.
 343
 344 <b> Usage </b>
 345 - To delete media-svc specified items, user should call minfo_destroy_mtype_item(). It can delete all media-svc specified types below:
 346         - Mcluster
 347         - Mitem
 348         - Mmeta
 349         - Mbookmark
 350
 351 The following is a sample code:
 352
 353 @code
 354
 355 // plist is a list which user get through media-svc api
 356 int delete_all_mediasvc_items_exam(GList** plist)
 357 {
 358         int count = 0;
 359         int i = 0;
 360         void* item = NULL;
 361
 362         if(p_list == NULL)
 363         {
 364                 mb_svc_debug("p_list == NULL\n");
 365                 return MB_SVC_ERROR_INVALID_ARG;
 366         }
 367
 368         count = g_list_length(*p_list);
 369
 370         for(i = 0; i < count; i++)
 371         {
 372                 item = (void*)g_list_nth_data(*p_list, i);
 373
 374                 minfo_destroy_mtype_item(item);
 375                 item = NULL;
 376         }
 377
 378         g_list_free(*p_list);
 379         *p_list = NULL;
 380         return 0;
 381 }
 382
 383
 384 @endcode
 385
 386 <h2 class="pg"> Add a cluster to DB</h2>
 387 <b> Purpose </b>
 388 - To make and add new cluster to the media database.
 389
 390 <b> Usage </b>
 391 - User must specify the url of the cluster path.
 392 - User can get the id of the new cluster.
 393
 394 The following is a sample code:
 395
 396 @code
 397
 398 int minfo_add_cluster_exam()
 399 {
 400         const char* cluster_url = "/opt/media/Images and videos/new";
 401         int new_cluster_id;
 402
 403         err = minfo_add_cluster(cluster_url, &new_cluster_id);
 404
 405         if( err < 0)
 406         {
 407                 printf("minfo_add_media failed\n");
 408                 return -1;
 409         }
 410         else
 411         {
 412                 printf("minfo_add_media succeed. New cluster's id is %d\n", new_cluster_id);
 413                 return 0;
 414         }
 415 }
 416
 417 @endcode
 418
 419 <h2 class="pg"> Delete a cluster from DB</h2>
 420 <b> Purpose </b>
 421 - To delete a cluster in the media database.
 422
 423 <b> Usage </b>
 424 - User can delete a media by the id of the cluster.
 425
 426 The following is a sample code:
 427
 428 @code
 429
 430 int minfo_delete_cluster_exam()
 431 {
 432         int cluster_id = 1;
 433
 434         err = minfo_delete_cluster(cluster_id);
 435
 436         if( err < 0)
 437         {
 438                 printf("minfo_delete_media failed\n");
 439                 return -1;
 440         }
 441 }
 442
 443 @endcode
 444
 445 <h2 class="pg"> Add a media to DB</h2>
 446 <b> Purpose </b>
 447 - To add user's media item to the media database.
 448
 449 <b> Usage </b>
 450 - User must specify the url of the media file.
 451 - User must specify a type of the media. ( image or video )
 452
 453 The following is a sample code:
 454
 455 @code
 456
 457 int minfo_add_media_exam()
 458 {
 459         const char* file_url = "/opt/media/Images and videos/image.jpg";
 460         minfo_file_type type = MINFO_ITEM_IMAGE;
 461
 462         err = minfo_add_media(file_url, type);
 463
 464         if( err < 0)
 465         {
 466                 printf("minfo_add_media failed\n");
 467                 return -1;
 468         }
 469 }
 470
 471 @endcode
 472
 473 <h2 class="pg"> Update a media to DB</h2>
 474 <b> Purpose </b>
 475 - To update media in the media database.
 476
 477 <b> Usage </b>
 478 - To update a name of cluster, call minfo_update_cluster_name()
 479         -User must specify the id of the cluster and new name user wants.
 480 - To update a favorite set of media item, call minfo_update_media_favorite()
 481         -User must specify the id of the media and a value of favorite ( true or false )
 482 - To update a name of media item, call minfo_update_media_name()
 483         -User must specify the id of the media and new name user wants.
 484 - To update meta information of integer type of video item, call minfo_update_video_meta_info_int()
 485         - User can set minfo_video_meta_field_t
 486                 - MINFO_VIDEO_META_ID :  media medta ID field
 487                 - MINFO_VIDEO_META_MEDIA_ID media medta ID field
 488                 - MINFO_VIDEO_META_BOOKMARK_LAST_PLAYED : medta bookmark field
 489                 - MINFO_VIDEO_META_DURATION : medta duration field
 490 - To update meta information of string type of video item, call minfo_update_video_meta_info_string()
 491         - User can set minfo_video_meta_field_t
 492                 - MINFO_VIDEO_META_ALBUM : medta album field
 493                 - MINFO_VIDEO_META_ARTIST : medta artist field
 494                 - MINFO_VIDEO_META_TITLE : medta title field
 495                 - MINFO_VIDEO_META_DESCRIPTION : medta description field
 496                 - MINFO_VIDEO_META_YOUTUBE_CATEGORY : medta youtube cat field
 497
 498 The following is a sample code:
 499
 500 @code
 501
 502 int minfo_update_cluster_name_exam()
 503 {
 504         int err = -1;
 505         int cluster_id = 1;
 506         const char* new_name = "NewCluster";
 507
 508         err = minfo_update_cluster_name(cluster_id, new_name);
 509
 510         if( err < 0)
 511         {
 512                 printf("minfo_update_cluster_name failed\n");
 513                 return -1;
 514         }
 515 }
 516
 517 int minfo_update_media_name_exam()
 518 {
 519         int err = -1;
 520         int media_id = 1;
 521         const char* new_name = "NewMedia";
 522
 523         err = minfo_update_media_name(media_id, new_name);
 524
 525         if( err < 0)
 526         {
 527                 printf("minfo_update_media_name failed\n");
 528                 return -1;
 529         }
 530 }
 531
 532 int minfo_update_media_favorite_exam()
 533 {
 534         int err = -1;
 535         int media_id = 1;
 536         int favorite = TRUE;
 537
 538         err = minfo_update_media_favorite(media_id, favorite);
 539
 540         if( err < 0)
 541         {
 542                 printf("minfo_update_media_favorite failed\n");
 543                 return -1;
 544         }
 545 }
 546
 547 int minfo_update_media_videometa_exam()
 548 {
 549         int err = -1;
 550         int media_id = 1;
 551         minfo_video_meta_field_t meta_field;
 552         int last_played_time = 1259000000;
 553         const char* title = "New Title";
 554
 555         // Update last played time
 556         err = minfo_update_video_meta_info_int(media_id, last_played_time);
 557
 558         if( err < 0)
 559         {
 560                 printf("minfo_update_video_meta_info_int failed\n");
 561                 return -1;
 562         }
 563
 564         // Update title
 565         err = minfo_update_video_meta_info_string(media_id, title);
 566
 567         if( err < 0)
 568         {
 569                 printf("minfo_update_video_meta_info_string failed\n");
 570                 return -1;
 571         }
 572 }
 573
 574 @endcode
 575
 576 <h2 class="pg">  Copy media </h2>
 577 <b> Purpose </b>
 578 - To copy media from original folder to the other folder, not only updating database but also operating system call.
 579
 580 <b> Usage </b>
 581 - User can copy a media by the path of origin media and the path of destination cluster. In this case, user should call minfo_copy_media().
 582         - User must specify minfo_file_type.
 583                 - MINFO_ITEM_IMAGE : image
 584                 - MINFO_ITEM_VIDEO : video
 585 - User can copy a media by the id of the origin media and the id of destination cluster. In this case, user should call minfo_cp_media().
 586
 587 The following is a sample code:
 588
 589 @code
 590
 591 int minfo_copy_exam_by_path()
 592 {
 593         const char* file_url = "/opt/media/Images and videos/image.jpg";
 594         const char* dest_url = "/opt/media/Images and videos/second";
 595         minfo_file_type file_type = MINFO_ITEM_IMAGE;
 596
 597         err = minfo_copy_media(file_url, dest_url, file_type);
 598
 599         if( err < 0)
 600         {
 601                 printf("minfo_copy_media failed\n");
 602                 return -1;
 603         }
 604 }
 605
 606 int minfo_copy_exam_by_id()
 607 {
 608         int media_id = 1;
 609         int dest_cluster_id = 3;
 610
 611         err = minfo_cp_media(media_id, dest_cluster_id );
 612
 613         if( err < 0)
 614         {
 615                 printf("minfo_copy_media failed\n");
 616                 return -1;
 617         }
 618 }
 619
 620 @endcode
 621
 622 <h2 class="pg">  Move media </h2>
 623 <b> Purpose </b>
 624 - To move media from original folder to the other folder, not only updating database but also operating system call.
 625
 626 <b> Usage </b>
 627 - User can move a media by the path of origin media and the path of destination cluster. In this case, user should call minfo_move_media().
 628         - User must specify minfo_file_type.
 629                 - MINFO_ITEM_IMAGE : image
 630                 - MINFO_ITEM_VIDEO : video
 631 - User can move a media by the id of the origin media and the id of destination cluster. In this case, user should call minfo_mv_media().
 632
 633 The following is a sample code:
 634
 635 @code
 636
 637 int minfo_move_exam_by_path()
 638 {
 639         const char* file_url = "/opt/media/Images and videos/image.jpg";
 640         const char* dest_url = "/opt/media/Images and videos/second";
 641         minfo_file_type file_type = MINFO_ITEM_IMAGE;
 642
 643         err = minfo_move_media(file_url, dest_url, file_type);
 644
 645         if( err < 0)
 646         {
 647                 printf("minfo_move_media failed\n");
 648                 return -1;
 649         }
 650 }
 651
 652 int minfo_move_exam_by_id()
 653 {
 654         int media_id = 1;
 655         int dest_cluster_id = 3;
 656
 657         err = minfo_mv_media(media_id, dest_cluster_id );
 658
 659         if( err < 0)
 660         {
 661                 printf("minfo_mv_media failed\n");
 662                 return -1;
 663         }
 664 }
 665
 666 @endcode
 667
 668 <h2 class="pg"> Get a thumbnail of media </h2>
 669 <b> Purpose </b>
 670 - To get thumbnail of the choosen media.
 671
 672 <b> Usage </b>
 673 - User must specify the url of the video or image media .
 674 - If thumbnail of the media exists, just set the filepath of the thumbnail. If not, create new thumbnail and set the filepath of the thumbnail.
 675
 676 The following is a sample code:
 677
 678 @code
 679
 680 int minfo_get_thumb_path_exam()
 681 {
 682         int ret = -1;
 683         const char* file_url = "/opt/media/Images and videos/image.jpg";
 684         char thumb_path[255] = {0,};
 685
 686
 687         ret = minfo_get_thumb_path(file_url, thumb_path, 255);
 688
 689         if(ret < 0)
 690         {
 691                 printf("minfo_get_thumb_path fails\n" );
 692                 return -1;
 693         }
 694
 695         printf("minfo_get_thumb_path : %s\n", thumb_path);
 696 }
 697
 698 @endcode
 699
 700 @}
 701 */
 702