The Media Tag API provides functions to manage media content tags.

Required Header

#include <media_content.h>

Overview

A Tag is a special piece of information that may be associated with media content items. Tagging allows a user to organize large number of items into logical groups providing a simplified and faster way of accessing media content items.

Media Tag API provides functions to get basic information about existing tags and manage tags associated with Media Information (media_info_h). For inserting a new tag to the database call media_tag_insert_to_db() function and for deleting existing tag from database call media_tag_delete_from_db() function.
A Media item can be associated and dissociated from tags by calling media_tag_add_media() and media_tag_remove_media() function respectively. Finally, media_tag_update_to_db function should be called so as to update the given item in the media database.

Foreach Operations

FOREACH	CALLBACK	DESCRIPTION
media_tag_foreach_tag_from_db()	media_tag_cb()	Iterates through tags
media_tag_foreach_media_from_db()	media_info_cb()	Iterates through the media items for a given tag

Functions
int	media_tag_insert_to_db (const char tag_name, media_tag_h tag)
	Inserts a new tag in the media database.
int	media_tag_delete_from_db (int tag_id)
	Deletes a given tag from the media database.
int	media_tag_get_tag_count_from_db (filter_h filter, int *tag_count)
	Gets the count of the tag for the passed filter from the media database.
int	media_tag_foreach_tag_from_db (filter_h filter, media_tag_cb callback, void *user_data)
	Iterates through tags from the media database.
int	media_tag_get_media_count_from_db (int tag_id, filter_h filter, int *media_count)
	Gets the number of media files for the passed filter in the given tag_id from the media database.
int	media_tag_foreach_media_from_db (int tag_id, filter_h filter, media_info_cb callback, void *user_data)
	Iterates through media items for a given tag from the media database.
int	media_tag_clone (media_tag_h *dst, media_tag_h src)
	Clones the media tag.
int	media_tag_destroy (media_tag_h tag)
	Destroys the media tag.
int	media_tag_get_tag_id (media_tag_h tag, int *tag_id)
	Gets the media tag ID.
int	media_tag_get_name (media_tag_h tag, char **tag_name)
	Gets the tag name.
int	media_tag_get_tag_from_db (int tag_id, media_tag_h *tag)
	Gets the media tag from the media database.
int	media_tag_add_media (media_tag_h tag, const char *media_id)
	Adds a new media info to the tag.
int	media_tag_remove_media (media_tag_h tag, const char *media_id)
	Removes the media info from the given tag.
int	media_tag_set_name (media_tag_h tag, const char *tag_name)
	Sets the name of the tag.
int	media_tag_update_to_db (media_tag_h tag)
	Updates the media tag to the media database.
Typedefs
typedef struct media_tag_s *	media_tag_h
	The structure type for the Media tag handle.
typedef bool(*	media_tag_cb )(media_tag_h tag, void *user_data)
	Called for every tag in the obtained list of tags.

Typedef Documentation

typedef bool(* media_tag_cb)(media_tag_h tag, void *user_data)

Called for every tag in the obtained list of tags.

Iterates over a list of tags.

Since :: 2.3

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

Parameters:

[in]	tag	The handle to the media tag
[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_tag_foreach_tag_from_db(), media_info_foreach_tag_from_db() will invoke this function.

See also:: media_tag_clone(); media_tag_foreach_tag_from_db(); media_info_foreach_tag_from_db()

typedef struct media_tag_s* media_tag_h

The structure type for the Media tag handle.

Since :: 2.3

Function Documentation

int media_tag_add_media	(	media_tag_h	tag,
		const char *	media_id
	)

Adds a new media info to the tag.

Since :: 2.3

Parameters:

[in]	tag	The handle to the media tag
[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_tag_update_to_db()

See also:: media_content_connect(); media_tag_remove_media()

int media_tag_clone	(	media_tag_h *	dst,
		media_tag_h	src
	)

Clones the media tag.

This function copies the media tag handle from a source to destination. There is no media_tag_create() function. The media_tag_h is created internally and available through media tag foreach function such as media_tag_foreach_tag_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_tag_destroy().

Parameters:

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

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_OUT_OF_MEMORY	Out of memory
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

See also:: media_tag_destroy()

int media_tag_delete_from_db ( int tag_id )

Deletes a given tag from the media database.

Since :: 2.3

Privilege Level:: public

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

Parameters:

[in] tag_id The ID of the media tag

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

int media_tag_destroy ( media_tag_h tag )

Destroys the media tag.

This function frees all resources related to the tag handle. The tag handle can no longer be used for any operations. A new tag handle has to be created before next usage.

Since :: 2.3

Parameters:

[in] tag The handle to the media tag

Returns:: 0 on success, otherwise a negative error value

Return values:

MEDIA_CONTENT_ERROR_NONE	Successful
MEDIA_CONTENT_ERROR_INVALID_PARAMETER	Invalid parameter

Precondition:: A copy of the media tag handle created by calling media_tag_clone() or media_tag_insert_to_db().

See also:: media_tag_clone(); media_tag_insert_to_db()

int media_tag_foreach_media_from_db	(	int	tag_id,
		filter_h	filter,
		media_info_cb	callback,
		void *	user_data
	)

Iterates through media items for a given tag from the media database.

This function gets all media items associated with a given tag and meeting a desired filter and calls a registered callback function for every retrieved media item. If NULL is passed to the filter, no filtering is applied.

Since :: 2.3

Parameters:

[in]	tag_id	The ID of the media tag
[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_content_connect(); media_info_cb(); media_filter_create()

int media_tag_foreach_tag_from_db	(	filter_h	filter,
		media_tag_cb	callback,
		void *	user_data
	)

Iterates through tags from the media database.

This function gets all tags meeting a desired filter and calls a registered callback function for every retrieved tag. 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_tag_cb().

See also:: media_content_connect(); media_tag_cb; media_filter_create()

int media_tag_get_media_count_from_db	(	int	tag_id,
		filter_h	filter,
		int *	media_count
	)

Gets the number of media files for the passed filter in the given tag_id from the media database.

Since :: 2.3

Parameters:

[in]	tag_id	The ID of the media tag
[in]	filter	The handle to the media filter
[out]	media_count	The count 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_tag_get_name	(	media_tag_h	tag,
		char **	tag_name
	)

Gets the tag name.

Since :: 2.3

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

Parameters:

[in]	tag	The handle to the media tag
[out]	tag_name	The name of the media tag

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_tag_get_tag_count_from_db	(	filter_h	filter,
		int *	tag_count
	)

Gets the count of the tag for the passed filter from the media database.

Since :: 2.3

Parameters:

[in]	filter	The handle to the media filter
[out]	tag_count	The count of the media tag

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_tag_get_tag_from_db	(	int	tag_id,
		media_tag_h *	tag
	)

Gets the media tag from the media database.

This function creates a new media tag handle from the media database by the given tag_id. Media tag will be created and will be filled with tag information.

Since :: 2.3

Remarks:: The tag should be released using media_tag_destroy().

Parameters:

[in]	tag_id	The ID of the media tag
[out]	tag	The handle to the media tag

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

int media_tag_get_tag_id	(	media_tag_h	tag,
		int *	tag_id
	)

Gets the media tag ID.

Since :: 2.3

Parameters:

[in]	tag	The handle to the media tag
[out]	tag_id	The ID of the media tag

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_tag_insert_to_db	(	const char *	tag_name,
		media_tag_h *	tag
	)

Inserts a new tag in the media database.

Since :: 2.3

Privilege Level:: public

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

Remarks:: The tag should be released using media_tag_destroy().

Parameters:

[in]	tag_name	The tag name to be inserted
[out]	tag	The handle to the media tag

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_tag_delete_from_db(); media_tag_destroy()

int media_tag_remove_media	(	media_tag_h	tag,
		const char *	media_id
	)

Removes the media info from the given tag.

Since :: 2.3

Parameters:

[in]	tag	The handle to the media tag
[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_tag_update_to_db()

See also:: media_content_connect(); media_tag_add_media()

int media_tag_set_name	(	media_tag_h	tag,
		const char *	tag_name
	)

Sets the name of the tag.

Since :: 2.3

Parameters:

[in]	tag	The handle to the media tag
[in]	tag_name	The name of the media tag

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

int media_tag_update_to_db ( media_tag_h tag )

Updates the media tag to the media database.

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

Since :: 2.3

Privilege Level:: public

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

Parameters:

[in] tag The handle to the media tag

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_tag_destroy(); media_tag_add_media(); media_tag_remove_media(); media_tag_set_name()

Required Header

Overview

Foreach Operations

Functions

Typedefs

Typedef Documentation

Function Documentation