Tizen Native API  3.0
Media Content

The Media Content API provides functions, enumerations used in the entire Content Service.

Required Header

#include <media_content.h>

Overview

The Media Content API provides functions and enumerations used in the entire Content Service.
The information about media items i.e. image, audio and video, are managed in the content database and operations that involve database requires an active connection with the media content service.
During media scanning, Media Service extract media information automatically. media information include basic file info like path, size, modified time etc and some metadata like ID3tag, EXIF, thumbnail, etc. (thumbnail extracted only in Internal and SD card storage.)
Since 3.0, a thumbnail is not automatically extracted during media scanning. A thumbnail will be created only when media_info_create_thumbnail() is called by any application.
Media content services do not manage hidden files.
The API provides functions for connecting (media_content_connect()) and disconnecting (media_content_disconnect()) from the media content service.

The API consists of Media Folder,Media Tag,Media Filter, Media Information API and others.

API Description
Media Folder Provide information about folders (e.g. path, name, modification date) stored on the device.
Provide information about the media items present in the folders.
Media Tag Provide information about media tags.
Provide functions to insert or delete tag from database.
Provide functions to add and remove media item from tags in the database.
Media Filter Provide functions for creating and destroying media filters.
Provide functions to get filter properties
Media Information Provide generic information about media content items (i.e. image, audio, video and others).
Provide details about audio files (e.g. name, author, genre etc) present in the device.
Provide details about image files (e.g. width, height, orientation etc) present in the device.
Provide details about video files (e.g. width, height, duration etc) present in the device .
Media Playlist Provide information about the media playlist.
Media Album Provide information about the media album.
Media Group Provide information about the media group(e.g. media artist, composer, genre, year).
Media Bookmark

Provide information about the media bookmark.

Functions

int media_content_connect (void)
 Connects to the media content service.
int media_content_disconnect (void)
 Disconnects from the media content service.
int media_content_scan_file (const char *path)
 Requests to scan a media file.
int media_content_scan_folder (const char *path, bool is_recursive, media_scan_completed_cb callback, void *user_data)
 Requests to scan a media folder, asynchronously.
int media_content_cancel_scan_folder (const char *path)
 Requests to cancel the media folder scanning.
int media_content_set_db_updated_cb (media_content_db_update_cb callback, void *user_data) TIZEN_DEPRECATED_API
 Subscribes notifications of the media DB change.
int media_content_unset_db_updated_cb (void) TIZEN_DEPRECATED_API
 Unsubscribes notifications of the media DB change.
int media_content_add_db_updated_cb (media_content_db_update_cb callback, void *user_data, media_content_noti_h *noti_handle)
 Subscribes notifications of the media DB change.
int media_content_remove_db_updated_cb (media_content_noti_h noti_handle)
 Unsubscribes notifications of the media DB change.

Typedefs

typedef void * media_content_noti_h
 The structure type for the Media content noti handle.
typedef void(* media_scan_completed_cb )(media_content_error_e error, void *user_data)
 Called when the media scanning is finished.
typedef void(* media_content_db_update_cb )(media_content_error_e error, int pid, media_content_db_update_item_type_e update_item, media_content_db_update_type_e update_type, media_content_type_e media_type, char *uuid, char *path, char *mime_type, void *user_data)
 Called when the notification of the media DB change is subscribed.

Typedef Documentation

typedef void(* media_content_db_update_cb)(media_content_error_e error, int pid, media_content_db_update_item_type_e update_item, media_content_db_update_type_e update_type, media_content_type_e media_type, char *uuid, char *path, char *mime_type, void *user_data)

Called when the notification of the media DB change is subscribed.

