Tizen Native API

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 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 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_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)
 Gets the modified date of the folder.
int media_folder_get_storage_type (media_folder_h folder, media_content_storage_e *storage_type)
 Gets the folder storage type.
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_update_to_db (media_folder_h folder)
 Updates the media folder to the media database.
int media_folder_set_name (media_folder_h folder, const char *name)
 Sets the folder name.

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.

Defines

#define FOLDER_ID   "FOLDER_ID"
#define FOLDER_PATH   "FOLDER_PATH"
#define FOLDER_NAME   "FOLDER_NAME"
#define FOLDER_MODIFIED_TIME   "FOLDER_MODIFIED_TIME"
#define FOLDER_STORAGE_TYPE   "FOLDER_STORAGE_TYPE"
#define FOLDER_NAME_PINYIN   "FOLDER_NAME_PINYIN"

Define Documentation

#define FOLDER_ID   "FOLDER_ID"

Folder ID

#define FOLDER_MODIFIED_TIME   "FOLDER_MODIFIED_TIME"

Folder modified time

#define FOLDER_NAME   "FOLDER_NAME"

Folder base name

#define FOLDER_NAME_PINYIN   "FOLDER_NAME_PINYIN"

Folder base name pinyin

#define FOLDER_PATH   "FOLDER_PATH"

Folder full path

#define FOLDER_STORAGE_TYPE   "FOLDER_STORAGE_TYPE"

Folder storage. 0-internal storage, 1-external storage


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.

Remarks:
To use the folder outside this function, copy the handle with the media_folder_clone() function.
Parameters:
[in]folderThe handle to the media folder
[in]user_dataThe 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()

Enumeration Type Documentation

Enumeration for the storage type.

This information is used to establish where the folder is.

Enumerator:
MEDIA_CONTENT_STORAGE_INTERNAL 

The device's internal storage

MEDIA_CONTENT_STORAGE_EXTERNAL 

The device's external storage


Function Documentation

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.1
Remarks:
The destination handle must be released with media_folder_destroy().
Parameters:
[out]dstThe destination handle to the media folder
[in]srcThe source handle to the media folder
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
See also:
media_folder_destroy()
media_folder_foreach_folder_from_db()

Destroys the media folder.

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

Since :
2.3.1
Parameters:
[in]folderThe handle to the media folder
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:
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.1
Remarks:
Do not call updating DB fuction 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]filterThe handle to the media folder filter
[in]callbackThe callback function to be invoked
[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_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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 from the media database.

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

Since :
2.3.1
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_idThe ID of the media folder
[in]filterThe handle to the media info filter
[in]callbackThe callback function to be invoked
[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_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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.1
Parameters:
[in]filterThe handle to filter
To allow searching over different content types, you should use filter_h.
[out]folder_countThe count of the media folder
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_DB_FAILEDDB operation failed
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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.1
Remarks:
You must release folder using media_folder_destroy().
Parameters:
[in]folder_idThe ID of the media folder
[out]folderThe media folder handle associated with the folder ID
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().
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.1
Remarks:
You must release folder_id using free().
Parameters:
[in]folderThe handle to the media folder
[out]folder_idThe ID of the media folder
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
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 from the media database.

Since :
2.3.1
Parameters:
[in]folder_idThe ID of the media folder
[in]filterThe filter of the media content
[out]media_countThe count of media folder items
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_DB_FAILEDDB operation failed
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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.

Since :
2.3.1
Parameters:
[in]folderThe handle to the media folder
[out]dateThe modified date of the folder
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
int media_folder_get_name ( media_folder_h  folder,
char **  folder_name 
)

Gets the media folder name.

Since :
2.3.1
Remarks:
You must release folder_name using free().
Parameters:
[in]folderThe handle to the media folder
[out]folder_nameThe name of the media folder
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
int media_folder_get_path ( media_folder_h  folder,
char **  path 
)

Gets the absolute path to the media folder.

Since :
2.3.1
Remarks:
You must release path using free().
Parameters:
[in]folderThe handle to the media folder
[out]pathThe path of the media folder
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied

Gets the folder storage type.

Since :
2.3.1
Parameters:
[in]folderThe handle to the media folder
[out]storage_typeThe storage type of the media folder
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
int media_folder_set_name ( media_folder_h  folder,
const char *  name 
)

Sets the folder name.

Since :
2.3.1
Parameters:
[in]folderThe handle to the media folder
[in]nameThe name of the media folder
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
Postcondition:
media_folder_update_to_db()

Updates the media folder to the media database.

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. For example, after using media_folder_set_name() for setting the name of the folder, the media_folder_update_to_db() function should be called so as to update the given folder attributes in the media database.

Since :
2.3.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/content.write
Parameters:
[in]folderThe handle to the media folder
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().
If you do not set new name of folder by using media_folder_set_name(), your updating function is failed.
See also:
media_content_connect()
media_folder_destroy()
media_folder_set_name()