libgimpthumb/gimpthumb-error.c libgimpthumb/gimpthumb-utils.[ch] some code

2003-12-14  Sven Neumann  <sven@gimp.org>

	* libgimpthumb/gimpthumb-error.c
	* libgimpthumb/gimpthumb-utils.[ch]
	* libgimpthumb/gimpthumbnail.c: some code review and addition of
	API documentation. Not finished yet...

ChangeLog

@@ -1,3 +1,10 @@
+2003-12-14  Sven Neumann  <sven@gimp.org>
+
+	* libgimpthumb/gimpthumb-error.c
+	* libgimpthumb/gimpthumb-utils.[ch]
+	* libgimpthumb/gimpthumbnail.c: some code review and addition of
+	API documentation. Not finished yet...
+
 2003-12-14  Raphaël Quinet  <quinet@gamers.org>
 
 	* libgimp/gimpui.h: Removed inclusion of libgimp/gimpmiscui.h,

devel-docs/ChangeLog

@@ -1,3 +1,7 @@
+2003-12-14  Sven Neumann  <sven@gimp.org>
+
+	* libgimp/Makefile.am (IGNORE_HFILES): removed gimpmiscui.h.
+
 2003-12-12  Michael Natterer  <mitch@gimp.org>
 
 	* libgimp/libgimp-sections.txt

devel-docs/libgimp/Makefile.am

