# Directory Operations

## Name

Directory Operations -- reading the contents of directories

## Synopsis

    enum        GnomeVFSDirectoryVisitOptions;
    gboolean    (*GnomeVFSDirectoryVisitFunc)   (const gchar *rel_path,
                                                 GnomeVFSFileInfo *info,
                                                 gboolean recursing_will_loop,
                                                 gpointer 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 *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);
    GnomeVFSResult gnome_vfs_make_directory_for_uri
                                                (GnomeVFSURI *uri,
                                                 guint perm);
    GnomeVFSResult gnome_vfs_make_directory     (const gchar *text_uri,
                                                 guint perm);
    GnomeVFSResult gnome_vfs_remove_directory_from_uri
                                                (GnomeVFSURI *uri);
    GnomeVFSResult gnome_vfs_remove_directory   (const gchar *text_uri);

## Description

## Details

### enum GnomeVFSDirectoryVisitOptions

    typedef enum {
    	GNOME_VFS_DIRECTORY_VISIT_DEFAULT = 0,
    	GNOME_VFS_DIRECTORY_VISIT_SAMEFS = 1 << 0,
    	GNOME_VFS_DIRECTORY_VISIT_LOOPCHECK = 1 << 1
    } GnomeVFSDirectoryVisitOptions;

### GnomeVFSDirectoryVisitFunc ()

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

`rel_path` : |
`info` : |
`recursing_will_loop` : |
`data` : |
`recurse` : |
Returns : |

### 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` : | A 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` : | A 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 entry 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 *uri,
                                                 GnomeVFSFileInfoOptions info_options,
                                                 GnomeVFSDirectoryVisitOptions visit_options,
                                                 GnomeVFSDirectoryVisitFunc callback,
                                                 gpointer data);

Visit `uri`, retrieving information as specified by `info_options`.

`uri` : | URI to start from
`info_options` : | Options specifying what kind of file information must be retrieved
`visit_options` : | Options specifying the type of visit
`callback` : | Callback to be called for every visited file
`data` : | Data to be passed to `callback` at each iteration
Returns : |

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

`uri` : | URI to start from
`info_options` : | Options specifying what kind of file information must be retrieved
`visit_options` : | Options specifying the type of visit
`callback` : | Callback to be called for every visited file
`data` : | Data to be passed to `callback` at each iteration
Returns : | A result code 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`.

`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` : | options controlling e.g. loop prevention, and filesystem checks. Affects the way visiting is done.
`callback` : | function to call with the file info structs
`data` : | data to pass to `callback`.
Returns : | a GnomeVFSResult indication 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`.

`uri` : | 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` : | options controlling e.g. loop prevention, and filesystem checks. Affects the way visiting is done.
`callback` : | function to call with the file info structs
`data` : | data to pass to `callback`.
Returns : | a GnomeVFSResult indication 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` : | An address of a pointer to a list of GnomeVFSFileInfo
`text_uri` : | A text URI
`options` : | Options for loading the directory
Returns : | An integer representing the result of the operation.

### gnome_vfs_make_directory_for_uri ()

    GnomeVFSResult gnome_vfs_make_directory_for_uri
                                                (GnomeVFSURI *uri,
                                                 guint perm);

Create a directory at `uri`. Only succeeds if a file or directory does not already exist at `uri`.

`uri` : | URI of the directory to be created
`perm` : | Unix-style permissions for the newly created directory
Returns : | An integer representing the result of the operation

### gnome_vfs_make_directory ()

    GnomeVFSResult gnome_vfs_make_directory     (const gchar *text_uri,
                                                 guint perm);

Create `text_uri` as a directory.

`text_uri` : | URI of the directory to be created
`perm` : | Unix-style permissions for the newly created directory
Returns : | An integer representing the result of the operation

### gnome_vfs_remove_directory_from_uri ()

    GnomeVFSResult gnome_vfs_remove_directory_from_uri
                                                (GnomeVFSURI *uri);

Remove `uri`. `uri` must be an empty directory.

`uri` : | URI of the directory to be removed
Returns : | An integer representing the result of the operation

### gnome_vfs_remove_directory ()

    GnomeVFSResult gnome_vfs_remove_directory   (const gchar *text_uri);

Remove `text_uri`. `text_uri` must be an empty directory.

`text_uri` : | URI of the directory to be removed
Returns : | An integer representing the result of the operation