Pushed latest libmedia-service for tizen beta

[framework/multimedia/libmedia-service.git] / include / minfo-api.h

/*
 * libmedia-service
 *
 * Copyright (c) 2000 - 2011 Samsung Electronics Co., Ltd. All rights reserved.
 *
 * Contact: Hyunjun Ko <zzoon.ko@samsung.com>, Haejeong Kim <backto.kim@samsung.com>
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */
        
#ifndef _MINFO_INFO_H_
#define _MINFO_INFO_H_

/** 
 * This file defines minfo apis for media service..
 *
 * @file        minfo-api.h
 * @author      Hyunjun Ko <zzoon.ko@samsung.com>
 * @version     1.0
 * @brief       This file defines minfo apis for media service.
 */

#include "minfo-types.h"


#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/**
        @mainpage MINFO_SVC

        @par
        This document provides necessary information for developers who are
        going to implement gallery application and ug-imageviewer or other
        3rd party applications.
 */

/**
 *  @ingroup MEDIA_SVC
        @defgroup MINFO_SVC_API Media Service
        @{

        @par
        Call Directly.
 */



/**
* This function connects to media service database before any database operations. if it will check 
* whether these required tables(folder,media,video_bookmark,web_streaming,video_meta,
* image_meta) have existed, if no,  it will create all of them and operate them then.
* If finish operating the database file, call this function, minfo_finalize() to close the database
* file. 
*
* @return       This function returns 0 on success, or negative value with error code.
* @remarks      Before invoking any API of media service, this function must be 
*                   invoked first to initialize database connection.it should be invoked,
*                   but only once. it's thread-independent and thread-safe.
* @see           minfo_finalize()
* @pre          None
* @post         Call minfo_finalize() to finalize minfo api
* @par example
* @code


     #include <media-svc.h>
        void test_minfo_init(void)
        {
                int ret = -1;
                //open a databse file.
                ret = minfo_init();

                if(ret< 0) { 
                        printf("minfo_init error\n");
                        return ret;
                }
        }
* @endcode       
*/

int
minfo_init(void);


/** 
*  Close media service library. This is the function need to call before close the application. 
*  This function disconnects with the media database and shutdown the other used libary.
*
*
* @return       This function returns 0 on success, or negative value with error code.
* @remarks      After invoking any API of media service, this function must be 
*                  invoked to finalize database connection. if this function is missed, 
*                       database connection leak happenes .and if invoke it without minfo_init,
*                       it fails directly and return error.
* @see           minfo_init()
* @pre          minfo_init is already called.
* @post         None
* @par example
* @code


#include <media-svc.h>
        void test_minfo_finalize(void)
        {
                int ret = -1;
                minfo_init();

                //close database file.
                ret = minfo_finalize();

                if(ret< 0) { 
                        printf("minfo_finalize error\n");
                        return ret;
                }
        }
* @endcode      
*/

int
minfo_finalize(void);


/**
 * This function gets mitem list, which include all or portion of a cluster or folder specified by 
 * @p cluster_id. @p filter could specify some filter conditions, like, type of got items, sort by type,
 * start and end positions of items, including meta data or not, whether just get the favorites, etc.
 * Menawhile data of each mitem instance mainly derive from media table record. However meta data
 * is composed of video_meta or image_meta record.
 * 
 *
 * @param       cluster_id      [in]    the folder id in which media files are in. if the parameter is -1, then query all folders.
 * @param       filter          [in]    the filter to specify some filter conditions, like, type of got items, sort by type, start and end positions of items, including meta data or not, whether just get the favorites, etc.
 * @param       func      [in]  Iterative callback implemented by a user. This callback is called when an item has to be inserted to user's list.
 * @param       user_data      [out]   user's data structure to contain items of the type Mitem. It is passed to the iterative callback.
 
 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     type of data memeber of list is pointer to the structure type 'Mitem'
 *                      when free list, it need free every item first and then free list itself. 
 * @see         None.
 * @pre         None
 * @post        None
 * @par example
 * @code
 
    #include <media-svc.h>
     
        int mitem_ite_cb(Mitem *item, void *user_data)
        {
                GList** list = (GList**)user_data;
                //append an item to linked list.
                *list = g_list_append(*list, item);
        }

        void test_minfo_get_item_list(void)
        {
                int ret = -1;
                int img_cnt = 0;
                GList *p_list = NULL;
                const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";

                minfo_item_filter item_filter = {MINFO_ITEM_VIDEO,MINFO_MEDIA_SORT_BY_DATE_ASC,3,10,true,true};
                //get a set of items
                ret = minfo_get_item_list(cluster_id, item_filter, mitem_ite_cb, &p_list);

                if(ret< 0) { 
                        printf("minfo_get_item_list error\n");
                        return;
                }
        }
 * @endcode  

 */

int
minfo_get_item_list(const char *cluster_id, const minfo_item_filter filter, minfo_item_ite_cb func, void *user_data);

/**
 * This function gets mitem list, which include all or portion of a or many clusters or folders specified by 
 * @p cluster_type. @p filter could specify some filter conditions, like, type of got items, sort by type,
 * start and end positions of items, including meta data or not, whether just get the favorites, etc.
 * Meanwhile data of each mitem instance mainly derive from media table record. However meta data
 * is composed of video_meta or image_meta record.
 * 
 *
 * @param       cluster_type    [in]    the folder type which specify media files belong to.
 * @param       filter          [in]    the filter to specify some filter conditions, like, type of got items, sort by type, start and end positions of items, including meta data or not, whether just get the favorites, etc.
 * @param       func      [in]  Iterative callback implemented by a user. This callback is called when an item has to be inserted to user's list.
 * @param       user_data      [out]   user's data structure to contain items of the type Mitem. It is passed to the iterative callback.
 
 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     type of data memeber of list is pointer to the structure type 'Mitem'
 *                      when free list, it need free every item first and then free list itself. 
 * @see         minfo_get_item_list.
 * @pre         None
 * @post        None
 * @par example
 * @code
 
    #include <media-svc.h>
     
        int mitem_ite_cb(Mitem *item, void *user_data)
        {
                GList** list = (GList**)user_data;
                //append an item to linked list.
                *list = g_list_append(*list, item);
        }

        void test_minfo_get_item_list(void)
        {
                int ret = -1;
                int img_cnt = 0;
                GList *p_list = NULL;

                minfo_item_filter item_filter = {MINFO_ITEM_VIDEO,MINFO_MEDIA_SORT_BY_DATE_ASC,3,10,true,true};
                //get a set of items, which all reside on local storage, including MMC and phone.
                ret = minfo_get_all_item_list(MINFO_CLUSTER_TYPE_LOCAL_ALL, item_filter, mitem_ite_cb, &p_list);

                if(ret< 0) { 
                        printf("minfo_get_item_list error\n");
                        return;
                }
        }
 * @endcode  

 */

int
minfo_get_all_item_list(const minfo_folder_type cluster_type, const minfo_item_filter filter, minfo_item_ite_cb func, void *user_data);

/**
 * This function gets mitem list, which is searched by string specified by user.
 * @p search_field is a field to want to search. @p search_str could specify string to search.
 * Menawhile data of each mitem instance mainly derive from media table record. However meta data
 * is composed of video_meta or image_meta record.
 *
 * @param       search_field    [in] A field to want search. Please refer the enum type minfo_search_field_t in 'minfo-types.h'.
 * @param       search_str      [in]    A string to search.
 * @param       folder_type     [in]    the folder type which specify media files belong to.
 * @param       filter          [in]    the filter to specify some filter conditions, like, type of got items, sort by type, start and end positions of items, including meta data or not, whether just get the favorites, etc.
 * @param   func      [in]  Iterative callback implemented by a user. This callback is called when an item has to be inserted to user's list.
 * @param   user_data      [out]   user's data structure to contain items of the type Mitem. It is passed to the iterative callback.
 
 * @return      This function returns 0 on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 * @remarks     type of data memeber of list is pointer to the structure type 'Mitem'
 *                      when free list, it need free every item first and then free list itself. 
 * @see         None.
 * @pre         None
 * @post        None
 * @par example
 * @code
 
    #include <media-svc.h>
     
        int mitem_ite_cb(Mitem *item, void *user_data)
        {
                GList **list = (GList **)user_data;
                //append an item to linked list.
                *list = g_list_append(*list, item);
        }

        void test_minfo_get_item_list_search(void)
        {
                int ret = -1;
                GList *p_list = NULL;
                const char *search_str = "Hiphop";
                minfo_search_field_t search_field = MINFO_SEARCH_BY_NAME;
                minfo_folder_type folder_type = MINFO_CLUSTER_TYPE_ALL;

                minfo_item_filter item_filter = {MINFO_ITEM_VIDEO, MINFO_MEDIA_SORT_BY_NAME_ASC, 0, 9, false, MINFO_MEDIA_FAV_ALL};

                ret = minfo_get_item_list_search(search_field, search_str, folder_type, item_filter, mitem_ite_cb, &p_list);

                if (ret< 0) {
                        printf("minfo_get_item_list_search error\n");
                        return;
                }
        }
 * @endcode  

 */

int
minfo_get_item_list_search(minfo_search_field_t search_field, const char *search_str, minfo_folder_type folder_type, const minfo_item_filter filter, minfo_item_ite_cb func, void *user_data);

/**
 * This function gets count of all records in media table. This function returns the count of all items, which are unlocked excluding web media.
 *
 * @param   cnt         [out]   returned value, count of all records
 * @return      This function returns zero(MB_SVC_ERROR_BASE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 * @remarks     None. 
 * @see         None.
 * @pre         None
 * @post        None
 * @par example
 * @code


     #include <media-svc.h>
     
        void test_minfo_get_all_item_cnt(void)
        {
                int ret = -1;
                int cnt = 0;

                ret = minfo_get_all_item_cnt(&cnt);
                if(ret< 0) { 
                        printf("minfo_get_all_item_cnt error\n");
                        return;
                }
        }
 * @endcode
 */

int
minfo_get_all_item_cnt(int *cnt);


