4 * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
6 * Contact: Hyunjun Ko <zzoon.ko@samsung.com>, Haejeong Kim <backto.kim@samsung.com>
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
12 * http://www.apache.org/licenses/LICENSE-2.0
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.
24 * @defgroup MB_SVC_PG Media Service
29 <h1 class="pg">Introduction</h1>
30 <h2 class="pg">Purpose</h2>
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.
35 <h2 class="pg">Scope</h2>
37 The scope of this document is limited to Samsung platform Media Service API usage.
39 <h2 class="pg">Abbreviations</h2>
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
55 Application Programming Interface
63 a collection of related images or videos like Album or Folder
71 Extracts metadata associated with a particular media format from a file or records in the databases.
79 Detect and manage all of file system chagnes.
84 <h1 class="pg"> Media Service Architecture</h1>
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.
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.
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.
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.
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.
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.
107 <h2 class="pg">Architecture diagram</h2>
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.
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.
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.
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.
125 @image html SLP_MediaSvc_PG_image001.png
127 <h1 class="pg">Database Schema Design</h1>
129 This image describes the design of the media database schema.
131 @image html SLP_MediaSvc_PG_image002.png
133 <h1 class="pg"> API descriptions </h2>
135 <h2 class="pg"> Open and close media service </h2>
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.
144 The following is a sample code:
147 #include <media-svc.h>
151 //open a databse file.
155 printf("minfo_init error\n");
159 //close database file.
160 ret = minfo_finalize();
164 printf("minfo_finalize error\n");
170 <h2 class="pg"> Get a cluster list of media </h2>
172 - To get a list of clusters in the media database.
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.
193 The following is a sample code:
196 #include <media-svc.h>
198 static int _cluster_ite_fn( Mcluster* cluster, void* user_data)
200 GList** list = (GList**) user_data;
201 *list = g_list_append( *list, cluster );
206 int get_cluster_list_exam()
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};
217 err = minfo_get_cluster_list(cluster_filter_all, _cluster_ite_fn, &p_list);
221 printf("minfo_get_cluster_list failed\n");
225 img_cnt = g_list_length(p_list);
227 for(i=0; i<img_cnt; i++)
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);
233 err = minfo_get_cluster_list(cluster_filter_mmc, _cluster_ite_fn, &p_list);
237 printf("minfo_get_cluster_list failed\n");
241 img_cnt = g_list_length(p_list);
243 for(i=0; i<img_cnt; i++)
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);
254 <h2 class="pg"> Get a item list of media </h2>
256 - To get a list of items in a cluster in the media database.
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.
278 The following is a sample code:
282 static int _ite_fn( Mitem* item, void* user_data)
284 GList** list = (GList**) user_data;
285 *list = g_list_append( *list, item );
290 int get_item_list_exam()
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};
303 // Id of the cluster in which user want to get items
305 err = minfo_get_item_list(cluster_id, item_filter_all, _ite_fn, &p_list);
309 printf("minfo_get_item_list failed\n");
313 img_cnt = g_list_length(p_list);
315 for(i=0; i<img_cnt; i++)
317 mitem = (Mitem*)g_list_nth_data(p_list, i);
318 printf("mitem ID=%d, %s\n",mitem->_id, mitem->file_url);
321 err = minfo_get_item_list(cluster_id, item_filter_image, &p_list);
325 printf("minfo_get_item_list failed\n");
329 img_cnt = g_list_length(p_list);
331 for(i=0; i<img_cnt; i++)
333 mitem = (Mitem*)g_list_nth_data(p_list, i);
334 printf("mitem ID=%d, %p\n",mitem->_id, mitem);
340 <h2 class="pg"> Delete a user list, which is got by media-svc </h2>
342 - To delete media-svc items that user get through media-svc api.
345 - To delete media-svc specified items, user should call minfo_destroy_mtype_item(). It can delete all media-svc specified types below:
351 The following is a sample code:
355 // plist is a list which user get through media-svc api
356 int delete_all_mediasvc_items_exam(GList** plist)
364 mb_svc_debug("p_list == NULL\n");
365 return MB_SVC_ERROR_INVALID_ARG;
368 count = g_list_length(*p_list);
370 for(i = 0; i < count; i++)
372 item = (void*)g_list_nth_data(*p_list, i);
374 minfo_destroy_mtype_item(item);
378 g_list_free(*p_list);
386 <h2 class="pg"> Add a cluster to DB</h2>
388 - To make and add new cluster to the media database.
391 - User must specify the url of the cluster path.
392 - User can get the id of the new cluster.
394 The following is a sample code:
398 int minfo_add_cluster_exam()
400 const char* cluster_url = "/opt/media/Images and videos/new";
403 err = minfo_add_cluster(cluster_url, &new_cluster_id);
407 printf("minfo_add_media failed\n");
412 printf("minfo_add_media succeed. New cluster's id is %d\n", new_cluster_id);
419 <h2 class="pg"> Delete a cluster from DB</h2>
421 - To delete a cluster in the media database.
424 - User can delete a media by the id of the cluster.
426 The following is a sample code:
430 int minfo_delete_cluster_exam()
434 err = minfo_delete_cluster(cluster_id);
438 printf("minfo_delete_media failed\n");
445 <h2 class="pg"> Add a media to DB</h2>
447 - To add user's media item to the media database.
450 - User must specify the url of the media file.
451 - User must specify a type of the media. ( image or video )
453 The following is a sample code:
457 int minfo_add_media_exam()
459 const char* file_url = "/opt/media/Images and videos/image.jpg";
460 minfo_file_type type = MINFO_ITEM_IMAGE;
462 err = minfo_add_media(file_url, type);
466 printf("minfo_add_media failed\n");
473 <h2 class="pg"> Update a media to DB</h2>
475 - To update media in the media database.
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
498 The following is a sample code:
502 int minfo_update_cluster_name_exam()
506 const char* new_name = "NewCluster";
508 err = minfo_update_cluster_name(cluster_id, new_name);
512 printf("minfo_update_cluster_name failed\n");
517 int minfo_update_media_name_exam()
521 const char* new_name = "NewMedia";
523 err = minfo_update_media_name(media_id, new_name);
527 printf("minfo_update_media_name failed\n");
532 int minfo_update_media_favorite_exam()
538 err = minfo_update_media_favorite(media_id, favorite);
542 printf("minfo_update_media_favorite failed\n");
547 int minfo_update_media_videometa_exam()
551 minfo_video_meta_field_t meta_field;
552 int last_played_time = 1259000000;
553 const char* title = "New Title";
555 // Update last played time
556 err = minfo_update_video_meta_info_int(media_id, last_played_time);
560 printf("minfo_update_video_meta_info_int failed\n");
565 err = minfo_update_video_meta_info_string(media_id, title);
569 printf("minfo_update_video_meta_info_string failed\n");
576 <h2 class="pg"> Copy media </h2>
578 - To copy media from original folder to the other folder, not only updating database but also operating system call.
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().
587 The following is a sample code:
591 int minfo_copy_exam_by_path()
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;
597 err = minfo_copy_media(file_url, dest_url, file_type);
601 printf("minfo_copy_media failed\n");
606 int minfo_copy_exam_by_id()
609 int dest_cluster_id = 3;
611 err = minfo_cp_media(media_id, dest_cluster_id );
615 printf("minfo_copy_media failed\n");
622 <h2 class="pg"> Move media </h2>
624 - To move media from original folder to the other folder, not only updating database but also operating system call.
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().
633 The following is a sample code:
637 int minfo_move_exam_by_path()
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;
643 err = minfo_move_media(file_url, dest_url, file_type);
647 printf("minfo_move_media failed\n");
652 int minfo_move_exam_by_id()
655 int dest_cluster_id = 3;
657 err = minfo_mv_media(media_id, dest_cluster_id );
661 printf("minfo_mv_media failed\n");
668 <h2 class="pg"> Get a thumbnail of media </h2>
670 - To get thumbnail of the choosen media.
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.
676 The following is a sample code:
680 int minfo_get_thumb_path_exam()
683 const char* file_url = "/opt/media/Images and videos/image.jpg";
684 char thumb_path[255] = {0,};
687 ret = minfo_get_thumb_path(file_url, thumb_path, 255);
691 printf("minfo_get_thumb_path fails\n" );
695 printf("minfo_get_thumb_path : %s\n", thumb_path);