GimpThumb-utils: GIMP Thumbnail Library Reference Manual

+ + +

GimpThumb-utils

GimpThumb-utils — Utility functions provided and used by libgimpthumb

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+gboolean +	+gimp_thumb_init () +
const gchar * +	+gimp_thumb_get_thumb_base_dir () +
+gchar * +	+gimp_thumb_find_thumb () +
+GimpThumbFileType +	+gimp_thumb_file_test () +
+gchar * +	+gimp_thumb_name_from_uri () +
+gboolean +	+gimp_thumb_ensure_thumb_dir () +
const gchar * +	+gimp_thumb_get_thumb_dir () +
+void +	+gimp_thumbs_delete_for_uri () +
+gchar * +	+gimp_thumb_name_from_uri_local () +
+gboolean +	+gimp_thumb_ensure_thumb_dir_local () +
+gchar * +	+gimp_thumb_get_thumb_dir_local () +
+void +	+gimp_thumbs_delete_for_uri_local () +

Description

Utility functions provided and used by libgimpthumb

Functions

gimp_thumb_init ()

gboolean
+gimp_thumb_init (const gchar *creator,
+                 const gchar *thumb_basedir);

This function initializes the thumbnail system. It must be called +before any other functions from libgimpthumb are used. You may call +it more than once if you want to change the thumb_basedir + but if +you do that, you should make sure that no thread is still using the +library. Apart from this function, libgimpthumb is multi-thread +safe.

The creator + string must be 7bit ASCII and should contain the name +of the software that creates the thumbnails. It is used to handle +thumbnail creation failures. See the spec for more details.

Usually you will pass NULL for thumb_basedir +. Thumbnails will +then be stored in the user's personal thumbnail directory as +defined in the spec. If you wish to use libgimpthumb to store +application-specific thumbnails, you can specify a different base +directory here.

Parameters

+++++ + + + + + + + + + + + + +

creator	an ASCII string that identifies the thumbnail creator
thumb_basedir	an absolute path or `NULL` to use the default

Returns

TRUE if the library was successfully initialized.

gimp_thumb_get_thumb_base_dir ()

const gchar *
+gimp_thumb_get_thumb_base_dir (void);

Returns the base directory of thumbnails cache. +It uses the Freedesktop Thumbnail Managing Standard on UNIX, +"~/Library/Caches/org.freedesktop.thumbnails" on OSX, and a cache +folder determined by glib on Windows (currently the common repository +for temporary Internet files). +The returned string belongs to GIMP and must not be changed nor freed.

Returns

the thumbnails cache directory.

Since: 2.10

gimp_thumb_find_thumb ()

gchar *
+gimp_thumb_find_thumb (const gchar *uri,
+                       GimpThumbSize *size);

This function attempts to locate a thumbnail for the given +uri +. First it tries the size that is stored at size +. If no +thumbnail of that size is found, it will look for a larger +thumbnail, then falling back to a smaller size.

If the user's thumbnail repository doesn't provide a thumbnail but +a local thumbnail repository exists for the folder the image is +located in, the same search is done among the local thumbnails (if +there are any).

If a thumbnail is found, it's size is written to the variable +pointer to by size + and the file location is returned.

Parameters

+++++ + + + + + + + + + + + + +

uri	an escaped URI
size	pointer to a GimpThumbSize

Returns

a newly allocated string in the encoding of the +filesystem or NULL if no thumbnail for uri +was found

gimp_thumb_file_test ()

GimpThumbFileType
+gimp_thumb_file_test (const gchar *filename,
+                      gint64 *mtime,
+                      gint64 *size,
+                      gint *err_no);

This is a convenience and portability wrapper around stat(). It +checks if the given filename + exists and returns modification time +and file size in 64bit integer values.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

filename	a filename in the encoding of the filesystem
mtime	return location for modification time
size	return location for file size
err_no	return location for system "errno"

Returns