/**
 * This function gets count of matched records in media table with the specified @p filter, which 
 * specify some filter conditions, like, type of got items, sort by type, start and end positions 
 * of items, including meta data or not, whether just get the favorites, etc.
 * The detail structure type of @p filter, could refer to the defination 'minfo_item_filter'
 * in header file, minfo-types.h.
 *
 * @param       cluster_id      [in]    the folder id in which media files are in. if the parameter is -1, then query all folders.
 * @param       filter          [in]    the filter to specify some filter conditions, like, type of got items, sort by type, start and end positions of items, including meta data or not, whether just get the favorites, etc.
 * @param   cnt         [out]   returned value, count of matched records
 
 * @return      This function returns 0 on success, or negative value with error code.
 *                      
 * @remarks     list contains a set of full path string of cover file. 
 * @see                 minfo_get_item_list.
 * @pre         None
 * @post        None
 * @par example
 * @code


     #include <media-svc.h>
     
        void test_minfo_get_item_cnt(void)
        {
                int ret = -1;
                const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";

                minfo_item_filter item_filter = {MINFO_ITEM_VIDEO,MINFO_MEDIA_SORT_BY_DATE_ASC,-1,10,true,true};

                //get count of a set of items.
                ret = minfo_get_item_cnt(cluster_id, item_filter, &cnt);
                if(ret< 0) { 
                        printf("test_minfo_get_item_cnt error\n");
                        return;
                }
        }
 * @endcode
 */

int
minfo_get_item_cnt(const char *cluster_id, const minfo_item_filter filter, int *cnt);



/**
 * This function gets count of matched records from folder table  with the specified @p filter, which 
 * specify some filter conditions, like, type of got clusters, sort by type, start and end positions 
 * of clusters, etc. The detail structure type of @p filter, could refer to the defination 'minfo_cluster_filter'
 * in header file, minfo-types.h.
 * 
 *
 *
 * @param       filter          [in]    filter to specify some filter conditions, like, type of got clusters, sort by type, start and end positions of clusters
 * @param   cnt         [out]  returned value, count of matched records
 * @return      This function returns 0 on success, or negative
 *                      value with error code.
 * @remarks     None.
 * @see                                  minfo_get_cluster_list.         
 * @pre         None
 * @post        None
 * @par example
 * @code

   
      #include <media-svc.h>
     
        void test_minfo_get_cluster_cnt(void)
        {
                int ret = -1;
                minfo_cluster_filter cluster_filter ={MINFO_CLUSTER_TYPE_ALL,MINFO_CLUSTER_SORT_BY_NONE,-1,10};

                //get the count of items which is owned by a cluster.
                ret = minfo_get_cluster_cnt(cluster_filter, &cnt);
                if(ret< 0) { 
                        printf("test_minfo_get_cluster_cnt error\n");
                        return;
                }
        }
 * @endcode    
 */

int
minfo_get_cluster_cnt(const minfo_cluster_filter filter, int *cnt);


/**
 * This function gets Mcluster instances list. Data of each instance is composed of the matched records from folder table 
 * with the @p filter, which specify some filter conditions, like, type of got clusters, sort by type, start and end positions 
 * The detail structure type of @p filter, could refer to the defination 'minfo_cluster_filter'
 * in header file, minfo-types.h.
 *
 * @param       filter          [in]    filter to specify some filter conditions, like, type of got clusters, sort by type, start and end positions of clusters
 * @param       func      [in]  Iterative callback implemented by a user. This callback is called when an item has to be inserted to user's list.
 * @param       user_data      [out]   user's data structure to contain items of the type Mcluster. It is passed to the iterative callback.
 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks          item type in list is pointer to structure mcluster
 *                    when free list, it need free every item first and then free list itself.
 * @see         None.
 * @pre         None
 * @post        None
 * @par example
 * @code

    #include <media-svc.h>
     
        int mcluster_ite_cb(Mcluster *cluster, void *user_data)
        {
                GList** list = (GList**)user_data;
                *list = g_list_append(*list, cluster);
        }

        void test_minfo_get_cluster_list(void)
        {
                int ret = -1;
                int i;
                int img_cnt;
                GList *p_list = NULL;
                Mcluster* cluster = NULL;

        //get a linked list which include all of clusters based on a specified filter.
                minfo_cluster_filter cluster_filter ={MINFO_CLUSTER_TYPE_ALL,MINFO_CLUSTER_SORT_BY_NONE,0,10};

                ret = minfo_get_cluster_list(cluster_filter, mcluster_ite_cb, &p_list);

                if( ret < 0) {
                         return;
                }
        }
 * @endcode      
 */

int
minfo_get_cluster_list(const minfo_cluster_filter filter, minfo_cluster_ite_cb func, void *user_data);


/**
 * This function gets matched 'Mmeta' instances. Data of the instance is composed of the matched media record from 
 * 'video_meta'/'image_meta' table, when finish using the Mmeta instance, should call API, minfo_mmeta_destroy to 
 * destroy this created instance.
 *
 * @param                       media_id       [in]                     specified _id field in media table record
 * @param                   meta                   [out]                pointer to pointer of matched Mmeta instance

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     after using meta, it must be freed.           .                               
 * @see         None.
 * @pre         None
 * @post        None
 * @par example
 * @code


     #include <media-svc.h>
     
        void test_minfo_get_meta_info(void)
        {
                int ret = -1;
                Mmeta* mt = NULL;
                const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";

                //get a matched meta data.
                ret = minfo_get_meta_info(media_id, &mt);
                if( ret < 0) {
                        printf("minfo_get_meta_info failed\n");
                        return ret;
                }
                minfo_mmeta_destroy(mt);
        }

 * @endcode                
 */

int
minfo_get_meta_info(const char *media_id, Mmeta** meta);

/**
 * This function will update the corresponding field's value in database 'image_meta' table, this will be decided by the
 * @p meta_field, whose type is 'minfo_image_meta_field_t', and indicate which field will be replaced by the value of int type
 * pointered to by @p updated_value.
 *
 * @param                   media_id       [in]                 specified _id field in media table record
 * @param                   meta_field             [in]         the enum value indicate which field of database table will be updated
 * @param                   updated_value         [in]          value of int, which will replace the original value in database image meta table

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     after using meta, it must be freed.
 * @see         None.
 * @pre         None
 * @post        None
 * @par example
 * @code


      #include <media-svc.h>
     
        void test_minfo_update_image_meta_info_int(void)
        {
                int ret = -1;
                int width = 640;
                int height = 480;
                const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";

                // update image meta's 'width and height' member 
                ret = minfo_update_image_meta_info_int(media_id, MINFO_IMAGE_META_WIDTH, width, MINFO_IMAGE_META_HEIGHT, height);
                if( ret < 0) {
                        printf("minfo_update_image_meta_info_int failed\n");
                        return;
                }
        }

 * @endcode                
 */

EXPORT_API int
minfo_update_image_meta_info_int(const char *media_id,
                                minfo_image_meta_field_t meta_field,
                                const int updated_value,
                                ...);

/**
 * This function will update the corresponding field's value in database 'video_meta' table, this will be decided by the
 * @p meta_field, whose type is 'minfo_video_meta_field_t', and indicate which field will be replaced by the value of int type
 * pointered to by @p updated_value.
 *
 * @param                   media_id       [in]                 specified _id field in media table record
 * @param                   meta_field             [in]         the enum value indicate which field of database table will be updated
 * @param                   updated_value         [in]          value of int, which will replace the original value in database video meta table

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     after using meta, it must be freed.
 * @see         None.
 * @pre         None
 * @post        None
 * @par example
 * @code


      #include <media-svc.h>
     
        void test_minfo_update_video_meta_info_int(void)
        {
                int ret = -1;
                int _value = 876;
                const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";

                //update video meta's 'last_played_time' member
                ret = minfo_update_video_meta_info_int(media_id, MINFO_VIDEO_META_BOOKMARK_LAST_PLAYED, _value);

                if( ret < 0) {
                        printf("minfo_update_video_meta_info_int failed\n");
                        return;
                }
        }

 * @endcode                
 */

int
minfo_update_video_meta_info_int(const char *media_id, minfo_video_meta_field_t meta_field, const int updated_value);


/**
* 
* This function free an type instantiated object, whose type may be any one recognized by media-svc, these type
* will include Mitem, Mimage, Mvideo, Mmeta, Mcluster, etc. In this function, it will check the concrete type for the 
* @p item, and then decide which free function will really be called.
*
* @return            This function returns 0 on success, and negativa value on failure.
* @param             item [in]        the input parameter, inlcuding the instanciated object.
* @exception                    None.
* @remarks             This function is general one, it will be able to destroy any recognized instantiated object 
*                               by media-svc, so when you create or get an instantiated object from media-svc, and then call
*                         this function to free it.                        
*                                       
* @see  None.
* @pre  None
* @post None
* @par example
* @code

     #include <media-svc.h>
     
        void test_minfo_destroy_mtype_item(void)
        {
                int ret = -1;
                Mitem *mi = NULL;
                
                char* file_url = "/opt/media/Images/Wallpapers/Home_01.png";
                ret = minfo_get_item(file_url, &mi);

                //destroy an item whose type is 'Mitem'.
                ret = minfo_destroy_mtype_item(mi);

                if( ret < 0) {
                         return ret;
                }
                
        }
 * @endcode      
*/

int
minfo_destroy_mtype_item(void* item);


/**
 * This function inserts new media file information into media table,video_meta table/image_meta table.
   Or updates file information in these tables if the file is updated
 *
 * @param      trans_count  [in]              count of trasaction user wants

 * @return      This function returns 0/positive on success, or negative value with error code. (0 : added, 1: updated, 2: skipped )
 * @remarks     if invoke this function with same input parameter, it fails
 * @see         minfo_add_media_end, minfo_add_media_batch
 * @pre         None
 * @post        None
 * @par example
 * @code
 
    #include <media-svc.h>
     
        void test_minfo_add_media_batch(void)
        {
                int err = -1, i;

                err = minfo_add_media_start(100);
                if( err < 0) {
                        printf("minfo_add_media_start failed\n");
                        return;
                }

                for (i = 0; i < 200; i++) {
                        err = minfo_add_media_batch(image_files[i], MINFO_ITEM_IMAGE);

                        if( err < 0) {
                                printf("minfo_add_media_start failed\n");
                                return;
                        }
                }

                err = minfo_add_media_end();
                if( err < 0) {
                        printf("minfo_add_media_end failed\n");
                        return;
                }
        }
 * @endcode                    
 */

int
minfo_add_media_start(int trans_count);


