Media Folder

---

The Media folder API provides functions to get information about folders.

Required Header

#include <media_content.h>

Overview

A Folder is used to organize media content files i.e. image, audio, video files, in the physical storage of the device. The Media Folder API provides functions to get basic information about existing folders e.g. folder name, path and storage type. It also provides functions to get information related to media items present in the folder.

For getting information about folder call the respective get functions e.g. to get path and name of a given folder call media_folder_get_path() and media_folder_get_name() function respectively and so on.
Similarly call media_folder_get_media_count_from_db() to get count of media items present in a given folder.

Foreach Operations

FOREACH	CALLBACK	DESCRIPTION
media_folder_foreach_folder_from_db()	media_folder_cb()	Iterates over a folder information list
media_folder_foreach_media_from_db()	media_info_cb()	Iterates media information trough the folder

Functions
int	media_folder_get_folder_count_from_db (filter_h filter, int *folder_count)
	Gets the count of folder for the passed filter from the media database.
int	media_folder_foreach_folder_from_db (filter_h filter, media_folder_cb callback, void *user_data)
	Iterates through available media folders with optional filter from the media database.
int	media_folder_get_media_count_from_db (const char *folder_id, filter_h filter, int *media_count)
	Gets the count of media files for the passed filter in the given folder_id from the media database.
int	media_folder_foreach_media_from_db (const char *folder_id, filter_h filter, media_info_cb callback, void *user_data)
	Iterates through the media files with an optional filter in the given folder_id from the media database.
int	media_folder_clone (media_folder_h *dst, media_folder_h src)
	Clones the media folder.
int	media_folder_destroy (media_folder_h folder)
	Destroys the media folder.
int	media_folder_get_folder_id (media_folder_h folder, char **folder_id)
	Gets the media folder ID.
int	media_folder_get_parent_folder_id (media_folder_h folder, char **parent_folder_id) TIZEN_DEPRECATED_API
	Gets the parent folder ID.
int	media_folder_get_path (media_folder_h folder, char **path)
	Gets the absolute path to the media folder.
int	media_folder_get_name (media_folder_h folder, char **folder_name)
	Gets the media folder name.
int	media_folder_get_modified_time (media_folder_h folder, time_t *date) TIZEN_DEPRECATED_API
	Gets the modified date of the folder.
int	media_folder_get_storage_type (media_folder_h folder, media_content_storage_e *storage_type) TIZEN_DEPRECATED_API
	Gets the folder storage type.
int	media_folder_get_storage_id (media_folder_h folder, char **storage_id) TIZEN_DEPRECATED_API
	Gets the storage id of the folder.
int	media_folder_get_order (media_folder_h folder, int *order) TIZEN_DEPRECATED_API
	Gets the folder viewing order.
int	media_folder_get_folder_from_db (const char *folder_id, media_folder_h *folder)
	Gets the media folder from the media database.
int	media_folder_set_name (media_folder_h folder, const char *name) TIZEN_DEPRECATED_API
	Sets the folder name.
int	media_folder_set_order (media_folder_h folder, int order) TIZEN_DEPRECATED_API
	Sets the folder viewing order.
int	media_folder_update_to_db (media_folder_h folder) TIZEN_DEPRECATED_API
	Updates the media folder to the media database.
Typedefs
typedef struct media_folder_s *	media_folder_h
	The structure type for the Media folder handle.
typedef bool(*	media_folder_cb )(media_folder_h folder, void *user_data)
	Called for every available media folder.

---

Typedef Documentation

typedef bool(* media_folder_cb)(media_folder_h folder, void *user_data)

Called for every available media folder.

Iterates over a list of folders.

Since :

2.3

Remarks:

To use the folder outside this function, copy the handle with the media_folder_clone() function.
The callback is called in the main loop.

Parameters:

[in]	folder	The handle to the media folder
[in]	user_data	The user data passed from the foreach function

Returns:

true to continue with the next iteration of the loop, otherwise false to break out of the loop

Precondition:

media_folder_foreach_folder_from_db() will invoke this function.

See also:

media_folder_clone()

media_folder_foreach_folder_from_db()

typedef struct media_folder_s* media_folder_h

The structure type for the Media folder handle.

Since :

2.3

---

Function Documentation

int media_folder_clone	(	media_folder_h *	dst,
		media_folder_h	src
	)

Clones the media folder.

This function copies the media folder handle from a source to destination. There is no media_folder_create() function. The media_folder_h is created internally and available through media folder foreach function such as media_folder_foreach_folder_from_db(). To use this handle outside of these foreach functions, use this function.

