Tizen(Headed) Native API  6.5
Media Controller Playlist

The Media Controller Playlist API provides functions for playlist of the media.

Required Header

#include <media_controller_playlist.h>

Overview

The Media Controller Playlist API allows you to get playlist name and its items (mc_playlist_get_name() and mc_playlist_foreach_item()).
You can copy the playlist by using mc_playlist_clone(). And if you don't use handle anymore, you have to destroy it(mc_playlist_destroy()).

Functions

int mc_playlist_get_name (mc_playlist_h playlist, char **playlist_name)
 Gets the name of the playlist.
int mc_playlist_get_item_count (mc_playlist_h playlist, int *item_count)
 Gets the number of the media item in a playlist.
int mc_playlist_foreach_item (mc_playlist_h playlist, mc_playlist_item_cb callback, void *user_data)
 Iterates through media items in a playlist.
int mc_playlist_get_playlist_count (const char *app_id, int *playlist_count)
 Gets the number of playlists for the given app_id.
int mc_playlist_foreach_playlist (const char *app_id, mc_playlist_cb callback, void *user_data)
 Iterates over playlists of the media controller server.
int mc_playlist_get_playlist (const char *app_id, const char *playlist_name, mc_playlist_h *playlist)
 Gets the playlist handle.
int mc_playlist_clone (mc_playlist_h src, mc_playlist_h *dst)
 Clones a media controller playlist handle.
int mc_playlist_destroy (mc_playlist_h playlist)
 Destroys a media controller playlist handle.

Typedefs

typedef bool(* mc_playlist_cb )(mc_playlist_h playlist, void *user_data)
 Called for every playlist.
typedef bool(* mc_playlist_item_cb )(const char *index, mc_metadata_h metadata, void *user_data)
 Called for every playlist item in the playlist.

Typedef Documentation

typedef bool(* mc_playlist_cb)(mc_playlist_h playlist, void *user_data)

Called for every playlist.

Since :
4.0
Remarks:
The playlist should not be released by the application.
To use the playlist outside this function, copy the handle with the mc_playlist_clone() function.
The callback is called in the main loop.
Parameters:
[in]playlistThe handle of the media controller 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:
mc_playlist_foreach_playlist() will invoke this function.
See also:
mc_playlist_clone()
mc_playlist_foreach_playlist()
mc_playlist_get_name()
mc_playlist_foreach_item()
typedef bool(* mc_playlist_item_cb)(const char *index, mc_metadata_h metadata, void *user_data)

Called for every playlist item in the playlist.

