8.4 Directory Operations

These functions create and remove directories (as usual, all return values are GnomeVFSResult ):

gnome_vfs_make_directory(const gchar * uri_string , guint permissions )

Creates a directory at uri_string with permissions permissions (see Section 8.3.1). Remember that you need to have execute permission for a directory to access any file inside.
gnome_vfs_make_directory_for_uri(GnomeVFSURI * uri , guint permissions )

Same as the preceding function, but for a URI structure at uri .
gnome_vfs_remove_directory(const gchar * uri_string )

Removes the directory at uri_string ; fails if the directory is not empty.
gnome_vfs_remove_directory_from_uri(GnomeVFSURI * uri )

Same as the preceding function, but for a URI structure at uri .

8.4.1 Directory Navigation

GnomeVFS directory functions are very similar to Unix counterparts. If you are familiar with opendir() , readdir() , and closedir() , you won't have any trouble with the GNOME API.

To access a directory, you need a special GnomeVFSDirectoryHandle descriptor. These functions operate on directory descriptors and return GnomeVFSResult :

gnome_vfs_directory_open(GnomeVFSDirectoryHandle ** handle_addr , const gchar * uri_string , GnomeVFSFileInfoOptions options )

Opens the directory at uri_string and writes the directory descriptor into * handle_addr . See Section 8.3.3 for options ; these apply to each item that you read from the directory.
gnome_vfs_directory_open_from_uri(GnomeVFSDirectoryHandle ** handle_addr , GnomeVFSURI * uri , GnomeVFSFileInfoOptions options )

Same as the preceding function, but uses the URI structure uri .
gnome_vfs_directory_read_next(GnomeVFSDirectoryHandle * handle , GnomeVFSFileInfo * info )

Reads the next item from handle into info .
gnome_vfs_directory_close(GnomeVFSDirectoryHandle * handle )

Closes the directory descriptor handle .

You might find it more convenient to operate on a directory's entire contents at once:

gnome_vfs_directory_list_load(GList ** list , const gchar * uri_string , GnomeVFSFileInfoOptions options )

Loads all entries in uri_string into a newly allocated list at * list . List nodes have GnomeVFSFileInfo structures that follow options .
gnome_vfs_file_info_list_free(GList * list )

Deallocates a list of GnomeVFSFileInfo structures. This function has no return value.
gnome_vfs_directory_visit(const gchar * uri_string , GnomeVFSFileInfoOptions info_options , GnomeVFSDirectoryVisitOptions visit_options , GnomeVFSDirectoryVisitFunc function , gpointer data )

Recursively traverses the directory at uri_string , running function on each item in the directory (see the discussion that follows for the type definition). Use info_options for extracting file information for function .

The visit_options parameter is a bitwise OR of any of these options:
- GNOME_VFS_DIRECTORY_VISIT_DEFAULT
- GNOME_VFS_DIRECTORY_VISIT_SAMEFS (does not leave the current file system)
- GNOME_VFS_DIRECTORY_VISIT_LOOPCHECK (avoids infinite loops )
gnome_vfs_directory_visit_uri(GnomeVFSURI * uri , GnomeVFSFileInfoOptions info_options , GnomeVFSDirectoryVisitOptions visit_options , GnomeVFSDirectoryVisitFunc function , gpointer data )

Same as the preceding function, but uses the URI structure uri .
gnome_vfs_directory_visit_files(const gchar * uri_string , GList * files , GnomeVFSDirectoryVisitOptions visit_options , GnomeVFSDirectoryVisitFunc function , gpointer data )

Like gnome_vfs_directory_visit() , but visits only the files in files (a list of gchar * relative pathnames).
gnome_vfs_directory_visit_files_at_uri(GnomeVFSURI * uri , GList * files , GnomeVFSDirectoryVisitOptions visit_options , GnomeVFSDirectoryVisitFunc function , gpointer data )

Same as the preceding function, but uses the URI structure uri .

Here is the GnomeVFSDirectoryVisitFunc type definition:

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

The preceding functions call a GnomeVFSDirectoryVisitFunc with rel_path set to the item path relative to the directory URI, and info filled with the directory entry information. If the item is a subdirectory, you can set *recurse to FALSE if you don't want to visit the subdirectory. If you activate loop detection, GnomeVFS initially sets *recurse to FALSE when it detects a possible loop.

To halt the directory traversal, have your visiting function return FALSE rather than TRUE .

There is one special utility for creating and finding GNOME-specific directories:

 gnome_vfs_find_directory(GnomeVFSURI *  near_uri  ,                          GnomeVFSFindDirectoryKind  type  ,                             GnomeVFSURI **  result  ,                             gboolean  create  ,                             gboolean  find  ,                             guint  permissions  )

This function searches near_uri 's volume for type :

GNOME_VFS_DIRECTORY_KIND_DESKTOP (GNOME desktop directory)
GNOME_VFS_DIRECTORY_KIND_TRASH (GNOME trash directory)

A successful result goes into * result . If search is TRUE , this function looks around if the location isn't obvious (this can take some time). If the directory does not exist and create is TRUE , this function creates the directory according to permissions .