doc/xml/gnome-vfs-directory-find-ops.xml

   1 <refentry id="gnome-vfs-20-gnome-vfs-directory-find-ops">
   2 <refmeta>
   3 <refentrytitle>Locating Standard Directories</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Locating Standard Directories</refname><refpurpose>
  10 Utilities for locating standard directories such as the desktop and trash</refpurpose>
  11 </refnamediv>
  12
  13 <refsynopsisdiv><title>Synopsis</title>
  14
  15 <synopsis>
  16
  17
  18
  19 enum        <link linkend="GnomeVFSFindDirectoryKind">GnomeVFSFindDirectoryKind</link>;
  20 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-find-directory">gnome_vfs_find_directory</link>     (<link linkend="GnomeVFSURI">GnomeVFSURI</link> *near_uri,
  21                                              <link linkend="GnomeVFSFindDirectoryKind">GnomeVFSFindDirectoryKind</link> kind,
  22                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> **result,
  23                                              <link linkend="gboolean">gboolean</link> create_if_needed,
  24                                              <link linkend="gboolean">gboolean</link> find_if_needed,
  25                                              <link linkend="guint">guint</link> permissions);
  26 </synopsis>
  27 </refsynopsisdiv>
  28
  29
  30
  31
  32
  33
  34
  35
  36
  37 <refsect1>
  38 <title>Description</title>
  39 <para>
  40
  41 </para>
  42 </refsect1>
  43
  44 <refsect1>
  45 <title>Details</title>
  46 <refsect2>
  47 <title><anchor id="GnomeVFSFindDirectoryKind"/>enum GnomeVFSFindDirectoryKind</title>
  48 <indexterm><primary>GnomeVFSFindDirectoryKind</primary></indexterm><programlisting>typedef enum {
  49         GNOME_VFS_DIRECTORY_KIND_DESKTOP = 1000,
  50         GNOME_VFS_DIRECTORY_KIND_TRASH = 1001
  51 } GnomeVFSFindDirectoryKind;
  52 </programlisting>
  53 <para>
  54
  55 </para></refsect2>
  56 <refsect2>
  57 <title><anchor id="gnome-vfs-find-directory"/>gnome_vfs_find_directory ()</title>
  58 <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,
  59                                              <link linkend="GnomeVFSFindDirectoryKind">GnomeVFSFindDirectoryKind</link> kind,
  60                                              <link linkend="GnomeVFSURI">GnomeVFSURI</link> **result,
  61                                              <link linkend="gboolean">gboolean</link> create_if_needed,
  62                                              <link linkend="gboolean">gboolean</link> find_if_needed,
  63                                              <link linkend="guint">guint</link> permissions);</programlisting>
  64 <para>
  65 Used to return well known directories such as Trash, Desktop, etc. from different
  66 file systems.
  67 </para>
  68 <para>
  69 There is quite a complicated logic behind finding/creating a Trash directory
  70 and you need to be aware of some implications:
  71 Finding the Trash the first time when using the file method may be pretty
  72 expensive. A cache file is used to store the location of that Trash file
  73 for next time.
  74 If <parameter>ceate_if_needed</parameter> is specified without <parameter>find_if_needed</parameter>, you may end up
  75 creating a Trash file when there already is one. Your app should start out
  76 by doing a gnome_vfs_find_directory with the <parameter>find_if_needed</parameter> to avoid this
  77 and then use the <parameter>create_if_needed</parameter> flag to create Trash lazily when it is
  78 needed for throwing away an item on a given disk.</para>
  79 <para>
  80
  81 </para><variablelist role="params">
  82 <varlistentry><term><parameter>near_uri</parameter>&nbsp;:</term>
  83 <listitem><simpara> find a well known directory on the same volume as <parameter>near_uri</parameter>
  84 </simpara></listitem></varlistentry>
  85 <varlistentry><term><parameter>kind</parameter>&nbsp;:</term>
  86 <listitem><simpara> kind of well known directory
  87 </simpara></listitem></varlistentry>
  88 <varlistentry><term><parameter>result</parameter>&nbsp;:</term>
  89 <listitem><simpara> newly created URI of the directory we found
  90 </simpara></listitem></varlistentry>
  91 <varlistentry><term><parameter>create_if_needed</parameter>&nbsp;:</term>
  92 <listitem><simpara> If directory we are looking for does not exist, try to create it
  93 </simpara></listitem></varlistentry>
  94 <varlistentry><term><parameter>find_if_needed</parameter>&nbsp;:</term>
  95 <listitem><simpara> If we don't know where trash is yet, look for it.
  96 </simpara></listitem></varlistentry>
  97 <varlistentry><term><parameter>permissions</parameter>&nbsp;:</term>
  98 <listitem><simpara> If creating, use these permissions
  99 </simpara></listitem></varlistentry>
 100 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> An integer representing the result of the operation
 101 </simpara></listitem></varlistentry>
 102 </variablelist></refsect2>
 103
 104 </refsect1>
 105
 106
 107
 108
 109 </refentry>