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.

Since :: 2.3.1

Iterates over an album list.

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.1

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.1

Remarks:: You must release the destination handle using media_album_destroy().

Parameters:

[in]	src	The source handle to the media album
[out]	dst	The destination 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_PERMISSION_DENIED	Permission denied

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 operation. A new handle has to be created before the next use.

Since :: 2.3.1

Parameters:

[in] album 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_PERMISSION_DENIED	Permission denied

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.1

Parameters:

[in]	filter	The media filter handle
[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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

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 registered callback function for every retrieved media info. If NULL is passed to the filter, no filtering is applied.

Since :: 2.3.1

Parameters:

[in]	album_id	The ID of the media album
[in]	filter	The media filter handle
[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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission 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_album_get_album_art	(	media_album_h	album,
		char **	album_art
	)

Gets the album art path from the album.

Since :: 2.3.1

Remarks:: You must release album_art using free().

Parameters:

[in]	album	The media album handle
[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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

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.1

Parameters:

[in]	filter	The media filter handle
[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
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()

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.1

Remarks:: You must release folder using media_album_destroy().

Parameters:

[in]	album_id	The ID of the media album
[out]	album	The album handle associated with the album ID

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

int media_album_get_album_id	(	media_album_h	album,
		int *	album_id
	)

Gets the ID of the album.

Since :: 2.3.1

Parameters:

[in]	album	The media album handle
[out]	album_id	The media album ID

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_PERMISSION_DENIED	Permission denied

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.1

Remarks:: You must release artist using free().

Parameters:

[in]	album	The media album handle
[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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

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.1

Parameters:

[in]	album_id	The ID of the media album
[in]	filter	The media filter handle
[out]	media_count	The count of the 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
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()

int media_album_get_name	(	media_album_h	album,
		char **	album_name
	)

Gets the name of the album.

Since :: 2.3.1

Remarks:: You must release album_name using free().

Parameters:

[in]	album	The media album handle
[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
MEDIA_CONTENT_ERROR_PERMISSION_DENIED	Permission denied

Required Header

Overview

Foreach Operations

Functions

Typedefs

Typedef Documentation

Function Documentation