1 /* GIO - GLib Input, Output and Streaming Library
3 * Copyright (C) 2006-2007 Red Hat, Inc.
5 * SPDX-License-Identifier: LGPL-2.1-or-later
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
17 * You should have received a copy of the GNU Lesser General
18 * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
20 * Author: Alexander Larsson <alexl@redhat.com>
26 #include "glib-private.h"
27 #include "glocalvfs.h"
28 #include "gresourcefile.h"
29 #include "giomodule-priv.h"
35 * @short_description: Virtual File System
38 * Entry point for using GIO functionality.
42 static GRWLock additional_schemes_lock;
44 typedef struct _GVfsPrivate {
45 GHashTable *additional_schemes;
46 char const **supported_schemes;
50 GVfsFileLookupFunc uri_func;
52 GDestroyNotify uri_destroy;
54 GVfsFileLookupFunc parse_name_func;
55 gpointer parse_name_data;
56 GDestroyNotify parse_name_destroy;
59 G_DEFINE_TYPE_WITH_PRIVATE (GVfs, g_vfs, G_TYPE_OBJECT)
62 g_vfs_dispose (GObject *object)
64 GVfs *vfs = G_VFS (object);
65 GVfsPrivate *priv = g_vfs_get_instance_private (vfs);
67 g_clear_pointer (&priv->additional_schemes, g_hash_table_destroy);
68 g_clear_pointer (&priv->supported_schemes, g_free);
70 G_OBJECT_CLASS (g_vfs_parent_class)->dispose (object);
74 g_vfs_class_init (GVfsClass *klass)
76 GObjectClass *object_class = G_OBJECT_CLASS (klass);
77 object_class->dispose = g_vfs_dispose;
81 resource_parse_name (GVfs *vfs,
82 const char *parse_name,
85 if (g_str_has_prefix (parse_name, "resource:"))
86 return _g_resource_file_new (parse_name);
92 resource_get_file_for_uri (GVfs *vfs,
96 return _g_resource_file_new (uri);
100 g_vfs_uri_lookup_func_closure_free (gpointer data)
102 GVfsURISchemeData *closure = data;
104 if (closure->uri_destroy)
105 closure->uri_destroy (closure->uri_data);
106 if (closure->parse_name_destroy)
107 closure->parse_name_destroy (closure->parse_name_data);
113 g_vfs_init (GVfs *vfs)
115 GVfsPrivate *priv = g_vfs_get_instance_private (vfs);
116 priv->additional_schemes =
117 g_hash_table_new_full (g_str_hash, g_str_equal,
118 g_free, g_vfs_uri_lookup_func_closure_free);
120 g_vfs_register_uri_scheme (vfs, "resource",
121 resource_get_file_for_uri, NULL, NULL,
122 resource_parse_name, NULL, NULL);
129 * Checks if the VFS is active.
131 * Returns: %TRUE if construction of the @vfs was successful
132 * and it is now active.
135 g_vfs_is_active (GVfs *vfs)
139 g_return_val_if_fail (G_IS_VFS (vfs), FALSE);
141 class = G_VFS_GET_CLASS (vfs);
143 return (* class->is_active) (vfs);
148 * g_vfs_get_file_for_path:
150 * @path: a string containing a VFS path.
152 * Gets a #GFile for @path.
154 * Returns: (transfer full): a #GFile.
155 * Free the returned object with g_object_unref().
158 g_vfs_get_file_for_path (GVfs *vfs,
163 g_return_val_if_fail (G_IS_VFS (vfs), NULL);
164 g_return_val_if_fail (path != NULL, NULL);
166 class = G_VFS_GET_CLASS (vfs);
168 return (* class->get_file_for_path) (vfs, path);
172 parse_name_internal (GVfs *vfs,
173 const char *parse_name)
175 GVfsPrivate *priv = g_vfs_get_instance_private (vfs);
177 GVfsURISchemeData *closure;
180 g_rw_lock_reader_lock (&additional_schemes_lock);
181 g_hash_table_iter_init (&iter, priv->additional_schemes);
183 while (g_hash_table_iter_next (&iter, NULL, (gpointer *) &closure))
185 ret = closure->parse_name_func (vfs, parse_name,
186 closure->parse_name_data);
192 g_rw_lock_reader_unlock (&additional_schemes_lock);
198 get_file_for_uri_internal (GVfs *vfs,
201 GVfsPrivate *priv = g_vfs_get_instance_private (vfs);
204 GVfsURISchemeData *closure;
206 scheme = g_uri_parse_scheme (uri);
210 g_rw_lock_reader_lock (&additional_schemes_lock);
211 closure = g_hash_table_lookup (priv->additional_schemes, scheme);
214 ret = closure->uri_func (vfs, uri, closure->uri_data);
216 g_rw_lock_reader_unlock (&additional_schemes_lock);
223 * g_vfs_get_file_for_uri:
225 * @uri: a string containing a URI
227 * Gets a #GFile for @uri.
229 * This operation never fails, but the returned object
230 * might not support any I/O operation if the URI
231 * is malformed or if the URI scheme is not supported.
233 * Returns: (transfer full): a #GFile.
234 * Free the returned object with g_object_unref().
237 g_vfs_get_file_for_uri (GVfs *vfs,
243 g_return_val_if_fail (G_IS_VFS (vfs), NULL);
244 g_return_val_if_fail (uri != NULL, NULL);
246 class = G_VFS_GET_CLASS (vfs);
248 ret = get_file_for_uri_internal (vfs, uri);
250 ret = (* class->get_file_for_uri) (vfs, uri);
252 g_assert (ret != NULL);
254 return g_steal_pointer (&ret);
258 * g_vfs_get_supported_uri_schemes:
261 * Gets a list of URI schemes supported by @vfs.
263 * Returns: (transfer none): a %NULL-terminated array of strings.
264 * The returned array belongs to GIO and must
265 * not be freed or modified.
267 const gchar * const *
268 g_vfs_get_supported_uri_schemes (GVfs *vfs)
272 g_return_val_if_fail (G_IS_VFS (vfs), NULL);
274 priv = g_vfs_get_instance_private (vfs);
276 if (!priv->supported_schemes)
279 const char * const *default_schemes;
280 const char *additional_scheme;
281 GPtrArray *supported_schemes;
284 class = G_VFS_GET_CLASS (vfs);
286 default_schemes = (* class->get_supported_uri_schemes) (vfs);
287 supported_schemes = g_ptr_array_new ();
289 for (; default_schemes && *default_schemes; default_schemes++)
290 g_ptr_array_add (supported_schemes, (gpointer) *default_schemes);
292 g_rw_lock_reader_lock (&additional_schemes_lock);
293 g_hash_table_iter_init (&iter, priv->additional_schemes);
295 while (g_hash_table_iter_next
296 (&iter, (gpointer *) &additional_scheme, NULL))
297 g_ptr_array_add (supported_schemes, (gpointer) additional_scheme);
299 g_rw_lock_reader_unlock (&additional_schemes_lock);
301 g_ptr_array_add (supported_schemes, NULL);
303 g_free (priv->supported_schemes);
304 priv->supported_schemes =
305 (char const **) g_ptr_array_free (supported_schemes, FALSE);
308 return priv->supported_schemes;
314 * @parse_name: a string to be parsed by the VFS module.
316 * This operation never fails, but the returned object might
317 * not support any I/O operations if the @parse_name cannot
318 * be parsed by the #GVfs module.
320 * Returns: (transfer full): a #GFile for the given @parse_name.
321 * Free the returned object with g_object_unref().
324 g_vfs_parse_name (GVfs *vfs,
325 const char *parse_name)
330 g_return_val_if_fail (G_IS_VFS (vfs), NULL);
331 g_return_val_if_fail (parse_name != NULL, NULL);
333 class = G_VFS_GET_CLASS (vfs);
335 ret = parse_name_internal (vfs, parse_name);
339 return (* class->parse_name) (vfs, parse_name);
342 static GVfs *vfs_default_singleton = NULL; /* (owned) (atomic) */
347 * Gets the default #GVfs for the system.
349 * Returns: (not nullable) (transfer none): a #GVfs, which will be the local
350 * file system #GVfs if no other implementation is available.
353 g_vfs_get_default (void)
355 if (GLIB_PRIVATE_CALL (g_check_setuid) ())
356 return g_vfs_get_local ();
358 if (g_once_init_enter (&vfs_default_singleton))
362 singleton = _g_io_module_get_default (G_VFS_EXTENSION_POINT_NAME,
364 (GIOModuleVerifyFunc) g_vfs_is_active);
366 g_once_init_leave (&vfs_default_singleton, singleton);
369 return vfs_default_singleton;
375 * Gets the local #GVfs for the system.
377 * Returns: (transfer none): a #GVfs.
380 g_vfs_get_local (void)
382 static gsize vfs = 0;
384 if (g_once_init_enter (&vfs))
385 g_once_init_leave (&vfs, (gsize)_g_local_vfs_new ());
391 * g_vfs_register_uri_scheme:
393 * @scheme: an URI scheme, e.g. "http"
394 * @uri_func: (scope notified) (nullable): a #GVfsFileLookupFunc
395 * @uri_data: (nullable): custom data passed to be passed to @uri_func, or %NULL
396 * @uri_destroy: (nullable): function to be called when unregistering the
397 * URI scheme, or when @vfs is disposed, to free the resources used
398 * by the URI lookup function
399 * @parse_name_func: (scope notified) (nullable): a #GVfsFileLookupFunc
400 * @parse_name_data: (nullable): custom data passed to be passed to
401 * @parse_name_func, or %NULL
402 * @parse_name_destroy: (nullable): function to be called when unregistering the
403 * URI scheme, or when @vfs is disposed, to free the resources used
404 * by the parse name lookup function
406 * Registers @uri_func and @parse_name_func as the #GFile URI and parse name
407 * lookup functions for URIs with a scheme matching @scheme.
408 * Note that @scheme is registered only within the running application, as
409 * opposed to desktop-wide as it happens with GVfs backends.
411 * When a #GFile is requested with an URI containing @scheme (e.g. through
412 * g_file_new_for_uri()), @uri_func will be called to allow a custom
413 * constructor. The implementation of @uri_func should not be blocking, and
414 * must not call g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme().
416 * When g_file_parse_name() is called with a parse name obtained from such file,
417 * @parse_name_func will be called to allow the #GFile to be created again. In
418 * that case, it's responsibility of @parse_name_func to make sure the parse
419 * name matches what the custom #GFile implementation returned when
420 * g_file_get_parse_name() was previously called. The implementation of
421 * @parse_name_func should not be blocking, and must not call
422 * g_vfs_register_uri_scheme() or g_vfs_unregister_uri_scheme().
424 * It's an error to call this function twice with the same scheme. To unregister
425 * a custom URI scheme, use g_vfs_unregister_uri_scheme().
427 * Returns: %TRUE if @scheme was successfully registered, or %FALSE if a handler
428 * for @scheme already exists.
433 g_vfs_register_uri_scheme (GVfs *vfs,
435 GVfsFileLookupFunc uri_func,
437 GDestroyNotify uri_destroy,
438 GVfsFileLookupFunc parse_name_func,
439 gpointer parse_name_data,
440 GDestroyNotify parse_name_destroy)
443 GVfsURISchemeData *closure;
445 g_return_val_if_fail (G_IS_VFS (vfs), FALSE);
446 g_return_val_if_fail (scheme != NULL, FALSE);
448 priv = g_vfs_get_instance_private (vfs);
450 g_rw_lock_reader_lock (&additional_schemes_lock);
451 closure = g_hash_table_lookup (priv->additional_schemes, scheme);
452 g_rw_lock_reader_unlock (&additional_schemes_lock);
457 closure = g_new0 (GVfsURISchemeData, 1);
458 closure->uri_func = uri_func;
459 closure->uri_data = uri_data;
460 closure->uri_destroy = uri_destroy;
461 closure->parse_name_func = parse_name_func;
462 closure->parse_name_data = parse_name_data;
463 closure->parse_name_destroy = parse_name_destroy;
465 g_rw_lock_writer_lock (&additional_schemes_lock);
466 g_hash_table_insert (priv->additional_schemes, g_strdup (scheme), closure);
467 g_rw_lock_writer_unlock (&additional_schemes_lock);
469 /* Invalidate supported schemes */
470 g_clear_pointer (&priv->supported_schemes, g_free);
476 * g_vfs_unregister_uri_scheme:
478 * @scheme: an URI scheme, e.g. "http"
480 * Unregisters the URI handler for @scheme previously registered with
481 * g_vfs_register_uri_scheme().
483 * Returns: %TRUE if @scheme was successfully unregistered, or %FALSE if a
484 * handler for @scheme does not exist.
489 g_vfs_unregister_uri_scheme (GVfs *vfs,
495 g_return_val_if_fail (G_IS_VFS (vfs), FALSE);
496 g_return_val_if_fail (scheme != NULL, FALSE);
498 priv = g_vfs_get_instance_private (vfs);
500 g_rw_lock_writer_lock (&additional_schemes_lock);
501 res = g_hash_table_remove (priv->additional_schemes, scheme);
502 g_rw_lock_writer_unlock (&additional_schemes_lock);
506 /* Invalidate supported schemes */
507 g_clear_pointer (&priv->supported_schemes, g_free);