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)
	Removes 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.
Defines
#define	MEDIA_CONTENT_ERROR_CLASS   TIZEN_ERROR_MEDIA_CONTENT
	Error class.

---

Define Documentation

#define MEDIA_CONTENT_ERROR_CLASS   TIZEN_ERROR_MEDIA_CONTENT

Error class.

Class for Media Content error

Since :

2.3

---

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.

The following error codes can be received:
MEDIA_CONTENT_ERROR_NONE : Success

Since :

2.3

Remarks:

The callback is called in a separate thread(not in the main loop).

Parameters:

[in]	error	The error code
[in]	pid	The PID which publishes notification
[in]	update_item	The update item of notification
[in]	update_type	The update type of notification
[in]	media_type	The type of the media content (media_content_type_e)
[in]	uuid	The UUID of media or directory, which is updated
[in]	path	The path of the media or directory
[in]	mime_type	The MIME of the media info
[in]	user_data	The 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.

The following error codes can be received:
MEDIA_CONTENT_ERROR_NONE : Success
MEDIA_CONTENT_ERROR_INVALID_PARAMETER : Invalid parameter
MEDIA_CONTENT_ERROR_INVALID_OPERATION : Invalid operation
MEDIA_CONTENT_ERROR_PERMISSION_DENIED : Permission denied
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY : Out of memory
MEDIA_CONTENT_ERROR_DB_FAILED : DB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSY : DB Operation busy
MEDIA_CONTENT_ERROR_NETWORK : Network fail

Since :

2.3

Remarks:

The callback is called in a separate thread(not in the main loop).

Parameters:

[in]	error	The error code
[in]	user_data	The user data passed from the foreach function

Precondition:

media_content_scan_folder().

See also:

media_content_scan_folder()

---

Enumeration Type Documentation

enum media_content_collation_e

Enumeration for collations.

Since :

2.3

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

enum media_content_db_update_item_type_e

Enumeration for media content DB update items.

Since :

2.3

Enumerator:

MEDIA_ITEM_FILE	File type, an item updated to DB
MEDIA_ITEM_DIRECTORY	Directory type, an item updated to DB

enum media_content_db_update_type_e

Enumeration for media content DB update types.

Since :

2.3

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

enum media_content_error_e

Enumeration for a media content error.

Since :

2.3

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

enum media_content_order_e

Enumeration for ordering.

Since :

2.3

Enumerator:

MEDIA_CONTENT_ORDER_ASC	Ascending order
MEDIA_CONTENT_ORDER_DESC	Descending order
MEDIA_CONTENT_ORDER_OTHER	order by order key

enum media_content_storage_e

Enumeration for the storage type.

This information is used to establish where the folder is.

Since :

2.3

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 2.4)
MEDIA_CONTENT_STORAGE_CLOUD	The Cloud storage (Since 2.4, Deprecated since 4.0)

enum media_content_type_e

Enumeration for the media file format.

Since :

2.3

Remarks:

Since 4.0, MEDIA_CONTENT_TYPE_OTHERS is related to the following feature:
http://tizen.org/feature/content.scanning.others
If this feature is not supported on the device, MEDIA_CONTENT_TYPE_OTHERS type file is not scanned.

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

enum media_group_e

Enumeration for a media group.

Since :

2.3

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 (Deprecated since 4.0)
MEDIA_CONTENT_GROUP_RATING	Media group ID for a rating
MEDIA_CONTENT_GROUP_AUTHOR	Media group ID for an author (Deprecated since 4.0)
MEDIA_CONTENT_GROUP_PROVIDER	Media group ID for a provider (Deprecated since 4.0)
MEDIA_CONTENT_GROUP_CONTENT_NAME	Media group ID for the content name (Deprecated since 4.0)
MEDIA_CONTENT_GROUP_CATEGORY	Media group ID for a category (Deprecated since 4.0)
MEDIA_CONTENT_GROUP_LOCATION_TAG	Media group ID for a location tag (Deprecated since 4.0)
MEDIA_CONTENT_GROUP_AGE_RATING	Media group ID for an age rating (Deprecated since 4.0)
MEDIA_CONTENT_GROUP_KEYWORD	Media group ID for a keyword (Deprecated since 4.0)
MEDIA_CONTENT_GROUP_WEATHER	Media group ID for the weather (Deprecated since 4.0)
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 function, multiple callback is possible to register in one process.