The type of the file, or GIMP_THUMB_FILE_TYPE_NONE if +the file doesn't exist.

gimp_thumb_name_from_uri ()

gchar *
+gimp_thumb_name_from_uri (const gchar *uri,
+                          GimpThumbSize size);

Creates the name of the thumbnail file of the specified size + that +belongs to an image file located at the given uri +.

Parameters

+++++ + + + + + + + + + + + + +

uri	an escaped URI
size	a GimpThumbSize

Returns

a newly allocated filename in the encoding of the +filesystem or NULL if uri +points to the user's +thumbnail repository.

gimp_thumb_ensure_thumb_dir ()

gboolean
+gimp_thumb_ensure_thumb_dir (GimpThumbSize size,
+                             GError **error);

This function checks if the directory that is required to store +thumbnails for a particular size + exist and attempts to create it +if necessary.

You shouldn't have to call this function directly since +gimp_thumbnail_save_thumb() and gimp_thumbnail_save_failure() will +do this for you.

Parameters

+++++ + + + + + + + + + + + + +

size	a GimpThumbSize
error	return location for possible errors

Returns

TRUE is the directory exists, FALSE if it could not +be created

gimp_thumb_get_thumb_dir ()

const gchar *
+gimp_thumb_get_thumb_dir (GimpThumbSize size);

Retrieve the name of the thumbnail folder for a specific size. The +returned pointer will become invalid if gimp_thumb_init() is used +again. It must not be changed or freed.

Parameters

+++++ + + + + + +

size

a GimpThumbSize

Returns

the thumbnail directory in the encoding of the filesystem

gimp_thumbs_delete_for_uri ()

void
+gimp_thumbs_delete_for_uri (const gchar *uri);

Deletes all thumbnails for the image file specified by uri + from the +user's thumbnail repository.

Parameters

+++++ + + + + + +

uri

an escaped URI

Since: 2.2

gimp_thumb_name_from_uri_local ()

gchar *
+gimp_thumb_name_from_uri_local (const gchar *uri,
+                                GimpThumbSize size);

Creates the name of a local thumbnail file of the specified size + +that belongs to an image file located at the given uri +. Local +thumbnails have been introduced with version 0.7 of the spec.

Parameters

+++++ + + + + + + + + + + + + +

uri	an escaped URI
size	a GimpThumbSize

Returns

a newly allocated filename in the encoding of the +filesystem or NULL if uri +is a remote file or +points to the user's thumbnail repository.

Since: 2.2

gimp_thumb_ensure_thumb_dir_local ()

gboolean
+gimp_thumb_ensure_thumb_dir_local (const gchar *dirname,
+                                   GimpThumbSize size,
+                                   GError **error);

This function checks if the directory that is required to store +local thumbnails for a particular size + exist and attempts to +create it if necessary.

You shouldn't have to call this function directly since +gimp_thumbnail_save_thumb_local() will do this for you.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

dirname	the basename of the dir, without the actual dirname itself
size	a GimpThumbSize
error	return location for possible errors

Returns

TRUE is the directory exists, FALSE if it could not +be created

Since: 2.2

gimp_thumb_get_thumb_dir_local ()

gchar *
+gimp_thumb_get_thumb_dir_local (const gchar *dirname,
+                                GimpThumbSize size);

Retrieve the name of the local thumbnail folder for a specific +size. Unlike gimp_thumb_get_thumb_dir() the returned string is not +constant and should be free'd when it is not any longer needed.

Parameters

+++++ + + + + + + + + + + + + +

dirname	the basename of the dir, without the actual dirname itself
size	a GimpThumbSize

Returns

the thumbnail directory in the encoding of the filesystem

Since: 2.2

gimp_thumbs_delete_for_uri_local ()

void
+gimp_thumbs_delete_for_uri_local (const gchar *uri);

Deletes all thumbnails for the image file specified by uri + from +the local thumbnail repository.

Parameters

+++++ + + + + + +

uri

an escaped URI

Since: 2.2