Tizen(Headed) Native API  6.5
Media Bookmark

The Media Bookmark Information API provides functions to manage bookmark information on the media items.

Required Header

#include <media_content.h>

Overview

A Bookmark allows you to mark interesting moment in a media(video and audio) to enable fast searching. The Bookmark Information API provides functions to get information about bookmarks associated with video and audio items.

API allows to:

  • get and filter existing bookmarks
  • insert new bookmarks
  • delete bookmarks

For inserting a bookmark to media item, call media_bookmark_insert_to_db() function and for deleting already set bookmark from a media, call media_bookmark_delete_from_db() function. For retrieving time where the bookmark is placed on the media, call media_bookmark_get_marked_time() function.

Foreach Operations

FOREACH CALLBACK DESCRIPTION
media_info_foreach_bookmark_from_db() media_bookmark_cb() Iterates through bookmarks

Functions

int media_bookmark_insert_to_db (const char *media_id, time_t time, const char *thumbnail_path)
 Inserts a new bookmark in media on the specified time offset to the media database.
int media_bookmark_delete_from_db (int bookmark_id)
 Removes a media bookmark from the media database.
int media_bookmark_get_bookmark_count_from_db (filter_h filter, int *bookmark_count)
 Gets the number of bookmarks with an optional filter from the media database.
int media_bookmark_foreach_bookmark_from_db (filter_h filter, media_bookmark_cb callback, void *user_data)
 Iterates through the bookmarks with an optional filter from the media database.
int media_bookmark_clone (media_bookmark_h *dst, media_bookmark_h src)
 Clones a media bookmark.
int media_bookmark_destroy (media_bookmark_h bookmark)
 Destroys a media bookmark.
int media_bookmark_get_bookmark_id (media_bookmark_h bookmark, int *bookmark_id)
 Gets the bookmark ID.
int media_bookmark_get_marked_time (media_bookmark_h bookmark, time_t *marked_time)
 Gets the bookmark time marked parameter.
int media_bookmark_get_thumbnail_path (media_bookmark_h bookmark, char **path)
 Gets the media bookmark thumbnail.
int media_bookmark_get_name (media_bookmark_h bookmark, char **name)
 Gets the media bookmark name which user set.
int media_bookmark_set_name (media_bookmark_h bookmark, const char *name)
 Sets the media bookmark name.
int media_bookmark_update_to_db (media_bookmark_h bookmark)
 Updates bookmark information to the media database.

Typedefs

typedef struct media_bookmark_s * media_bookmark_h
 The structure type for the Media bookmark handle.
typedef bool(* media_bookmark_cb )(media_bookmark_h bookmark, void *user_data)
 Called for every bookmark in the obtained list of bookmarks.

Typedef Documentation

typedef bool(* media_bookmark_cb)(media_bookmark_h bookmark, void *user_data)

Called for every bookmark in the obtained list of bookmarks.

Iterates over a bookmark list.

Since :
2.3
Remarks:
To use the bookmark outside this function, copy the handle with the media_bookmark_clone() function.
The callback is called in the main loop.
Parameters:
[in]bookmarkThe handle to the media bookmark
[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_info_foreach_bookmark_from_db() will invoke this function.
See also:
media_info_foreach_bookmark_from_db()
typedef struct media_bookmark_s* media_bookmark_h

The structure type for the Media bookmark handle.

Since :
2.3

Function Documentation

Clones a media bookmark.

This function copies the media bookmark handle from a source to destination. There is no media_bookmark_create() function. The media_bookmark_h is created internally and available through media bookmark foreach function such as media_info_foreach_bookmark_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_bookmark_destroy().
Parameters:
[out]dstThe destination handle to the media bookmark
[in]srcThe source handle to the media bookmark
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_bookmark_destroy()
media_info_foreach_bookmark_from_db()
int media_bookmark_delete_from_db ( int  bookmark_id)

Removes a media bookmark from the media database.

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/content.write
Parameters:
[in]bookmark_idThe ID of the media bookmark
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_bookmark_insert_to_db()

Destroys a media bookmark.

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

Since :
2.3
Parameters:
[in]bookmarkThe handle to the media bookmark
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
Precondition:
Get copy of bookmark handle by calling media_bookmark_clone().
See also:
media_bookmark_clone()
int media_bookmark_foreach_bookmark_from_db ( filter_h  filter,
media_bookmark_cb  callback,
void *  user_data 
)

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

This function gets all bookmarks associated with the given filter and calls callback for every retrieved media bookmark. If NULL is passed to the filter, then no filtering is applied.

Since :
4.0
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_bookmark_cb().
See also:
media_content_connect()
media_bookmark_cb()
media_filter_create()
int media_bookmark_get_bookmark_count_from_db ( filter_h  filter,
int *  bookmark_count 
)

Gets the number of bookmarks with an optional filter from the media database.

Since :
2.3
Parameters:
[in]filterThe handle to the media filter
[out]bookmark_countThe count of the media bookmark
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_bookmark_get_bookmark_id ( media_bookmark_h  bookmark,
int *  bookmark_id 
)

Gets the bookmark ID.

Since :
2.3
Parameters:
[in]bookmarkThe handle to the media bookmark
[out]bookmark_idThe ID of the media bookmark
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
int media_bookmark_get_marked_time ( media_bookmark_h  bookmark,
time_t *  marked_time 
)

Gets the bookmark time marked parameter.

This function returns time offset in seconds from beginning of the movie on which bookmark was placed.

Since :
2.3
Parameters:
[in]bookmarkThe handle to the media bookmark
[out]marked_timeThe bookmark time offset (in seconds)
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
int media_bookmark_get_name ( media_bookmark_h  bookmark,
char **  name 
)

Gets the media bookmark name which user set.

Since :
4.0
Remarks:
The name should be released using free().
Parameters:
[in]bookmarkThe handle to the media bookmark
[out]nameThe name of media bookmark. If name was not set, empty string is returned. If User set bookmark name to NULL, name will be empty string also.
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_bookmark_get_thumbnail_path ( media_bookmark_h  bookmark,
char **  path 
)

Gets the media bookmark thumbnail.

Since :
2.3
Remarks:
The path should be released using free().
Parameters:
[in]bookmarkThe handle to the media bookmark
[out]pathThe thumbnail path of media bookmark
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_bookmark_insert_to_db ( const char *  media_id,
time_t  time,
const char *  thumbnail_path 
)

Inserts a new bookmark in media on the specified time offset to the media database.

Since :
2.3
Privilege Level:
public
Privilege:
http://tizen.org/privilege/content.write
Parameters:
[in]media_idThe media ID
[in]timeThe bookmark time offset (in seconds)
[in]thumbnail_pathThe thumbnail path of video bookmark\ n If the media type is audio, then thumbnail is null.
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_bookmark_delete_from_db()
int media_bookmark_set_name ( media_bookmark_h  bookmark,
const char *  name 
)

Sets the media bookmark name.

Since :
4.0
Parameters:
[in]bookmarkThe handle to the media bookmark
[in]nameThe name of media bookmark. Can be NULL, empty or non-empty string.
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_bookmark_update_to_db()

Updates bookmark information to the media database.

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

Since :
4.0
Privilege Level:
public
Privilege:
http://tizen.org/privilege/content.write
Remarks:
Do not call this function in callback function of foreach function like media_info_foreach_bookmark_from_db().
Parameters:
[in]bookmarkThe handle to the media bookmark
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 when Application has no privilege
Precondition:
This function requires opened connection to content service by media_content_connect().
See also:
media_content_connect()
media_bookmark_set_name()