/**
 * This function inserts new media file information into media table,video_meta table/image_meta table.
   Or updates file information in these tables if the file is updated
 *
 * @param      file_url  [in]              the local file full path
 * @param       type     [in]     the file type, maybe it's video file or image file

 * @return      This function returns 0/positive on success, or negative value with error code. (0 : added, 1: updated, 2: skipped )
 * @remarks     if invoke this function with same input parameter, it fails
 * @see          minfo_add_media_start, minfo_add_media_end
 * @pre None
 * @post        None
 * @par example
 * @code
 
    #include <media-svc.h>
        
        void test_minfo_add_media_batch(void)
        {
                int err = -1, i;

                err = minfo_add_media_start(100);
                if( err < 0) {
                        printf("minfo_add_media_start failed\n");
                        return;
                }

                for (i = 0; i < 100; i++) {
                        err = minfo_add_media_batch(image_files[i], MINFO_ITEM_IMAGE);

                        if( err < 0) {
                                printf("minfo_add_media_start failed\n");
                                return;
                        }
                }

                err = minfo_add_media_end();
                if( err < 0) {
                        printf("minfo_add_media_end failed\n");
                        return;
                }
        }
 * @endcode                    
 */

int
minfo_add_media_batch(const char* file_url, minfo_file_type content_type);

/**
 * This function inserts new media file information into media table,video_meta table/image_meta table.
   Or updates file information in these tables if the file is updated
 *
 * @return      This function returns 0/positive on success, or negative value with error code. (0 : added, 1: updated, 2: skipped )
 * @remarks     if invoke this function with same input parameter, it fails
 * @see         minfo_add_media_start, minfo_add_media_batch
 * @pre         None
 * @post        None
 * @par example
 * @code

 
    #include <media-svc.h>
     
        void test_minfo_add_media_batch(void)
        {
                int err = -1, i;

                err = minfo_add_media_start(100);
                if( err < 0) {
                        printf("minfo_add_media_start failed\n");
                        return;
                }

                for (i = 0; i < 200; i++) {
                        err = minfo_add_media_batch(image_files[i], MINFO_ITEM_IMAGE);

                        if( err < 0) {
                                printf("minfo_add_media_start failed\n");
                                return;
                        }
                }

                err = minfo_add_media_end();
                if( err < 0) {
                        printf("minfo_add_media_end failed\n");
                        return;
                }
        }
 * @endcode                    
 */

int
minfo_add_media_end();

/**
 * This function inserts new media file information into media table,video_meta table/image_meta table.
   Or updates file information in these tables if the file is updated
 *
 * @param      file_url  [in]              the local file full path
 * @param       type     [in]     the file type, maybe it's video file or image file

 * @return      This function returns 0/positive on success, or negative value with error code. (0 : added, 1: updated, 2: skipped )
 * @remarks     if invoke this function with same input parameter, it fails
 * @see          minfo_delete_media
 * @pre None
 * @post        None
 * @par example
 * @code

 
       #include <media-svc.h>
     
        void test_minfo_add_media(void)
        {
                int err = -1;
                char *file_url = "/opt/media/Images/Wallpapers/Home_01.png";

                //add a new media content whose url is 'file_url'.
                err = minfo_add_media(file_url, MINFO_ITEM_IMAGE);

                if( err < 0) {
                        printf("minfo_add_media failed\n");
                        return;
                }
        }
 * @endcode                    
 */


int
minfo_add_media(const char* file_url, minfo_file_type content_type);



/**
 * This function deletes matched media table record, video_meta/image_meta record. After that, if the folder which this file is in is empty, then delete the folder record.
 * When user actually delete a media file in file system, he/she should call this function to delete the corresponding record in 'media' table, meanwhile it may delete the 
 * folder record in 'folder' table if this folder will not include any media content.
 *
 * @param                       file_url       [in]                      matched local file full path

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks      None.  
 * @see          minfo_add_media 
 * @pre None
 * @post        None
 * @par example
 * @code

    #include <media-svc.h>
     
    void test_minfo_delete_media(void) 
        {
                int ret = -1;
                char *file_url = "/opt/media/Images/Wallpapers/Home_01.png";

                //delete a media reord from 'media' table.
                ret= minfo_delete_media(file_url);

                if( ret < 0) {
                        printf("minfo_delete_media failed\n");
                        return;
                }
        }
 * @endcode                
 */

int
minfo_delete_media(const char* file_url);



/**
 * This function moves the media file to another place. When user actually move a media file ( @p old_file_url )in file system to the destination
 * pathname ( @p new_file_url ), he/she need to call this function to move the record of 'media' table. Meanwhile user is responsible for identifying 
 * the file's type, like image, video, etc. 
 * @param    old_file_url   [in]                old local file full path of the media file
 * @param        new_file_url   [in]                new local file full path of the media file
 * @param        type           [in]                     media file type,maybe vidoe or image

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     None.   
 * @see   minfo_mv_media, minfo_copy_media, minfo_update_media_name.
 * @pre None
 * @post        None
 * @par example
 * @code


      #include <media-svc.h>
     
        void test_minfo_move_media(void)
        {
                int ret = -1;
                char* old_file_url = "/opt/media/Images/Wallpapers/Home_01.png";
                char* new_file_url = "/opt/media/Images/Wallpapers/Home_01_1.png";

                //move an item to a specified location.
                ret = minfo_move_media(old_file_url, new_file_url, MINFO_ITEM_IMAGE);

                if( ret < 0) {
                        printf("minfo_move_media failed\n");
                        return;
                }
        }
 * @endcode     
 */

int
minfo_move_media(const char* old_file_url, const char *new_file_url, minfo_file_type content_type);



/**
 * This function copies the media file to another place. User should pass the full pathnames for these parameters, @p old_file_url and @ new_file_url
 * respectively. The @p old_file_url indicate the original full pathname of this media content, and @ new_file_url indicate the destination full pathname of
 * the copied file.
 * @param    old_file_url   [in]                old local file full path of the media file
 * @param        new_file_url   [in]                new local file full path of the media file
 * @param        type           [in]                     media file type, maybe vidoe or image

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     This function will not return the thumbnail pathname of new media file, user could get this new thumnail file using the function, minfo_get_thumb_path.
 * @see         minfo_cp_media, minfo_update_media_name, minfo_move_media
 * @pre None
 * @post        None
 * @par example
 * @code

    #include <media-svc.h>
     
    void test_minfo_copy_media(void)
    {
        int ret =-1;
        
        char *file_url = "/opt/media/Images/Wallpapers/Home_01.png";
            char *new_file_url = "/opt/media/Images/Wallpapers/Home_01_1.png";

            //copy a media file to other location whos name is specified by 'new_file_url'.
        ret  = minfo_copy_media( old_file_url, new_file_url, file_type);
        if( ret < 0) {
              printf("minfo_copy_media failed\n");
              return;
                }

    }
 * @endcode     
 */

int
minfo_copy_media(const char* old_file_url, const char *new_file_url, minfo_file_type content_type);


/**
 * This function rename a image or video file. Here this function will assume the folder name of 
 * file whose name is changed keep unchanged. That is, this file which is changed name still is located in the same folder.
 * This function actually call sqlite3 
 * UPDATE %s SET ... WHERE _id = _id;
 * @param    media_id   [in]           the id of specified media file
 * @param        new_name       [in]                new name of the media file

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks      None.  
 * @see    minfo_move_media, minfo_copy_media.   
 * @pre None
 * @post        None
 * @par example
 * @code

     #include <media-svc.h>
     
     void test_minfo_update_media_name(void)
     {
        int ret = -1;
                const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";  

        //update media name
        ret = minfo_update_media_name(media_id, new_name);
            if( ret < 0) {
               printf("test_minfo_update_media_name failed\n");
               return;
            }
     }
 * @endcode      
 */

int
minfo_update_media_name(const char *media_id, const char* new_name);

/**
 * This function updates a thumbpath of the media in DB.
 * @param    media_id   [in]           the id of specified media file
 * @param        thumb_path     [in]                new thumbnail path of the media file

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks      None.  
 * @see None
 * @pre None
 * @post None
 * @par example
 * @code

     #include <media-svc.h>
     
     void test_minfo_update_media_thumb(void)
     {
        int ret = -1;
                const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";
                const char *thumb_path = "/opt/media/test.jpg";

        //update thumbnail path
        ret = minfo_update_media_thumb(media_id, thumb_path);
        if( ret < 0) {
                   printf("minfo_update_media_thumb failed\n");
                   return;
            }
     }
 * @endcode      
 */

int
minfo_update_media_thumb(const char *media_id, const char* thumb_path);

/**
 * This function updates favorite field of image or video file in 'media' table. This function actually call the Sqlite3 UPDATE,
 * In Gallery application or ug-imageviewer, user could want to set a media file as favorite or unfovarite, so he/she could call
 * this API to do it.
 * @param    media_id       [in]               Unique id of the media file
 * @param    favorite_level     [in]               new favorite_level of the media file, indicate whether this media content is favorite or unfavorite.

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     None.   
 * @see     None.
 * @pre         None
 * @post        None
 * @par example
 * @code

     #include <media-svc.h>
     
     void test_minfo_update_media_favorite(void)
     {
         int ret = -1;
                 const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";

         //update an item's favorite record
         ret = minfo_update_media_favorite(media_id, favorite_level);

             if( ret < 0) {
                    printf("minfo_update_media_favorite failed\n");
                    return;
             }
     }
 * @endcode     
 */

int  
minfo_update_media_favorite(const char *media_id, const int favorite_level);


/**
 * This function updates modified date of image or video file in 'media' table. This function actually call the Sqlite3 UPDATE.
 * In Gallery application or ug-imageviewer, user could want to set moedified date of a media, so he/she could call this API to do it.
 * @return  This function returns zero(MB_SVC_ERROR_BASE) on success, or negative value with error code.
 * @param    media_id       [in]               Unique id of the media file
 * @param    modified_date      [in]               date to modify, which is a type of time_t 
 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     None.   
 * @see     None.
 * @pre         None
 * @post        None
 * @par example
 * @code

     #include <media-svc.h>
     
     void test_minfo_update_media_date(void)
     {
        int ret = -1;
                const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";

                time_t today;
        time(&today);

        //update an item's date record
        ret = minfo_update_media_date(media_id, today);
            if( ret < 0) {
                   printf("minfo_update_media_date failed\n");
                   return;
            }
     }
 * @endcode     
 */

