Listing Directory Contents

Listing Directory Contents — Listing the contents of directories.

Synopsis




typedef             GnomeVFSDirectoryHandle;
enum                GnomeVFSDirectoryVisitOptions;
gboolean            (*GnomeVFSDirectoryVisitFunc)       (const gchar *rel_path,
                                                         GnomeVFSFileInfo *info,
                                                         gboolean recursing_will_loop,
                                                         gpointer user_data,
                                                         gboolean *recurse);
GnomeVFSResult      gnome_vfs_directory_open            (GnomeVFSDirectoryHandle **handle,
                                                         const gchar *text_uri,
                                                         GnomeVFSFileInfoOptions options);
GnomeVFSResult      gnome_vfs_directory_open_from_uri   (GnomeVFSDirectoryHandle **handle,
                                                         GnomeVFSURI *uri,
                                                         GnomeVFSFileInfoOptions options);
GnomeVFSResult      gnome_vfs_directory_read_next       (GnomeVFSDirectoryHandle *handle,
                                                         GnomeVFSFileInfo *file_info);
GnomeVFSResult      gnome_vfs_directory_close           (GnomeVFSDirectoryHandle *handle);
GnomeVFSResult      gnome_vfs_directory_visit           (const gchar *text_uri,
                                                         GnomeVFSFileInfoOptions info_options,
                                                         GnomeVFSDirectoryVisitOptions visit_options,
                                                         GnomeVFSDirectoryVisitFunc callback,
                                                         gpointer data);
GnomeVFSResult      gnome_vfs_directory_visit_uri       (GnomeVFSURI *uri,
                                                         GnomeVFSFileInfoOptions info_options,
                                                         GnomeVFSDirectoryVisitOptions visit_options,
                                                         GnomeVFSDirectoryVisitFunc callback,
                                                         gpointer data);
GnomeVFSResult      gnome_vfs_directory_visit_files     (const gchar *text_uri,
                                                         GList *file_list,
                                                         GnomeVFSFileInfoOptions info_options,
                                                         GnomeVFSDirectoryVisitOptions visit_options,
                                                         GnomeVFSDirectoryVisitFunc callback,
                                                         gpointer data);
GnomeVFSResult      gnome_vfs_directory_visit_files_at_uri
                                                        (GnomeVFSURI *uri,
                                                         GList *file_list,
                                                         GnomeVFSFileInfoOptions info_options,
                                                         GnomeVFSDirectoryVisitOptions visit_options,
                                                         GnomeVFSDirectoryVisitFunc callback,
                                                         gpointer data);
GnomeVFSResult      gnome_vfs_directory_list_load       (GList **list,
                                                         const gchar *text_uri,
                                                         GnomeVFSFileInfoOptions options);

Description

Details

GnomeVFSDirectoryHandle

typedef struct GnomeVFSDirectoryHandle GnomeVFSDirectoryHandle;

enum GnomeVFSDirectoryVisitOptions

typedef enum {
	GNOME_VFS_DIRECTORY_VISIT_DEFAULT = 0,
	GNOME_VFS_DIRECTORY_VISIT_SAMEFS = 1 << 0,
	GNOME_VFS_DIRECTORY_VISIT_LOOPCHECK = 1 << 1,
	GNOME_VFS_DIRECTORY_VISIT_IGNORE_RECURSE_ERROR = 1 << 2
} 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().

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

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.

Note

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.