Tizen Native API

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

Defines

#define TAG_NAME   "TAG_NAME"
#define TAG_MEDIA_COUNT   "TAG_MEDIA_COUNT"

Define Documentation

#define TAG_MEDIA_COUNT   "TAG_MEDIA_COUNT"

Media count in tag view

#define TAG_NAME   "TAG_NAME"

Tag name


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.

Remarks:
To use the tag outside this function, copy the handle with the media_tag_clone() function.
Parameters:
[in]tagThe handle to the media tag
[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_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()

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.1
Parameters:
[in]tagThe media tag handle
[in]media_idThe ID to the media info which is added
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_PERMISSION_DENIEDPermission denied
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.1
Remarks:
You must release the destination handle using media_tag_destroy().
Parameters:
[out]dstThe destination handle to the media tag
[in]srcThe source handle to the media tag
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/content.write
Parameters:
[in]tag_idThe ID of media tag
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
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_tag_insert_to_db()

Destroys the media tag.

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

Since :
2.3.1
Parameters:
[in]tagThe media tag handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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.1
Parameters:
[in]tag_idThe ID of the media tag
[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_PERMISSION_DENIEDPermission denied
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.1
Parameters:
[in]filterThe tag filter handle
[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_OUT_OF_MEMORYOut of memory
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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 from the media database.

Since :
2.3.1
Parameters:
[in]tag_idThe ID of the media tag
[in]filterThe handle to the media filter
[out]media_countThe count 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_PERMISSION_DENIEDPermission denied
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.1
Remarks:
You must release tag_name using free().
Parameters:
[in]tagThe media tag handle
[out]tag_nameThe name of the tag
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_PERMISSION_DENIEDPermission denied
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.1
Parameters:
[in]filterThe handle to the filter
[out]tag_countThe count of the media tag
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_PERMISSION_DENIEDPermission denied
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.1
Remarks:
You must release folder using media_tag_destroy().
Parameters:
[in]tag_idThe ID of the media tag
[out]tagThe media tag handle associated with the tag 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_PERMISSION_DENIEDPermission denied
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.1
Parameters:
[in]tagThe media tag handle
[out]tag_idThe ID of the media tag
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
MEDIA_CONTENT_ERROR_PERMISSION_DENIEDPermission denied
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.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/content.write
Remarks:
The created tag handle must be released using media_tag_destroy().
Parameters:
[in]tag_nameThe tag name to be inserted
[out]tagThe created handle to the media tag
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_PERMISSION_DENIEDPermission 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.1
Parameters:
[in]tagThe media tag handle
[in]media_idThe ID to the media info which is removed
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_PERMISSION_DENIEDPermission denied
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,
char *  tag_name 
)

Sets the name of the tag.

Since :
2.3.1
Parameters:
[in]tagThe media tag handle
[in]tag_nameThe name of the media tag
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_PERMISSION_DENIEDPermission denied
Postcondition:
media_tag_update_to_db()

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.1
Privilege Level:
public
Privilege:
http://tizen.org/privilege/content.write
Parameters:
[in]tagThe media tag handle
Returns:
0 on success, otherwise a negative error value
Return values:
MEDIA_CONTENT_ERROR_NONESuccessful
MEDIA_CONTENT_ERROR_INVALID_PARAMETERInvalid parameter
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()