@@ -29,9 +29,7 @@ CFILE_GLOB = $(DOC_SOURCE_DIR)/*.c
 IGNORE_HFILES = \
 	gimpcompat.h		\
 	gimpmisc.h		\
-	gimpmiscui.h		\
 	gimpunitcache.h		\
-	gimpintl.h 		\
 	libgimp-intl.h		\
 	stdplugins-intl.h
 

libgimpthumb/gimpthumb-error.c

@@ -30,6 +30,13 @@
 #include "gimpthumb-error.h"
 
 
+/**
+ * gimp_thumb_error_quark:
+ *
+ * This function is never called directly. Use GIMP_THUMB_ERROR() instead.
+ *
+ * Return value: the #GQuark that defines the GimpThumb error domain.
+ **/
 GQuark
 gimp_thumb_error_quark (void)
 {

libgimpthumb/gimpthumb-utils.c

@@ -62,6 +62,30 @@ static gchar      *thumb_fail_subdir      = NULL;
 
 
 
+/**
+ * gimp_thumb_init:
+ * @creator: an ASCII string that identifies the thumbnail creator
+ * @thumb_basedir: an absolute path or %NULL to use the default
+ *
+ * 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.
+ *
+ * Return value: %TRUE if the library was successfully initialized.
+ **/
 gboolean
 gimp_thumb_init (const gchar *creator,
                  const gchar *thumb_basedir)
@@ -71,6 +95,8 @@ gimp_thumb_init (const gchar *creator,
   gint        i;
 
   g_return_val_if_fail (creator != NULL, FALSE);
+  g_return_val_if_fail (thumb_basedir == NULL ||
+                        g_path_is_absolute (thumb_basedir), FALSE);
 
   if (gimp_thumb_initialized)
     gimp_thumb_exit ();
@@ -102,7 +128,17 @@ gimp_thumb_init (const gchar *creator,
   return gimp_thumb_initialized;
 }
 
-gchar *
+/**
+ * gimp_thumb_get_thumb_dir:
+ * @size: a GimpThumbSize
+ *
+ * Retrieve the name of a 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.
+ *
+ * Return value: the thumbnail directory in the encoding of the filesystem
+ **/
+const gchar *
 gimp_thumb_get_thumb_dir (GimpThumbSize  size)
 {
   g_return_val_if_fail (gimp_thumb_initialized, FALSE);
@@ -112,6 +148,22 @@ gimp_thumb_get_thumb_dir (GimpThumbSize  size)
   return thumb_subdirs[size];
 }
 
+/**
+ * gimp_thumb_ensure_thumb_dir:
+ * @size: a GimpThumbSize
+ * @error: return location for possible errors
+ *
+ * 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.
+ *
+ * Return value: %TRUE is the directory exists, %FALSE if it could not
+ *               be created
+ **/
 gboolean
 gimp_thumb_ensure_thumb_dir (GimpThumbSize   size,
                              GError        **error)
@@ -145,28 +197,50 @@ gimp_thumb_ensure_thumb_dir (GimpThumbSize   size,
   return FALSE;
 }
 
+/**
+ * gimp_thumb_name_from_uri:
+ * @uri: an escaped URI in UTF-8 encoding
+ * @size: a #GimpThumbSize
+ *
+ * Creates the name of the thumbnail file of the specified @size that
+ * belongs to an image file located at the given @uri.
+ *
+ * Return value: a newly allocated filename in the encoding of the
+ *               filesystem or %NULL if you attempt to create thumbnails
+ *               for files in the thumbnail directory.
+ **/
 gchar *
 gimp_thumb_name_from_uri (const gchar   *uri,
-                          GimpThumbSize  *size)
+                          GimpThumbSize  size)
 {
-  const gchar  *name;
   gint i;
 
   g_return_val_if_fail (gimp_thumb_initialized, NULL);
-  g_return_val_if_fail (size != NULL, NULL);
+  g_return_val_if_fail (uri != NULL, NULL);
 
   if (strstr (uri, thumb_dir))
     return NULL;
 
-  name = gimp_thumb_png_name (uri);
+  i = gimp_thumb_size (size);
 
-  i = gimp_thumb_size (*size);
+  return g_build_filename (thumb_subdirs[i], gimp_thumb_png_name (uri), NULL);
-
-  *size = thumb_sizes[i];
-
-  return g_build_filename (thumb_subdirs[i], name, NULL);
 }
 
+/**
+ * gimp_thumb_find_thumb:
+ * @uri: an escaped URI in UTF-8 encoding
+ * @size: pointer to a #GimpThumbSize
+ *
+ * This function attempts to locate a thumbnail for the given
+ * @url. 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 a thumbnail is
+ * found, it's size is written to the variable pointer to by @size
+ * and the file location is returned.
+ *
+ * Return value: a newly allocated string in the encoding of the
+ *               filesystem or %NULL if no thumbnail for @uri was found
+ **/
 gchar *
 gimp_thumb_find_thumb (const gchar   *uri,
                        GimpThumbSize *size)
@@ -176,6 +250,8 @@ gimp_thumb_find_thumb (const gchar   *uri,
   gint         i, n;
 
   g_return_val_if_fail (gimp_thumb_initialized, NULL);
+  g_return_val_if_fail (uri != NULL, NULL);
+  g_return_val_if_fail (size != NULL, NULL);
   g_return_val_if_fail (*size > GIMP_THUMB_SIZE_FAIL, NULL);
 
   name = gimp_thumb_png_name (uri);
@@ -211,6 +287,18 @@ gimp_thumb_find_thumb (const gchar   *uri,
   return NULL;
 }
 
+/**
+ * gimp_thumb_file_test:
+ * @filename: a filename in the encoding of the filesystem
+ * @mtime: return location for modification time
+ * @size: return location for file size
+ *
+ * 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.
+ *
+ * Return value: %TRUE if the file exists, %FALSE otherwise
+ **/
 gboolean
 gimp_thumb_file_test (const gchar *filename,
                       gint64      *mtime,
@@ -218,6 +306,8 @@ gimp_thumb_file_test (const gchar *filename,
 {
   struct stat s;
 
+  g_return_val_if_fail (filename != NULL, FALSE);
+
   if (stat (filename, &s) == 0 && (S_ISREG (s.st_mode)))
     {
       if (mtime)

libgimpthumb/gimpthumb-utils.h

@@ -32,12 +32,12 @@ G_BEGIN_DECLS
 gboolean      gimp_thumb_init             (const gchar    *creator,
                                            const gchar    *thumb_basedir);
 
-gchar     * gimp_thumb_get_thumb_dir    (GimpThumbSize   size);
+const gchar * gimp_thumb_get_thumb_dir    (GimpThumbSize   size);
 gboolean      gimp_thumb_ensure_thumb_dir (GimpThumbSize   size,
                                            GError        **error);
 
 gchar       * gimp_thumb_name_from_uri    (const gchar    *uri,
-                                         GimpThumbSize  *size);
+                                           GimpThumbSize   size);
 gchar       * gimp_thumb_find_thumb       (const gchar    *uri,
                                            GimpThumbSize  *size);
 

libgimpthumb/gimpthumbnail.c

@@ -85,7 +85,8 @@ static void   gimp_thumbnail_invalidate_thumb (GimpThumbnail  *thumbnail);
 static void   gimp_thumbnail_reset_info       (GimpThumbnail  *thumbnail);
 
 static void   gimp_thumbnail_update_image     (GimpThumbnail  *thumbnail);
-static void   gimp_thumbnail_update_thumb     (GimpThumbnail  *thumbnail);
+static void   gimp_thumbnail_update_thumb     (GimpThumbnail  *thumbnail,
+                                               GimpThumbSize   size);
 
 
 static GObjectClass *parent_class = NULL;
@@ -411,7 +412,7 @@ gimp_thumbnail_peek_thumb (GimpThumbnail *thumbnail,
   g_object_freeze_notify (G_OBJECT (thumbnail));
 
   gimp_thumbnail_update_image (thumbnail);
-  gimp_thumbnail_update_thumb (thumbnail);
+  gimp_thumbnail_update_thumb (thumbnail, size);
 
   g_object_thaw_notify (G_OBJECT (thumbnail));
 
@@ -501,14 +502,16 @@ gimp_thumbnail_update_image (GimpThumbnail *thumbnail)
 }
 
 static void
-gimp_thumbnail_update_thumb (GimpThumbnail *thumbnail)
+gimp_thumbnail_update_thumb (GimpThumbnail *thumbnail,
+                             GimpThumbSize  size)
 {
   GimpThumbState  state;
-  GimpThumbSize   size;
+  GimpThumbSize   s;
   gint64          filesize;
   gint64          mtime;
 
   state = thumbnail->thumb_state;
+  s = size;
 
   switch (state)
     {
@@ -521,7 +524,7 @@ gimp_thumbnail_update_thumb (GimpThumbnail *thumbnail)
       g_return_if_fail (thumbnail->thumb_filename == NULL);
 
       thumbnail->thumb_filename =
-        gimp_thumb_find_thumb (thumbnail->image_uri, &size);
+        gimp_thumb_find_thumb (thumbnail->image_uri, &s);
       break;
 
     default:
@@ -532,10 +535,15 @@ gimp_thumbnail_update_thumb (GimpThumbnail *thumbnail)
    switch (state)
      {
      default:
-       if (gimp_thumb_file_test (thumbnail->thumb_filename, &mtime, &filesize))
+       if (thumbnail->thumb_filename &&
+           gimp_thumb_file_test (thumbnail->thumb_filename, &mtime, &filesize))
+         {
            state = GIMP_THUMB_STATE_EXISTS;
+         }
        else
+         {
            state = GIMP_THUMB_STATE_NOT_FOUND;
+         }
        break;
      }
 
@@ -692,7 +700,7 @@ gimp_thumbnail_save_thumb (GimpThumbnail  *thumbnail,
   if (size < 1)
     return TRUE;
 
-  name = gimp_thumb_name_from_uri (thumbnail->image_uri, &size);
+  name = gimp_thumb_name_from_uri (thumbnail->image_uri, size);
   if (! name)
     return TRUE;
 
@@ -756,7 +764,6 @@ gimp_thumbnail_save_failure (GimpThumbnail  *thumbnail,
                              GError        **error)
 {
   GdkPixbuf *pixbuf;
-  GimpThumbSize  size = GIMP_THUMB_SIZE_FAIL;
   gchar     *name;
   gchar     *desc;
   gchar     *time_str;
@@ -767,11 +774,11 @@ gimp_thumbnail_save_failure (GimpThumbnail  *thumbnail,
   g_return_val_if_fail (thumbnail->image_uri != NULL, FALSE);
   g_return_val_if_fail (software != NULL, FALSE);
 
-  name = gimp_thumb_name_from_uri (thumbnail->image_uri, &size);
+  name = gimp_thumb_name_from_uri (thumbnail->image_uri, GIMP_THUMB_SIZE_FAIL);
   if (! name)
     return TRUE;
 
-  if (! gimp_thumb_ensure_thumb_dir (size, error))
+  if (! gimp_thumb_ensure_thumb_dir (GIMP_THUMB_SIZE_FAIL, error))
     {
       g_free (name);
       return FALSE;