Since :

2.3

Remarks:

The dst should be released using media_folder_destroy().

Parameters:

[out]	dst	The destination handle to the media folder
[in]	src	The source handle to the media folder

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

See also:

media_folder_destroy()

media_folder_foreach_folder_from_db()

int media_folder_destroy

(

media_folder_h

folder

)

Destroys the media folder.

The function frees all resources related to the folder handle. This handle no longer can be used to perform any operations. A new handle has to be created before the next use.

Since :

2.3

Parameters:

[in]

folder

The handle to the media folder

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:

A copy of the media folder handle created by calling media_folder_clone().

See also:

media_folder_clone()

int media_folder_foreach_folder_from_db	(	filter_h	filter,
		media_folder_cb	callback,
		void *	user_data
	)

Iterates through available media folders with optional filter from the media database.

This function gets the media folder meeting the given filter. The callback function will be invoked for every retrieved folder. If NULL is passed to the filter, no filtering is applied.

Since :

2.3

Remarks:

Do not call updating DB function like media_folder_update_to_db() in your callback function, your callback function is invoked as inline function.
So, your callback function is in read state in SQLite. When you are in read state, sometimes you do not update DB.
We do not recommend you call updating DB function in callback of foreach function.

Parameters:

[in]	filter	The handle to the media filter
[in]	callback	The callback function to be invoked
[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_OUT_OF_MEMORY	Out of memory
MEDIA_CONTENT_ERROR_DB_FAILED	DB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSY	DB Operation busy

Precondition:

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

A filter handle has to be created by calling media_filter_create().

Postcondition:

This function invokes media_folder_cb().

See also:

media_content_connect()

media_folder_cb()

media_filter_create()

int media_folder_foreach_media_from_db	(	const char *	folder_id,
		filter_h	filter,
		media_info_cb	callback,
		void *	user_data
	)

Iterates through the media files with an optional filter in the given folder_id from the media database.

This function gets all media files associated with the given folder and meeting desired filter option and calls callback for every retrieved media item. If NULL is passed to the filter, no filtering is applied.

Since :

2.3

Remarks:

Do not call updating DB function like media_info_update_to_db(), media_info_refresh_metadata_to_db(), audio_meta_update_to_db(), image_meta_update_to_db() and video_meta_update_to_db() in your callback function, your callback function is invoked as inline function.
So, your callback function is in read state in SQLite. When you are in read state, sometimes you do not update DB.
We do not recommend you call updating DB function in callback of foreach function.

Parameters:

[in]	folder_id	The ID of the media folder
[in]	filter	The handle to the media filter
[in]	callback	The callback function to be invoked
[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_OUT_OF_MEMORY	Out of memory
MEDIA_CONTENT_ERROR_DB_FAILED	DB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSY	DB Operation busy

Precondition:

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

Postcondition:

This function invokes media_info_cb().

See also:

media_info_cb

media_content_connect()

media_filter_create()

int media_folder_get_folder_count_from_db	(	filter_h	filter,
		int *	folder_count
	)

Gets the count of folder for the passed filter from the media database.

Since :

2.3

Parameters:

[in]	filter	The handle to the media filter
[out]	folder_count	The count of the media folder

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_DB_FAILED	DB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSY	DB Operation busy

Precondition:

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

See also:

media_content_connect()

int media_folder_get_folder_from_db	(	const char *	folder_id,
		media_folder_h *	folder
	)

Gets the media folder from the media database.

This function creates a new media folder handle from the media database by the given folder_id. Media folder will be created, which is filled with folder information.

Since :

2.3

Remarks:

The folder should be released using media_folder_destroy().

Parameters:

[in]	folder_id	The ID of the media folder
[out]	folder	The handle to the media folder

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_OUT_OF_MEMORY	Out of memory
MEDIA_CONTENT_ERROR_DB_FAILED	DB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSY	DB Operation busy

Precondition:

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

See also:

media_content_connect()

media_folder_destroy()

int media_folder_get_folder_id	(	media_folder_h	folder,
		char **	folder_id
	)

Gets the media folder ID.

Since :

2.3

Remarks:

The folder_id should be released using free().

Parameters:

[in]	folder	The handle to the media folder
[out]	folder_id	The ID of the media folder

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int media_folder_get_media_count_from_db	(	const char *	folder_id,
		filter_h	filter,
		int *	media_count
	)

Gets the count of media files for the passed filter in the given folder_id from the media database.

Since :

2.3

Parameters:

[in]	folder_id	The ID of the media folder
[in]	filter	The handle to the media filter
[out]	media_count	The count of media folder items

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_DB_FAILED	DB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSY	DB Operation busy

Precondition:

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

See also:

media_content_connect()

int media_folder_get_modified_time	(	media_folder_h	folder,
		time_t *	date
	)

Gets the modified date of the folder.

Deprecated:

Deprecated since 4.0.

Since :

2.3

Parameters:

[in]	folder	The handle to the media folder
[out]	date	The modified date of the media folder

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int media_folder_get_name	(	media_folder_h	folder,
		char **	folder_name
	)

Gets the media folder name.

Since :

2.3

Remarks:

The folder_name should be released using free().

Parameters:

[in]	folder	The handle to the media folder
[out]	folder_name	The name of the media folder

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_OUT_OF_MEMORY	Out of memory

int media_folder_get_order	(	media_folder_h	folder,
		int *	order
	)

Gets the folder viewing order.

Deprecated:

Deprecated since 4.0.
This function does not guarantee order independence between applications. It is recommended that the viewing order is managed by the application.

Since :

2.4

Parameters:

[in]	folder	The handle to the media folder
[out]	order	The viewing order of the media folder

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

Postcondition:

media_folder_update_to_db()

int media_folder_get_parent_folder_id	(	media_folder_h	folder,
		char **	parent_folder_id
	)

Gets the parent folder ID.

Deprecated:

Deprecated since 4.0.

Since :

2.4

Remarks:

The parent_folder_id should be released using free().

Parameters:

[in]	folder	The handle to the media folder
[out]	parent_folder_id	The ID of the upper media folder

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int media_folder_get_path	(	media_folder_h	folder,
		char **	path
	)

Gets the absolute path to the media folder.

Since :

2.3

Remarks:

The path should be released using free().

Parameters:

[in]	folder	The handle to the media folder
[out]	path	The path of the media folder

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_OUT_OF_MEMORY	Out of memory

int media_folder_get_storage_id	(	media_folder_h	folder,
		char **	storage_id
	)

Gets the storage id of the folder.

Deprecated:

Deprecated since 5.0.

Since :

2.4

Remarks:

The storage_id should be released using free().

Parameters:

[in]	folder	The handle to the media folder
[out]	storage_id	The storage id of the media folder

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_OUT_OF_MEMORY	Out of memory

int media_folder_get_storage_type	(	media_folder_h	folder,
		media_content_storage_e *	storage_type
	)

Gets the folder storage type.

Deprecated:

Deprecated since 5.0. Use storage_get_type_dev() instead.

Since :

2.3

Parameters:

[in]	folder	The handle to the media folder
[out]	storage_type	The storage type of the media folder

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int media_folder_set_name	(	media_folder_h	folder,
		const char *	name
	)

Sets the folder name.

Deprecated:

Deprecated since 4.0. Use media_content_scan_folder() or media_info_move_to_db() instead.

Since :

2.3

Parameters:

[in]	folder	The handle to the media folder
[in]	name	The name of the media folder

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

int media_folder_set_order	(	media_folder_h	folder,
		int	order
	)

Sets the folder viewing order.

Deprecated:

Deprecated since 4.0.
This function does not guarantee order independence between applications. It is recommended that the viewing order is managed by the application.

If you set the order value for each folder, you can sort in ascending or descending order as the set order values using the filter.
Moreover, more detailed settings are possible when used with the filter.

Since :

2.4

Remarks:

If you don't set the order value, the order value will be set default value. Default is 0.
If you don't use the filter, the set order value does not effect the folder viewing order.

Parameters:

[in]	folder	The handle to the media folder
[in]	order	The viewing order of the media folder

Returns:

0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

int media_folder_update_to_db

(

media_folder_h

folder

)

Updates the media folder to the media database.

Deprecated:

Deprecated since 4.0. Related setter functions are deprecated, therefore this function is not needed anymore.

The function updates the given media folder in the media database. The function should be called after any change in folder attributes, to be updated to the media database.

Since :

2.3

Privilege Level:

public

Privilege:

http://tizen.org/privilege/content.write

Parameters:

[in]

folder

The handle to the media folder

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_OUT_OF_MEMORY	Out of memory
MEDIA_CONTENT_ERROR_INVALID_OPERATION	Invalid operation
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_PERMISSION_DENIED	Permission denied

Precondition:

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

See also:

media_content_connect()

media_folder_destroy()