Listing Directory Contents

Listing Directory Contents — Listing the contents of directories.

Synopsis

typedef             MateVFSDirectoryHandle;
enum                MateVFSDirectoryVisitOptions;
gboolean            (*MateVFSDirectoryVisitFunc)        (const gchar *rel_path,
                                                         MateVFSFileInfo *info,
                                                         gboolean recursing_will_loop,
                                                         gpointer user_data,
                                                         gboolean *recurse);
MateVFSResult       mate_vfs_directory_open             (MateVFSDirectoryHandle **handle,
                                                         const gchar *text_uri,
                                                         MateVFSFileInfoOptions options);
MateVFSResult       mate_vfs_directory_open_from_uri    (MateVFSDirectoryHandle **handle,
                                                         MateVFSURI *uri,
                                                         MateVFSFileInfoOptions options);
MateVFSResult       mate_vfs_directory_read_next        (MateVFSDirectoryHandle *handle,
                                                         MateVFSFileInfo *file_info);
MateVFSResult       mate_vfs_directory_close            (MateVFSDirectoryHandle *handle);
MateVFSResult       mate_vfs_directory_visit            (const gchar *text_uri,
                                                         MateVFSFileInfoOptions info_options,
                                                         MateVFSDirectoryVisitOptions visit_options,
                                                         MateVFSDirectoryVisitFunc callback,
                                                         gpointer data);
MateVFSResult       mate_vfs_directory_visit_uri        (MateVFSURI *uri,
                                                         MateVFSFileInfoOptions info_options,
                                                         MateVFSDirectoryVisitOptions visit_options,
                                                         MateVFSDirectoryVisitFunc callback,
                                                         gpointer data);
MateVFSResult       mate_vfs_directory_visit_files      (const gchar *text_uri,
                                                         GList *file_list,
                                                         MateVFSFileInfoOptions info_options,
                                                         MateVFSDirectoryVisitOptions visit_options,
                                                         MateVFSDirectoryVisitFunc callback,
                                                         gpointer data);
MateVFSResult       mate_vfs_directory_visit_files_at_uri
                                                        (MateVFSURI *uri,
                                                         GList *file_list,
                                                         MateVFSFileInfoOptions info_options,
                                                         MateVFSDirectoryVisitOptions visit_options,
                                                         MateVFSDirectoryVisitFunc callback,
                                                         gpointer data);
MateVFSResult       mate_vfs_directory_list_load        (GList **list,
                                                         const gchar *text_uri,
                                                         MateVFSFileInfoOptions options);

Description

Details

MateVFSDirectoryHandle

typedef struct MateVFSDirectoryHandle MateVFSDirectoryHandle;


enum MateVFSDirectoryVisitOptions

typedef enum {
	MATE_VFS_DIRECTORY_VISIT_DEFAULT = 0,
	MATE_VFS_DIRECTORY_VISIT_SAMEFS = 1 << 0,
	MATE_VFS_DIRECTORY_VISIT_LOOPCHECK = 1 << 1,
	MATE_VFS_DIRECTORY_VISIT_IGNORE_RECURSE_ERROR = 1 << 2
} MateVFSDirectoryVisitOptions;

These options control the way in which directories are visited. They are passed to mate_vfs_directory_visit(), mate_vfs_directory_visit_uri() mate_vfs_directory_visit_files() and mate_vfs_directory_visit_files_at_uri().

MATE_VFS_DIRECTORY_VISIT_DEFAULT

Default options, i.e. call the specified MateVFSDirectoryVisitFunc for each file.

MATE_VFS_DIRECTORY_VISIT_SAMEFS

Visit only directories on the same file system as the parent

MATE_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 MateVFSDirectoryVisitFunc will be notified using its recursing_will_loop parameter. If this is not set, the MateVFSDirectoryVisitFunc's recursing_will_loop parameter will always be set to FALSE.

MATE_VFS_DIRECTORY_VISIT_IGNORE_RECURSE_ERROR


MateVFSDirectoryVisitFunc ()

gboolean            (*MateVFSDirectoryVisitFunc)        (const gchar *rel_path,
                                                         MateVFSFileInfo *info,
                                                         gboolean recursing_will_loop,
                                                         gpointer user_data,
                                                         gboolean *recurse);

This function is passed to mate_vfs_directory_visit(), mate_vfs_directory_visit_uri(), mate_vfs_directory_visit_files() and mate_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 MateVFSFileInfo 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 mate_vfs_directory_visit(), mate_vfs_directory_visit_uri(), mate_vfs_directory_visit_files() or mate_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 MateVFSDirectoryVisitFunc 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.

mate_vfs_directory_open ()

MateVFSResult       mate_vfs_directory_open             (MateVFSDirectoryHandle **handle,
                                                         const gchar *text_uri,
                                                         MateVFSFileInfoOptions options);

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

handle :

pointer to a pointer to a MateVFSDirectoryHandle object.

text_uri :

