Tizen(Headed) Native API
6.5
|
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, otherwisefalse
to break out of the loop
- Precondition:
- media_tag_foreach_tag_from_db(), media_info_foreach_tag_from_db() will invoke this function.
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()
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().
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().
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().
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().
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().
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().
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()
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().