2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
4
<refentry id="rhythmbox-rb-file-helpers">
6
<refentrytitle role="top_of_page" id="rhythmbox-rb-file-helpers.top_of_page">rb-file-helpers</refentrytitle>
7
<manvolnum>3</manvolnum>
8
<refmiscinfo>RHYTHMBOX Library</refmiscinfo>
12
<refname>rb-file-helpers</refname>
13
<refpurpose>An assortment of file and URI helper functions</refpurpose>
16
<refsynopsisdiv id="rhythmbox-rb-file-helpers.synopsis" role="synopsis">
17
<title role="synopsis.title">Synopsis</title>
20
const <link linkend="char">char</link> * <link linkend="rb-file">rb_file</link> (const <link linkend="char">char</link> *filename);
21
const <link linkend="char">char</link> * <link linkend="rb-user-data-dir">rb_user_data_dir</link> (void);
22
const <link linkend="char">char</link> * <link linkend="rb-user-cache-dir">rb_user_cache_dir</link> (void);
23
const <link linkend="char">char</link> * <link linkend="rb-music-dir">rb_music_dir</link> (void);
24
<link linkend="char">char</link> * <link linkend="rb-find-user-data-file">rb_find_user_data_file</link> (const <link linkend="char">char</link> *name,
25
<link linkend="GError">GError</link> **error);
26
<link linkend="char">char</link> * <link linkend="rb-find-user-cache-file">rb_find_user_cache_file</link> (const <link linkend="char">char</link> *name,
27
<link linkend="GError">GError</link> **error);
28
<link linkend="void">void</link> <link linkend="rb-file-helpers-init">rb_file_helpers_init</link> (<link linkend="gboolean">gboolean</link> uninstalled);
29
<link linkend="void">void</link> <link linkend="rb-file-helpers-shutdown">rb_file_helpers_shutdown</link> (void);
30
<link linkend="char">char</link> * <link linkend="rb-uri-resolve-symlink">rb_uri_resolve_symlink</link> (const <link linkend="char">char</link> *uri,
31
<link linkend="GError">GError</link> **error);
32
<link linkend="gboolean">gboolean</link> <link linkend="rb-uri-is-directory">rb_uri_is_directory</link> (const <link linkend="char">char</link> *uri);
33
<link linkend="gboolean">gboolean</link> <link linkend="rb-uri-exists">rb_uri_exists</link> (const <link linkend="char">char</link> *uri);
34
<link linkend="gboolean">gboolean</link> <link linkend="rb-uri-is-readable">rb_uri_is_readable</link> (const <link linkend="char">char</link> *uri);
35
<link linkend="gboolean">gboolean</link> <link linkend="rb-uri-is-writable">rb_uri_is_writable</link> (const <link linkend="char">char</link> *uri);
36
<link linkend="gboolean">gboolean</link> <link linkend="rb-uri-is-local">rb_uri_is_local</link> (const <link linkend="char">char</link> *uri);
37
<link linkend="gboolean">gboolean</link> <link linkend="rb-uri-is-hidden">rb_uri_is_hidden</link> (const <link linkend="char">char</link> *uri);
38
<link linkend="gboolean">gboolean</link> <link linkend="rb-uri-could-be-podcast">rb_uri_could_be_podcast</link> (const <link linkend="char">char</link> *uri,
39
<link linkend="gboolean">gboolean</link> *is_opml);
40
<link linkend="char">char</link> * <link linkend="rb-uri-make-hidden">rb_uri_make_hidden</link> (const <link linkend="char">char</link> *uri);
41
<link linkend="void">void</link> <link linkend="rb-uri-handle-recursively">rb_uri_handle_recursively</link> (const <link linkend="char">char</link> *uri,
42
<link linkend="GCancellable">GCancellable</link> *cancel,
43
<link linkend="RBUriRecurseFunc">RBUriRecurseFunc</link> func,
44
<link linkend="gpointer">gpointer</link> user_data);
45
<link linkend="void">void</link> <link linkend="rb-uri-handle-recursively-async">rb_uri_handle_recursively_async</link> (const <link linkend="char">char</link> *uri,
46
<link linkend="GCancellable">GCancellable</link> *cancel,
47
<link linkend="RBUriRecurseFunc">RBUriRecurseFunc</link> func,
48
<link linkend="gpointer">gpointer</link> user_data,
49
<link linkend="GDestroyNotify">GDestroyNotify</link> data_destroy);
50
<link linkend="gboolean">gboolean</link> <link linkend="rb-uri-mkstemp">rb_uri_mkstemp</link> (const <link linkend="char">char</link> *prefix,
51
<link linkend="char">char</link> **uri_ret,
52
<link linkend="GOutputStream">GOutputStream</link> **stream,
53
<link linkend="GError">GError</link> **error);
54
<link linkend="char">char</link> * <link linkend="rb-canonicalise-uri">rb_canonicalise_uri</link> (const <link linkend="char">char</link> *uri);
55
<link linkend="char">char</link>* <link linkend="rb-uri-append-path">rb_uri_append_path</link> (const <link linkend="char">char</link> *uri,
56
const <link linkend="char">char</link> *path);
57
<link linkend="char">char</link>* <link linkend="rb-uri-append-uri">rb_uri_append_uri</link> (const <link linkend="char">char</link> *uri,
58
const <link linkend="char">char</link> *fragment);
59
<link linkend="char">char</link> * <link linkend="rb-uri-get-dir-name">rb_uri_get_dir_name</link> (const <link linkend="char">char</link> *uri);
60
<link linkend="char">char</link> * <link linkend="rb-uri-get-short-path-name">rb_uri_get_short_path_name</link> (const <link linkend="char">char</link> *uri);
61
<link linkend="gboolean">gboolean</link> <link linkend="rb-check-dir-has-space">rb_check_dir_has_space</link> (<link linkend="GFile">GFile</link> *dir,
62
<link linkend="guint64">guint64</link> bytes_needed);
63
<link linkend="gboolean">gboolean</link> <link linkend="rb-check-dir-has-space-uri">rb_check_dir_has_space_uri</link> (const <link linkend="char">char</link> *uri,
64
<link linkend="guint64">guint64</link> bytes_needed);
65
<link linkend="char">char</link> * <link linkend="rb-uri-get-mount-point">rb_uri_get_mount_point</link> (const <link linkend="char">char</link> *uri);
66
<link linkend="gboolean">gboolean</link> <link linkend="rb-uri-create-parent-dirs">rb_uri_create_parent_dirs</link> (const <link linkend="char">char</link> *uri,
67
<link linkend="GError">GError</link> **error);
68
<link linkend="GFile">GFile</link> * <link linkend="rb-file-find-extant-parent">rb_file_find_extant_parent</link> (<link linkend="GFile">GFile</link> *file);
69
<link linkend="char">char</link> * <link linkend="rb-uri-get-filesystem-type">rb_uri_get_filesystem_type</link> (const <link linkend="char">char</link> *uri);
70
<link linkend="void">void</link> <link linkend="rb-sanitize-path-for-msdos-filesystem">rb_sanitize_path_for_msdos_filesystem</link>
71
(<link linkend="char">char</link> *path);
72
<link linkend="char">char</link> * <link linkend="rb-sanitize-uri-for-filesystem">rb_sanitize_uri_for_filesystem</link> (const <link linkend="char">char</link> *uri);
73
<link linkend="gboolean">gboolean</link> (<link linkend="RBUriRecurseFunc">*RBUriRecurseFunc</link>) (<link linkend="GFile">GFile</link> *file,
74
<link linkend="gboolean">gboolean</link> dir,
75
<link linkend="gpointer">gpointer</link> data);
87
<refsect1 id="rhythmbox-rb-file-helpers.description" role="desc">
88
<title role="desc.title">Description</title>
90
This is a variety of functions for dealing with files and URIs, including
91
locating installed files, finding user cache and config directories,
92
and dealing with file naming restrictions for various filesystems.</para>
97
<refsect1 id="rhythmbox-rb-file-helpers.details" role="details">
98
<title role="details.title">Details</title>
99
<refsect2 id="rb-file" role="function">
100
<title>rb_file ()</title>
101
<indexterm zone="rb-file"><primary sortas="rb_file">rb_file</primary></indexterm><programlisting>const <link linkend="char">char</link> * rb_file (const <link linkend="char">char</link> *filename);</programlisting>
103
Searches for an installed file, returning the full path name
104
if found, NULL otherwise.</para>
106
</para><variablelist role="params">
107
<varlistentry><term><parameter>filename</parameter> :</term>
108
<listitem><simpara> name of file to search for
109
</simpara></listitem></varlistentry>
110
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> Full file name, if found. Must not be freed.
111
</simpara></listitem></varlistentry>
112
</variablelist></refsect2>
113
<refsect2 id="rb-user-data-dir" role="function">
114
<title>rb_user_data_dir ()</title>
115
<indexterm zone="rb-user-data-dir"><primary sortas="rb_user_data_dir">rb_user_data_dir</primary></indexterm><programlisting>const <link linkend="char">char</link> * rb_user_data_dir (void);</programlisting>
117
This will create the rhythmbox user data directory, using the XDG Base
118
Directory specification. If none of the XDG environment variables are
119
set, this will be ~/.local/share/rhythmbox.</para>
121
</para><variablelist role="params">
122
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> string holding the path to the rhythmbox user data directory, or
123
NULL if the directory does not exist and cannot be created.
124
</simpara></listitem></varlistentry>
125
</variablelist></refsect2>
126
<refsect2 id="rb-user-cache-dir" role="function">
127
<title>rb_user_cache_dir ()</title>
128
<indexterm zone="rb-user-cache-dir"><primary sortas="rb_user_cache_dir">rb_user_cache_dir</primary></indexterm><programlisting>const <link linkend="char">char</link> * rb_user_cache_dir (void);</programlisting>
130
This will create the rhythmbox user cache directory, using the XDG
131
Base Directory specification. If none of the XDG environment
132
variables are set, this will be ~/.cache/rhythmbox.</para>
134
</para><variablelist role="params">
135
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> string holding the path to the rhythmbox user cache directory, or
136
NULL if the directory does not exist and could not be created.
137
</simpara></listitem></varlistentry>
138
</variablelist></refsect2>
139
<refsect2 id="rb-music-dir" role="function">
140
<title>rb_music_dir ()</title>
141
<indexterm zone="rb-music-dir"><primary sortas="rb_music_dir">rb_music_dir</primary></indexterm><programlisting>const <link linkend="char">char</link> * rb_music_dir (void);</programlisting>
143
Returns the default directory for the user's music library.
144
This will usually be the 'Music' directory under the home directory.</para>
146
</para><variablelist role="params">
147
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> user's music directory. must not be freed.
148
</simpara></listitem></varlistentry>
149
</variablelist></refsect2>
150
<refsect2 id="rb-find-user-data-file" role="function">
151
<title>rb_find_user_data_file ()</title>
152
<indexterm zone="rb-find-user-data-file"><primary sortas="rb_find_user_data_file">rb_find_user_data_file</primary></indexterm><programlisting><link linkend="char">char</link> * rb_find_user_data_file (const <link linkend="char">char</link> *name,
153
<link linkend="GError">GError</link> **error);</programlisting>
155
Determines the full path to use for user-specific files, such as rhythmdb.xml.
156
This first checks in the user data directory (see <parameter>rb_user_data_dir</parameter>).
157
If the file does not exist in the user data directory, it then checks the
158
old .gnome2 directory, moving the file to the user data directory if found there.
159
If an error occurs while moving the file, this will be reported through <parameter>error</parameter>
160
and the .gnome2 path will be returned.</para>
162
</para><variablelist role="params">
163
<varlistentry><term><parameter>name</parameter> :</term>
164
<listitem><simpara> name of file to find
165
</simpara></listitem></varlistentry>
166
<varlistentry><term><parameter>error</parameter> :</term>
167
<listitem><simpara> returns error information
168
</simpara></listitem></varlistentry>
169
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> allocated string containing the location of the file to use, even if
171
</simpara></listitem></varlistentry>
172
</variablelist></refsect2>
173
<refsect2 id="rb-find-user-cache-file" role="function">
174
<title>rb_find_user_cache_file ()</title>
175
<indexterm zone="rb-find-user-cache-file"><primary sortas="rb_find_user_cache_file">rb_find_user_cache_file</primary></indexterm><programlisting><link linkend="char">char</link> * rb_find_user_cache_file (const <link linkend="char">char</link> *name,
176
<link linkend="GError">GError</link> **error);</programlisting>
178
Determines the full path to use for user-specific cached files.
179
This first checks in the user cache directory (see <parameter>rb_user_cache_dir</parameter>).
180
If the file does not exist in the user cache directory, it then checks the
181
old .gnome2 directory, moving the file to the user cache directory if found there.
182
If an error occurs while moving the file, this will be reported through <parameter>error</parameter>
183
and the .gnome2 path will be returned.</para>
185
</para><variablelist role="params">
186
<varlistentry><term><parameter>name</parameter> :</term>
187
<listitem><simpara> name of file to find
188
</simpara></listitem></varlistentry>
189
<varlistentry><term><parameter>error</parameter> :</term>
190
<listitem><simpara> returns error information
191
</simpara></listitem></varlistentry>
192
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> allocated string containing the location of the file to use, even if
194
</simpara></listitem></varlistentry>
195
</variablelist></refsect2>
196
<refsect2 id="rb-file-helpers-init" role="function">
197
<title>rb_file_helpers_init ()</title>
198
<indexterm zone="rb-file-helpers-init"><primary sortas="rb_file_helpers_init">rb_file_helpers_init</primary></indexterm><programlisting><link linkend="void">void</link> rb_file_helpers_init (<link linkend="gboolean">gboolean</link> uninstalled);</programlisting>
200
Sets up file search paths for <parameter>rb_file</parameter>. Must be called on startup.</para>
202
</para><variablelist role="params">
203
<varlistentry><term><parameter>uninstalled</parameter> :</term>
204
<listitem><simpara> if <link linkend="TRUE--CAPS"><literal>TRUE</literal></link>, search in source and build directories
205
as well as installed locations
206
</simpara></listitem></varlistentry>
207
</variablelist></refsect2>
208
<refsect2 id="rb-file-helpers-shutdown" role="function">
209
<title>rb_file_helpers_shutdown ()</title>
210
<indexterm zone="rb-file-helpers-shutdown"><primary sortas="rb_file_helpers_shutdown">rb_file_helpers_shutdown</primary></indexterm><programlisting><link linkend="void">void</link> rb_file_helpers_shutdown (void);</programlisting>
212
Frees various data allocated by file helper functions.
213
Should be called on shutdown.</para>
216
<refsect2 id="rb-uri-resolve-symlink" role="function">
217
<title>rb_uri_resolve_symlink ()</title>
218
<indexterm zone="rb-uri-resolve-symlink"><primary sortas="rb_uri_resolve_symlink">rb_uri_resolve_symlink</primary></indexterm><programlisting><link linkend="char">char</link> * rb_uri_resolve_symlink (const <link linkend="char">char</link> *uri,
219
<link linkend="GError">GError</link> **error);</programlisting>
221
Attempts to resolve symlinks in <parameter>uri</parameter> and return a canonical URI for the file
222
it identifies.</para>
224
</para><variablelist role="params">
225
<varlistentry><term><parameter>uri</parameter> :</term>
226
<listitem><simpara> the URI to process
227
</simpara></listitem></varlistentry>
228
<varlistentry><term><parameter>error</parameter> :</term>
229
<listitem><simpara> returns error information
230
</simpara></listitem></varlistentry>
231
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> resolved URI, or NULL on error
232
</simpara></listitem></varlistentry>
233
</variablelist></refsect2>
234
<refsect2 id="rb-uri-is-directory" role="function">
235
<title>rb_uri_is_directory ()</title>
236
<indexterm zone="rb-uri-is-directory"><primary sortas="rb_uri_is_directory">rb_uri_is_directory</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_uri_is_directory (const <link linkend="char">char</link> *uri);</programlisting>
238
Checks if <parameter>uri</parameter> identifies a directory.</para>
240
</para><variablelist role="params">
241
<varlistentry><term><parameter>uri</parameter> :</term>
242
<listitem><simpara> the URI to check
243
</simpara></listitem></varlistentry>
244
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>uri</parameter> is a directory
245
</simpara></listitem></varlistentry>
246
</variablelist></refsect2>
247
<refsect2 id="rb-uri-exists" role="function">
248
<title>rb_uri_exists ()</title>
249
<indexterm zone="rb-uri-exists"><primary sortas="rb_uri_exists">rb_uri_exists</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_uri_exists (const <link linkend="char">char</link> *uri);</programlisting>
251
Checks if a URI identifies a resource that exists</para>
253
</para><variablelist role="params">
254
<varlistentry><term><parameter>uri</parameter> :</term>
255
<listitem><simpara> a URI to check
256
</simpara></listitem></varlistentry>
257
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>uri</parameter> exists
258
</simpara></listitem></varlistentry>
259
</variablelist></refsect2>
260
<refsect2 id="rb-uri-is-readable" role="function">
261
<title>rb_uri_is_readable ()</title>
262
<indexterm zone="rb-uri-is-readable"><primary sortas="rb_uri_is_readable">rb_uri_is_readable</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_uri_is_readable (const <link linkend="char">char</link> *uri);</programlisting>
264
Checks if the user can read the resource identified by <parameter>uri</parameter></para>
266
</para><variablelist role="params">
267
<varlistentry><term><parameter>uri</parameter> :</term>
268
<listitem><simpara> a URI to check
269
</simpara></listitem></varlistentry>
270
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>uri</parameter> is readable
271
</simpara></listitem></varlistentry>
272
</variablelist></refsect2>
273
<refsect2 id="rb-uri-is-writable" role="function">
274
<title>rb_uri_is_writable ()</title>
275
<indexterm zone="rb-uri-is-writable"><primary sortas="rb_uri_is_writable">rb_uri_is_writable</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_uri_is_writable (const <link linkend="char">char</link> *uri);</programlisting>
277
Checks if the user can write to the resource identified by <parameter>uri</parameter></para>
279
</para><variablelist role="params">
280
<varlistentry><term><parameter>uri</parameter> :</term>
281
<listitem><simpara> a URI to check
282
</simpara></listitem></varlistentry>
283
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>uri</parameter> is writable
284
</simpara></listitem></varlistentry>
285
</variablelist></refsect2>
286
<refsect2 id="rb-uri-is-local" role="function">
287
<title>rb_uri_is_local ()</title>
288
<indexterm zone="rb-uri-is-local"><primary sortas="rb_uri_is_local">rb_uri_is_local</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_uri_is_local (const <link linkend="char">char</link> *uri);</programlisting>
290
Checks if <parameter>uri</parameter> identifies a local resource. Currently this just
291
checks that it uses the 'file' URI scheme.</para>
293
</para><variablelist role="params">
294
<varlistentry><term><parameter>uri</parameter> :</term>
295
<listitem><simpara> a URI to check
296
</simpara></listitem></varlistentry>
297
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>uri</parameter> is local
298
</simpara></listitem></varlistentry>
299
</variablelist></refsect2>
300
<refsect2 id="rb-uri-is-hidden" role="function">
301
<title>rb_uri_is_hidden ()</title>
302
<indexterm zone="rb-uri-is-hidden"><primary sortas="rb_uri_is_hidden">rb_uri_is_hidden</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_uri_is_hidden (const <link linkend="char">char</link> *uri);</programlisting>
304
Checks if <parameter>uri</parameter> is hidden, according to the Unix filename convention.
305
If the filename component of <parameter>uri</parameter> begins with a dot, the file is considered
308
</para><variablelist role="params">
309
<varlistentry><term><parameter>uri</parameter> :</term>
310
<listitem><simpara> a URI to check
311
</simpara></listitem></varlistentry>
312
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>uri</parameter> is hidden
313
</simpara></listitem></varlistentry>
314
</variablelist></refsect2>
315
<refsect2 id="rb-uri-could-be-podcast" role="function">
316
<title>rb_uri_could_be_podcast ()</title>
317
<indexterm zone="rb-uri-could-be-podcast"><primary sortas="rb_uri_could_be_podcast">rb_uri_could_be_podcast</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_uri_could_be_podcast (const <link linkend="char">char</link> *uri,
318
<link linkend="gboolean">gboolean</link> *is_opml);</programlisting>
320
Checks if <parameter>uri</parameter> identifies a resource that is probably a podcast
321
(RSS or Atom feed). This does not perform any IO, it just guesses
322
based on the URI itself.</para>
324
</para><variablelist role="params">
325
<varlistentry><term><parameter>uri</parameter> :</term>
326
<listitem><simpara> a URI to check
327
</simpara></listitem></varlistentry>
328
<varlistentry><term><parameter>is_opml</parameter> :</term>
329
<listitem><simpara> returns whether the URI identifies an OPML document
330
</simpara></listitem></varlistentry>
331
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if <parameter>uri</parameter> may be a podcast
332
</simpara></listitem></varlistentry>
333
</variablelist></refsect2>
334
<refsect2 id="rb-uri-make-hidden" role="function">
335
<title>rb_uri_make_hidden ()</title>
336
<indexterm zone="rb-uri-make-hidden"><primary sortas="rb_uri_make_hidden">rb_uri_make_hidden</primary></indexterm><programlisting><link linkend="char">char</link> * rb_uri_make_hidden (const <link linkend="char">char</link> *uri);</programlisting>
338
Constructs a URI that is similar to <parameter>uri</parameter> but which identifies
339
a hidden file. This can be used for temporary files that should not
340
be visible to the user while they are in use.</para>
342
</para><variablelist role="params">
343
<varlistentry><term><parameter>uri</parameter> :</term>
344
<listitem><simpara> a URI to construct a hidden version of
345
</simpara></listitem></varlistentry>
346
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> hidden URI, must be freed by the caller.
347
</simpara></listitem></varlistentry>
348
</variablelist></refsect2>
349
<refsect2 id="rb-uri-handle-recursively" role="function">
350
<title>rb_uri_handle_recursively ()</title>
351
<indexterm zone="rb-uri-handle-recursively"><primary sortas="rb_uri_handle_recursively">rb_uri_handle_recursively</primary></indexterm><programlisting><link linkend="void">void</link> rb_uri_handle_recursively (const <link linkend="char">char</link> *uri,
352
<link linkend="GCancellable">GCancellable</link> *cancel,
353
<link linkend="RBUriRecurseFunc">RBUriRecurseFunc</link> func,
354
<link linkend="gpointer">gpointer</link> user_data);</programlisting>
356
Calls <parameter>func</parameter> for each file found under the directory identified by <parameter>uri</parameter>.
357
If <parameter>uri</parameter> identifies a file, calls <parameter>func</parameter> for that instead.</para>
359
</para><variablelist role="params">
360
<varlistentry><term><parameter>uri</parameter> :</term>
361
<listitem><simpara> URI to visit
362
</simpara></listitem></varlistentry>
363
<varlistentry><term><parameter>cancel</parameter> :</term>
364
<listitem><simpara> an optional <link linkend="GCancellable"><type>GCancellable</type></link> to allow cancellation
365
</simpara></listitem></varlistentry>
366
<varlistentry><term><parameter>func</parameter> :</term>
367
<listitem><simpara> Callback function
368
</simpara></listitem></varlistentry>
369
<varlistentry><term><parameter>user_data</parameter> :</term>
370
<listitem><simpara> Data for callback function
371
</simpara></listitem></varlistentry>
372
</variablelist></refsect2>
373
<refsect2 id="rb-uri-handle-recursively-async" role="function">
374
<title>rb_uri_handle_recursively_async ()</title>
375
<indexterm zone="rb-uri-handle-recursively-async"><primary sortas="rb_uri_handle_recursively_async">rb_uri_handle_recursively_async</primary></indexterm><programlisting><link linkend="void">void</link> rb_uri_handle_recursively_async (const <link linkend="char">char</link> *uri,
376
<link linkend="GCancellable">GCancellable</link> *cancel,
377
<link linkend="RBUriRecurseFunc">RBUriRecurseFunc</link> func,
378
<link linkend="gpointer">gpointer</link> user_data,
379
<link linkend="GDestroyNotify">GDestroyNotify</link> data_destroy);</programlisting>
381
Calls <parameter>func</parameter> for each file found under the directory identified
382
by <parameter>uri</parameter>, or if <parameter>uri</parameter> identifies a file, calls it once
386
Directory recursion happens on a separate thread, but the callbacks
387
are called on the main thread.
390
If non-NULL, <parameter>destroy_data</parameter> will be called once all files have been
391
processed, or when the operation is cancelled.</para>
393
</para><variablelist role="params">
394
<varlistentry><term><parameter>uri</parameter> :</term>
395
<listitem><simpara> the URI to visit
396
</simpara></listitem></varlistentry>
397
<varlistentry><term><parameter>cancel</parameter> :</term>
398
<listitem><simpara> a <link linkend="GCancellable"><type>GCancellable</type></link> to allow cancellation
399
</simpara></listitem></varlistentry>
400
<varlistentry><term><parameter>func</parameter> :</term>
401
<listitem><simpara> callback function
402
</simpara></listitem></varlistentry>
403
<varlistentry><term><parameter>user_data</parameter> :</term>
404
<listitem><simpara> data to pass to callback
405
</simpara></listitem></varlistentry>
406
<varlistentry><term><parameter>data_destroy</parameter> :</term>
407
<listitem><simpara> function to call to free <parameter>user_data</parameter>
408
</simpara></listitem></varlistentry>
409
</variablelist></refsect2>
410
<refsect2 id="rb-uri-mkstemp" role="function">
411
<title>rb_uri_mkstemp ()</title>
412
<indexterm zone="rb-uri-mkstemp"><primary sortas="rb_uri_mkstemp">rb_uri_mkstemp</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_uri_mkstemp (const <link linkend="char">char</link> *prefix,
413
<link linkend="char">char</link> **uri_ret,
414
<link linkend="GOutputStream">GOutputStream</link> **stream,
415
<link linkend="GError">GError</link> **error);</programlisting>
417
Creates a temporary file whose URI begins with <parameter>prefix</parameter>, returning
418
the file URI and an output stream for writing to it.</para>
420
</para><variablelist role="params">
421
<varlistentry><term><parameter>prefix</parameter> :</term>
422
<listitem><simpara> URI prefix
423
</simpara></listitem></varlistentry>
424
<varlistentry><term><parameter>uri_ret</parameter> :</term>
425
<listitem><simpara> returns the temporary file URI
426
</simpara></listitem></varlistentry>
427
<varlistentry><term><parameter>stream</parameter> :</term>
428
<listitem><simpara> returns a <parameter>GOutputStream</parameter> for the temporary file
429
</simpara></listitem></varlistentry>
430
<varlistentry><term><parameter>error</parameter> :</term>
431
<listitem><simpara> returns error information
432
</simpara></listitem></varlistentry>
433
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if successful
434
</simpara></listitem></varlistentry>
435
</variablelist></refsect2>
436
<refsect2 id="rb-canonicalise-uri" role="function">
437
<title>rb_canonicalise_uri ()</title>
438
<indexterm zone="rb-canonicalise-uri"><primary sortas="rb_canonicalise_uri">rb_canonicalise_uri</primary></indexterm><programlisting><link linkend="char">char</link> * rb_canonicalise_uri (const <link linkend="char">char</link> *uri);</programlisting>
440
Converts <parameter>uri</parameter> to canonical URI form, ensuring it doesn't contain
441
any redundant directory fragments or unnecessarily escaped characters.
442
All URIs passed to <link linkend="RhythmDB"><type>RhythmDB</type></link> functions should be canonicalised.</para>
444
</para><variablelist role="params">
445
<varlistentry><term><parameter>uri</parameter> :</term>
446
<listitem><simpara> URI to canonicalise
447
</simpara></listitem></varlistentry>
448
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> canonical URI, must be freed by caller
449
</simpara></listitem></varlistentry>
450
</variablelist></refsect2>
451
<refsect2 id="rb-uri-append-path" role="function">
452
<title>rb_uri_append_path ()</title>
453
<indexterm zone="rb-uri-append-path"><primary sortas="rb_uri_append_path">rb_uri_append_path</primary></indexterm><programlisting><link linkend="char">char</link>* rb_uri_append_path (const <link linkend="char">char</link> *uri,
454
const <link linkend="char">char</link> *path);</programlisting>
456
Creates a new URI consisting of <parameter>path</parameter> appended to <parameter>uri</parameter>.</para>
458
</para><variablelist role="params">
459
<varlistentry><term><parameter>uri</parameter> :</term>
460
<listitem><simpara> the URI to append to
461
</simpara></listitem></varlistentry>
462
<varlistentry><term><parameter>path</parameter> :</term>
463
<listitem><simpara> the path fragment to append
464
</simpara></listitem></varlistentry>
465
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> new URI, must be freed by caller
466
</simpara></listitem></varlistentry>
467
</variablelist></refsect2>
468
<refsect2 id="rb-uri-append-uri" role="function">
469
<title>rb_uri_append_uri ()</title>
470
<indexterm zone="rb-uri-append-uri"><primary sortas="rb_uri_append_uri">rb_uri_append_uri</primary></indexterm><programlisting><link linkend="char">char</link>* rb_uri_append_uri (const <link linkend="char">char</link> *uri,
471
const <link linkend="char">char</link> *fragment);</programlisting>
473
Creates a new URI consisting of <parameter>fragment</parameter> appended to <parameter>uri</parameter>.
474
Generally isn't a good idea.</para>
476
</para><variablelist role="params">
477
<varlistentry><term><parameter>uri</parameter> :</term>
478
<listitem><simpara> the URI to append to
479
</simpara></listitem></varlistentry>
480
<varlistentry><term><parameter>fragment</parameter> :</term>
481
<listitem><simpara> the URI fragment to append
482
</simpara></listitem></varlistentry>
483
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> new URI, must be freed by caller
484
</simpara></listitem></varlistentry>
485
</variablelist></refsect2>
486
<refsect2 id="rb-uri-get-dir-name" role="function">
487
<title>rb_uri_get_dir_name ()</title>
488
<indexterm zone="rb-uri-get-dir-name"><primary sortas="rb_uri_get_dir_name">rb_uri_get_dir_name</primary></indexterm><programlisting><link linkend="char">char</link> * rb_uri_get_dir_name (const <link linkend="char">char</link> *uri);</programlisting>
490
Returns the directory component of <parameter>uri</parameter>, that is, everything up
491
to the start of the filename.</para>
493
</para><variablelist role="params">
494
<varlistentry><term><parameter>uri</parameter> :</term>
495
<listitem><simpara> a URI
496
</simpara></listitem></varlistentry>
497
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> new URI for parent of <parameter>uri</parameter>, must be freed by caller.
498
</simpara></listitem></varlistentry>
499
</variablelist></refsect2>
500
<refsect2 id="rb-uri-get-short-path-name" role="function">
501
<title>rb_uri_get_short_path_name ()</title>
502
<indexterm zone="rb-uri-get-short-path-name"><primary sortas="rb_uri_get_short_path_name">rb_uri_get_short_path_name</primary></indexterm><programlisting><link linkend="char">char</link> * rb_uri_get_short_path_name (const <link linkend="char">char</link> *uri);</programlisting>
504
Returns the filename component of <parameter>uri</parameter>, that is, everything after the
505
final slash and before the start of the query string or fragment.</para>
507
</para><variablelist role="params">
508
<varlistentry><term><parameter>uri</parameter> :</term>
509
<listitem><simpara> a URI
510
</simpara></listitem></varlistentry>
511
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> filename component of <parameter>uri</parameter>, must be freed by caller
512
</simpara></listitem></varlistentry>
513
</variablelist></refsect2>
514
<refsect2 id="rb-check-dir-has-space" role="function">
515
<title>rb_check_dir_has_space ()</title>
516
<indexterm zone="rb-check-dir-has-space"><primary sortas="rb_check_dir_has_space">rb_check_dir_has_space</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_check_dir_has_space (<link linkend="GFile">GFile</link> *dir,
517
<link linkend="guint64">guint64</link> bytes_needed);</programlisting>
519
Checks that the filesystem holding <parameter>file</parameter> has at least <parameter>bytes_needed</parameter>
520
bytes available.</para>
522
</para><variablelist role="params">
523
<varlistentry><term><parameter>dir</parameter> :</term>
524
<listitem><simpara> a <link linkend="GFile"><type>GFile</type></link> to check
525
</simpara></listitem></varlistentry>
526
<varlistentry><term><parameter>bytes_needed</parameter> :</term>
527
<listitem><simpara> number of bytes to check for
528
</simpara></listitem></varlistentry>
529
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if enough space is available.
530
</simpara></listitem></varlistentry>
531
</variablelist></refsect2>
532
<refsect2 id="rb-check-dir-has-space-uri" role="function">
533
<title>rb_check_dir_has_space_uri ()</title>
534
<indexterm zone="rb-check-dir-has-space-uri"><primary sortas="rb_check_dir_has_space_uri">rb_check_dir_has_space_uri</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_check_dir_has_space_uri (const <link linkend="char">char</link> *uri,
535
<link linkend="guint64">guint64</link> bytes_needed);</programlisting>
537
Checks that the filesystem holding <parameter>uri</parameter> has at least <parameter>bytes_needed</parameter>
538
bytes available.</para>
540
</para><variablelist role="params">
541
<varlistentry><term><parameter>uri</parameter> :</term>
542
<listitem><simpara> a URI to check
543
</simpara></listitem></varlistentry>
544
<varlistentry><term><parameter>bytes_needed</parameter> :</term>
545
<listitem><simpara> number of bytes to check for
546
</simpara></listitem></varlistentry>
547
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if enough space is available.
548
</simpara></listitem></varlistentry>
549
</variablelist></refsect2>
550
<refsect2 id="rb-uri-get-mount-point" role="function">
551
<title>rb_uri_get_mount_point ()</title>
552
<indexterm zone="rb-uri-get-mount-point"><primary sortas="rb_uri_get_mount_point">rb_uri_get_mount_point</primary></indexterm><programlisting><link linkend="char">char</link> * rb_uri_get_mount_point (const <link linkend="char">char</link> *uri);</programlisting>
554
Returns the mount point of the filesystem holding <parameter>uri</parameter>.
555
If <parameter>uri</parameter> is on a normal filesystem mount (such as /, /home,
556
/var, etc.) this will be NULL.</para>
558
</para><variablelist role="params">
559
<varlistentry><term><parameter>uri</parameter> :</term>
560
<listitem><simpara> a URI
561
</simpara></listitem></varlistentry>
562
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> filesystem mount point (must be freed by caller)
564
</simpara></listitem></varlistentry>
565
</variablelist></refsect2>
566
<refsect2 id="rb-uri-create-parent-dirs" role="function">
567
<title>rb_uri_create_parent_dirs ()</title>
568
<indexterm zone="rb-uri-create-parent-dirs"><primary sortas="rb_uri_create_parent_dirs">rb_uri_create_parent_dirs</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> rb_uri_create_parent_dirs (const <link linkend="char">char</link> *uri,
569
<link linkend="GError">GError</link> **error);</programlisting>
571
Ensures that all parent directories of <parameter>uri</parameter> exist so that
572
<parameter>uri</parameter> itself can be created directly.</para>
574
</para><variablelist role="params">
575
<varlistentry><term><parameter>uri</parameter> :</term>
576
<listitem><simpara> a URI for which to create parent directories
577
</simpara></listitem></varlistentry>
578
<varlistentry><term><parameter>error</parameter> :</term>
579
<listitem><simpara> returns error information
580
</simpara></listitem></varlistentry>
581
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="TRUE--CAPS"><literal>TRUE</literal></link> if successful
582
</simpara></listitem></varlistentry>
583
</variablelist></refsect2>
584
<refsect2 id="rb-file-find-extant-parent" role="function">
585
<title>rb_file_find_extant_parent ()</title>
586
<indexterm zone="rb-file-find-extant-parent"><primary sortas="rb_file_find_extant_parent">rb_file_find_extant_parent</primary></indexterm><programlisting><link linkend="GFile">GFile</link> * rb_file_find_extant_parent (<link linkend="GFile">GFile</link> *file);</programlisting>
588
Walks up the filesystem hierarchy to find a <link linkend="GFile"><type>GFile</type></link> representing
589
the nearest extant ancestor of the specified file, which may be
590
the file itself if it exists.</para>
592
</para><variablelist role="params">
593
<varlistentry><term><parameter>file</parameter> :</term>
594
<listitem><simpara> a <link linkend="GFile"><type>GFile</type></link> to find an extant ancestor of
595
</simpara></listitem></varlistentry>
596
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="GFile"><type>GFile</type></link> for the nearest extant ancestor
597
</simpara></listitem></varlistentry>
598
</variablelist></refsect2>
599
<refsect2 id="rb-uri-get-filesystem-type" role="function">
600
<title>rb_uri_get_filesystem_type ()</title>
601
<indexterm zone="rb-uri-get-filesystem-type"><primary sortas="rb_uri_get_filesystem_type">rb_uri_get_filesystem_type</primary></indexterm><programlisting><link linkend="char">char</link> * rb_uri_get_filesystem_type (const <link linkend="char">char</link> *uri);</programlisting>
603
Returns a string describing the type of the filesystem containing <parameter>uri</parameter>.</para>
605
</para><variablelist role="params">
606
<varlistentry><term><parameter>uri</parameter> :</term>
607
<listitem><simpara> URI to get filesystem type for
608
</simpara></listitem></varlistentry>
609
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> filesystem type string, must be freed by caller.
610
</simpara></listitem></varlistentry>
611
</variablelist></refsect2>
612
<refsect2 id="rb-sanitize-path-for-msdos-filesystem" role="function">
613
<title>rb_sanitize_path_for_msdos_filesystem ()</title>
614
<indexterm zone="rb-sanitize-path-for-msdos-filesystem"><primary sortas="rb_sanitize_path_for_msdos_filesystem">rb_sanitize_path_for_msdos_filesystem</primary></indexterm><programlisting><link linkend="void">void</link> rb_sanitize_path_for_msdos_filesystem
615
(<link linkend="char">char</link> *path);</programlisting>
617
Modifies <parameter>path</parameter> such that it represents a legal path for MS DOS
620
</para><variablelist role="params">
621
<varlistentry><term><parameter>path</parameter> :</term>
622
<listitem><simpara> a path to sanitize (modified in place)
623
</simpara></listitem></varlistentry>
624
</variablelist></refsect2>
625
<refsect2 id="rb-sanitize-uri-for-filesystem" role="function">
626
<title>rb_sanitize_uri_for_filesystem ()</title>
627
<indexterm zone="rb-sanitize-uri-for-filesystem"><primary sortas="rb_sanitize_uri_for_filesystem">rb_sanitize_uri_for_filesystem</primary></indexterm><programlisting><link linkend="char">char</link> * rb_sanitize_uri_for_filesystem (const <link linkend="char">char</link> *uri);</programlisting>
629
Removes characters from <parameter>uri</parameter> that are not allowed by the filesystem
630
on which it would be stored. At present, this only supports MS DOS
633
</para><variablelist role="params">
634
<varlistentry><term><parameter>uri</parameter> :</term>
635
<listitem><simpara> a URI to sanitize
636
</simpara></listitem></varlistentry>
637
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> sanitized copy of <parameter>uri</parameter>, must be freed by caller.
638
</simpara></listitem></varlistentry>
639
</variablelist></refsect2>
640
<refsect2 id="RBUriRecurseFunc" role="function">
641
<title>RBUriRecurseFunc ()</title>
642
<indexterm zone="RBUriRecurseFunc"><primary sortas="RBUriRecurseFunc">RBUriRecurseFunc</primary></indexterm><programlisting><link linkend="gboolean">gboolean</link> (*RBUriRecurseFunc) (<link linkend="GFile">GFile</link> *file,
643
<link linkend="gboolean">gboolean</link> dir,
644
<link linkend="gpointer">gpointer</link> data);</programlisting>
646
</para><variablelist role="params">
647
<varlistentry><term><parameter>file</parameter> :</term>
649
</simpara></listitem></varlistentry>
650
<varlistentry><term><parameter>dir</parameter> :</term>
652
</simpara></listitem></varlistentry>
653
<varlistentry><term><parameter>data</parameter> :</term>
655
</simpara></listitem></varlistentry>
656
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>
657
</simpara></listitem></varlistentry>
658
</variablelist></refsect2>
added
removed
doc/reference/xml/rb-file-helpers.xml
