← Back to branch summary

~ubuntu-branches/ubuntu/natty/gnome-vfs/natty

« back to all changes in this revision

Viewing changes to doc/html/gnome-vfs-20-gnome-vfs-directory-find-ops.html

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2009-03-17 16:12:58 UTC
  • mfrom: (0.2.2 upstream)
  • Revision ID: james.westby@ubuntu.com-20090317161258-px3a2czt9g2ktjz3
Tags: 1:2.24.1-0ubuntu1
New upstream version

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/html/gnome-vfs-20-gnome-vfs-directory-find-ops.html
1
 
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
 
<html>
3
 
<head>
4
 
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5
 
<title>Locating Standard Directories</title>
6
 
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2">
7
 
<link rel="start" href="index.html" title="GnomeVFS - Filesystem Abstraction library">
8
 
<link rel="up" href="gnome-vfs-directory-ops.html" title="Directory-Specific Operations">
9
 
<link rel="prev" href="gnome-vfs-20-gnome-vfs-directory-list-ops.html" title="Listing Directory Contents">
10
 
<link rel="next" href="gnome-vfs-file-and-dirs-ops.html" title="Advanced File/Directory Operations">
11
 
<meta name="generator" content="GTK-Doc V1.11 (XML mode)">
12
 
<link rel="stylesheet" href="style.css" type="text/css">
13
 
<link rel="chapter" href="about.html" title="Introduction to GnomeVFS">
14
 
<link rel="chapter" href="data-types.html" title="Basic Data Types">
15
 
<link rel="chapter" href="gnome-vfs-basic-file-ops.html" title="File Operations">
16
 
<link rel="chapter" href="gnome-vfs-directory-ops.html" title="Directory-Specific Operations">
17
 
<link rel="chapter" href="gnome-vfs-file-and-dirs-ops.html" title="Advanced File/Directory Operations">
18
 
<link rel="chapter" href="gnome-vfs-file-async-ops.html" title="Asynchronous Operations">
19
 
<link rel="chapter" href="volumes.html" title="Volumes and Drives Handling">
20
 
<link rel="chapter" href="networking.html" title="Networking">
21
 
<link rel="chapter" href="mime-registry.html" title="MIME Registry">
22
 
<link rel="chapter" href="modules.html" title="Filesystem Modules">
23
 
</head>
24
 
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
25
 
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
26
 
<tr valign="middle">
27
 
<td><a accesskey="p" href="gnome-vfs-20-gnome-vfs-directory-list-ops.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
28
 
<td><a accesskey="u" href="gnome-vfs-directory-ops.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
29
 
<td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
30
 
<th width="100%" align="center">GnomeVFS - Filesystem Abstraction library</th>
31
 
<td><a accesskey="n" href="gnome-vfs-file-and-dirs-ops.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
32
 
</tr>
33
 
<tr><td colspan="5" class="shortcuts">
34
 
<a href="#gnome-vfs-20-gnome-vfs-directory-find-ops.synopsis" class="shortcut">Top</a>
35
 
                 | 
36
 
                <a href="#gnome-vfs-20-gnome-vfs-directory-find-ops.description" class="shortcut">Description</a>
37
 
</td></tr>
38
 
</table>
39
 
<div class="refentry" lang="en">
40
 
<a name="gnome-vfs-20-gnome-vfs-directory-find-ops"></a><div class="titlepage"></div>
41
 
<div class="refnamediv"><table width="100%"><tr>
42
 
<td valign="top">
43
 
<h2><span class="refentrytitle"><a name="gnome-vfs-20-gnome-vfs-directory-find-ops.top_of_page"></a>Locating Standard Directories</span></h2>
44
 
<p>Locating Standard Directories — Utilities for locating standard directories such as the desktop and trash</p>
45
 
</td>
46
 
<td valign="top" align="right"></td>
47
 
</tr></table></div>
48
 
<div class="refsynopsisdiv">
49
 
<a name="gnome-vfs-20-gnome-vfs-directory-find-ops.synopsis"></a><h2>Synopsis</h2>
50
 
