The Media Playlist API provides functions to manage media playlists.

Required Header

#include <media_content.h>

Overview

A Playlist is a list of songs which can be played in some sequence i.e. sequential or shuffled order. The Media Playlist API provides functions to insert, delete or updates a media playlist in the database.

For inserting new playlist (media_playlist_h) in the database, call media_playlist_insert_to_db() function and call media_playlist_delete_from_db() function to delete a playlist from the database.
For adding a media item to the playlist, call media_playlist_add_media() function, for removing a media item from the playlist, call media_playlist_remove_media() function.
Finally, media_playlist_update_to_db() function should be called so as to update the given item in the media database.

Foreach Operations

FOREACH	CALLBACK	DESCRIPTION
media_playlist_foreach_playlist_from_db()	media_playlist_cb()	Iterates through playlist
media_playlist_foreach_media_from_db()	media_info_cb()	Iterates through playlist's items

Functions
int	media_playlist_get_playlist_count_from_db (filter_h filter, int *playlist_count)
	Gets the number of playlists for the passed filter from the media database.
int	media_playlist_foreach_playlist_from_db (filter_h filter, media_playlist_cb callback, void *user_data)
	Iterates through the media playlists with an optional filter from the media database.
int	media_playlist_get_media_count_from_db (int playlist_id, filter_h filter, int *media_count)
	Gets the number of the media info for the given playlist present in the media database.
int	media_playlist_foreach_media_from_db (int playlist_id, filter_h filter, playlist_member_cb callback, void *user_data)
	Iterates through the media files with an optional filter in the given audio playlist from the media database.
int	media_playlist_insert_to_db (const char name, media_playlist_h playlist)
	Inserts a new playlist with the given name into the media database.
int	media_playlist_delete_from_db (int playlist_id)
	Deletes the given playlist from the media database.
int	media_playlist_get_playlist_from_db (int playlist_id, media_playlist_h *playlist)
	Gets the media playlist from the media database.
int	media_playlist_destroy (media_playlist_h playlist)
	Destroys a playlist handle.
int	media_playlist_clone (media_playlist_h *dst, media_playlist_h src)
	Clones a playlist handle.
int	media_playlist_get_playlist_id (media_playlist_h playlist, int *playlist_id)
	Gets the media playlist ID.
int	media_playlist_get_name (media_playlist_h playlist, char **playlist_name)
	Gets a name of the playlist.
int	media_playlist_set_name (media_playlist_h playlist, const char *playlist_name)
	Sets the name of the playlist.
int	media_playlist_get_thumbnail_path (media_playlist_h playlist, char **path)
	Gets a thumbnail path of the playlist.
int	media_playlist_set_thumbnail_path (media_playlist_h playlist, const char *path)
	Sets the thumbnail path of the playlist.
int	media_playlist_set_play_order (media_playlist_h playlist, int playlist_member_id, int play_order)
	Sets the playing order in the playlist.
int	media_playlist_add_media (media_playlist_h playlist, const char *media_id)
	Adds a new media info to the playlist.
int	media_playlist_remove_media (media_playlist_h playlist, int playlist_member_id)
	Removes the playlist members related with the media from the given playlist.
int	media_playlist_get_play_order (media_playlist_h playlist, int playlist_member_id, int *play_order)
	Gets the played order of the playlist.
int	media_playlist_update_to_db (media_playlist_h playlist)
	Updates the media playlist to the media database.
Typedefs
typedef struct media_playlist_s *	media_playlist_h
	The structure type for the Media playlist handle.
typedef bool(*	media_playlist_cb )(media_playlist_h playlist, void *user_data)
	Called for every playlist in the obtained list of playlists.
typedef bool(*	playlist_member_cb )(int playlist_member_id, media_info_h media, void *user_data)
	Called for every media info with playlist member ID in the obtained list of media info.
Defines
#define	PLAYLIST_NAME "PLAYLIST_NAME"
#define	PLAYLIST_MEMBER_ORDER "PLAYLIST_MEMBER_ORDER"
#define	PLAYLIST_MEDIA_COUNT "PLAYLIST_MEDIA_COUNT"

Define Documentation

#define PLAYLIST_MEDIA_COUNT "PLAYLIST_MEDIA_COUNT"

Media count in playlist view

#define PLAYLIST_MEMBER_ORDER "PLAYLIST_MEMBER_ORDER"

Playlist name

#define PLAYLIST_NAME "PLAYLIST_NAME"