Since :
2.3.1
Remarks:
The callback is called in a separate thread(not in the main loop).
Parameters:
[in]errorThe error code
[in]pidThe PID which publishes notification
[in]update_itemThe update item of notification
[in]update_typeThe update type of notification
[in]media_typeThe type of the media content (media_content_type_e)
[in]uuidThe UUID of media or directory, which is updated
[in]pathThe path of the media or directory
[in]mime_typeThe mime type of the media info
[in]user_dataThe user data passed from the foreach function
Precondition:
media_content_db_update_subscribe().
See also:
media_content_db_update_subscribe()
typedef void* media_content_noti_h

The structure type for the Media content noti handle.

Since :
3.0
typedef void(* media_scan_completed_cb)(media_content_error_e error, void *user_data)

Called when the media scanning is finished.

Since :
2.3.1
Remarks:
The callback is called in a separate thread(not in the main loop).
Parameters:
[in]errorThe error code
[in]user_dataThe user data passed from the foreach function
Precondition:
media_content_scan().
See also:
media_content_scan()

Enumeration Type Documentation

Enumeration for collations.

Since :
2.3.1
Enumerator:
MEDIA_CONTENT_COLLATE_DEFAULT 

Default collation BINARY

MEDIA_CONTENT_COLLATE_NOCASE 

Collation NOCASE, not case sensitive

MEDIA_CONTENT_COLLATE_RTRIM 

Collation RTRIM, trailing space characters are ignored

MEDIA_CONTENT_COLLATE_LOCALIZED 

Collation LOCALIZATION, NOCASE also applied

Enumeration for media content DB update items.

Since :
2.3.1
Enumerator:
MEDIA_ITEM_FILE 

File type, an item updated to DB

MEDIA_ITEM_DIRECTORY 

Directory type, an item updated to DB

Enumeration for media content DB update types.

Since :
2.3.1
Enumerator:
MEDIA_CONTENT_INSERT 

Insert, the type of DB update

MEDIA_CONTENT_DELETE 

Delete, The type of DB update

MEDIA_CONTENT_UPDATE 

Update, The type of DB update

Enumeration for a media content error.

Since :
2.3.1
Enumerator:
MEDIA_CONTENT_ERROR_NONE 

Successful

MEDIA_CONTENT_ERROR_INVALID_PARAMETER 

Invalid parameter

MEDIA_CONTENT_ERROR_OUT_OF_MEMORY 

Out of memory

MEDIA_CONTENT_ERROR_INVALID_OPERATION 

Invalid Operation

MEDIA_CONTENT_FILE_NO_SPACE_ON_DEVICE 

No space left on device

MEDIA_CONTENT_ERROR_PERMISSION_DENIED 

Permission denied

MEDIA_CONTENT_ERROR_DB_FAILED 

DB operation failed

MEDIA_CONTENT_ERROR_DB_BUSY 

DB operation BUSY

MEDIA_CONTENT_ERROR_NETWORK 

Network Fail

MEDIA_CONTENT_ERROR_UNSUPPORTED_CONTENT 

Unsupported Content

MEDIA_CONTENT_ERROR_NOT_SUPPORTED 

Not supported

Enumeration for ordering.

Since :
2.3.1
Enumerator:
MEDIA_CONTENT_ORDER_ASC 

Ascending order

MEDIA_CONTENT_ORDER_DESC 

Descending order

Enumeration for the storage type.

This information is used to establish where the folder is.

Since :
2.3.1
Enumerator:
MEDIA_CONTENT_STORAGE_INTERNAL 

The device's internal storage

MEDIA_CONTENT_STORAGE_EXTERNAL 

The device's external storage like sd card

MEDIA_CONTENT_STORAGE_EXTERNAL_USB 

The external USB storage (Since 3.0)

MEDIA_CONTENT_STORAGE_CLOUD 

The Cloud storage (Since 3.0)

Enumeration for the media file format.

Since :
2.3.1
Enumerator:
MEDIA_CONTENT_TYPE_IMAGE 

The type of an image

MEDIA_CONTENT_TYPE_VIDEO 

The type of a video

MEDIA_CONTENT_TYPE_SOUND 

The type of sound

