## 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.