1
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>gimpthumb-utils</title><meta name="generator" content="DocBook XSL Stylesheets V1.66.1"><link rel="start" href="index.html" title="GIMP Thumbnail Library Reference Manual"><link rel="up" href="libgimpthumb.html" title="Part�I.�GIMP Thumbnail Library"><link rel="prev" href="GimpThumbnail.html" title="GimpThumbnail"><link rel="next" href="libgimpthumb-gimpthumb-enums.html" title="gimpthumb-enums"><meta name="generator" content="GTK-Doc V1.3 (XML mode)"><link rel="stylesheet" href="style.css" type="text/css"><link rel="part" href="libgimpthumb.html" title="Part�I.�GIMP Thumbnail Library"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="GimpThumbnail.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="libgimpthumb.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">GIMP Thumbnail Library Reference Manual</th><td><a accesskey="n" href="libgimpthumb-gimpthumb-enums.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="refentry" lang="en"><a name="libgimpthumb-gimpthumb-utils"></a><div class="titlepage"></div><div class="refnamediv"><table width="100%"><tr><td valign="top"><h2><span class="refentrytitle">gimpthumb-utils</span></h2><p>gimpthumb-utils — Utility functions provided and used by libgimpthumb</p></td><td valign="top" align="right"></td></tr></table></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
5
gboolean <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumb-init">gimp_thumb_init</a> (const gchar *creator,
6
const gchar *thumb_basedir);
7
gchar* <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumb-find-thumb">gimp_thumb_find_thumb</a> (const gchar *uri,
8
<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> *size);
9
<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbFileType">GimpThumbFileType</a> <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumb-file-test">gimp_thumb_file_test</a> (const gchar *filename,
13
gchar* <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumb-name-from-uri">gimp_thumb_name_from_uri</a> (const gchar *uri,
14
<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> size);
15
gboolean <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumb-ensure-thumb-dir">gimp_thumb_ensure_thumb_dir</a> (<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> size,
17
const gchar* <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumb-get-thumb-dir">gimp_thumb_get_thumb_dir</a> (<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> size);
18
void <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumbs-delete-for-uri">gimp_thumbs_delete_for_uri</a> (const gchar *uri);
19
gchar* <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumb-name-from-uri-local">gimp_thumb_name_from_uri_local</a> (const gchar *uri,
20
<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> size);
21
gboolean <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumb-ensure-thumb-dir-local">gimp_thumb_ensure_thumb_dir_local</a>
22
(const gchar *dirname,
23
<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> size,
25
gchar* <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumb-get-thumb-dir-local">gimp_thumb_get_thumb_dir_local</a> (const gchar *dirname,
26
<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> size);
27
void <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumbs-delete-for-uri-local">gimp_thumbs_delete_for_uri_local</a>
29
</pre></div><div class="refsect1" lang="en"><a name="id2569626"></a><h2>Description</h2><p>
31
</p></div><div class="refsect1" lang="en"><a name="id2569635"></a><h2>Details</h2><div class="refsect2" lang="en"><a name="id2569640"></a><h3><a name="gimp-thumb-init"></a>gimp_thumb_init ()</h3><a class="indexterm" name="id2569649"></a><pre class="programlisting">gboolean gimp_thumb_init (const gchar *creator,
32
const gchar *thumb_basedir);</pre><p>
33
This function initializes the thumbnail system. It must be called
34
before any other functions from libgimpthumb are used. You may call
35
it more than once if you want to change the <i class="parameter"><tt>thumb_basedir</tt></i> but if
36
you do that, you should make sure that no thread is still using the
37
library. Apart from this function, libgimpthumb is multi-thread
40
The <i class="parameter"><tt>creator</tt></i> string must be 7bit ASCII and should contain the name
41
of the software that creates the thumbnails. It is used to handle
42
thumbnail creation failures. See the spec for more details.
44
Usually you will pass <tt class="literal">NULL</tt> for <i class="parameter"><tt>thumb_basedir</tt></i>. Thumbnails will
45
then be stored in the user's personal thumbnail directory as
46
defined in the spec. If you wish to use libgimpthumb to store
47
application-specific thumbnails, you can specify a different base
48
directory here.</p><p>
50
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>creator</tt></i>�:</span></td><td> an ASCII string that identifies the thumbnail creator
51
</td></tr><tr><td><span class="term"><i class="parameter"><tt>thumb_basedir</tt></i>�:</span></td><td> an absolute path or <tt class="literal">NULL</tt> to use the default
52
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>�:</span></td><td> <tt class="literal">TRUE</tt> if the library was successfully initialized.
53
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2495692"></a><h3><a name="gimp-thumb-find-thumb"></a>gimp_thumb_find_thumb ()</h3><a class="indexterm" name="id2495700"></a><pre class="programlisting">gchar* gimp_thumb_find_thumb (const gchar *uri,
54
<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> *size);</pre><p>
55
This function attempts to locate a thumbnail for the given
56
<i class="parameter"><tt>uri</tt></i>. First it tries the size that is stored at <i class="parameter"><tt>size</tt></i>. If no
57
thumbnail of that size is found, it will look for a larger
58
thumbnail, then falling back to a smaller size.
60
If the user's thumbnail repository doesn't provide a thumbnail but
61
a local thumbnail repository exists for the folder the image is
62
located in, the same search is done among the local thumbnails (if
65
If a thumbnail is found, it's size is written to the variable
66
pointer to by <i class="parameter"><tt>size</tt></i> and the file location is returned.</p><p>
68
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>uri</tt></i>�:</span></td><td> an escaped URI
69
</td></tr><tr><td><span class="term"><i class="parameter"><tt>size</tt></i>�:</span></td><td> pointer to a <a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize"><span class="type">GimpThumbSize</span></a>
70
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>�:</span></td><td> a newly allocated string in the encoding of the
71
filesystem or <tt class="literal">NULL</tt> if no thumbnail for <i class="parameter"><tt>uri</tt></i> was found
72
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2495804"></a><h3><a name="gimp-thumb-file-test"></a>gimp_thumb_file_test ()</h3><a class="indexterm" name="id2495813"></a><pre class="programlisting"><a href="libgimpthumb-gimpthumb-enums.html#GimpThumbFileType">GimpThumbFileType</a> gimp_thumb_file_test (const gchar *filename,
75
gint *err_no);</pre><p>
76
This is a convenience and portability wrapper around <tt class="function">stat()</tt>. It
77
checks if the given <i class="parameter"><tt>filename</tt></i> exists and returns modification time
78
and file size in 64bit integer values.</p><p>
80
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>filename</tt></i>�:</span></td><td> a filename in the encoding of the filesystem
81
</td></tr><tr><td><span class="term"><i class="parameter"><tt>mtime</tt></i>�:</span></td><td> return location for modification time
82
</td></tr><tr><td><span class="term"><i class="parameter"><tt>size</tt></i>�:</span></td><td> return location for file size
83
</td></tr><tr><td><span class="term"><i class="parameter"><tt>err_no</tt></i>�:</span></td><td> return location for system "errno"
84
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>�:</span></td><td> The type of the file, or <span class="type">GIMP_THUMB_FILE_TYPE_NONE</span> if
85
the file doesn't exist.
86
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2469635"></a><h3><a name="gimp-thumb-name-from-uri"></a>gimp_thumb_name_from_uri ()</h3><a class="indexterm" name="id2469643"></a><pre class="programlisting">gchar* gimp_thumb_name_from_uri (const gchar *uri,
87
<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> size);</pre><p>
88
Creates the name of the thumbnail file of the specified <i class="parameter"><tt>size</tt></i> that
89
belongs to an image file located at the given <i class="parameter"><tt>uri</tt></i>.</p><p>
91
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>uri</tt></i>�:</span></td><td> an escaped URI
92
</td></tr><tr><td><span class="term"><i class="parameter"><tt>size</tt></i>�:</span></td><td> a <a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize"><span class="type">GimpThumbSize</span></a>
93
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>�:</span></td><td> a newly allocated filename in the encoding of the
94
filesystem or <tt class="literal">NULL</tt> if <i class="parameter"><tt>uri</tt></i> points to the user's
96
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2469731"></a><h3><a name="gimp-thumb-ensure-thumb-dir"></a>gimp_thumb_ensure_thumb_dir ()</h3><a class="indexterm" name="id2469740"></a><pre class="programlisting">gboolean gimp_thumb_ensure_thumb_dir (<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> size,
97
GError **error);</pre><p>
98
This function checks if the directory that is required to store
99
thumbnails for a particular <i class="parameter"><tt>size</tt></i> exist and attempts to create it
102
You shouldn't have to call this function directly since
103
<a href="GimpThumbnail.html#gimp-thumbnail-save-thumb"><tt class="function">gimp_thumbnail_save_thumb()</tt></a> and <a href="GimpThumbnail.html#gimp-thumbnail-save-failure"><tt class="function">gimp_thumbnail_save_failure()</tt></a> will
104
do this for you.</p><p>
106
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>size</tt></i>�:</span></td><td> a GimpThumbSize
107
</td></tr><tr><td><span class="term"><i class="parameter"><tt>error</tt></i>�:</span></td><td> return location for possible errors
108
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>�:</span></td><td> <tt class="literal">TRUE</tt> is the directory exists, <tt class="literal">FALSE</tt> if it could not
110
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2469834"></a><h3><a name="gimp-thumb-get-thumb-dir"></a>gimp_thumb_get_thumb_dir ()</h3><a class="indexterm" name="id2469843"></a><pre class="programlisting">const gchar* gimp_thumb_get_thumb_dir (<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> size);</pre><p>
111
Retrieve the name of the thumbnail folder for a specific size. The
112
returned pointer will become invalid if <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumb-init"><tt class="function">gimp_thumb_init()</tt></a> is used
113
again. It must not be changed or freed.</p><p>
115
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>size</tt></i>�:</span></td><td> a GimpThumbSize
116
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>�:</span></td><td> the thumbnail directory in the encoding of the filesystem
117
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2584358"></a><h3><a name="gimp-thumbs-delete-for-uri"></a>gimp_thumbs_delete_for_uri ()</h3><a class="indexterm" name="id2584368"></a><pre class="programlisting">void gimp_thumbs_delete_for_uri (const gchar *uri);</pre><p>
118
Deletes all thumbnails for the image file specified by <i class="parameter"><tt>uri</tt></i> from the
119
user's thumbnail repository.</p><p>
121
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>uri</tt></i>�:</span></td><td> an escaped URI
122
</td></tr></tbody></table></div><p>Since GIMP 2.2
123
</p></div><hr><div class="refsect2" lang="en"><a name="id2584415"></a><h3><a name="gimp-thumb-name-from-uri-local"></a>gimp_thumb_name_from_uri_local ()</h3><a class="indexterm" name="id2584426"></a><pre class="programlisting">gchar* gimp_thumb_name_from_uri_local (const gchar *uri,
124
<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> size);</pre><p>
125
Creates the name of a local thumbnail file of the specified <i class="parameter"><tt>size</tt></i>
126
that belongs to an image file located at the given <i class="parameter"><tt>uri</tt></i>. Local
127
thumbnails have been introduced with version 0.7 of the spec.</p><p>
129
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>uri</tt></i>�:</span></td><td> an escaped URI
130
</td></tr><tr><td><span class="term"><i class="parameter"><tt>size</tt></i>�:</span></td><td> a <a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize"><span class="type">GimpThumbSize</span></a>
131
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>�:</span></td><td> a newly allocated filename in the encoding of the
132
filesystem or <tt class="literal">NULL</tt> if <i class="parameter"><tt>uri</tt></i> is a remote file or
133
points to the user's thumbnail repository.
135
</td></tr></tbody></table></div><p>Since GIMP 2.2
136
</p></div><hr><div class="refsect2" lang="en"><a name="id2584520"></a><h3><a name="gimp-thumb-ensure-thumb-dir-local"></a>gimp_thumb_ensure_thumb_dir_local ()</h3><a class="indexterm" name="id2584532"></a><pre class="programlisting">gboolean gimp_thumb_ensure_thumb_dir_local
137
(const gchar *dirname,
138
<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> size,
139
GError **error);</pre><p>
140
This function checks if the directory that is required to store
141
local thumbnails for a particular <i class="parameter"><tt>size</tt></i> exist and attempts to
142
create it if necessary.
144
You shouldn't have to call this function directly since
145
<a href="GimpThumbnail.html#gimp-thumbnail-save-thumb-local"><tt class="function">gimp_thumbnail_save_thumb_local()</tt></a> will do this for you.</p><p>
147
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>dirname</tt></i>�:</span></td><td>
148
</td></tr><tr><td><span class="term"><i class="parameter"><tt>size</tt></i>�:</span></td><td> a GimpThumbSize
149
</td></tr><tr><td><span class="term"><i class="parameter"><tt>error</tt></i>�:</span></td><td> return location for possible errors
150
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>�:</span></td><td> <tt class="literal">TRUE</tt> is the directory exists, <tt class="literal">FALSE</tt> if it could not
153
</td></tr></tbody></table></div><p>Since GIMP 2.2
154
</p></div><hr><div class="refsect2" lang="en"><a name="id2584644"></a><h3><a name="gimp-thumb-get-thumb-dir-local"></a>gimp_thumb_get_thumb_dir_local ()</h3><a class="indexterm" name="id2584655"></a><pre class="programlisting">gchar* gimp_thumb_get_thumb_dir_local (const gchar *dirname,
155
<a href="libgimpthumb-gimpthumb-enums.html#GimpThumbSize">GimpThumbSize</a> size);</pre><p>
156
Retrieve the name of the local thumbnail folder for a specific
157
size. Unlike <a href="libgimpthumb-gimpthumb-utils.html#gimp-thumb-get-thumb-dir"><tt class="function">gimp_thumb_get_thumb_dir()</tt></a> the returned string is not
158
constant and should be free'd when it is not any longer needed.</p><p>
160
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>dirname</tt></i>�:</span></td><td>
161
</td></tr><tr><td><span class="term"><i class="parameter"><tt>size</tt></i>�:</span></td><td> a GimpThumbSize
162
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span>�:</span></td><td> the thumbnail directory in the encoding of the filesystem
164
</td></tr></tbody></table></div><p>Since GIMP 2.2
165
</p></div><hr><div class="refsect2" lang="en"><a name="id2584735"></a><h3><a name="gimp-thumbs-delete-for-uri-local"></a>gimp_thumbs_delete_for_uri_local ()</h3><a class="indexterm" name="id2584746"></a><pre class="programlisting">void gimp_thumbs_delete_for_uri_local
166
(const gchar *uri);</pre><p>
167
Deletes all thumbnails for the image file specified by <i class="parameter"><tt>uri</tt></i> from
168
the local thumbnail repository.</p><p>
170
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>uri</tt></i>�:</span></td><td> an escaped URI
171
</td></tr></tbody></table></div><p>Since GIMP 2.2
172
</p></div></div></div><table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle"><td align="left"><a accesskey="p" href="GimpThumbnail.html"><b><<�GimpThumbnail</b></a></td><td align="right"><a accesskey="n" href="libgimpthumb-gimpthumb-enums.html"><b>gimpthumb-enums�>></b></a></td></tr></table></body></html>
added
removed
devel-docs/libgimpthumb/html/libgimpthumb-gimpthumb-utils.html