int  
minfo_update_media_date(const char *media_id, time_t modified_date);


/**
 * This function adds new local folder. This function could be called when user want to add a Album(local folder)
 * in Gallery application. This function actually call the sqlite INSERT statement to insert the record in folder
 * table. Meanwhile it will return new added local folder's ID to @p id.
 * Sqlie3 statement looks like this, INSERT INTO folder (...);
 * @param    cluster_url       [in]           the local directory of added folder, it should be full pathname of local folder
 * @param        id                    [out]      id of the added folder, this function will return a unique ID to calling application

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     if invoke this function with same input parameter, it fails   
 * @see     minfo_delete_cluster
 * @pre         None
 * @post        None
 * @par example
 * @code

     #include <media-svc.h>
     
        void test_minfo_add_cluster(void)
        {
                int ret = -1;
                char *cluster_url = "/opt/media/Images/Wallpapers";
                char cluster_id[256];

                //add a new cluster whose url is 'cluster_url'.
                ret = minfo_add_cluster(cluster_url, cluster_id, sizeof(cluster_id));
                if( ret < 0) {
                        printf("minfo_add_cluster failed\n");
                        return;
                }
        }
 * @endcode    
 */

int
minfo_add_cluster(const char* cluster_url, char *id, int max_length);

/**
 * This function gets mitem information. When user could get the unique ID of a media content, he/she
 * could get the detail information with the type 'Mitem', which include the below feilds, like, item's unique id,
 * media content type, media content's thumbnail name, media content's pathname, etc. The detail defination 
 * of this structute, could refer to the header, minfo-item.h.
 * @param    media_id       [in]              the local file media id
 * @param    mitem           [out]        the returned data structure whose type is Mitem.

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks        when invoking this function, *mitem must equals NULL, and
 *                  the @p media_id should be valid ID, if it is invalid, like -1 or 0, this 
 *                      function will return @p mitem whose content is NULL. If normally, @p mitem must be freed with minfo_mitem_destroy.
 * @see     minfo_get_item.
 * @pre         None
 * @post        None
 * @par example
 * @code

     #include <media-svc.h>
     
        void test_minfo_get_item_by_id(void)
        {
                int ret = -1;
                const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";
                Mitem *mi = NULL;

                //get an item based on its media ID.
                ret = minfo_get_item_by_id(media_id, &mi);
                if(ret < 0) {
                        return;
                }

                minfo_destroy_mtype_item(mi);
        }
 * @endcode    
 */

int
minfo_get_item_by_id(const char *media_id, Mitem **mitem);


/**
 * This function gets mitem information. When user could get the full pathname of a media content, he/she
 * could get the detail information with the type 'Mitem', which include the below feilds, like, item's unique id,
 * media content type, media content's thumbnail name, media content's pathname, etc. The detail defination 
 * of this structute, could refer to the header, minfo-item.h.
 * @param    file_url          [in]           the local file full pathname
 * @param    mitem           [out]        the returned data structure whose type is Mitem.

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks        when invoking this function, *mitem must equals NULL, and
 *                  after using mitem, it must be freed with minfo_mitem_destroy.
 * @see     minfo_get_item_by_id.
 * @pre         None
 * @post        None
 * @par example
 * @code

     #include <media-svc.h>
     
        void test_minfo_get_item(void)
        {
                int ret = -1;
                Mitem *mi = NULL;
                char* file_url = "/opt/media/Images/Wallpapers/Home_01.png";

                //get an item based on its url.
                ret = minfo_get_item(file_url, &mi);
                if(ret < 0) {
                        return;
                }

                minfo_destroy_mtype_item(mi);
        }
 * @endcode    
 */

int
minfo_get_item(const char* file_url, Mitem **mitem);

/**
 * This function gets mitem information. When user could get the http url of a media content, which is downloaded from web, he/she
 * could get the detail information with the type 'Mitem', which include the below feilds, like, item's unique id,
 * media content type, media content's thumbnail name, etc. The detail defination 
 * of this structute, could refer to the header, minfo_item/minfo-item.h.
 * @param    http_url    [in]         the http url of a media, which is downloaded from web.
 * @param    mitem           [out]        the returned data structure whose type is Mitem.

 * @return      This function returns 0 on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 * @remarks        when invoking this function, *mitem must equals NULL, and
 *                  after using mitem, it must be freed with minfo_mitem_destroy.
 * @see     minfo_get_item_by_id, minfo_get_item
 * @pre         None
 * @post        None
 * @par example
 * @code

     #include <media-svc.h>
     
        void test_minfo_get_item_by_http_url(void)
        {
                int ret = -1;
                Mitem *mi = NULL;
                char* http_url = "http://picasa.com/myaccount/Home_01.png";

                //get an item based on its http url.
                ret = minfo_get_item_by_http_url(http_url, &mi);
                if(ret < 0) {
                        return;
                }

                minfo_destroy_mtype_item(mi);
        }
 * @endcode    
 */

int 
minfo_get_item_by_http_url(const char* http_url, Mitem **mitem);


/**
* 
* This function gets mcluster information by folder full path or cluster id when user could not know exact url of cluster. When user could get full path of a folder, he/she
* could get the detail information with the type 'Mcluster' about this cluster/local folder, the type 'Mcluster'
* mainly include folder/cluster ID, display name, count of included media content, etc. The detail defination
* of this type could refer to the herder file, minfo-cluster.h.
*
* @return             This function returns 0 on success, or negative value with error code.
* @param             cluster_url [in]          local folder full path, it indicate which folder user want to get it's detail information
* @param             cluster_id  [in]  the cluster ID which indentify a cluster
* @param             mcluster [out]   mcluster to be returned, which is a 'Mcluster' type
* @exception                    None.
* @remarks                        when user could not know exact url of a cluster, he/she could choose alternative way he/she pass cluster id to this function, so that 
*                                      this function still could get the wanted cluster.
*                                      when invoking this function, *mcluster must equals NULL, and
*                                     after using mitem, it must be freed with minfo_mcluster_destroy.
* @see      minfo_mcluster_destroy
* @pre          None
* @post None
* @par example
* @code
*

     #include <media-svc.h>
     
     void test_minfo_get_cluster(void)
     {
            int ret = -1;
            Mcluster *mc = NULL;
            char *cluster_url = "/opt/media/Images/Wallpapers";
                        const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";

            //get a cluster using cluster's url.
            ret = minfo_get_cluster(cluster_url, cluster_id, &mc);
                        if(ret < 0) {
                                printf("minfo_get_cluster fail: %d \n", ret);
                                return;
                        }

                        printf("minfo_get_cluster: %s \n", mc->display_name);
                        minfo_mcluster_destroy(mc);
         }
* @endcode
*/

int 
minfo_get_cluster(const char* cluster_url, const char *cluster_id, Mcluster **mcluster);


/**
 * This function gets thumbnail path of cover files by cluster id. This function could get the cover of a cluster
 * or folder which may include first several items' thumbnails, maybe 5 or other number, user could specify it
 * using @p img_cnt. 
 *
 * @param       cluster_id      [in]    the folder id in which media files are in. if the parameter is -1, then query all folders.
 * @param       img_cnt         [in]    the count of cover thumbnails
 * @param       func      [in]  Iterative callback implemented by a user. This callback is called when an thumbnail path has to be inserted to user's list.
 * @param       user_data      [out]   user's data structure to contain items of thumbnail path. It is passed to the iterative callback.
 *
 * @return      This function returns 0 on success, or negative value with error code.
 *                      
 * @remarks     type of item is pointer to char*,
 *                      when free list, needn't free every string. 
 * @see         None.
 * @pre         None
 * @post        None
 * @par example
 * @code
 *

 
    #include <media-svc.h>

        int cover_ite_cb(char *thumb_path, void *user_data)
        {
                GList** list = (GList**)user_data;
                *list = g_list_append(*list, thumb_path);
        }

        void test_minfo_get_cluster_cover(void)
        {
                int ret = -1;
                GList *p_list = NULL;
                int img_cnt = 5;
                const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";

                //get the cover of a cluster.
                ret = minfo_get_cluster_cover(cluster_id, img_cnt, cover_ite_cb, &p_list);
                if(ret< 0) { 
                        printf("test_minfo_get_cluster_cover error\n");
                        return;
                }
        }

  * @endcode
  */

int 
minfo_get_cluster_cover(const char *cluster_id, const int img_cnt, minfo_cover_ite_cb func, void *user_data);


/**
 * This function gets the type 'Mbookmark' instances list. Data of each this type instance is 
 * composed of the matched record indentified by the media id from  'video_bookmark' table. 
 * The type 'Mbookmark' mainly include the these information, like, bookmark id, media id, 
 * marked time, corresponding thumbnail pathanme, etc.
 *
 * @param       media_id                   [in] media_id field of video_bookmark table record
 * @param       func      [in]  Iterative callback implemented by a user. This callback is called when an item has to be inserted to user's list.
 * @param       user_data      [out]   User's data structure to contain items of the type Mbookmark. It is passed to the iterative callback.
 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks        member data in list is pointer to structure Mbookmark,
 *                    when free list, it need free every item first and then free list itself.
 * @see         None.
 * @pre         None
 * @post        None
 * @par example
 * @code


    #include <media-svc.h>

        int mbookmark_ite_cb(Mbookmark *bm, void *user_data)
        {
                GList** list = (GList**)user_data;
                *list = g_list_append(*list, bm);
        }
     
    void test_minfo_get_bookmark_list(void)
        {
                int ret = -1;
                const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";
                GList *p_list = NULL;

        //get a linked list which will include all of bookmarks of a media file.
                ret = minfo_get_bookmark_list(media_id, mbookmar_ite_cb, &p_list);
                if( ret < 0) {
                        return;
                }
        }
  * @endcode     
 */

int
minfo_get_bookmark_list(const char *media_id, minfo_bm_ite_cb func, void *user_data);


