## GimpThumb-utils GimpThumb-utils — Utility functions provided and used by libgimpthumb |

## Synopsis

    gboolean            gimp_thumb_init                     (const gchar *creator,
                                                             const gchar *thumb_basedir);
    gchar *             gimp_thumb_find_thumb               (const gchar *uri,
                                                             GimpThumbSize *size);
    GimpThumbFileType   gimp_thumb_file_test                (const gchar *filename,
                                                             gint64 *mtime,
                                                             gint64 *size,
                                                             gint *err_no);
    gchar *             gimp_thumb_name_from_uri            (const gchar *uri,
                                                             GimpThumbSize size);
    gboolean            gimp_thumb_ensure_thumb_dir         (GimpThumbSize size,
                                                             GError **error);
    const gchar *       gimp_thumb_get_thumb_dir            (GimpThumbSize size);
    void                gimp_thumbs_delete_for_uri          (const gchar *uri);
    gchar *             gimp_thumb_name_from_uri_local      (const gchar *uri,
                                                             GimpThumbSize size);
    gboolean            gimp_thumb_ensure_thumb_dir_local   (const gchar *dirname,
                                                             GimpThumbSize size,
                                                             GError **error);
    gchar *             gimp_thumb_get_thumb_dir_local      (const gchar *dirname,
                                                             GimpThumbSize size);
    void                gimp_thumbs_delete_for_uri_local    (const gchar *uri);

## Description

Utility functions provided and used by libgimpthumb

## Details

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

`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_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.

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

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

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

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

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

`uri` : | an escaped URI

Since GIMP 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.

`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 GIMP 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.

`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 GIMP 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.

`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 GIMP 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.

`uri` : | an escaped URI

Since GIMP 2.2