Listing Directory Contents: GnomeVFS - Filesystem Abstraction library

Listing Directory Contents

Listing Directory Contents — Listing the contents of directories.

Types and Values

typedef	GnomeVFSDirectoryHandle
enum	GnomeVFSDirectoryVisitOptions

Description

Functions

GnomeVFSDirectoryVisitFunc ()

gboolean
(*GnomeVFSDirectoryVisitFunc) (const gchar *rel_path,
                               GnomeVFSFileInfo *info,
                               gboolean recursing_will_loop,
                               gpointer user_data,
                               gboolean *recurse);

This function is passed to gnome_vfs_directory_visit(), gnome_vfs_directory_visit_uri(), gnome_vfs_directory_visit_files() and gnome_vfs_directory_visit_files_at_uri(), and is called for each file in the specified directory.

When a recursive visit was requested for a particular directory, errors during the child visit will lead to a cancellation of the overall visit. Thus, you must ensure that the user has sufficient access rights to visit a directory before requesting a recursion.

Parameters

rel_path	A char * specifying the path of the currently visited file relative to the base directory for the visit.
info	The GnomeVFSFileInfo of the currently visited file.
recursing_will_loop	Whether setting *`recurse` to `TRUE` will cause a loop, i.e. whether this is a link pointing to a parent directory.
user_data	The user data passed to `gnome_vfs_directory_visit()`, `gnome_vfs_directory_visit_uri()`, `gnome_vfs_directory_visit_files()` or `gnome_vfs_directory_visit_files_at_uri()`.
recurse	A valid pointer to a gboolean, which points to `FALSE` by default and can be modified to point to `TRUE`, which indicates that the currently considered file should be visited recursively. The recursive visit will only be actually done if `info` refers to a directory, *`recurse` is `TRUE` and the return value of the GnomeVFSDirectoryVisitFunc is `TRUE`. *`recurse` should usually not be set to `TRUE` if `recursing_will_loop` is `TRUE`.

Returns

TRUE if visit should be continued, FALSE otherwise.

gnome_vfs_directory_open ()

GnomeVFSResult
gnome_vfs_directory_open (GnomeVFSDirectoryHandle **handle,
                          const gchar *text_uri,
                          GnomeVFSFileInfoOptions options);

Open directory text_uri for reading. On return, @*handle will point to a GnomeVFSDirectoryHandle object which can be used to read the directory entries one by one.

Parameters

handle	pointer to a pointer to a GnomeVFSDirectoryHandle object.
text_uri	string representing the uri to open.
options	options for reading file information.

Returns

an integer representing the result of the operation.

gnome_vfs_directory_open_from_uri ()

GnomeVFSResult
gnome_vfs_directory_open_from_uri (GnomeVFSDirectoryHandle **handle,
                                   GnomeVFSURI *uri,
                                   GnomeVFSFileInfoOptions options);

Open directory text_uri for reading. On return, @*handle will point to a GnomeVFSDirectoryHandle object which can be used to read the directory entries one by one.

Parameters

handle	pointer to a pointer to a GnomeVFSDirectoryHandle object.
uri	uri to open.
options	options for reading file information.

Returns

an integer representing the result of the operation.

gnome_vfs_directory_read_next ()

GnomeVFSResult
gnome_vfs_directory_read_next (GnomeVFSDirectoryHandle *handle,
                               GnomeVFSFileInfo *file_info);

Read the next directory entry from handle .

Parameters

handle	a directory handle.
file_info	pointer to a GnomeVFSFileInfo struct where the data about the directory at `handle` will be stored.

Returns

an integer value representing the result of the operation.

gnome_vfs_directory_close ()

GnomeVFSResult
gnome_vfs_directory_close (GnomeVFSDirectoryHandle *handle);

Close handle .

Parameters

handle

a directory handle.

Returns

an integer representing the result of the operation.

gnome_vfs_directory_visit ()

GnomeVFSResult
gnome_vfs_directory_visit (const gchar *text_uri,
                           GnomeVFSFileInfoOptions info_options,
                           GnomeVFSDirectoryVisitOptions visit_options,
                           GnomeVFSDirectoryVisitFunc callback,
                           gpointer data);

Visit text_uri , retrieving information as specified by info_options .

This function is identical to gnome_vfs_directory_visit_uri(), except that it takes a text URI instead of a GnomeVFSURI.

Parameters

text_uri	uri string representation of a directory to visit the files in.
info_options	GnomeVFSFileInfoOptions specifying what kind of file information must be retrieved about the contents of the directory referenced by `uri` .
visit_options	GnomeVFSDirectoryVisitOptions controlling e.g. loop prevention, and filesystem checks. These affect the way visiting is done.
callback	GnomeVFSDirectoryVisitFunc callback to be called for every visited file.
data	data to be passed to `callback` at each iteration.

Returns

a GnomeVFSResult indicating the success of the operation.

gnome_vfs_directory_visit_uri ()

GnomeVFSResult
gnome_vfs_directory_visit_uri (GnomeVFSURI *uri,
                               GnomeVFSFileInfoOptions info_options,
                               GnomeVFSDirectoryVisitOptions visit_options,
                               GnomeVFSDirectoryVisitFunc callback,
                               gpointer data);

Visit uri , retrieving information as specified by info_options .

This function is identical to gnome_vfs_directory_visit(), except that it takes a GnomeVFSURI instead of a text URI.

Parameters

