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.1

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]	bookmark	The handle to the media bookmark
[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_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.1

Function Documentation

int media_bookmark_clone	(	media_bookmark_h *	dst,
		media_bookmark_h	src
	)

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.1

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

Parameters:

[out]	dst	The destination handle to the media bookmark
[in]	src	The source handle to the media bookmark

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

Privilege Level:: public

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

Parameters:

[in] bookmark_id The ID of the media bookmark

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_bookmark_insert_to_db()

int media_bookmark_destroy ( media_bookmark_h bookmark )

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.1

Parameters:

[in] bookmark The handle to the media bookmark

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 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]	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_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.1

Parameters:

[in]	filter	The handle to the media filter
[out]	bookmark_count	The count of the media bookmark

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_bookmark_get_bookmark_id	(	media_bookmark_h	bookmark,
		int *	bookmark_id
	)

Gets the bookmark ID.

Since :: 2.3.1

Parameters:

[in]	bookmark	The handle to the media bookmark
[out]	bookmark_id	The ID of the media bookmark

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

Parameters:

[in]	bookmark	The handle to the media bookmark
[out]	marked_time	The bookmark time offset (in seconds)

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_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]	bookmark	The handle to the media bookmark
[out]	name	The 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_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

int media_bookmark_get_thumbnail_path	(	media_bookmark_h	bookmark,
		char **	path
	)

Gets the media bookmark thumbnail.

Since :: 2.3.1

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

Parameters:

[in]	bookmark	The handle to the media bookmark
[out]	path	The thumbnail path of media bookmark

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

Privilege Level:: public

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

Parameters:

[in]	media_id	The media ID
[in]	time	The bookmark time offset (in seconds)
[in]	thumbnail_path	The 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_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_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]	bookmark	The handle to the media bookmark
[in]	name	The 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_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory

Postcondition:: media_bookmark_update_to_db()

int media_bookmark_update_to_db ( media_bookmark_h bookmark )

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] bookmark The handle to the media bookmark

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 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()

Required Header

Overview

Foreach Operations

Functions

Typedefs

Typedef Documentation

Function Documentation