GimpThumb-utils

GimpThumb-utils — Utility functions provided and used by libgimpthumb

Functions

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