/**
 * This function gets the type 'Mitem' instances list. Data of each instance is composed of the matched record identified 
 * by @p filter from 'media' table. Except that the got items pass the criterion of  @p filter, they should position where the longitude
 * is between @p min_longitude and @p max_longitude, and the latitude is between @p min_latitude and @p max_latitude.
*  This function gets 'Mitem' list matched with latitude, longitude, filter and cluster id.

 * @param                       cluster_id       [in]                   indicate the value, 'fold_id' field in 'media' table record
 * @param                       filter           [in]           specified filter to get matched media record
 * @param                       store_filter           [in]             specified storage filter to get matched media record
 * @param                       min_longitude    [in]                    minimum value of 'longitude' field in 'vidoe_meta'/'image_meta' table
 * @param                       max_longitude    [in]            maximum value of longitude field in 'vidoe_meta'/'image_meta' table
 * @param                       min_latitude     [in]            minimum value of 'latitude' field in 'video_meta'/'image_meta' record 
 * @param                       max_latitude     [in]            maximum value of 'latitude' field in 'video_meta'/'image_meta' record
 * @param       func      [in]  Iterative callback implemented by a user. This callback is called when an item has to be inserted to user's list.
 * @param       user_data      [out]   user's data structure to contain items of the type Mitem. It is passed to the iterative callback.

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks          item type in list is pointer to structure Mitem,
 *                    when free list, it need free every item first  and then free list itself. 
 * @see         None.
 * @pre         None
 * @post        None
 * @par example
 * @code


    #include <media-svc.h>

        int mitem_ite_cb(Mitem *item, void *user_data)
        {
                GList** list = (GList**)user_data;
                *list = g_list_append(*list, item);
        }
     
    void test_minfo_get_geo_item_list(void)
    {

                int ret = -1; 
                const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";
                int min_longitude = 120.0;
                int max_longitude = 123.0;
                int min_latitude = 19.0;
                int max_latitude = 24.0;
                GList *p_list = NULL;

                //get a linked list which include a set of items based on their location.
                ret = minfo_get_geo_item_list(cluster_id, 
                                                store_filter,
                                    filter, 
                                    min_longitude, 
                                    max_longitude, 
                                    min_latitude, 
                                    max_latitude,
                                                mitem_ite_cb,
                                    &p_list);
                if( ret < 0) {
                        printf("minfo_get_geo_item_list failed\n");
                        return;
                }
    }
  * @endcode      
 */

int
minfo_get_geo_item_list(const char *cluster_id, 
                                                minfo_folder_type store_filter,
                                                minfo_item_filter filter, 
                                                double min_longitude, 
                                                double max_longitude, 
                                                double min_latitude, 
                                                double max_latitude,
                                                minfo_item_ite_cb func,
                        void *user_data);





/**
 * This function gets thumbnail path of specified image file. When user could get the full pathname of a image content.
 * He/She wants to get the thumbnail file corresponding to the image content identified by the @p file_url.
 * User is responsible for allocating the memory for @p thumb_path so that this function could fill up the thumbnail pathname to it.
 * @param                                        file_url         [in]          local file full path, identify a media record in 'media' table
 * @param                                        thumb_path       [out] the returned thumbnail path of specified file, user is responsible for allocating memory for it first
 * @param                                       max_thumb_path    [in] The max length of the returned thumbnail path
 *
 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks                      one file full path always matches one thumbnail path,
                               here, it returns thumbnail path , but maybe thumbnail file doesn't exist, return NULL. 
 * @see         minfo_get_thumb_path_for_video.
 * @pre         None
 * @post        None
 * @par example
 * @code


     #include <media-svc.h>
     
        void test_minfo_get_thumb_path(void)
        {
                int ret = -1;
                char thumb_path[256] = {'\0'};
                char *file_url = "/opt/media/Images/Wallpapers/Home_01.png";

                //get thumbnail pathname of an item.
                ret = minfo_get_thumb_path(file_url, thumb_path, sizeof(thumb_path));
                if( ret < 0) {
                        printf("minfo_get_thumb_path failed\n");
                        return;
                }
        }
* @endcode       
 */

int
minfo_get_thumb_path(const char* file_url, char* thumb_path, size_t max_thumb_path);

/**
 * This function gets thumbnail path of specified video file. When user could get the full pathname of a video content.
 * He/She wants to get the thumbnail file corresponding to the video content identified by the @p file_url.
 * User is responsible for allocating the memory for @p thumb_path so that this function could fill up the thumbnail pathname to it.
 * @param                                        file_url         [in]          local file full path, identify a media record in 'media' table
 * @param                                        thumb_path       [out] the returned thumbnail path of specified file, user is responsible for allocating memory for it first
 * @param                                       max_thumb_path    [in] The max length of the returned thumbnail path
 *
 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks                      one file full path always matches one thumbnail path,
                               here, it returns thumbnail path , but maybe thumbnail file doesn't exist, return NULL. 
 * @see         minfo_get_thumb_path.
 * @pre         None
 * @post        None
 * @par example
 * @code


     #include <media-svc.h>
     
        void test_minfo_get_thumb_path_for_video(void)
        {
                int ret = -1;
                char thumb_path[256] = {'\0'};
                char *file_url = "/opt/media/Images and videos/My video clip/Helicopter.mp4";

                //get thumbnail pathname of an item.
                ret = minfo_get_thumb_path_for_video(file_url,thumb_path, sizeof(thumb_path));
                if( ret < 0) {
                        printf("minfo_get_thumb_path_for_video failed\n");
                        return;
                }
        }
* @endcode       
 */

int
minfo_get_thumb_path_for_video(const char* file_url, char* thumb_path, size_t max_thumb_path);

/**
 * This function deletes matched record identified by the @p media_id from 'media' table , 'video_meta'/'image_meta' record. 
 * After that, if the folder which this deleted file is in becomes empty, then delete the folder record from 'folder' table, too. 
 * In order that user could successfully delete the corresponding record from 'media' table, he/she should be able to the correct _id 
 * of media content before it.
 *
 * @param       media_id       [in]                      represent the value, media '_id' in 'media' table record

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     None.  
 * @see     minfo_delete_media.  
 * @pre         None
 * @post        None
 * @par example
 * @code


       #include <media-svc.h>
     
    void test_minfo_delete_media_id(void) 
        {
                int ret = -1;
                const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";

                //delete an item according to its ID.
                ret = minfo_delete_media_id(media_id);
                if( ret < 0) {
                        printf("test_minfo_delete_media_id failed\n");
                        return;
                }
        }
* @endcode              
 */

int
minfo_delete_media_id(const char *media_id);



/**
 * This function copies specified media file to another folder, which is identified by the folder id, @p dst_cluster_id. Meanwhile the copied media file
 * is identified by it's media id. Compared to API, minfo_copy_media, the different is , this function copy a media content to specified folder,
 * according to the media content id and the destination folder's id, however the function, minfo_copy_media, copy a media content to specified folder
 * according to the media file's full pathname and folder's full name.
 * @param    src_media_id       [in]           id of the source media file, it's value is from '_id' field of the 'media' table
 * @param        dst_cluster_id     [in]                   id of the destination folder, it's value is from '_id' field of the 'folder' table 

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     This function will implement the same functionality as minfo_copy_media.
 * @see  minfo_copy_media
 * @pre         None
 * @post        None
 * @par example
 * @code


    #include <media-svc.h>
     
     void test_minfo_cp_media(void)
     {
             int ret = -1;
                         const char *src_media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";
                         const char *dst_cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";

             //copy the a media file whose ID is specified by, 'src_media_id', to a cluster.
             ret = minfo_cp_media(src_media_id, dst_cluster_id);
                     if( ret < 0) {
                printf("minfo_cp_media failed\n");
                return;
                     }
     }
* @endcode      
 */

int
minfo_cp_media(const char *src_media_id, const char *dst_cluster_id);



/**
 * This function moves specified media file to another folder, which is identified by the folder id, @p dst_cluster_id. Meanwhile the moved media file
 * is identified by it's media id. Compared to API, minfo_move_media, the difference is that this function moves a media content to specified folder,
 * according to the media content id and the destination folder's id, however the function, minfo_move_media, move a media content to specified folder
 * according to the media file's full pathname and folder's full name.
 * @param    src_media_id       [in]           id of the source media file, it's value is from '_id' field of the 'media' table
 * @param        dst_cluster_id     [in]         id of the destination folder, it's value is from '_id' field of the 'folder' table 

 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     None.   
 * @see   minfo_move_media.
 * @pre         None
 * @post        None
 * @par example
 * @code

 
     #include <media-svc.h>
     
     void test_minfo_mv_media(void)
     {
                int ret = -1;
                const char *src_media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";
                const char *dst_cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";

        //move an item to specified cluster.
                ret = minfo_mv_media(src_media_id, dst_cluster_id);
                if( ret < 0) {
                        printf("minfo_mv_media failed\n");
                        return;
                }
     }
* @endcode  
 */


int
minfo_mv_media(const char *src_media_id, const char *dst_cluster_id);



/**
 * This function deletes specified cluster, which is identified by the @p cluster_id. When user launch Gallery and in edit 'Albums' mode, if he/she
 * want to delete a cluster/folder, so call this function to do it. When delete a cluster/folder, the media-svc will not only delete the record in 'folder' table,
 * but delete all of records in 'media' table which are located in this folder, meanwhile delete the corresponding records in 'video_bookmark' table, etc.
 * @param                                        cluster_id    [in]             cluster id, to indicate the deleted folder/cluster
 * @return      This function returns 0 on success, or negative value with error code.
* @remarks                        delete all releated contents in cluster together with cluster
*                                     like all media files, image/video meta,bookmark information.   
 * @see   minfo_add_cluster
 * @pre         None
 * @post        None
 * @par example
 * @code


     #include <media-svc.h>
     
     void test_minfo_delete_cluster(void)
     {
        int ret = -1;
                const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";

        //delete a cluster record, meanwhile this function will delete all of items owned by this cluster.
        ret = minfo_delete_cluster(cluster_id);
                if( ret < 0) {
                        printf("minfo_delete_cluster failed\n");
                        return;
                }
     }
* @endcode       
 */

int
minfo_delete_cluster(const char *cluster_id);