<pre class="synopsis">
51
 
enum                <a class="link" href="gnome-vfs-20-gnome-vfs-directory-find-ops.html#GnomeVFSFindDirectoryKind" title="enum GnomeVFSFindDirectoryKind">GnomeVFSFindDirectoryKind</a>;
52
 
<a class="link" href="gnome-vfs-20-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult">GnomeVFSResult</a>      <a class="link" href="gnome-vfs-20-gnome-vfs-directory-find-ops.html#gnome-vfs-find-directory" title="gnome_vfs_find_directory ()">gnome_vfs_find_directory</a>            (<a class="link" href="gnome-vfs-20-gnome-vfs-uri.html#GnomeVFSURI" title="GnomeVFSURI">GnomeVFSURI</a> *near_uri,
53
 
                                                         <a class="link" href="gnome-vfs-20-gnome-vfs-directory-find-ops.html#GnomeVFSFindDirectoryKind" title="enum GnomeVFSFindDirectoryKind">GnomeVFSFindDirectoryKind</a> kind,
54
 
                                                         <a class="link" href="gnome-vfs-20-gnome-vfs-uri.html#GnomeVFSURI" title="GnomeVFSURI">GnomeVFSURI</a> **result,
55
 
                                                         gboolean create_if_needed,
56
 
                                                         gboolean find_if_needed,
57
 
                                                         guint permissions);
58
 
</pre>
59
 
</div>
60
 
<div class="refsect1" lang="en">
61
 
<a name="gnome-vfs-20-gnome-vfs-directory-find-ops.description"></a><h2>Description</h2>
62
 
<p>
63
 
</p>
64
 
</div>
65
 
<div class="refsect1" lang="en">
66
 
<a name="gnome-vfs-20-gnome-vfs-directory-find-ops.details"></a><h2>Details</h2>
67
 
<div class="refsect2" lang="en">
68
 
<a name="GnomeVFSFindDirectoryKind"></a><h3>enum GnomeVFSFindDirectoryKind</h3>
69
 
<pre class="programlisting">typedef enum {
70
 
        GNOME_VFS_DIRECTORY_KIND_DESKTOP = 1000,
71
 
        GNOME_VFS_DIRECTORY_KIND_TRASH = 1001
72
 
} GnomeVFSFindDirectoryKind;
73
 
</pre>
74
 
<p>
75
 
Specifies what directory <a class="link" href="gnome-vfs-20-gnome-vfs-directory-find-ops.html#gnome-vfs-find-directory" title="gnome_vfs_find_directory ()"><code class="function">gnome_vfs_find_directory()</code></a> or
76
 
<code class="function">gnome_vfs_find_directory_cancellable()</code> should find.</p>
77
 
<p>
78
 
</p>
79
 
<div class="variablelist"><table border="0">
80
 
<col align="left" valign="top">
81
 
<tbody>
82
 
<tr>
83
 
<td><p><a name="GNOME-VFS-DIRECTORY-KIND-DESKTOP--CAPS"></a><span class="term"><code class="literal">GNOME_VFS_DIRECTORY_KIND_DESKTOP</code></span></p></td>
84
 
<td> Desktop directory.
85
 
</td>
86
 
</tr>
87
 
<tr>
88
 
<td><p><a name="GNOME-VFS-DIRECTORY-KIND-TRASH--CAPS"></a><span class="term"><code class="literal">GNOME_VFS_DIRECTORY_KIND_TRASH</code></span></p></td>
89
 
<td> Trash directory.
90
 
</td>
91
 
</tr>
92
 
</tbody>
93
 
</table></div>
94
 
</div>
95
 
<hr>
96
 
<div class="refsect2" lang="en">
97
 
<a name="gnome-vfs-find-directory"></a><h3>gnome_vfs_find_directory ()</h3>
98
 