MEDIA_CONTENT_TYPE_MUSIC 

The type of music

MEDIA_CONTENT_TYPE_OTHERS 

The type of other

Enumeration for a media group.

Since :
2.3.1
Enumerator:
MEDIA_CONTENT_GROUP_DISPLAY_NAME 

Media group ID for display name

MEDIA_CONTENT_GROUP_TYPE 

Media group ID for a media type

MEDIA_CONTENT_GROUP_MIME_TYPE 

Media group ID for a mime type

MEDIA_CONTENT_GROUP_SIZE 

Media group ID for content size

MEDIA_CONTENT_GROUP_ADDED_TIME 

Media group ID for the added time

MEDIA_CONTENT_GROUP_MODIFIED_TIME 

Media group ID for the modified time

MEDIA_CONTENT_GROUP_TITLE 

Media group ID for a content title

MEDIA_CONTENT_GROUP_ARTIST 

Media group ID for an artist

MEDIA_CONTENT_GROUP_ALBUM_ARTIST 

Media group ID for an album artist

MEDIA_CONTENT_GROUP_GENRE 

Media group ID for a genre

MEDIA_CONTENT_GROUP_COMPOSER 

Media group ID for a composer

MEDIA_CONTENT_GROUP_YEAR 

Media group ID for a year

MEDIA_CONTENT_GROUP_RECORDED_DATE 

Media group ID for the recorded date

MEDIA_CONTENT_GROUP_COPYRIGHT 

Media group ID for the copyright

MEDIA_CONTENT_GROUP_TRACK_NUM 

Media group ID for a track number

MEDIA_CONTENT_GROUP_DESCRIPTION 

Media group ID for a description

MEDIA_CONTENT_GROUP_LONGITUDE 

Media group ID for the longitude

MEDIA_CONTENT_GROUP_LATITUDE 

Media group ID for the latitude

MEDIA_CONTENT_GROUP_ALTITUDE 

Media group ID for the altitude

MEDIA_CONTENT_GROUP_BURST_IMAGE 

Media group ID for the burst shot

MEDIA_CONTENT_GROUP_RATING 

Media group ID for a rating

MEDIA_CONTENT_GROUP_AUTHOR 

Media group ID for an author

MEDIA_CONTENT_GROUP_PROVIDER 

Media group ID for a provider

MEDIA_CONTENT_GROUP_CONTENT_NAME 

Media group ID for the content name

MEDIA_CONTENT_GROUP_CATEGORY 

Media group ID for a category

MEDIA_CONTENT_GROUP_LOCATION_TAG 

Media group ID for a location tag

MEDIA_CONTENT_GROUP_AGE_RATING 

Media group ID for an age rating

MEDIA_CONTENT_GROUP_KEYWORD 

Media group ID for a keyword

MEDIA_CONTENT_GROUP_WEATHER 

Media group ID for the weather

MEDIA_CONTENT_GROUP_MAX 

Invalid media group ID


Function Documentation

int media_content_add_db_updated_cb ( media_content_db_update_cb  callback,
void *  user_data,
media_content_noti_h noti_handle 
)

Subscribes notifications of the media DB change.

This function subscribes notifications of the media DB change which are published by the media server or other apps.
media_content_db_update_cb() function will be called when notification of the media DB change is subscribed.
Using this API, multiple callback is possible to register in one process.

Since :
3.0
Remarks:
To release the registered callback, you must use media_content_remove_db_updated_cb() API.
media_content_unset_db_updated_cb() API can not release the callbacks added by this API.
If you set the same callback that you previously added, this API returns MEDIA_CONTENT_ERROR_INVALID_OPERATION error.
Parameters:
[in]callbackThe callback to be invoked when the scanning is finished
[in]user_dataThe user data to be passed to the callback function
[out]noti_handleThe handle to db updated notification
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
See also:
media_content_db_update_cb()
media_content_remove_db_updated_cb()
int media_content_cancel_scan_folder ( const char *  path)