Since :

3.0

Remarks:

The noti_handle should be released using media_content_remove_db_updated_cb().
If you set the same callback that you previously added, this function returns MEDIA_CONTENT_ERROR_INVALID_OPERATION error.

Parameters:

[in]	callback	The callback to be invoked when the scanning is finished
[in]	user_data	The user data to be passed to the callback function
[out]	noti_handle	The handle to db updated notification

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_INVALID_OPERATION	Invalid operation
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out 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 :

2.4

Parameters:

[in]

path

The folder path

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_INVALID_OPERATION	Invalid operation

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

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_DB_FAILED	DB operation failed

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

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_DB_FAILED	DB operation failed

Precondition:

media_content_connect()

See also:

media_content_connect()

int media_content_remove_db_updated_cb

(

media_content_noti_h

noti_handle

)

Removes 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_handle

The handle to db updated notification

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid 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.
If file information does not exist in DB, this function will be return MEDIA_CONTENT_ERROR_INVALID_PARAMETER.

Since :

2.3

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 function, you should add privilege http://tizen.org/privilege/mediastorage.
Or if you want to access only external storage by using this function, you should add privilege http://tizen.org/privilege/externalstorage.
If you can access both storage, you must add all privilege.
Since 4.0, This function does not allow a symbolic link.

Since 4.0, this function is related to the following feature:
http://tizen.org/feature/content.scanning.others
If this feature is not supported on the device, MEDIA_CONTENT_TYPE_OTHERS type file is not scanned.

Parameters:

[in]

path

The file path

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_INVALID_OPERATION	Invalid operation
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_NOT_SUPPORTED	Not supported

Precondition:

This function requires opened connection to content service by media_content_connect().

See also:

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. After adding or removing a folder from the filesystem, call this function on its source location (this will add or remove an entry from the database).
After moving or renaming a folder in the filesystem, call this function on its source location (this will remove an entry from the database) and call this function again on its destination location (this will add a new entry to the database).
Alternatively, you can call this function on any parent of source location and on any parent of destination location.
You can also call the function once, on a folder which is a parent of both source and destination.

Since :

2.3

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 function, you should add privilege http://tizen.org/privilege/mediastorage.
Or if you want to access only external storage by using this function, you should add privilege http://tizen.org/privilege/externalstorage.
If you can access both storage, you must add all privilege.
Since 4.0, This function does not allow a symbolic link.

Parameters:

[in]	path	The folder path
[in]	is_recursive	Set true to scan recursively subdirectories, otherwise false to scan only the current directory
[in]	callback	The callback to be invoked when the scanning is finished
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_INVALID_OPERATION	Invalid operation
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory
MEDIA_CONTENT_ERROR_DB_FAILED	DB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSY	DB Operation busy
MEDIA_CONTENT_ERROR_NETWORK	Network fail

Precondition:

This function requires opened connection to content service by media_content_connect().

See also:

media_scan_completed_cb()

media_content_connect()

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

Parameters:

[in]	callback	The callback to be invoked when the scanning is finished
[in]	user_data	The user data to be passed to the callback function

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_INVALID_OPERATION	Invalid operation
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

See also:

media_content_db_update_cb()

media_content_unset_db_updated_cb()

int media_content_unset_db_updated_cb

(

void

)

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

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE

Successful

Precondition:

media_content_set_db_updated_cb()

See also:

media_content_set_db_updated_cb()