uri	GnomeVFSURI of a directory to visit the files in.
info_options	GnomeVFSFileInfoOptions specifying what kind of file information must be retrieved about the contents of the directory referenced by `uri` .
visit_options	GnomeVFSDirectoryVisitOptions controlling e.g. loop prevention, and filesystem checks. These affect the way visiting is done.
callback	GnomeVFSDirectoryVisitFunc callback to be called for every visited file.
data	data to be passed to `callback` at each iteration.

Returns

a GnomeVFSResult indicating whether the operation succeeded.

gnome_vfs_directory_visit_files ()

GnomeVFSResult
gnome_vfs_directory_visit_files (const gchar *text_uri,
                                 GList *file_list,
                                 GnomeVFSFileInfoOptions info_options,
                                 GnomeVFSDirectoryVisitOptions visit_options,
                                 GnomeVFSDirectoryVisitFunc callback,
                                 gpointer data);

Fetches information about a list of files in a base uri uri .

If any of the files refers to a directory, and the callback requests recursion for the specified file, gnome_vfs_directory_visit_uri() will be called for the directory.

This function is identical to gnome_vfs_directory_visit_files_at_uri(), except that it takes a text URI instead of a GnomeVFSURI.

Parameters

text_uri	string representing the uri of a directory to visit the files in.
file_list	GList of char s of file names in `uri`* to visit.
info_options	bitmask controlling the type of information to fetch.
visit_options	GnomeVFSDirectoryVisitOptions controlling e.g. loop prevention, and filesystem checks. These affect the way visiting is done.
callback	GnomeVFSDirectoryVisitFunc callback to call with the file info structs.
data	data to pass to `callback` .

Returns

a GnomeVFSResult indicating the success of the operation.

gnome_vfs_directory_visit_files_at_uri ()

GnomeVFSResult
gnome_vfs_directory_visit_files_at_uri
                               (GnomeVFSURI *uri,
                                GList *file_list,
                                GnomeVFSFileInfoOptions info_options,
                                GnomeVFSDirectoryVisitOptions visit_options,
                                GnomeVFSDirectoryVisitFunc callback,
                                gpointer data);

Fetches information about a list of files in a base uri uri .

This function is identical to gnome_vfs_directory_visit_files_at_uri(), except that it takes a GnomeVFSURI instead of a text URI.

If any of the files refers to a directory, and the callback requests recursion for the specified file, gnome_vfs_directory_visit_uri() will be called for the directory.

Parameters

uri	GnomeVFSURI of a directory to visit the files in.
file_list	GList of char s of file names in `uri`* to visit.
info_options	GnomeVFSFileInfoOptions specifying what kind of file information must be retrieved about the contents of the directory referenced by `uri` .
visit_options	GnomeVFSDirectoryVisitOptions controlling e.g. loop prevention, and filesystem checks. These affect the way visiting is done.
callback	GnomeVFSDirectoryVisitFunc callback to call with the file info structs.
data	data to pass to `callback` .

Returns

a GnomeVFSResult indicating the success of the operation.

gnome_vfs_directory_list_load ()

GnomeVFSResult
gnome_vfs_directory_list_load (GList **list,
                               const gchar *text_uri,
                               GnomeVFSFileInfoOptions options);

Load a directory from text_uri with the specified options into a list.

Parameters

list	address of a pointer to a list of GnomeVFSFileInfo.
text_uri	a string representing the uri of the directory.
options	options for loading the directory.

Returns

an integer representing the result of the operation.

Types and Values

GnomeVFSDirectoryHandle

typedef struct GnomeVFSDirectoryHandle GnomeVFSDirectoryHandle;

enum GnomeVFSDirectoryVisitOptions

These options control the way in which directories are visited. They are passed to gnome_vfs_directory_visit(), gnome_vfs_directory_visit_uri() gnome_vfs_directory_visit_files() and gnome_vfs_directory_visit_files_at_uri().

Members

GNOME_VFS_DIRECTORY_VISIT_DEFAULT	Default options, i.e. call the specified GnomeVFSDirectoryVisitFunc for each file.
GNOME_VFS_DIRECTORY_VISIT_SAMEFS	Visit only directories on the same file system as the parent
GNOME_VFS_DIRECTORY_VISIT_LOOPCHECK	Loop prevention. If this is set, and a file is found to be a directory referencing a prefiously found directory inode (i.e. already used for one of it's parents), this is considered a recursion loop, and GnomeVFSDirectoryVisitFunc will be notified using its `recursing_will_loop` parameter. If this is not set, the GnomeVFSDirectoryVisitFunc's `recursing_will_loop` parameter will always be set to `FALSE`.
GNOME_VFS_DIRECTORY_VISIT_IGNORE_RECURSE_ERROR

gboolean	(*GnomeVFSDirectoryVisitFunc) ()
GnomeVFSResult	gnome_vfs_directory_open ()
GnomeVFSResult	gnome_vfs_directory_open_from_uri ()
GnomeVFSResult	gnome_vfs_directory_read_next ()
GnomeVFSResult	gnome_vfs_directory_close ()
GnomeVFSResult	gnome_vfs_directory_visit ()
GnomeVFSResult	gnome_vfs_directory_visit_uri ()
GnomeVFSResult	gnome_vfs_directory_visit_files ()
GnomeVFSResult	gnome_vfs_directory_visit_files_at_uri ()
GnomeVFSResult	gnome_vfs_directory_list_load ()