Tizen Native API  5.0
Media Playlist

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]playlistThe handle to the media playlist
[in]user_dataThe 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_idThe ID of the playlist member
[in]mediaThe handle to the media info
[in]user_dataThe 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]playlistThe handle to the media playlist
[in]media_idThe media ID
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut 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()

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]dstThe destination handle to the media playlist
[in]srcThe source handle to the media playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut 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_idThe ID of media playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_CONTENT_ERROR_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB Operation busy
MEDIA_CONTENT_ERROR_NETWORKNetwork fail
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
Precondition:
This function requires opened connection to content service by media_content_connect().
See also:
media_content_connect()
media_playlist_insert_to_db()

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]playlistThe handle to the media playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid 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]playlistThe handle to the media playlist
[in]pathpath The path to export the playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_CONTENT_ERROR_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB Operation busy
MEDIA_CONTENT_ERROR_NETWORKNetwork fail
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission 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_idThe ID of the media playlist
[in]filterThe handle to the media filter
[in]callbackThe callback function to be invoked
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB 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]filterThe handle to the media filter
[in]callbackThe callback function to be invoked
[in]user_dataThe user data to be passed to the callback function
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB 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_idThe ID of the media playlist
[in]filterThe handle to the media filter
[out]media_countThe number of media items
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB 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]playlistThe handle to the media playlist
[out]playlist_nameThe playlist name
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut 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]playlistThe handle to the media playlist
[in]playlist_member_idThe ID of the playlist member
[out]play_orderThe played order
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid 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]filterThe handle to the media filter
[out]playlist_countThe count of the media playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB 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_idThe ID of the media playlist
[out]playlistThe handle to the media playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB 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]playlistThe handle to the media playlist
[out]playlist_idThe ID of the media playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid 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]playlistThe handle to the media playlist
[out]pathThe path of the thumbnail
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut 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_nameThe name of the media playlist to save
[in]pathThe path to import the playlist file
[out]playlistThe handle to the media playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_CONTENT_ERROR_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB Operation busy
MEDIA_CONTENT_ERROR_NETWORKNetwork fail
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission 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]nameThe name of the inserted playlist
[out]playlistThe handle to the media playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_CONTENT_ERROR_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB Operation busy
MEDIA_CONTENT_ERROR_NETWORKNetwork fail
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission 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]playlistThe handle to the media playlist
[in]playlist_member_idThe ID of the playlist member
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut 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]playlistThe handle to the media playlist
[in]playlist_nameThe name of the media playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut 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]playlistThe handle to the media playlist
[in]playlist_member_idThe ID of the playlist member
[in]play_orderThe playing order
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut 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]playlistThe handle to the media playlist
[in]pathThe path of the thumbnail
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
Postcondition:
media_playlist_update_to_db()

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]playlistThe handle to the media playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_CONTENT_ERROR_DB_FAILEDDB Operation failed
MEDIA_CONTENT_ERROR_DB_BUSYDB Operation busy
MEDIA_CONTENT_ERROR_NETWORKNetwork fail
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission 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()