Listing Directory Contents
3
GNOME-VFS-2.0 Library

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

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.