/**
 * This function updates the specified cluster name using @p new_name, which just indicate the new folder name. User could 
 * call this function, when he/she wants to change some folder/cluster name. This really update the corresponding record in 
 * 'folder' table.
 * @param                                        cluster_id    [in]             cluster id, this value is from the '_id' field of 'folder' table
 * @param                                        new_name      [in]             new cluster name
 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     None.   
 * @see   None.
 * @pre         None
 * @post        None
 * @par example
 * @code


     #include <media-svc.h>
     
     void test_minfo_update_cluster_name(void)
     {
        int ret = -1;
                const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";
        char *new_name = "newfolder";

        //update a cluster's name
        ret = minfo_update_cluster_name(cluster_id,new_name);
                if( ret < 0) {
                        printf("minfo_update_cluster_name failed\n");
                        return;
                }
     }
* @endcode      
 */

int
minfo_update_cluster_name(const char *cluster_id, const char* new_name);

/**
 * This function updates the specified cluster modified date using @p modified_date, which just indicate the new modified date. User could 
 * call this function, when he/she wants to change some clsuter's modified date. This really update the corresponding record in the DB
 * @param                                        cluster_id    [in]             cluster id, this value is the identifier of the cluster
 * @param                                        modified_date      [in]                date to modify, which is a type of time_t
 * @return      This function returns zero(MB_SVC_ERROR_BASE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 * @remarks     None.   
 * @see   None.
 * @pre         None
 * @post        None
 * @par example
 * @code


     #include <media-svc.h>
         #include <time.h>
     
     void test_minfo_update_cluster_date(void)
     {
                int ret = -1;
                const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";
                time_t today;
                time(&today);

                //update a cluster's name
                ret = minfo_update_cluster_date(cluster_id, today);

                if( ret < 0) {
                        printf("minfo_update_cluster_date failed\n");
                        return;
                }
     }
* @endcode      
 */

int
minfo_update_cluster_date(const char *cluster_id,  time_t modified_date);



/**
 * This function inserts new bookmark record into 'video_bookmark' table. The inserted data should include marked time of video content, @p position 
 * and @p thumb_path, current extracted thumbnail file in marked time, etc. User should use @p media_id to identify the 
 * video content, so that add bookmark to it.
 * @param                                        media_id    [in]               media file id, uniquely identify the media content
 * @param                                        position    [in]               marked time of the media file
 * @param                                        thumb_path  [in]               the extracted thumbnail path for this marked time
 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks                         if add same input parameters twice, it fails           
 * @see    minfo_delete_bookmark
 * @pre         None
 * @post        None
 * @par example
 * @code


     #include <media-svc.h>
     
     void test_minfo_add_bookmark(void)
     {
        int ret = -1;
        int position = 2346;
                const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";
        char *thumb_path = "tmp1";

        //add a bookmark which include position, thumbnail, etc. to an item.
        ret = minfo_add_bookmark(media_id,position,thumb_path);
                if( ret < 0) {
                        printf("minfo_add_bookmark failed\n");
                        return;
                }
     }
* @endcode        
 */


int
minfo_add_bookmark(const char *media_id, const int position, const char* thumb_path);


/**
 * This function deletes specified bookmark record from 'video_bookmark' table, the deleted bookmark should be identified by @p bookmark_id. 
 * This function actually call the sqlite3 statement, 
 * "DELETE FROM video_bookmark WHERE _id = bookmark_id; "
 * In gallery or ug-imageviewer, user could get a linked list bookmark for some media file, so he/she could delete one of them using @p bookmark_id.
 * 
 * @param                                        bookmark_id    [in]            _id field in video_bookmark table.
 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     user should give a correct bookmark ID to successfully delete it.
 * @see  minfo_add_bookmark
 * @pre         None
 * @post        None
 * @par example
 * @code


     #include <media-svc.h>
     
     void test_minfo_delete_bookmark(void)
     {
        int ret = -1;
        int bookmark_id = 1;

        //delete a bookmark record in 'video_bookmark' table.
        ret = minfo_delete_bookmark(bookmark_id);

                if( ret < 0) {
                        printf("minfo_delete_bookmark failed\n");
                        return;
                }
     }
* @endcode      
 */

int
minfo_delete_bookmark(const int bookmark_id);




/**
* 
* This function gets some folder's full path. This will be called when user want to know what one folder's unique
* ID is. 
*
* @return                                       This function returns 0 on success, and -1 on failure.
* @param[in]                            url         folder  path
* @param[out]                           cluster_id               folder ID
* @exception                            None.
* @remarks                                      None.  
* @see  None.
* @pre          None
* @post None
* @par example
* @code

     #include <media-svc.h>
     
     void test_minfo_get_cluster_id_by_url(void)
     {
        int ret = -1;
                char cluster_id[256] = {0,};
        char *url = "/opt/media/Images/Wallpapers";

        //get cluster's ID using cluster's url.
        ret = minfo_get_cluster_id_by_url(url, cluster_id, sizeof(cluster_id));
                if( ret < 0) {
                        printf("test_minfo_get_cluster_id_by_url failed\n");
                        return;
                }
     }
* @endcode      
*/
int 
minfo_get_cluster_id_by_url(const char* url, char* cluster_id, int max_length);


/**
* 
* This function gets folder's name. This will be called when user want to know what one folder's name
*
* @return                                       This function returns 0 on success, and -1 on failure.
* @param[in]                            cluster_id         folder ID
* @param[out]                           cluster_name       folder name
* @param[in]                            max_length         The max length of the returned folder name.
* @exception                            None.
* @remarks                                      None.  
* @see  None.
* @pre          None
* @post None
* @par example
* @code

     #include <media-svc.h>
     
     void test_minfo_get_cluster_name_by_id(void)
     {
                int ret = -1;
                const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";
                char *cluster_name[1024];

                //get cluster's name using cluster's id.
                ret = minfo_get_cluster_name_by_id(cluster_id, cluster_name, sizeof(cluster_name));

                if( ret < 0) {
                        printf("test_minfo_get_cluster_name_by_id failed\n");
                        return;
                } else {
                        printf("cluster name is %s\n", cluster_name);
                        return;
                }
     }
* @endcode
*/
int 
minfo_get_cluster_name_by_id(const char *cluster_id, char *cluster_name, int max_length );

/**
* 
* This function gets folder's full path. This will be called when user want to know what one folder's full path.
* User should specify the maximum length of the @p folder_path, so as to avoid over flow of the string.
*
* @return                                       This function returns 0 on success, and -1 on failure.
* @param[in]                            cluster_id         folder ID
* @param[out]                           folder_path       folder path name
* @param[in]                      max_length   specify the maximum length of @p folder_path.

* @exception                            None.
* @remarks                                      None.  
* @see  None.
* @pre          None
* @post None
* @par example
* @code

     #include <media-svc.h>
     
     void test_minfo_get_cluster_fullpath_by_id(void)
     {
                int ret = -1;
                const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";
                char *folder_path[1024];

                //get cluster's path name using cluster's id.
                ret = minfo_get_cluster_fullpath_by_id(cluster_id, folder_path, sizeof(folder_path));

                if( ret < 0) {
                        printf("test_minfo_get_cluster_fullpath_by_id failed\n");
                        return;
                } else {
                        printf("path name is %s\n", cluster_name);
                        return;
                }
     }
* @endcode      
*/

int
minfo_get_cluster_fullpath_by_id(const char *cluster_id, char *folder_path, int max_length);



/**
* @fn     int  minfo_set_cluster_lock_status( int cluster_id, int lock_status );
* This function set status for lock to DB. This will be called when user want to set to lock an album.
*
* @return                                       This function returns 0 on success, and -1 on failure.
* @param[in]                            cluster_id          folder ID
* @param[in]                            lock_status         status for lock to be saved ( 0 : unlock, 1 : lock )
* @exception                            None.
* @remarks                                      None.  
* @see  minfo_get_cluster_lock_status.
* @pre          None
* @post None
* @par example
* @code

     #include <media-svc.h>
     
     void test_minfo_set_cluster_lock_status(void)
     {
        int ret = -1;
        int status = 1;
                const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";

        //set s cluster lock status.
        ret = minfo_set_cluster_lock_status(cluster_id, status);

                if( ret < 0) {
                        printf("test_minfo_set_cluster_lock_status failed\n");
                        return;
                }
     }
* @endcode
*/

int
minfo_set_cluster_lock_status(const char *cluster_id, int lock_status);

/**
* @fn     int  minfo_get_cluster_lock_status( int cluster_id, int *lock_status );
* This function gets status for lock from DB.  This will be called when user want to get lock status for an album.
*
* @return                                       This function returns 0 on success, and -1 on failure.
* @param[in]                            cluster_id          folder ID
* @param[out]                           lock_status         status for cuurent lock status
* @exception                            None.
* @remarks                                      None.  
* @see  minfo_set_cluster_lock_status.
* @pre          None
* @post None
* @par example
* @code

     #include <media-svc.h>
     
     void test_minfo_get_cluster_lock_status(void)
     {
        int ret = -1;
                const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";
                int status = -1;

        //get a cluster's status.
        ret = minfo_get_cluster_lock_status(cluster_id, &status);

                if( ret < 0) {
                        printf("test_minfo_get_cluster_lock_status failed\n");
                        return;
                } else {
                        print("Current status : %d\n", status);
                        return;
                }
     }
* @endcode
*/

int
minfo_get_cluster_lock_status(const char *cluster_id, int *lock_status );

/**
* @fn     int  minfo_get_media_path( minfo_store_type storage_type, char* media_path, size_t max_media_path);
* This function gets the path of media.  This will be called when user want to get path of direcotry containing media in device.
*
*
* @return                                       This function returns 0 on success, and -1 on failure.
* @param[in]                            storage_type         store type, which means type of device containg media.
* @param[out]                           media_path         path of media
* @param[in]                            max_media_path     The max length of the returned media_path.
* @exception                            None.
* @remarks                              None.  
* @see  None.
* @pre          None
* @post None
* @par example
* @code

     #include <media-svc.h>
     
     void test_minfo_get_media_path(void)
     {
        int ret = -1;
                char media_path[256] = {'\0'};

                //get media's fullpath.
        ret = minfo_get_media_path(MINFO_PHONE, media_path, sizeof(media_path));

                if( ret < 0) {
                        printf("minfo_get_media_path failed\n");
                        return;
                } else {
                        print("The returned path : %s\n", media_path);
                        return;
                }
     }
* @endcode
*/

int
minfo_get_media_path( minfo_store_type storage_type, char* media_path, size_t max_media_path );