Playlist name

Typedef Documentation

typedef bool(* media_playlist_cb)(media_playlist_h playlist, void *user_data)

Called for every playlist in the obtained list of playlists.

Iterates over a playlist list.

Remarks:: To use the playlist outside this function, copy the handle with the media_playlist_clone() function.

Parameters:

[in]	playlist	The handle to the media playlist
[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_playlist_foreach_playlist_from_db() will invoke this function.

See also:: media_playlist_clone(); media_playlist_foreach_playlist_from_db()

typedef bool(* playlist_member_cb)(int playlist_member_id, media_info_h media, void *user_data)

Called for every media info with playlist member ID in the obtained list of media info.

Iterates over playlist members.

Remarks:: To use the media outside this function, copy the handle with the media_info_clone() function.

Parameters:

[in]	playlist_member_id	The ID to member of the playlist
[in]	media	The handle to the media info
[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_playlist_foreach_media_from_db() will invoke this function.

See also:: media_info_clone(); media_playlist_foreach_media_from_db()

Function Documentation

int media_playlist_add_media	(	media_playlist_h	playlist,
		const char *	media_id
	)

Adds a new media info to the playlist.

Since :: 2.3.1

Parameters:

[in]	playlist	The media playlist handle
[in]	media_id	The ID to the media info which is added

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

Precondition:: This function requires opened connection to content service by media_content_connect().

Postcondition:: media_playlist_update_to_db()

See also:: media_content_connect(); media_playlist_remove_media()

int media_playlist_clone	(	media_playlist_h *	dst,
		media_playlist_h	src
	)

Clones a playlist handle.

This function copies the media playlist handle from a source to destination. There is no media_playlist_create() function. The media_playlist_h is created internally and available through media playlist foreach function such as media_playlist_foreach_playlist_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 using media_playlist_destroy().

Parameters:

[in]	src	The source handle of a media playlist
[out]	dst	The destination handle to a media playlist

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_playlist_destroy(); media_playlist_foreach_playlist_from_db()

int media_playlist_delete_from_db ( int playlist_id )

Deletes the given playlist from the media database.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/content.write

Parameters:

[in] playlist_id The ID of media playlist

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:: This function requires opened connection to content service by media_content_connect().

See also:: media_content_connect(); media_playlist_insert_to_db()

int media_playlist_destroy ( media_playlist_h playlist )

Destroys a playlist handle.

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

Since :: 2.3.1

Parameters:

[in] playlist The media playlist 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 a copy of playlist handle by calling media_playlist_clone() or media_playlist_insert_to_db().

See also:: media_playlist_clone()

int media_playlist_foreach_media_from_db	(	int	playlist_id,
		filter_h	filter,
		playlist_member_cb	callback,
		void *	user_data
	)

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

This function gets all media files associated with the given media playlist 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]	playlist_id	The ID of the media playlist
[in]	filter	The audio 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_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_playlist_foreach_playlist_from_db	(	filter_h	filter,
		media_playlist_cb	callback,
		void *	user_data
	)

Iterates through the media playlists with an optional filter from the media database.

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

Since :: 2.3.1

Parameters:

[in]	filter	The handle to the audio 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_PERMISSION_DENIED	Permission denied

Precondition:: This function requires opened connection to content service by media_content_connect().

Postcondition:: This function invokes media_playlist_cb().

See also:: media_playlist_cb(); media_content_connect(); media_filter_create()

int media_playlist_get_media_count_from_db	(	int	playlist_id,
		filter_h	filter,
		int *	media_count
	)

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

Since :: 2.3.1

Parameters:

[in]	playlist_id	The ID of the media playlist
[in]	filter	The media filter handle
[out]	media_count	The number of media items

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:: This function requires opened connection to content service by media_content_connect().

See also:: media_content_connect()

int media_playlist_get_name	(	media_playlist_h	playlist,
		char **	playlist_name
	)

Gets a name of the playlist.

Since :: 2.3.1

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

Parameters:

[in]	playlist	The media playlist handle
[out]	playlist_name	The playlist name

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_playlist_get_play_order	(	media_playlist_h	playlist,
		int	playlist_member_id,
		int *	play_order
	)

Gets the played order of the playlist.

Since :: 2.3.1

Parameters:

[in]	playlist	The media playlist handle
[in]	playlist_member_id	The playlist member ID
[out]	play_order	The played order

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

int media_playlist_get_playlist_count_from_db	(	filter_h	filter,
		int *	playlist_count
	)

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

Since :: 2.3.1

Parameters:

[in]	filter	The handle to the filter
[out]	playlist_count	The count of the media playlist

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

Precondition:: This function requires opened connection to content service by media_content_connect().

See also:: media_content_connect()

int media_playlist_get_playlist_from_db	(	int	playlist_id,
		media_playlist_h *	playlist
	)

Gets the media playlist from the media database.

This function creates a new media playlist handle from the media database by the given playlist_id. The media playlist will be created and will be filled with the playlist information.

Since :: 2.3.1

Remarks:: You must release playlist using media_playlist_destroy().

Parameters:

[in]	playlist_id	The ID of the media playlist
[out]	playlist	The media playlist handle associated with the playlist 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_PERMISSION_DENIED	Permission denied

Precondition:: This function requires opened connection to content service by media_content_connect().

See also:: media_content_connect(); media_playlist_destroy()

int media_playlist_get_playlist_id	(	media_playlist_h	playlist,
		int *	playlist_id
	)

Gets the media playlist ID.

Since :: 2.3.1

Parameters:

[in]	playlist	The media playlist handle
[out]	playlist_id	The ID of the media playlist

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

int media_playlist_get_thumbnail_path	(	media_playlist_h	playlist,
		char **	path
	)

Gets a thumbnail path of the playlist.

Since :: 2.3.1

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

Parameters:

[in]	playlist	The media playlist handle
[out]	path	The path of the thumbnail

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_playlist_insert_to_db	(	const char *	name,
		media_playlist_h *	playlist
	)

Inserts a new playlist with the given name into the media database.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/content.write

Remarks:: You must release the created handle using media_playlist_destroy().

Parameters:

[in]	name	The name of the inserted playlist
[out]	playlist	A created handle to media playlist

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_INVALID_OPERATION	Invalid operation
MEDIA_CONTENT_ERROR_DB_FAILED	DB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSY	DB Operation busy
MEDIA_CONTENT_ERROR_NETWORK	Network fail
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_playlist_delete_from_db()

int media_playlist_remove_media	(	media_playlist_h	playlist,
		int	playlist_member_id
	)

Removes the playlist members related with the media from the given playlist.

Since :: 2.3.1

Parameters:

[in]	playlist	The media playlist handle
[in]	playlist_member_id	The playlist member 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

Precondition:: This function requires opened connection to content service by media_content_connect().

Postcondition:: media_playlist_update_to_db()

See also:: media_content_connect(); media_playlist_add_media()

int media_playlist_set_name	(	media_playlist_h	playlist,
		const char *	playlist_name
	)

Sets the name of the playlist.

Since :: 2.3.1

Parameters:

[in]	playlist	The media playlist handle
[in]	playlist_name	The name of the media playlist

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

Postcondition:: media_playlist_update_to_db()

int media_playlist_set_play_order	(	media_playlist_h	playlist,
		int	playlist_member_id,
		int	play_order
	)

Sets the playing order in the playlist.

Since :: 2.3.1

Parameters:

[in]	playlist	The media playlist handle
[in]	playlist_member_id	The playlist member ID
[in]	play_order	The playing order

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

Postcondition:: media_playlist_update_to_db()

int media_playlist_set_thumbnail_path	(	media_playlist_h	playlist,
		const char *	path
	)

Sets the thumbnail path of the playlist.

Since :: 2.3.1

Parameters:

[in]	playlist	The media playlist handle
[in]	path	The path of the thumbnail

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

Postcondition:: media_playlist_update_to_db()

int media_playlist_update_to_db ( media_playlist_h playlist )

Updates the media playlist to the media database.

The function updates the given media playlist in the media database. The function should be called after any change in the playlist, to be updated to the media database. For example, after using media_playlist_set_name() for setting the name of the playlist, the media_playlist_update_to_db() function should be called so as to update the given playlist attributes in the media database.

Since :: 2.3.1

Privilege Level:: public

Privilege:: http://tizen.org/privilege/content.write

Parameters:

[in] playlist The media playlist 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:: This function requires opened connection to content service by media_content_connect().

See also:: media_content_connect(); media_playlist_destroy(); media_playlist_add_media(); media_playlist_remove_media(); media_playlist_set_name(); media_playlist_set_play_order()

Required Header

Overview

Foreach Operations

Functions

Typedefs

Defines

Define Documentation

Typedef Documentation

Function Documentation