Tizen Native API  4.0

The Media Album API provides information related to album of media items.

Required Header

#include <media_content.h>

Overview

An album is a logical collection or grouping of related audio files. It is also used for filtering media items.
The Media Album API allows to manage media albums which contains all video and audio items from the same album.

The API provides functions to get and search media items in album group. For getting the count of media items associated with a given album, call media_album_get_media_count_from_db() function.

Foreach Operations

FOREACH CALLBACK DESCRIPTION
media_album_foreach_album_from_db() media_album_cb() Iterates through albums
media_album_foreach_media_from_db() media_info_cb() Iterates through album's items

Functions

int media_album_get_album_count_from_db (filter_h filter, int *album_count)
 Gets the number of the album for the passed filter from the media database.
int media_album_foreach_album_from_db (filter_h filter, media_album_cb callback, void *user_data)
 Iterates through the media album with optional filter from the media database.
int media_album_get_media_count_from_db (int album_id, filter_h filter, int *media_count)
 Gets the number of media info for the given album present in the media database.
int media_album_foreach_media_from_db (int album_id, filter_h filter, media_info_cb callback, void *user_data)
 Iterates through the media files with an optional filter in the given media album from the media database.
int media_album_destroy (media_album_h album)
 Destroys the album handle.
int media_album_clone (media_album_h *dst, media_album_h src)
 Clones a media album.
int media_album_get_album_id (media_album_h album, int *album_id)
 Gets the ID of the album.
int media_album_get_name (media_album_h album, char **album_name)
 Gets the name of the album.
int media_album_get_artist (media_album_h album, char **artist)
 Gets the name of the artist from the given album.
int media_album_get_album_art (media_album_h album, char **album_art)
 Gets the album art path from the album.
int media_album_get_album_from_db (int album_id, media_album_h *album)
 Gets the media album from the media database.

Typedefs

typedef struct media_album_s * media_album_h
 The structure type for the Media album handle.
typedef bool(* media_album_cb )(media_album_h album, void *user_data)
 Called for every album in the obtained list of groups.

Typedef Documentation

typedef bool(* media_album_cb)(media_album_h album, void *user_data)

Called for every album in the obtained list of groups.

Iterates over an album list.

Since :
2.3
Remarks:
To use the album outside this function, copy the handle with the media_album_clone() function.
The callback is called in the main loop.
Parameters:
[in]albumThe handle to the media album
[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_album_foreach_album_from_db() will invoke this function.
See also:
media_album_clone()
media_album_foreach_album_from_db()
typedef struct media_album_s* media_album_h

The structure type for the Media album handle.

Since :
2.3

Function Documentation

int media_album_clone ( media_album_h dst,
media_album_h  src 
)

Clones a media album.

This function copies the media album handle from a source to destination. There is no media_album_create() function. The media_album_h is created internally and available through media album foreach function such as media_album_foreach_album_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_album_destroy().
Parameters:
[out]dstThe destination handle to the media album
[in]srcThe source handle to the media album
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
See also:
media_album_destroy()
media_album_foreach_album_from_db()

Destroys the album handle.

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

Since :
2.3
Parameters:
[in]albumThe handle to the media album
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
Get copy of album handle by calling media_album_clone().
See also:
media_album_clone()
int media_album_foreach_album_from_db ( filter_h  filter,
media_album_cb  callback,
void *  user_data 
)

Iterates through the media album with optional filter from the media database.

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

Since :
2.3
Parameters:
[in]filterThe handle to the media 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_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB Operation busy
Precondition:
This function requires opened connection to content service by media_content_connect().
Postcondition:
This function invokes media_album_cb().
See also:
media_album_cb
media_content_connect()
media_filter_create()
int media_album_foreach_media_from_db ( int  album_id,
filter_h  filter,
media_info_cb  callback,
void *  user_data 
)

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

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

Since :
2.3
Parameters:
[in]album_idThe ID of the media album
[in]filterThe handle to the media 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_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB 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_album_get_album_art ( media_album_h  album,
char **  album_art 
)

Gets the album art path from the album.

Since :
2.3
Remarks:
The album_art should be released using free().
Parameters:
[in]albumThe handle to the media album
[out]album_artThe path of the media album_art
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
int media_album_get_album_count_from_db ( filter_h  filter,
int *  album_count 
)

Gets the number of the album for the passed filter from the media database.

Since :
2.3
Parameters:
[in]filterThe handle to the media filter
[out]album_countThe count of the media album
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_DB_BUSYDB Operation busy
Precondition:
This function requires opened connection to content service by media_content_connect().
See also:
media_content_connect()
int media_album_get_album_from_db ( int  album_id,
media_album_h album 
)

Gets the media album from the media database.

This function creates a new media album handle from the media database by the given album_id. Media album will be created and will be filled with the album information.

Since :
2.3
Remarks:
The album should be released using media_album_destroy().
Parameters:
[in]album_idThe ID of the media album
[out]albumThe handle to the media album
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_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB Operation busy
Precondition:
This function requires opened connection to content service by media_content_connect().
See also:
media_content_connect()
media_album_destroy()
int media_album_get_album_id ( media_album_h  album,
int *  album_id 
)

Gets the ID of the album.

Since :
2.3
Parameters:
[in]albumThe handle to the media album
[out]album_idThe ID of the media album
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
See also:
media_album_foreach_album_from_db()
int media_album_get_artist ( media_album_h  album,
char **  artist 
)

Gets the name of the artist from the given album.

Since :
2.3
Remarks:
The artist should be released using free().
Parameters:
[in]albumThe handle to the media album
[out]artistThe name of the media artist
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
int media_album_get_media_count_from_db ( int  album_id,
filter_h  filter,
int *  media_count 
)

Gets the number of media info for the given album present in the media database.

Since :
2.3
Parameters:
[in]album_idThe ID of the media album
[in]filterThe handle to the media filter
[out]media_countThe count of the media album
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_DB_BUSYDB Operation busy
Precondition:
This function requires opened connection to content service by media_content_connect().
See also:
media_content_connect()
int media_album_get_name ( media_album_h  album,
char **  album_name 
)

Gets the name of the album.

Since :
2.3
Remarks:
The album_name should be released using free().
Parameters:
[in]albumThe handle to the media album
[out]album_nameThe name of the media album handle
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