/**
 *      minfo_set_db_valid:\n
 *      This function set whether all the media contents in a type of storage are valid, like phone or MMC.
 *      Actually media service will filter all the media contents query from database by the media validation.\n
 *      This function is always used for MMC card insert/inject operation, in file manager service library.
 *      When inject a MMC card, the media records for MMC are not deleted really, but are set to be invalid.
 *
 *      @param[in]   storage_type               information for storage type
 *      @param[in]      valid                           whether the track item is valid.
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            minfo_delete_invalid_media_records.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>

void set_db_valid()
{
        int ret = MB_SVC_ERROR_NONE;
        bool valid = TRUE;

        //set the validation of medias in MMC storage in db.
        ret = minfo_set_db_valid(MINFO_MMC, valid);
        if (ret < 0) {
                printf( "failed to set db invalid. error code->%d", ret);
                return;
        }
}

 *      @endcode
 */

int minfo_set_db_valid(const minfo_store_type storage_type, int valid);


/**
 *      minfo_delete_invalid_media_records:\n
 *      This function delete all of invalid media records in a type of storage are valid, like phone or MMC.
 *      Actually media service will filter all the media contents query from database by the media validation.\n
 *      This function is always used for MMC card insert/inject operation, in file manager service library.
 *      When inject a MMC card, the media records for MMC are not deleted really, but are set to be invalid.
 *
 *      @param[in]   storage_type               information for storage type
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            minfo_set_db_valid.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>

void set_db_valid()
{
        int ret = MB_SVC_ERROR_NONE;

        //delete the invalid media records in MMC storage in db.
        ret = minfo_delete_invalid_media_records(MINFO_MMC);
        if (ret < 0) {
                printf( "failed to delete invalid items. error code->%d", ret);
                return;
        }
}

 *      @endcode
 */

int
minfo_delete_invalid_media_records(const minfo_store_type storage_type);

/**
 *      minfo_delete_tag:\n
 *      This function could delete a tag or some member of the tag in 'media_tag' table in database. When user pass @p media_id not equal
 *    to -1, the tag will be deleted, otherwise some member of the tag will be deleted. Whatever cases, user should pass the correct tag name with
 *    @p tag_name to successfully delete.
 *
 *      @param[in]   media_id           identify a media item with this ID
 *      @param[in]   tag_name           name of deleted tag
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            None.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>

void add_a_tag()
{
        int ret = MB_SVC_ERROR_NONE;

        //delete all tag records in 'media_tag' in db, whose tag name is 'test_tag'.
        ret = minfo_delete_tag(-1, "test tag");
        if (ret < 0) {
                printf( "failed to delete a tag record. error code->%d", ret);
                return;
        }
}

 *      @endcode
 */

int
minfo_delete_tag(const char *media_id, const char* tag_name);


/**
 *      minfo_rename_tag:\n
 *      This function could rename a tag_name  to another tag_name in 'media_tag' table in database. User need to pass @p src_tagname which indicate original 
 *    tag name, @p dst_tag_name which is new tag name replacing @p src_tagname. This function will check whether the new tag name, @p dst_tag_name, has
 *    existed in 'media_tag' table. If yes, this function will item by item replace old tag name, if no, this function will directly update old tag name to new tag name.
 *   
 *
 *      @param[in]   src_tagname                identify original tag name
 *      @param[in]   dst_tag_name               new tag name.
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            None.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>

void test_minfo_rename_tag()
{
        int ret = MB_SVC_ERROR_NONE;

        //rename all tag records with new tag name 'test_tag2'.
        ret = minfo_rename_tag("test tag1", "test tag2");
        if (ret < 0) {
                printf( "failed to rename tag records. error code->%d", ret);
                return;
        }
}

 *      @endcode
 */

int
minfo_rename_tag(const char* src_tagname, const char* dst_tag_name);

/**
 *      minfo_rename_tag_by_id:\n
 *      This function could rename a tag_name for some tag record to another tag_name in 'media_tag' table in database. User need to pass @p src_tagname which indicate original 
 *    tag name, @p media_id which combine with the @p src_tagname to indentify one tag record, @p dst_tag_name which is new tag name replacing @p src_tagname. 
 *    This function will check whether the new tag name with @p media_id has existed in 'media_tag' table. If yes, this function will delete old tag record, if no, this function will directly 
 *    update old tag record  to new tag record.
 *   
 *
 *      @param[in]   media_id                   identify original tag record with @p src_tagname
 *      @param[in]   src_tagname                identify original tag record with @p media_id
 *      @param[in]   dst_tag_name               new tag name.
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            None.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>

void test_minfo_rename_tag_by_id()
{
        int ret = MB_SVC_ERROR_NONE;
        const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";

        //rename some tag record with new tag name 'test_tag2'.
        ret = minfo_rename_tag_by_id(media_id, "test tag1", "test tag2");
        if (ret < 0) {
                printf( "failed to rename tag records. error code->%d", ret);
                return;
        }
}

 *      @endcode
 */

int
minfo_rename_tag_by_id(const char *media_id, const char* src_tagname, const char* dst_tag_name);




/**
 *      minfo_add_tag:\n
 *      This function could add a new tag into 'media_tag' table in database. When user create a new tag and will
 *    not add any media item to it, he/she should set @p media_id as 0. When user create a new tag and want to add 
 *    some media items to it, he/she should do a loop to insert them into 'media_tag' table in database, meanwhile
 *    should fill up @p media_id and @p tag_name with appropriate values.
 *
 *      @param[in]   media_id           identify a media item with this ID
 *      @param[in]   tag_name           name of new added tag
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            None.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>

void add_a_tag()
{
        int ret = MB_SVC_ERROR_NONE;

        //add a tag record in 'media_tag' in db, and not add any media item to it.
        ret = minfo_add_tag(NULL, "test tag");
        if (ret < 0)
        {
                printf( "failed to add a tag record. error code->%d", ret);
                return;
        }

        return;
}

 *      @endcode
 */

int
minfo_add_tag(const char *media_id, const char* tag_name);

/**
 *      minfo_get_media_list_by_tagname:\n
 *      This function could get a media items' list who are included to the same tag according to tag name .
 *      User could dictate whether he/she hope to get meta data of media item with @p with_meta. Yes if TRUE,
 *    no if FALSE.
 *
 *      @param[in]   tag_name                   tag name
 *      @param[in]   with_meta          indicate whether want to get meta data of media item
 *      @param[in]      func        Iterative callback implemented by a user. This callback is called when an item has to be inserted to user's list.
 *      @param[out]  user_data       user's data structure to contain items of the type Mitem. It is passed to the iterative callback.
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            None.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>

int mitem_ite_cb(Mitem *item, void *user_data)
{
        GList** list = (GList**)user_data;
        *list = g_list_append(*list, item);
}


void get_media_list_tag_name()
{
        int ret = MB_SVC_ERROR_NONE;
        GList *p_list = NULL;

        //get a media items' list who are included to the same tag with 'test tag'.
        ret = minfo_get_media_list_by_tagname("test tag", FALSE, mitem_ite_cb, &p_list);
        if (ret < 0) {
                printf( "failed to get a media items' list. error code->%d", ret);
                return;
        }
}

 *      @endcode
 */

int
minfo_get_media_list_by_tagname(const char* tag_name, bool with_meta, minfo_item_ite_cb func, void* user_data );

/**
 *      minfo_get_media_list_by_tagname_with_filter:\n
 *      This function could get a media items' list who are included to the same tag according to tag name and filter.
 *      User could dictate whether he/she hope to get meta data of media item with @p with_meta. Yes if TRUE,
 *    no if FALSE.
 *
 *      @param[in]   tag_name           tag name
 *  @param[in]   filter                 the filter to specify some tag filter conditions, like, type of got items, sort by type, start and end positions of items, including meta data or not, etc.
 *      @param[in]      func        Iterative callback implemented by a user. This callback is called when an item has to be inserted to user's list.
 *      @param[out]  user_data       user's data structure to contain items of the type Mitem. It is passed to the iterative callback.
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            None.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>

int mitem_ite_cb(Mitem *item, void *user_data)
{
        GList** list = (GList**)user_data;
        *list = g_list_append(*list, item);
}


void get_media_list_by_tagname_with_filter()
{
        int ret = MB_SVC_ERROR_NONE;
        GList *p_list = NULL;
        minfo_tag_filter filter;

        filter.start_pos = 0;
        filter.end_pos = 3;
        filter.file_type = MINFO_ITEM_ALL;
        filter.with_meta = FALSE;

        //get a media items' list who are included to the same tag with 'test tag'.
        ret = minfo_get_media_list_by_tagname_with_filter("test tag", filter, mitem_ite_cb, &p_list);
        if (ret < 0) {
                printf( "failed to get a media items' list. error code->%d", ret);
                return;
        }
}

 *      @endcode
 */

int
minfo_get_media_list_by_tagname_with_filter(const char* tag_name, minfo_tag_filter filter, minfo_item_ite_cb func, void* user_data );

/**
 *      minfo_get_media_count_by_tagname:\n
 *      This function could get count of media items, which are included to the same tag according to tag name .
 *      User could dictate whether he/she hope to get count of media items.
 *
 *      @param[in]   tag_name           tag name
 *      @param[out]  count                      count of media items
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            None.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>

void test_minfo_get_media_count_by_tagname()
{
        int ret = MB_SVC_ERROR_NONE;
        int count = 0;

        //get count of media items, which are included to the same tag with 'test tag'.
        ret = minfo_get_media_count_by_tagname("test tag", &count);
        if (ret < 0) {
                printf( "failed to get a media items' list. error code->%d", ret);
        } else {
                printf( "Count is %d\n", count );       
        }

        return;
}

 *      @endcode
 */

int
minfo_get_media_count_by_tagname(const char* tag_name, int* count );

