338 lines
20 KiB
XML
338 lines
20 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
|
|
|
|
<refentry id="libgimpthumb-gimpthumb-utils">
|
|
<refmeta>
|
|
<refentrytitle role="top_of_page">gimpthumb-utils</refentrytitle>
|
|
<manvolnum>3</manvolnum>
|
|
<refmiscinfo>LIBGIMPTHUMB Library</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>gimpthumb-utils</refname>
|
|
<refpurpose>Utility functions provided and used by libgimpthumb</refpurpose>
|
|
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
|
|
</refnamediv>
|
|
|
|
<refsynopsisdiv role="synopsis">
|
|
<title role="synopsis.title">Synopsis</title>
|
|
|
|
<synopsis>
|
|
|
|
|
|
|
|
<link linkend="gboolean">gboolean</link> <link linkend="gimp-thumb-init">gimp_thumb_init</link> (const <link linkend="gchar">gchar</link> *creator,
|
|
const <link linkend="gchar">gchar</link> *thumb_basedir);
|
|
<link linkend="gchar">gchar</link>* <link linkend="gimp-thumb-find-thumb">gimp_thumb_find_thumb</link> (const <link linkend="gchar">gchar</link> *uri,
|
|
<link linkend="GimpThumbSize">GimpThumbSize</link> *size);
|
|
<link linkend="GimpThumbFileType">GimpThumbFileType</link> <link linkend="gimp-thumb-file-test">gimp_thumb_file_test</link> (const <link linkend="gchar">gchar</link> *filename,
|
|
<link linkend="gint64">gint64</link> *mtime,
|
|
<link linkend="gint64">gint64</link> *size,
|
|
<link linkend="gint">gint</link> *err_no);
|
|
<link linkend="gchar">gchar</link>* <link linkend="gimp-thumb-name-from-uri">gimp_thumb_name_from_uri</link> (const <link linkend="gchar">gchar</link> *uri,
|
|
<link linkend="GimpThumbSize">GimpThumbSize</link> size);
|
|
<link linkend="gboolean">gboolean</link> <link linkend="gimp-thumb-ensure-thumb-dir">gimp_thumb_ensure_thumb_dir</link> (<link linkend="GimpThumbSize">GimpThumbSize</link> size,
|
|
<link linkend="GError">GError</link> **error);
|
|
const <link linkend="gchar">gchar</link>* <link linkend="gimp-thumb-get-thumb-dir">gimp_thumb_get_thumb_dir</link> (<link linkend="GimpThumbSize">GimpThumbSize</link> size);
|
|
<link linkend="void">void</link> <link linkend="gimp-thumbs-delete-for-uri">gimp_thumbs_delete_for_uri</link> (const <link linkend="gchar">gchar</link> *uri);
|
|
<link linkend="gchar">gchar</link>* <link linkend="gimp-thumb-name-from-uri-local">gimp_thumb_name_from_uri_local</link> (const <link linkend="gchar">gchar</link> *uri,
|
|
<link linkend="GimpThumbSize">GimpThumbSize</link> size);
|
|
<link linkend="gboolean">gboolean</link> <link linkend="gimp-thumb-ensure-thumb-dir-local">gimp_thumb_ensure_thumb_dir_local</link> (const <link linkend="gchar">gchar</link> *dirname,
|
|
<link linkend="GimpThumbSize">GimpThumbSize</link> size,
|
|
<link linkend="GError">GError</link> **error);
|
|
<link linkend="gchar">gchar</link>* <link linkend="gimp-thumb-get-thumb-dir-local">gimp_thumb_get_thumb_dir_local</link> (const <link linkend="gchar">gchar</link> *dirname,
|
|
<link linkend="GimpThumbSize">GimpThumbSize</link> size);
|
|
<link linkend="void">void</link> <link linkend="gimp-thumbs-delete-for-uri-local">gimp_thumbs_delete_for_uri_local</link> (const <link linkend="gchar">gchar</link> *uri);
|
|
</synopsis>
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<refsect1 role="desc">
|
|
<title role="desc.title">Description</title>
|
|
<para>
|
|
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 role="details">
|
|
<title role="details.title">Details</title>
|
|
<refsect2>
|
|
<title><anchor id="gimp-thumb-init" role="function"/>gimp_thumb_init ()</title>
|
|
<indexterm><primary>gimp_thumb_init</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gimp_thumb_init (const <link linkend="gchar">gchar</link> *creator,
|
|
const <link linkend="gchar">gchar</link> *thumb_basedir);</programlisting>
|
|
<para>
|
|
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 <parameter>thumb_basedir</parameter> 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.
|
|
</para>
|
|
<para>
|
|
The <parameter>creator</parameter> 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.
|
|
</para>
|
|
<para>
|
|
Usually you will pass <link linkend="NULL:CAPS"><literal>NULL</literal></link> for <parameter>thumb_basedir</parameter>. 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.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>creator</parameter> :</term>
|
|
<listitem><simpara> an ASCII string that identifies the thumbnail creator
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>thumb_basedir</parameter> :</term>
|
|
<listitem><simpara> an absolute path or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to use the default
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the library was successfully initialized.
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-thumb-find-thumb" role="function"/>gimp_thumb_find_thumb ()</title>
|
|
<indexterm><primary>gimp_thumb_find_thumb</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* gimp_thumb_find_thumb (const <link linkend="gchar">gchar</link> *uri,
|
|
<link linkend="GimpThumbSize">GimpThumbSize</link> *size);</programlisting>
|
|
<para>
|
|
This function attempts to locate a thumbnail for the given
|
|
<parameter>uri</parameter>. First it tries the size that is stored at <parameter>size</parameter>. If no
|
|
thumbnail of that size is found, it will look for a larger
|
|
thumbnail, then falling back to a smaller size.
|
|
</para>
|
|
<para>
|
|
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).
|
|
</para>
|
|
<para>
|
|
If a thumbnail is found, it's size is written to the variable
|
|
pointer to by <parameter>size</parameter> and the file location is returned.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>uri</parameter> :</term>
|
|
<listitem><simpara> an escaped URI
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>size</parameter> :</term>
|
|
<listitem><simpara> pointer to a <link linkend="GimpThumbSize"><type>GimpThumbSize</type></link>
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated string in the encoding of the
|
|
filesystem or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if no thumbnail for <parameter>uri</parameter> was found
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-thumb-file-test" role="function"/>gimp_thumb_file_test ()</title>
|
|
<indexterm><primary>gimp_thumb_file_test</primary></indexterm><programlisting><link linkend="GimpThumbFileType">GimpThumbFileType</link> gimp_thumb_file_test (const <link linkend="gchar">gchar</link> *filename,
|
|
<link linkend="gint64">gint64</link> *mtime,
|
|
<link linkend="gint64">gint64</link> *size,
|
|
<link linkend="gint">gint</link> *err_no);</programlisting>
|
|
<para>
|
|
This is a convenience and portability wrapper around <link linkend="stat"><function>stat()</function></link>. It
|
|
checks if the given <parameter>filename</parameter> exists and returns modification time
|
|
and file size in 64bit integer values.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>filename</parameter> :</term>
|
|
<listitem><simpara> a filename in the encoding of the filesystem
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>mtime</parameter> :</term>
|
|
<listitem><simpara> return location for modification time
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>size</parameter> :</term>
|
|
<listitem><simpara> return location for file size
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>err_no</parameter> :</term>
|
|
<listitem><simpara> return location for system "errno"
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> The type of the file, or <link linkend="GIMP-THUMB-FILE-TYPE-NONE:CAPS"><type>GIMP_THUMB_FILE_TYPE_NONE</type></link> if
|
|
the file doesn't exist.
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-thumb-name-from-uri" role="function"/>gimp_thumb_name_from_uri ()</title>
|
|
<indexterm><primary>gimp_thumb_name_from_uri</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* gimp_thumb_name_from_uri (const <link linkend="gchar">gchar</link> *uri,
|
|
<link linkend="GimpThumbSize">GimpThumbSize</link> size);</programlisting>
|
|
<para>
|
|
Creates the name of the thumbnail file of the specified <parameter>size</parameter> that
|
|
belongs to an image file located at the given <parameter>uri</parameter>.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>uri</parameter> :</term>
|
|
<listitem><simpara> an escaped URI
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>size</parameter> :</term>
|
|
<listitem><simpara> a <link linkend="GimpThumbSize"><type>GimpThumbSize</type></link>
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated filename in the encoding of the
|
|
filesystem or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>uri</parameter> points to the user's
|
|
thumbnail repository.
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-thumb-ensure-thumb-dir" role="function"/>gimp_thumb_ensure_thumb_dir ()</title>
|
|
<indexterm><primary>gimp_thumb_ensure_thumb_dir</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gimp_thumb_ensure_thumb_dir (<link linkend="GimpThumbSize">GimpThumbSize</link> size,
|
|
<link linkend="GError">GError</link> **error);</programlisting>
|
|
<para>
|
|
This function checks if the directory that is required to store
|
|
thumbnails for a particular <parameter>size</parameter> exist and attempts to create it
|
|
if necessary.
|
|
</para>
|
|
<para>
|
|
You shouldn't have to call this function directly since
|
|
<link linkend="gimp-thumbnail-save-thumb"><function>gimp_thumbnail_save_thumb()</function></link> and <link linkend="gimp-thumbnail-save-failure"><function>gimp_thumbnail_save_failure()</function></link> will
|
|
do this for you.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>size</parameter> :</term>
|
|
<listitem><simpara> a GimpThumbSize
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>error</parameter> :</term>
|
|
<listitem><simpara> return location for possible errors
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> is the directory exists, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if it could not
|
|
be created
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-thumb-get-thumb-dir" role="function"/>gimp_thumb_get_thumb_dir ()</title>
|
|
<indexterm><primary>gimp_thumb_get_thumb_dir</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* gimp_thumb_get_thumb_dir (<link linkend="GimpThumbSize">GimpThumbSize</link> size);</programlisting>
|
|
<para>
|
|
Retrieve the name of the thumbnail folder for a specific size. The
|
|
returned pointer will become invalid if <link linkend="gimp-thumb-init"><function>gimp_thumb_init()</function></link> is used
|
|
again. It must not be changed or freed.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>size</parameter> :</term>
|
|
<listitem><simpara> a GimpThumbSize
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the thumbnail directory in the encoding of the filesystem
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-thumbs-delete-for-uri" role="function" condition="since:GIMP 2.2"/>gimp_thumbs_delete_for_uri ()</title>
|
|
<indexterm role="GIMP 2.2"><primary>gimp_thumbs_delete_for_uri</primary></indexterm><programlisting><link linkend="void">void</link> gimp_thumbs_delete_for_uri (const <link linkend="gchar">gchar</link> *uri);</programlisting>
|
|
<para>
|
|
Deletes all thumbnails for the image file specified by <parameter>uri</parameter> from the
|
|
user's thumbnail repository.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>uri</parameter> :</term>
|
|
<listitem><simpara> an escaped URI
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist><para role="since">Since GIMP 2.2
|
|
</para></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-thumb-name-from-uri-local" role="function" condition="since:GIMP 2.2"/>gimp_thumb_name_from_uri_local ()</title>
|
|
<indexterm role="GIMP 2.2"><primary>gimp_thumb_name_from_uri_local</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* gimp_thumb_name_from_uri_local (const <link linkend="gchar">gchar</link> *uri,
|
|
<link linkend="GimpThumbSize">GimpThumbSize</link> size);</programlisting>
|
|
<para>
|
|
Creates the name of a local thumbnail file of the specified <parameter>size</parameter>
|
|
that belongs to an image file located at the given <parameter>uri</parameter>. Local
|
|
thumbnails have been introduced with version 0.7 of the spec.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>uri</parameter> :</term>
|
|
<listitem><simpara> an escaped URI
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>size</parameter> :</term>
|
|
<listitem><simpara> a <link linkend="GimpThumbSize"><type>GimpThumbSize</type></link>
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> a newly allocated filename in the encoding of the
|
|
filesystem or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>uri</parameter> is a remote file or
|
|
points to the user's thumbnail repository.
|
|
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist><para role="since">Since GIMP 2.2
|
|
</para></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-thumb-ensure-thumb-dir-local" role="function" condition="since:GIMP 2.2"/>gimp_thumb_ensure_thumb_dir_local ()</title>
|
|
<indexterm role="GIMP 2.2"><primary>gimp_thumb_ensure_thumb_dir_local</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> gimp_thumb_ensure_thumb_dir_local (const <link linkend="gchar">gchar</link> *dirname,
|
|
<link linkend="GimpThumbSize">GimpThumbSize</link> size,
|
|
<link linkend="GError">GError</link> **error);</programlisting>
|
|
<para>
|
|
This function checks if the directory that is required to store
|
|
local thumbnails for a particular <parameter>size</parameter> exist and attempts to
|
|
create it if necessary.
|
|
</para>
|
|
<para>
|
|
You shouldn't have to call this function directly since
|
|
<link linkend="gimp-thumbnail-save-thumb-local"><function>gimp_thumbnail_save_thumb_local()</function></link> will do this for you.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>dirname</parameter> :</term>
|
|
<listitem><simpara>
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>size</parameter> :</term>
|
|
<listitem><simpara> a GimpThumbSize
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>error</parameter> :</term>
|
|
<listitem><simpara> return location for possible errors
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> is the directory exists, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> if it could not
|
|
be created
|
|
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist><para role="since">Since GIMP 2.2
|
|
</para></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-thumb-get-thumb-dir-local" role="function" condition="since:GIMP 2.2"/>gimp_thumb_get_thumb_dir_local ()</title>
|
|
<indexterm role="GIMP 2.2"><primary>gimp_thumb_get_thumb_dir_local</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* gimp_thumb_get_thumb_dir_local (const <link linkend="gchar">gchar</link> *dirname,
|
|
<link linkend="GimpThumbSize">GimpThumbSize</link> size);</programlisting>
|
|
<para>
|
|
Retrieve the name of the local thumbnail folder for a specific
|
|
size. Unlike <link linkend="gimp-thumb-get-thumb-dir"><function>gimp_thumb_get_thumb_dir()</function></link> the returned string is not
|
|
constant and should be free'd when it is not any longer needed.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>dirname</parameter> :</term>
|
|
<listitem><simpara>
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><parameter>size</parameter> :</term>
|
|
<listitem><simpara> a GimpThumbSize
|
|
</simpara></listitem></varlistentry>
|
|
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the thumbnail directory in the encoding of the filesystem
|
|
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist><para role="since">Since GIMP 2.2
|
|
</para></refsect2>
|
|
<refsect2>
|
|
<title><anchor id="gimp-thumbs-delete-for-uri-local" role="function" condition="since:GIMP 2.2"/>gimp_thumbs_delete_for_uri_local ()</title>
|
|
<indexterm role="GIMP 2.2"><primary>gimp_thumbs_delete_for_uri_local</primary></indexterm><programlisting><link linkend="void">void</link> gimp_thumbs_delete_for_uri_local (const <link linkend="gchar">gchar</link> *uri);</programlisting>
|
|
<para>
|
|
Deletes all thumbnails for the image file specified by <parameter>uri</parameter> from
|
|
the local thumbnail repository.</para>
|
|
<para>
|
|
|
|
</para><variablelist role="params">
|
|
<varlistentry><term><parameter>uri</parameter> :</term>
|
|
<listitem><simpara> an escaped URI
|
|
</simpara></listitem></varlistentry>
|
|
</variablelist><para role="since">Since GIMP 2.2
|
|
</para></refsect2>
|
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
|
|
</refentry>
|