string representing the uri to open.

options :

options for reading file information.

Returns :

an integer representing the result of the operation.

mate_vfs_directory_open_from_uri ()

MateVFSResult       mate_vfs_directory_open_from_uri    (MateVFSDirectoryHandle **handle,
                                                         MateVFSURI *uri,
                                                         MateVFSFileInfoOptions options);

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

handle :

pointer to a pointer to a MateVFSDirectoryHandle object.

uri :

uri to open.

options :

options for reading file information.

Returns :

an integer representing the result of the operation.

mate_vfs_directory_read_next ()

MateVFSResult       mate_vfs_directory_read_next        (MateVFSDirectoryHandle *handle,
                                                         MateVFSFileInfo *file_info);

Read the next directory entry from handle.

handle :

a directory handle.

file_info :

pointer to a MateVFSFileInfo struct where the data about the directory at handle will be stored.

Returns :

an integer value representing the result of the operation.

mate_vfs_directory_close ()

MateVFSResult       mate_vfs_directory_close            (MateVFSDirectoryHandle *handle);

Close handle.

handle :

a directory handle.

Returns :

an integer representing the result of the operation.

mate_vfs_directory_visit ()

MateVFSResult       mate_vfs_directory_visit            (const gchar *text_uri,
                                                         MateVFSFileInfoOptions info_options,
                                                         MateVFSDirectoryVisitOptions visit_options,
                                                         MateVFSDirectoryVisitFunc callback,
                                                         gpointer data);

Visit text_uri, retrieving information as specified by info_options.

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

text_uri :

uri string representation of a directory to visit the files in.

info_options :

MateVFSFileInfoOptions specifying what kind of file information must be retrieved about the contents of the directory referenced by uri.

visit_options :

MateVFSDirectoryVisitOptions controlling e.g. loop prevention, and filesystem checks. These affect the way visiting is done.

callback :

MateVFSDirectoryVisitFunc callback to be called for every visited file.

data :

data to be passed to callback at each iteration.

Returns :

a MateVFSResult indicating the success of the operation.

mate_vfs_directory_visit_uri ()

MateVFSResult       mate_vfs_directory_visit_uri        (MateVFSURI *uri,
                                                         MateVFSFileInfoOptions info_options,
                                                         MateVFSDirectoryVisitOptions visit_options,
                                                         MateVFSDirectoryVisitFunc callback,
                                                         gpointer data);

Visit uri, retrieving information as specified by info_options.

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

uri :

MateVFSURI of a directory to visit the files in.

info_options :

MateVFSFileInfoOptions specifying what kind of file information must be retrieved about the contents of the directory referenced by uri.

visit_options :

MateVFSDirectoryVisitOptions controlling e.g. loop prevention, and filesystem checks. These affect the way visiting is done.

callback :

MateVFSDirectoryVisitFunc callback to be called for every visited file.

data :

data to be passed to callback at each iteration.

Returns :

a MateVFSResult indicating whether the operation succeeded.

mate_vfs_directory_visit_files ()

MateVFSResult       mate_vfs_directory_visit_files      (const gchar *text_uri,
                                                         GList *file_list,
                                                         MateVFSFileInfoOptions info_options,
                                                         MateVFSDirectoryVisitOptions visit_options,
                                                         MateVFSDirectoryVisitFunc 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, mate_vfs_directory_visit_uri() will be called for the directory.

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

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 :

MateVFSDirectoryVisitOptions controlling e.g. loop prevention, and filesystem checks. These affect the way visiting is done.

callback :

MateVFSDirectoryVisitFunc callback to call with the file info structs.

data :

data to pass to callback.

Returns :

a MateVFSResult indicating the success of the operation.

mate_vfs_directory_visit_files_at_uri ()

MateVFSResult       mate_vfs_directory_visit_files_at_uri
                                                        (MateVFSURI *uri,
                                                         GList *file_list,
                                                         MateVFSFileInfoOptions info_options,
                                                         MateVFSDirectoryVisitOptions visit_options,
                                                         MateVFSDirectoryVisitFunc callback,
                                                         gpointer data);

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

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

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

uri :

MateVFSURI of a directory to visit the files in.

file_list :

GList of char *s of file names in uri to visit.

info_options :

MateVFSFileInfoOptions specifying what kind of file information must be retrieved about the contents of the directory referenced by uri.

visit_options :

MateVFSDirectoryVisitOptions controlling e.g. loop prevention, and filesystem checks. These affect the way visiting is done.

callback :

MateVFSDirectoryVisitFunc callback to call with the file info structs.

data :

data to pass to callback.

Returns :

a MateVFSResult indicating the success of the operation.

mate_vfs_directory_list_load ()

MateVFSResult       mate_vfs_directory_list_load        (GList **list,
                                                         const gchar *text_uri,
                                                         MateVFSFileInfoOptions options);

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

list :

address of a pointer to a list of MateVFSFileInfo.

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.