<refentry id="gnome-vfs-20-gnome-vfs-directory-find-ops">
<refmeta>
<refentrytitle id="top_of_page">Locating Standard Directories</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Locating Standard Directories</refname>
<refpurpose>
Utilities for locating standard directories such as the desktop and trash</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="synopsis">
<title id="synopsis.title">Synopsis</title>

<synopsis>



enum        <link linkend="GnomeVFSFindDirectoryKind">GnomeVFSFindDirectoryKind</link>;
<link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-find-directory">gnome_vfs_find_directory</link>     (<link linkend="GnomeVFSURI">GnomeVFSURI</link> *near_uri,
                                             <link linkend="GnomeVFSFindDirectoryKind">GnomeVFSFindDirectoryKind</link> kind,
                                             <link linkend="GnomeVFSURI">GnomeVFSURI</link> **result,
                                             <link linkend="gboolean">gboolean</link> create_if_needed,
                                             <link linkend="gboolean">gboolean</link> find_if_needed,
                                             <link linkend="guint">guint</link> permissions);
</synopsis>
</refsynopsisdiv>









<refsect1 id="desc">
<title id="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 id="details">
<title id="details.title">Details</title>
<refsect2>
<title><anchor id="GnomeVFSFindDirectoryKind" role="enum"/>enum GnomeVFSFindDirectoryKind</title>
<indexterm><primary>GnomeVFSFindDirectoryKind</primary></indexterm><programlisting>typedef enum {
	GNOME_VFS_DIRECTORY_KIND_DESKTOP = 1000,
	GNOME_VFS_DIRECTORY_KIND_TRASH = 1001
} GnomeVFSFindDirectoryKind;
</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="gnome-vfs-find-directory" role="function"/>gnome_vfs_find_directory ()</title>
<indexterm><primary>gnome_vfs_find_directory</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_find_directory     (<link linkend="GnomeVFSURI">GnomeVFSURI</link> *near_uri,
                                             <link linkend="GnomeVFSFindDirectoryKind">GnomeVFSFindDirectoryKind</link> kind,
                                             <link linkend="GnomeVFSURI">GnomeVFSURI</link> **result,
                                             <link linkend="gboolean">gboolean</link> create_if_needed,
                                             <link linkend="gboolean">gboolean</link> find_if_needed,
                                             <link linkend="guint">guint</link> permissions);</programlisting>
<para>
Used to return well known directories such as Trash, Desktop, etc. from different
file systems.
</para>
<para>
There is quite a complicated logic behind finding/creating a Trash directory
and you need to be aware of some implications:
Finding the Trash the first time when using the file method may be pretty 
expensive. A cache file is used to store the location of that Trash file
for next time.
If <parameter>create_if_needed</parameter> is specified without <parameter>find_if_needed</parameter>, you may end up
creating a Trash file when there already is one. Your app should start out
by doing a <link linkend="gnome-vfs-find-directory"><function>gnome_vfs_find_directory()</function></link> with the <parameter>find_if_needed</parameter> to avoid this
and then use the <parameter>create_if_needed</parameter> flag to create Trash lazily when it is
needed for throwing away an item on a given disk.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>near_uri</parameter>&nbsp;:</term>
<listitem><simpara> find a well known directory on the same volume as <parameter>near_uri</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>kind</parameter>&nbsp;:</term>
<listitem><simpara> kind of well known directory.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>result</parameter>&nbsp;:</term>
<listitem><simpara> newly created uri of the directory we found.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>create_if_needed</parameter>&nbsp;:</term>
<listitem><simpara> if directory we are looking for does not exist, try to create it.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>find_if_needed</parameter>&nbsp;:</term>
<listitem><simpara> if we don't know where directory is yet, look for it.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>permissions</parameter>&nbsp;:</term>
<listitem><simpara> if creating, use these permissions.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> an integer representing the result of the operation.
</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