/**
 *      minfo_get_tag_list_by_media_id:\n
 *      This function could get a tags' list whose memeber is Mtag type. User should pass @p media_id to indicate which
 *    media item will be searched. Also he/she should define a callback function to be called by this function.
 *
 *      @param[in]   media_id           identify a media item with ID
 *      @param[in]      func        Iterative callback implemented by a user. This callback is called when an item has to be inserted to user's list.
 *      @param[out]  user_data       user's data structure to contain items of the type Mtag. It is passed to the iterative callback.
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            minfo_set_db_valid.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>

int mtag_ite_cb(Mtag *i_tag, void *user_data)
{
        GList** list = (GList**)user_data;
        *list = g_list_append(*list, item);
}


void get_tag_list_media_id()
{
        int ret = MB_SVC_ERROR_NONE;
        const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";
        GList *p_list = NULL;

        //get a tags' list which include the same media item and it's media_id is b6a4f4ac-26ea-458c-a228-9aef7f70349d.
        ret = minfo_delete_invalid_media_records(media_id, mtag_ite_cb, &p_list);
        if (ret < 0) {
                printf( "failed to get a tags' list. error code->%d", ret);
                return;
        }
}

 *      @endcode
 */

int
minfo_get_tag_list_by_media_id(const char *media_id, minfo_tag_ite_cb func, void* user_data);

/**
 *      minfo_add_web_cluster:\n
 *      This function could add a web album through specifying it's @p name, @p account_id. After adding a web
 *    album, this function will return @p id.
 *
 *      @param[in]   sns_type           sns type, like, facebook, flickr, etc.
 *      @param[in]      name        new added web album's name.
 *      @param[in]  account_id       account ID.
 *      @param[out]  id                         return album's id.
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            minfo_add_web_cluster_album_id.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>


void add_web_cluster()
{
        int ret = MB_SVC_ERROR_NONE;
        char cluster_id[256] = {0,};
        
        //add a web album.
        ret = minfo_add_web_cluster(1, "web_album",  "1", cluster_id, sizeof(cluster_id));
        if (ret < 0) {
                printf( "failed to add a web album. error code->%d", ret);
        }

        return;
}

 *      @endcode
 */

int
minfo_add_web_cluster(int sns_type, const char* name,const char *account_id, char* id, int max_length);


/**
 *      minfo_add_web_cluster_album_id:\n
 *      This function could add a web album through specifying it's @p name, @p account_id, @p album_id. After adding a web
 *    album, this function will return @p id.
 *
 *      @param[in]   sns_type           sns type, like, facebook, flickr, etc.
 *      @param[in]      name        new added web album's name.
 *      @param[in]  account_id       account ID.
 *      @param[in]  album_id       web album id
 *      @param[out]  id                         return album's id.
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            minfo_add_web_cluster.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>


void add_web_cluster_album_id()
{
        int ret = MB_SVC_ERROR_NONE;
        char cluster_id[256] = {0,};
        
        //add a web album.
        ret = minfo_add_web_cluster_album_id(1, "web_album",  "1", "1", cluster_id, sizeof(cluster_id));
        if (ret < 0) {
                printf( "failed to add a web album. error code->%d", ret);
                return;
        }

        return;
}

 *      @endcode
 */

int
minfo_add_web_cluster_album_id(int sns_type, const char* name, const char *account_id, const char *album_id, char *id, int max_length);

/**
 *      minfo_delete_web_cluster:\n
 *      This function could delete a web album through specifying @p cluster_id. After deleteing a web
 *    album, the application will not be able to get this web album displaying.
 *
 *      @param[in]   cluster_id         cluster ID identifying a web album.
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            None.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>


void delete_web_cluster()
{
        int ret = MB_SVC_ERROR_NONE;
        const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";
        
        //delete a web album.
        ret = minfo_delete_web_cluster(cluster_id);
        if (ret < 0) {
                printf( "failed to delete a web album. error code->%d", ret);
                return;
        }

        return;
}

 *      @endcode
 */

int
minfo_delete_web_cluster(const char *cluster_id);

/**
* 
* This function gets list of mcluster by web account id. User could get the detail information with
* the type 'Mcluster' about this cluster, the type 'Mcluster' mainly include folder/cluster ID, display name, 
* count of included media content, etc. The detail defination of this type could refer to the herder file, minfo_item/minfo-cluster.h.
*
* @return            This function returns 0 on success, or negative value with error code.
*                    Please refer 'media-svc-error.h' to know the exact meaning of the error.
* @param             web_account_id  [in]  the web account ID which indentify a cluster
* @param                     func   [in]     Iterative callback implemented by a user. This callback is called when an item has to be inserted to user's list.
* @param                     user_data   [out]    user's data structure to contain items of the type Mcluster. It is passed to the iterative callback.
* @exception                    None.
* @remarks                        User could pass web account id to this function, so that 
*                                      this function still could get the wanted list of clusters 
*                                      when invoking this function.
* @see      None.
* @pre          None
* @post None
* @par example
* @code
*

     #include <media-svc.h>
     int mcluster_ite_cb(Mcluster *cluster, void *user_data)
         {
                GList** list = (GList**)user_data;
                *list = g_list_append(*list, cluster);
         }

     void test_minfo_get_web_cluster_by_web_account_id(void)
     {
                int ret = -1;
                const char* account_id = "user";
                GList *p_list = NULL;
                
                //get a web cluster using account id.
                ret = minfo_get_web_cluster_by_web_account_id(account_id, mcluster_ite_cb, &p_list);
                if(ret < 0) {
                        printf("minfo_get_web_cluster_by_web_account_id fail: %d \n", ret);
                        return;
                }
         }
* @endcode
*/

int
minfo_get_web_cluster_by_web_account_id(const char* web_account_id, minfo_cluster_ite_cb func, void *user_data);

/**
* 
* This function gets mcluster information by web cluster id. User could get the detail information with
* the type 'Mcluster' about this cluster, the type 'Mcluster' mainly include folder/cluster ID, display name, 
* count of included media content, etc. The detail defination of this type could refer to the herder file, minfo-cluster.h.
*
* @return             This function returns 0 on success, or negative value with error code.
* @param             cluster_id  [in]  the cluster ID which indentify a cluster
* @param             mcluster [out]   mcluster to be returned, which is a 'Mcluster' type
* @exception                    None.
* @remarks                        User could pass cluster id to this function, so that 
*                                      this function still could get the wanted cluster.
*                                      when invoking this function, *mcluster must equals NULL, and
*                                     after using mitem, it must be freed with minfo_destroy_mtype_item.
* @see      None.
* @pre          None
* @post None
* @par example
* @code
*

     #include <media-svc.h>
     
     void test_minfo_get_web_cluster_web_album_id(void)
     {
            int ret = -1;
            Mcluster *mc = NULL;
                        const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";
         
            //get a cluster using cluster's id.
            ret = minfo_get_web_cluster_web_album_id(cluster_id, &mc);
                        if(ret < 0) {
                                printf("minfo_get_web_cluster_web_album_id fail: %d \n", ret);
                                return;
                        }

                        minfo_destroy_mtype_item(mc);
         }
* @endcode
*/

int
minfo_get_web_cluster_web_album_id(const char *web_album_id, Mcluster **mcluster);

/**
 *      minfo_add_web_media:\n
 *      This function could add a web media to web album specified by @p cluster_id, in addition, user need to pass @p http_url, @p file_name
 *    @p thumb_path. If failed to add it to web album, this function will return an error code.
 *
 *      @param[in]   cluster_id         specify cluster id to indentify a web album.
 *      @param[in]      http_url        web media's url.
 *      @param[in]  file_name       file name.
 *      @param[in]  thumb_path       thumbnail full path of this web media
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            None.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>


void test_minfo_add_web_media()
{
        int ret = MB_SVC_ERROR_NONE;
        const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";
        
        //add a web media to a web album.
        ret = minfo_add_web_media(cluster_id, "http://user/specifying/address",  "web_media", "thumbnail path");
        if (ret < 0) {
                printf( "failed to add to a web album. error code->%d", ret);
                return;
        }

        return;
}

 *      @endcode
 */

DEPRECATED_API int
minfo_add_web_media(const char *cluster_id, const char* http_url, const char* file_name, const char* thumb_path);

/**
 *      minfo_add_web_media_with_type:\n
 *      This function could add a web media to web album specified by @p cluster_id, in addition, user need to pass @p http_url, @p file_name, @p content_type, 
 *    @p thumb_path. If failed to add it to web album, this function will return an error code.
 *
 *      @param[in]   cluster_id         specify cluster id to indentify a web album.
 *      @param[in]   http_url        web media's url.
 *      @param[in]  file_name        file name.
 *      @param[in]  content_type     type of the media.
 *      @param[in]  thumb_path       thumbnail full path of this web media
 *      @return This function returns zero(MB_SVC_ERROR_NONE) on success, or negative value with error code.
 *                      Please refer 'media-svc-error.h' to know the exact meaning of the error.
 *      @see            None.
 *      @pre            None
 *      @post           None
 *      @remark None
 *      @par example
 *      @code

#include <media-svc.h>


void test_minfo_add_web_media_with_type()
{
        int ret = MB_SVC_ERROR_NONE;
        const char *cluster_id = "51298053-feb7-4261-a1c8-26b05a6e0ae0";
        
        //add a web media to a web album.
        ret = minfo_add_web_media_with_type(cluster_id, "http://user/specifying/address",  "web_media", MINFO_ITEM_IMAGE, "thumbnail name");
        if (ret < 0) {
                printf( "failed to add to a web album. error code->%d", ret);
                return;
        }

        return;
}

 *      @endcode
 */

int
minfo_add_web_media_with_type(const char *cluster_id, const char* http_url, const char* file_name, minfo_file_type content_type, const char* thumb_path);

/**
 * This function extracts thumbnail and update thumbnail path of specified media in db table file and also update width and height in image meta table if the media is a type of image.
 * @param[in]           media_id        specified _id field in media table record
 * @param[in]           content_type    type of the media.
 * @return      This function returns 0 on success, or negative value with error code.
 * @remarks     None
 * @see         minfo_get_thumb_path_for_video.
 * @pre         None
 * @post        None
 * @par example
 * @code


     #include <media-svc.h>
     
        void test_minfo_extract_thumbnail(void)
        {
                int ret = -1;
                const char *media_id = "b6a4f4ac-26ea-458c-a228-9aef7f70349d";

                ret = minfo_extract_thumbnail(media_id, MINFO_ITEM_IMAGE);
                if( ret < 0) {
                        printf("minfo_extract_thumbnail failed\n");
                        return;
                }
        }
* @endcode       
 */

DEPRECATED_API int
minfo_extract_thumbnail(const char *media_id, minfo_file_type content_type);

/**
        @}
 */


#ifdef __cplusplus
}
#endif /* __cplusplus */





#endif /*_MINFO_API_H_*/