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.
int	media_playlist_import_from_file (const char playlist_name, const char path, media_playlist_h *playlist)
	Imports the playlist from m3u playlist file.
int	media_playlist_export_to_file (media_playlist_h playlist, const char *path)
	Exports the playlist to m3u playlist file.
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.

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.

Since :: 2.3

Remarks:: To use the playlist outside this function, copy the handle with the media_playlist_clone() function.
The callback is called in the main loop.

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 struct media_playlist_s* media_playlist_h

The structure type for the Media playlist handle.

Since :: 2.3

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.

Since :: 2.3

Remarks:: To use the media outside this function, copy the handle with the media_info_clone() function.
The callback is called in the main loop.

Parameters:

[in]	playlist_member_id	The ID of the playlist member
[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

Parameters:

[in]	playlist	The handle to the media playlist
[in]	media_id	The media 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

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

Remarks:: The dst should be released using media_playlist_destroy().

Parameters:

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

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

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_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_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 operations. A new handle has to be created before next usage.

Since :: 2.3

Parameters:

[in] playlist The handle to 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

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

Exports the playlist to m3u playlist file.

Since :: 2.4

Remarks:: http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.

Parameters:

[in]	playlist	The handle to the media playlist
[in]	path	path The path to export the 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

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

Since :: 2.3

Parameters:

[in]	playlist_id	The ID of the media playlist
[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_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

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

Parameters:

[in]	playlist_id	The ID of the media playlist
[in]	filter	The handle to the media filter
[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_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_playlist_get_name	(	media_playlist_h	playlist,
		char **	playlist_name
	)

Gets a name of the playlist.

Since :: 2.3

Remarks:: The playlist_name should be released using free().

Parameters:

[in]	playlist	The handle to the media playlist
[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

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

Parameters:

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

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

Parameters:

[in]	filter	The handle to the media 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_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_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

Remarks:: The playlist should be released using media_playlist_destroy().

Parameters:

[in]	playlist_id	The ID of the media playlist
[out]	playlist	The handle to 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_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_playlist_destroy()

int media_playlist_get_playlist_id	(	media_playlist_h	playlist,
		int *	playlist_id
	)

Gets the media playlist ID.

Since :: 2.3

Parameters:

[in]	playlist	The handle to the media playlist
[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

int media_playlist_get_thumbnail_path	(	media_playlist_h	playlist,
		char **	path
	)

Gets a thumbnail path of the playlist.

Since :: 2.3

Remarks:: The path should be released using free().

Parameters:

[in]	playlist	The handle to the media playlist
[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

int media_playlist_import_from_file	(	const char *	playlist_name,
		const char *	path,
		media_playlist_h *	playlist
	)

Imports the playlist from m3u playlist file.

This function reads a playlist from the m3u playlist file and insert into the db.

Since :: 2.4

Privilege Level:: public

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

Remarks:: The playlist should be released using media_playlist_destroy().; http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
This function does not support the file of extended m3u playlist.

Parameters:

[in]	playlist_name	The name of the media playlist to save
[in]	path	The path to import the playlist file
[out]	playlist	The handle to 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_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

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

Privilege Level:: public

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

Remarks:: The playlist should be released using media_playlist_destroy().

Parameters:

[in]	name	The name of the inserted playlist
[out]	playlist	The handle to 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_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

Parameters:

[in]	playlist	The handle to the media playlist
[in]	playlist_member_id	The ID of the playlist member

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

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

Parameters:

[in]	playlist	The handle to the media playlist
[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

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

Parameters:

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

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

Parameters:

[in]	playlist	The handle to the media playlist
[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

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

Privilege Level:: public

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

Parameters:

[in] playlist The handle to 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_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_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

Typedef Documentation

Function Documentation