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, 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]	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

See also:: media_album_destroy(); media_album_foreach_album_from_db()

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().

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_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().

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]	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().

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]	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

Required Header

Overview

Foreach Operations

Functions

Typedefs

Typedef Documentation

Function Documentation