Tizen Native API
7.0
|
The Thumbnail Util API provides functions for creating the thumbnail from a given media file.
Required Header
#include <thumbnail_util.h>
Overview
The Thumbnail Util API allows you to create thumbnails of the size you want from media files.
Thumbnails can be created as files(thumbnail_util_extract_to_file()) or buffers(thumbnail_util_extract_to_buffer()).
Functions | |
int | thumbnail_util_create (thumbnail_h *thumb) TIZEN_DEPRECATED_API |
Creates thumbnail info handle. | |
int | thumbnail_util_extract (thumbnail_h thumb, thumbnail_extracted_cb callback, void *user_data, char **request_id) TIZEN_DEPRECATED_API |
Extracts the thumbnail for the given media, asynchronously. | |
int | thumbnail_util_set_path (thumbnail_h thumb, const char *path) TIZEN_DEPRECATED_API |
Sets the path of original media file. | |
int | thumbnail_util_set_size (thumbnail_h thumb, int width, int height) TIZEN_DEPRECATED_API |
Sets the size of thumbnail to be extracted. | |
int | thumbnail_util_cancel (thumbnail_h thumb, const char *request_id) TIZEN_DEPRECATED_API |
Cancels the thumbnail extraction request for the given media. | |
int | thumbnail_util_destroy (thumbnail_h thumb) TIZEN_DEPRECATED_API |
Destroys thumbnail info handle. | |
int | thumbnail_util_extract_to_file (const char *path, unsigned int width, unsigned int height, const char *thumbnail_path) |
Extracts the thumbnail for the given media into a file, synchronously. | |
int | thumbnail_util_extract_to_buffer (const char *path, unsigned int width, unsigned int height, unsigned char **thumb_buffer, size_t *thumb_size, unsigned int *thumb_width, unsigned int *thumb_height) |
Extracts the thumbnail for the given media into a buffer, synchronously. | |
Typedefs | |
typedef struct thumbnail_s * | thumbnail_h |
The structure type for the thumbnail info handle. | |
typedef void(* | thumbnail_extracted_cb )(thumbnail_util_error_e error, const char *request_id, int thumb_width, int thumb_height, unsigned char *thumb_data, int thumb_size, void *user_data) |
Called when creating the thumbnail. | |
Defines | |
#define | THUMBNAIL_UTIL_ERROR_CLASS TIZEN_ERROR_THUMBNAIL_UTIL |
Definition for Thumbnail util Error Class. |
Define Documentation
#define THUMBNAIL_UTIL_ERROR_CLASS TIZEN_ERROR_THUMBNAIL_UTIL |
Definition for Thumbnail util Error Class.
- Since :
- 2.4
Typedef Documentation
typedef void(* thumbnail_extracted_cb)(thumbnail_util_error_e error, const char *request_id, int thumb_width, int thumb_height, unsigned char *thumb_data, int thumb_size, void *user_data) |
Called when creating the thumbnail.
- Deprecated:
- Deprecated since 5.0.
This callback is called for completion of generating the thumbnail. The following error codes can be received:
THUMBNAIL_UTIL_ERROR_NONE : Successful THUMBNAIL_UTIL_ERROR_INVALID_PARAMETER : Invalid parameter THUMBNAIL_UTIL_ERROR_PERMISSION_DENIED : Permission denied
- Since :
- 2.4
- Remarks:
- Color space of the generated thumbnail is BGRA.
The callback is called in a separate thread(not in the main loop).
The thumb_data should be released using free().
- Parameters:
-
[in] error The error code [in] request_id The generated request id by thumbnail extraction request [in] thumb_width The width of the thumbnail which is generated [in] thumb_height The height of the thumbnail which is generated [in] thumb_data The raw data of the thumbnail which is generated [in] thumb_size The size of the thumbnail which is generated [in] user_data The user data passed from the thumbnail_util_extract() function
- Precondition:
- thumbnail_util_extract() calls this callback.
- See also:
- thumbnail_util_extract()
typedef struct thumbnail_s* thumbnail_h |
Enumeration Type Documentation
Enumeration for a thumbnail util error.
- Since :
- 2.4
- Enumerator:
Function Documentation
int thumbnail_util_cancel | ( | thumbnail_h | thumb, |
const char * | request_id | ||
) |
Cancels the thumbnail extraction request for the given media.
- Deprecated:
- Deprecated since 5.0.
- Since :
- 2.4
- Remarks:
- If there is no request to be canceled, this function returns THUMBNAIL_UTIL_ERROR_INVALID_OPERATION
- Parameters:
-
[in] thumb The media thumbnail info handle [in] request_id The generated request id by thumbnail extraction request
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
THUMBNAIL_UTIL_ERROR_NONE Successful THUMBNAIL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- It is available before thumbnail_extracted_cb() is called.
- See also:
- thumbnail_util_extract()
int thumbnail_util_create | ( | thumbnail_h * | thumb | ) |
Creates thumbnail info handle.
- Deprecated:
- Deprecated since 5.0.
- Since :
- 2.4
- Remarks:
- The thumb info should be released using thumbnail_util_destroy().
- Parameters:
-
[in] thumb The handle to thumbnail info
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
THUMBNAIL_UTIL_ERROR_NONE Successful THUMBNAIL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter THUMBNAIL_UTIL_ERROR_OUT_OF_MEMORY Out of memory
- See also:
- thumbnail_util_destroy()
int thumbnail_util_destroy | ( | thumbnail_h | thumb | ) |
Destroys thumbnail info handle.
- Deprecated:
- Deprecated since 5.0.
The function frees all resources related to the thumbnail info handle. This handle can no longer be used to perform any operations. New thumbnail info handle has to be created before the next usage.
- Since :
- 2.4
- Parameters:
-
[in] thumb The thumbnail info handle
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
THUMBNAIL_UTIL_ERROR_NONE Successful THUMBNAIL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- Create a thumbnail info handle by calling thumbnail_util_create().
- See also:
- thumbnail_util_create()
int thumbnail_util_extract | ( | thumbnail_h | thumb, |
thumbnail_extracted_cb | callback, | ||
void * | user_data, | ||
char ** | request_id | ||
) |
Extracts the thumbnail for the given media, asynchronously.
- Deprecated:
- Deprecated since 5.0. Use thumbnail_util_extract_to_file() or thumbnail_util_extract_to_buffer() instead.
This function extracts the thumbnail for given media item and calls registered callback function for completion of extracting the thumbnail.
You can distinguish generated thumbnails by request_id. Therefore, the request_id must be maintained until the request is completed.
And the request_id is also used to cancel the request.
- Since :
- 2.4
- Remarks:
- The request_id should be released using free().
http://tizen.org/privilege/mediastorage is needed if input or output path are relevant to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path are relevant to external storage.
If you don't set the size, the thumbnail size will be set default size. Default size is 320x240.
Color space of the generated thumbnail is BGRA.
Since 3.0, http://tizen.org/privilege/content.write privilege is not required.
- Parameters:
-
[in] thumb The thumbnail info handle [in] callback The callback function to be invoked [in] user_data The user data to be passed to the callback function [out] request_id The request id for the thumbnail extraction request
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
THUMBNAIL_UTIL_ERROR_NONE Successful THUMBNAIL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter THUMBNAIL_UTIL_ERROR_PERMISSION_DENIED Permission denied
- Precondition:
- Create a thumbnail info handle by calling thumbnail_util_create().
The content path that you want to generate thumbnail must be set by calling thumbnail_util_set_path().
- Postcondition:
- Thumbnail extraction result except canceled is provided by thumbnail_extracted_cb().
int thumbnail_util_extract_to_buffer | ( | const char * | path, |
unsigned int | width, | ||
unsigned int | height, | ||
unsigned char ** | thumb_buffer, | ||
size_t * | thumb_size, | ||
unsigned int * | thumb_width, | ||
unsigned int * | thumb_height | ||
) |
Extracts the thumbnail for the given media into a buffer, synchronously.
This function creates thumbnails from a given media file.
The generated thumbnail is returned as a raw data stream.
- Since :
- 5.0
- Remarks:
- http://tizen.org/privilege/mediastorage is needed if input or output path points to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path points to external storage.
The width and height of the thumbnail to be generated cannot exceed 2000.
The width and height of the thumbnail to be generated cannot exceed the original resolution.
In the case of video file, color space of the generated thumbnail is RGB.
In the case of image file, color space of the generated thumbnail is BGRA.
The thumb_buffer should be released using free(). Since 5.5, if the width and height of the thumbnail to be generated exceeds the original resolution, the value changes to the original resolution.
In order to maintain the ratio, the requested size and generated size may be different. (Modify based on short axis)
- Parameters:
-
[in] path The path of the original media file [in] width The width of the thumbnail [in] height The height of the thumbnail [out] thumb_buffer The raw data of the thumbnail which is generated [out] thumb_size The size of the thumbnail which is generated [out] thumb_width The width of the thumbnail which is generated [out] thumb_height The height of the thumbnail which is generated
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
THUMBNAIL_UTIL_ERROR_NONE Successful THUMBNAIL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter THUMBNAIL_UTIL_ERROR_INVALID_OPERATION Invalid operation THUMBNAIL_UTIL_ERROR_OUT_OF_MEMORY Out of memory THUMBNAIL_UTIL_ERROR_PERMISSION_DENIED Permission denied
int thumbnail_util_extract_to_file | ( | const char * | path, |
unsigned int | width, | ||
unsigned int | height, | ||
const char * | thumbnail_path | ||
) |
Extracts the thumbnail for the given media into a file, synchronously.
This function creates thumbnail from a given media file.
The generated thumbnail is saved in the given thumbnail path.
The format of the thumbnail file is determined by the extension of the thumbnail path (e.g. path is input.jpg and thumbnail_path is thumbnail.png then thumbnail.png is encoded in the PNG format).
If the extension is missing or the format is not supported, the thumbnail is encoded in the same format as the given media (e.g. path is input.jpg and thumbnail_path is thumbnail.out then thumbnail.out is encoded in the JPEG format).
Supported image formats are as follows:
- GIF, JPEG, PNG, BMP, WBMP
Video files only support JPEG format thumbnail.
- Since :
- 5.0
- Remarks:
- http://tizen.org/privilege/mediastorage is needed if input or output path points to media storage.
http://tizen.org/privilege/externalstorage is needed if input or output path points to external storage.
The width and height of the thumbnail to be generated cannot exceed 2000.
The width and height of the thumbnail to be generated cannot exceed the original resolution.
Since 5.5, if the width and height of the thumbnail to be generated exceeds the original resolution, the value changes to the original resolution.
In order to maintain the ratio, the requested size and generated size may be different. (Modify based on short axis)
If the parent directory of the thumbnail path to be generated does not exist, an error is returned.
- Parameters:
-
[in] path The path of the original media file [in] width The width of the thumbnail [in] height The height of the thumbnail [in] thumbnail_path The path to save the generated thumbnail
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
THUMBNAIL_UTIL_ERROR_NONE Successful THUMBNAIL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter THUMBNAIL_UTIL_ERROR_INVALID_OPERATION Invalid operation THUMBNAIL_UTIL_ERROR_OUT_OF_MEMORY Out of memory THUMBNAIL_UTIL_ERROR_PERMISSION_DENIED Permission denied
int thumbnail_util_set_path | ( | thumbnail_h | thumb, |
const char * | path | ||
) |
Sets the path of original media file.
- Deprecated:
- Deprecated since 5.0.
- Since :
- 2.4
- Parameters:
-
[in] thumb The thumbnail info handle [in] path The path of the original media file
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
THUMBNAIL_UTIL_ERROR_NONE Successful THUMBNAIL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- Create a thumbnail info handle by calling thumbnail_util_create().
int thumbnail_util_set_size | ( | thumbnail_h | thumb, |
int | width, | ||
int | height | ||
) |
Sets the size of thumbnail to be extracted.
- Deprecated:
- Deprecated since 5.0.
- Since :
- 2.4
- Remarks:
- If you don't set the size, the thumbnail size will be set default size. Default size is 320x240.
If the set width is not a multiple of 8, it can be changed by inner process. the width will be a multiple of 8 greater than the set value.
- Parameters:
-
[in] thumb The thumbnail info handle [in] width The width of the thumbnail [in] height The height of the thumbnail
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
THUMBNAIL_UTIL_ERROR_NONE Successful THUMBNAIL_UTIL_ERROR_INVALID_PARAMETER Invalid parameter
- Precondition:
- Create a thumbnail info handle by calling thumbnail_util_create().