Requests to cancel the media folder scanning.

Since :
3.0
Parameters:
[in]pathThe folder path
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
media_content_scan_folder()
int media_content_connect ( void  )

Connects to the media content service.

Any media content related function call should be invoked after this function call.

Since :
2.3.1
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_DB_FAILEDDB operation failed
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
Postcondition:
media_content_disconnect()
See also:
media_content_disconnect()
int media_content_disconnect ( void  )

Disconnects from the media content service.

This function closes connection to the media content service. Any further media content related operation cannot be performed after this function is called.

Since :
2.3.1
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_DB_FAILEDDB operation failed
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
Precondition:
media_content_connect()
See also:
media_content_connect()

Unsubscribes notifications of the media DB change.

This function unsubscribes notifications of the media DB change which are published by the media server or other apps.

Since :
3.0
Parameters:
[in]noti_handleThe handle to db updated notification
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
media_content_add_db_updated_cb()
See also:
media_content_add_db_updated_cb()
int media_content_scan_file ( const char *  path)

Requests to scan a media file.

This function requests to scan a media file to the media server. If media file is not registered to DB yet, that media file information will be added to the media DB. If it is already registered to the DB, then this tries to refresh information. If requested file does not exist on file system, information of the media file will be removed from the media DB.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/content.write
http://tizen.org/privilege/mediastorage
http://tizen.org/privilege/externalstorage
Remarks:
You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path.
If you want to access only internal storage by using this API, you should add privilege http://tizen.org/privilege/mediastorage.
Or if you want to access only external storage by using this API, you should add privilege http://tizen.org/privilege/externalstorage.
If you can access both storage, you must add all privilege.
Parameters:
[in]pathThe file path
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
Precondition:
This function requires opened connection to content service by media_content_connect().
int media_content_scan_folder ( const char *  path,
bool  is_recursive,
media_scan_completed_cb  callback,
void *  user_data 
)

Requests to scan a media folder, asynchronously.

This function requests to scan a media folder to the media server with given completed callback function. media_scan_completed_cb() function will be called when the scanning is finished. The sub folders are also scanned, if there are sub folders in that folder.
If any folder must not be scanned, a blank file ".scan_ignore" has to be created in that folder.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/content.write
http://tizen.org/privilege/mediastorage
http://tizen.org/privilege/externalstorage
Remarks:
You must add privilege http://tizen.org/privilege/content.write. And You add more privilege depending on your choice of contents path.
If you want to access only internal storage by using this API, you should add privilege http://tizen.org/privilege/mediastorage.
Or if you want to access only external storage by using this API, you should add privilege http://tizen.org/privilege/externalstorage.
If you can access both storage, you must add all privilege.
Parameters:
[in]pathThe folder path
[in]is_recursiveSet true to scan recursively subdirectories, otherwise false to scan only the current directory
[in]callbackThe callback to be invoked when the scanning is finished
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
See also:
media_scan_completed_cb()
int media_content_set_db_updated_cb ( media_content_db_update_cb  callback,
void *  user_data 
)

Subscribes notifications of the media DB change.

Deprecated:
Deprecated since 3.0. Use media_content_add_db_updated_cb() instead.

This function subscribes notifications of the media DB change which are published by the media server or other apps. media_content_db_update_cb() function will be called when notification of the media DB change is subscribed.

Since :
2.3.1
Parameters:
[in]callbackThe callback to be invoked when the scanning is finished
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
See also:
media_content_db_update_cb()
media_content_unset_db_updated_cb()

Unsubscribes notifications of the media DB change.

Deprecated:
Deprecated since 3.0. Use media_content_remove_db_updated_cb() instead.

This function unsubscribes notifications of the media DB change which are published by the media server or other apps.

Since :
2.3.1
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
Precondition:
media_content_set_db_updated_cb()
See also:
media_content_set_db_updated_cb()