<pre class="programlisting"><a class="link" href="gnome-vfs-20-gnome-vfs-result.html#GnomeVFSResult" title="enum GnomeVFSResult">GnomeVFSResult</a>      gnome_vfs_find_directory            (<a class="link" href="gnome-vfs-20-gnome-vfs-uri.html#GnomeVFSURI" title="GnomeVFSURI">GnomeVFSURI</a> *near_uri,
99
 
                                                         <a class="link" href="gnome-vfs-20-gnome-vfs-directory-find-ops.html#GnomeVFSFindDirectoryKind" title="enum GnomeVFSFindDirectoryKind">GnomeVFSFindDirectoryKind</a> kind,
100
 
                                                         <a class="link" href="gnome-vfs-20-gnome-vfs-uri.html#GnomeVFSURI" title="GnomeVFSURI">GnomeVFSURI</a> **result,
101
 
                                                         gboolean create_if_needed,
102
 
                                                         gboolean find_if_needed,
103
 
                                                         guint permissions);</pre>
104
 
<p>
105
 
Used to return well known directories such as Trash, Desktop, etc. from different
106
 
file systems.
107
 
</p>
108
 
<p>
109
 
There is quite a complicated logic behind finding/creating a Trash directory
110
 
and you need to be aware of some implications:
111
 
Finding the Trash the first time when using the file method may be pretty 
112
 
expensive. A cache file is used to store the location of that Trash file
113
 
for next time.
114
 
If <em class="parameter"><code>create_if_needed</code></em> is specified without <em class="parameter"><code>find_if_needed</code></em>, you may end up
115
 
creating a Trash file when there already is one. Your app should start out
116
 
by doing a <a class="link" href="gnome-vfs-20-gnome-vfs-directory-find-ops.html#gnome-vfs-find-directory" title="gnome_vfs_find_directory ()"><code class="function">gnome_vfs_find_directory()</code></a> with the <em class="parameter"><code>find_if_needed</code></em> to avoid this
117
 
and then use the <em class="parameter"><code>create_if_needed</code></em> flag to create Trash lazily when it is
118
 
needed for throwing away an item on a given disk.</p>
119
 
<p>
120
 
</p>
121
 
<div class="variablelist"><table border="0">
122
 
<col align="left" valign="top">
123
 
<tbody>
124
 
<tr>
125
 
<td><p><span class="term"><em class="parameter"><code>near_uri</code></em> :</span></p></td>
126
 
<td> find a well known directory on the same volume as <em class="parameter"><code>near_uri</code></em>.
127
 
</td>
128
 
</tr>
129
 
<tr>
130
 
<td><p><span class="term"><em class="parameter"><code>kind</code></em> :</span></p></td>
131
 
<td> kind of well known directory.
132
 
</td>
133
 
</tr>
134
 
<tr>
135
 
<td><p><span class="term"><em class="parameter"><code>result</code></em> :</span></p></td>
136
 
<td> newly created uri of the directory we found.
137
 
</td>
138
 
</tr>
139
 
<tr>
140
 
<td><p><span class="term"><em class="parameter"><code>create_if_needed</code></em> :</span></p></td>
141
 
<td> if directory we are looking for does not exist, try to create it.
142
 
</td>
143
 
</tr>
144
 
<tr>
145
 
<td><p><span class="term"><em class="parameter"><code>find_if_needed</code></em> :</span></p></td>
146
 
<td> if we don't know where directory is yet, look for it.
147
 
</td>
148
 
</tr>
149
 
<tr>
150
 
<td><p><span class="term"><em class="parameter"><code>permissions</code></em> :</span></p></td>
151
 
<td> if creating, use these permissions.
152
 
</td>
153
 
</tr>
154
 
<tr>
155
 
<td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
156
 
<td> an integer representing the result of the operation.
157
 
</td>
158
 
</tr>
159
 
</tbody>
160
 
</table></div>
161
 
</div>
162
 
</div>
163
 
</div>
164
 
<div class="footer">
165
 
<hr>
166
 
          Generated by GTK-Doc V1.11</div>
167
 
</body>
168
 
</html>