Since :
4.0
Remarks:
The index and metadata should not be released by the application.
The index can be used only in the callback. To use outside, make a copy. And metadata also can be used only in the callback. To use outside, make a copy with the mc_metadata_clone() function.
The callback is called in the main loop.
Parameters:
[in]indexThe ID of the playlist member.
[in]metadataThe handle to metadata of the playlist item.
[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:
mc_playlist_foreach_item() will invoke this function.
See also:
mc_playlist_foreach_item()
mc_metadata_clone()
mc_metadata_get()

Function Documentation

int mc_playlist_clone ( mc_playlist_h  src,
mc_playlist_h dst 
)

Clones a media controller playlist handle.

This function copies the media controller playlist handle from a source to destination. The mc_playlist_h is created internally and available through media controller playlist functions.

Since :
4.0
Remarks:
The dst should be released using mc_playlist_destroy().
Parameters:
[in]srcThe source handle to the media controller playlist
[out]dstThe destination handle to the media controller playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTROLLER_ERROR_NONESuccessful
MEDIA_CONTROLLER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORYOut of memory
See also:
mc_playlist_destroy()

Destroys a media controller playlist handle.

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

Since :
4.0
Parameters:
[in]playlistThe handle of the media controller playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTROLLER_ERROR_NONESuccessful
MEDIA_CONTROLLER_ERROR_INVALID_PARAMETERInvalid parameter
See also:
mc_playlist_clone()
int mc_playlist_foreach_item ( mc_playlist_h  playlist,
mc_playlist_item_cb  callback,
void *  user_data 
)

Iterates through media items in a playlist.

This function iterates through all items in the playlist. The callback function will be invoked for every retrieved playlist item. If there are no items on the playlist, the callback will not be invoked.

Since :
4.0
Parameters:
[in]playlistThe handle of the media controller playlist
[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_CONTROLLER_ERROR_NONESuccessful
MEDIA_CONTROLLER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTROLLER_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORYOut of memory
Precondition:
The playlist handle should be received by calling mc_playlist_foreach_playlist() or mc_playlist_get_playlist().
Postcondition:
This function invokes mc_playlist_item_cb().
See also:
mc_playlist_foreach_playlist()
mc_playlist_get_playlist()
mc_playlist_item_cb()
mc_playlist_destroy()
int mc_playlist_foreach_playlist ( const char *  app_id,
mc_playlist_cb  callback,
void *  user_data 
)

Iterates over playlists of the media controller server.

This function iterates through all playlists of the given app_id. The media controller server can have several playlists. You can get playlists only for the activated media controller server. If app_id is not an ID of an activated media controller server, this function will return MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER. The callback function will be invoked for every retrieved playlist. If there are no playlists, the callback will not be invoked.

Since :
5.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/mediacontroller.server
http://tizen.org/privilege/mediacontroller.client
Remarks:
You must add privilege http://tizen.org/privilege/mediacontroller.server, if your application is a media controller server. You must add privilege http://tizen.org/privilege/mediacontroller.client, if your application is a media controller client.
Parameters:
[in]app_idThe app_id of the media controller server
[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_CONTROLLER_ERROR_NONESuccessful
MEDIA_CONTROLLER_ERROR_PERMISSION_DENIEDPermission denied
MEDIA_CONTROLLER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTROLLER_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORYOut of memory
Postcondition:
This function invokes mc_playlist_cb().
See also:
mc_playlist_cb()
int mc_playlist_get_item_count ( mc_playlist_h  playlist,
int *  item_count 
)

Gets the number of the media item in a playlist.

Since :
5.5
Parameters:
[in]playlistThe handle of the media controller playlist
[out]item_countThe number of media items.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTROLLER_ERROR_NONESuccessful
MEDIA_CONTROLLER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTROLLER_ERROR_INVALID_OPERATIONInvalid operation
Precondition:
The playlist handle should be received by calling mc_playlist_foreach_playlist() or mc_playlist_get_playlist().
See also:
mc_playlist_foreach_playlist()
mc_playlist_get_playlist()
mc_playlist_destroy()
int mc_playlist_get_name ( mc_playlist_h  playlist,
char **  playlist_name 
)

Gets the name of the playlist.

Since :
4.0
Remarks:
The playlist_name should be released using free().
Parameters:
[in]playlistThe handle of the media controller playlist
[out]playlist_nameThe name of the playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTROLLER_ERROR_NONESuccessful
MEDIA_CONTROLLER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORYOut of memory
Precondition:
The playlist handle should be received by calling mc_playlist_foreach_playlist() or mc_playlist_get_playlist().
See also:
mc_playlist_foreach_playlist()
mc_playlist_get_playlist()
mc_playlist_destroy()
int mc_playlist_get_playlist ( const char *  app_id,
const char *  playlist_name,
mc_playlist_h playlist 
)

Gets the playlist handle.

This function creates a new playlist handle for the given app_id and playlist_name. You can get the playlist only for the activated media controller server. If app_id is not an ID of an activated media controller server, or if playlist_name is invalid,
this function will return MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER.

Since :
5.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/mediacontroller.server
http://tizen.org/privilege/mediacontroller.client
Remarks:
You must add privilege http://tizen.org/privilege/mediacontroller.server, if your application is a media controller server. You must add privilege http://tizen.org/privilege/mediacontroller.client, if your application is a media controller client. The playlist should be released using mc_playlist_destroy().
Parameters:
[in]app_idThe app_id of the media controller server
[in]playlist_nameThe name of the playlist
[out]playlistThe handle of the media controller playlist
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTROLLER_ERROR_NONESuccessful
MEDIA_CONTROLLER_ERROR_PERMISSION_DENIEDPermission denied
MEDIA_CONTROLLER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTROLLER_ERROR_INVALID_OPERATIONInvalid operation
MEDIA_CONTROLLER_ERROR_OUT_OF_MEMORYOut of memory
See also:
mc_playlist_get_name()
mc_playlist_get_item_count()
mc_playlist_foreach_item()
mc_playlist_destroy()
int mc_playlist_get_playlist_count ( const char *  app_id,
int *  playlist_count 
)

Gets the number of playlists for the given app_id.

The media controller server can have several playlists. You can get a count of playlists only for the activated media controller server. If app_id is not the ID of an activated media controller server, this function returns MEDIA_CONTROLLER_ERROR_INVALID_PARAMETER.

Since :
5.5
Privilege Level:
public
Privilege:
http://tizen.org/privilege/mediacontroller.server
http://tizen.org/privilege/mediacontroller.client
Remarks:
You must add privilege http://tizen.org/privilege/mediacontroller.server, if your application is a media controller server. You must add privilege http://tizen.org/privilege/mediacontroller.client, if your application is a media controller client.
Parameters:
[in]app_idThe app_id of the media controller server
[out]playlist_countThe number of playlists that the media controller server has.
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTROLLER_ERROR_NONESuccessful
MEDIA_CONTROLLER_ERROR_PERMISSION_DENIEDPermission denied
MEDIA_CONTROLLER_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTROLLER_ERROR_INVALID_OPERATIONInvalid operation
See also:
mc_client_foreach_server()