Tizen Native API
7.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] album The handle to the media album [in] user_data The user data passed from the foreach function
- Returns:
true
to continue with the next iteration of the loop, otherwisefalse
to break out of the loop
- Precondition:
- media_album_foreach_album_from_db() will invoke this function.
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] dst The destination handle to the media album [in] src The source handle to the media album
- 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_album_destroy | ( | media_album_h | album | ) |
Destroys the album handle.
This function frees all resources related to the album handle. This handle can no longer be used to perform any operations. A new handle has to be created before the next use.
- Since :
- 2.3
- Parameters:
-
[in] album The handle to the media album
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
MEDIA_CONTENT_ERROR_NONE Successful MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid 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] 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_album_cb().
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_id The ID of the media album [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().
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] album The handle to the media album [out] album_art The path of the media album_art
- 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_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] filter The handle to the media filter [out] album_count The count of the media album
- 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_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_id The ID of the media album [out] album The handle to the media album
- 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().
int media_album_get_album_id | ( | media_album_h | album, |
int * | album_id | ||
) |
Gets the ID of the album.
- Since :
- 2.3
- Parameters:
-
[in] album The handle to the media album [out] album_id The ID of the media album
- 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_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] album The handle to the media album [out] artist The name of the media artist
- 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_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_id The ID of the media album [in] filter The handle to the media filter [out] media_count The count of the media album
- 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_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] album The handle to the media album [out] album_name The name of the media album handle
- 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