awn-vfs

## awn-vfs awn-vfs — VFS-related API wrappers and utility functions. |

## Synopsis

    #include <libawn/awn-vfs.h>

    typedef             AwnVfsMonitor;
    enum                AwnVfsMonitorEvent;
    enum                AwnVfsMonitorType;
    void                (*AwnVfsMonitorFunc)                (AwnVfsMonitor *monitor,
                                                             gchar *monitor_path,
                                                             gchar *event_path,
                                                             AwnVfsMonitorEvent event,
                                                             gpointer user_data);
    AwnVfsMonitor *     awn_vfs_monitor_add                 (gchar *path,
                                                             AwnVfsMonitorType monitor_type,
                                                             AwnVfsMonitorFunc callback,
                                                             gpointer user_data);
    void                awn_vfs_monitor_emit                (AwnVfsMonitor *monitor,
                                                             gchar *path,
                                                             AwnVfsMonitorEvent event);
    void                awn_vfs_monitor_remove              (AwnVfsMonitor *monitor);
    void                awn_vfs_init                        (void);
    GSList *            awn_vfs_get_pathlist_from_string    (gchar *paths,
                                                             GError **err);

## Description

Contains a file monitoring wrapper API and utility functions whose implementations depend on the compile-time configuration.

## Details

### AwnVfsMonitor

A wrapper structure for the VFS libraries' file/directory monitoring structure. In the case of the GIO implementation, it is an opaque structure.

### enum AwnVfsMonitorEvent

    typedef enum {
    	AWN_VFS_MONITOR_EVENT_CHANGED,
    	AWN_VFS_MONITOR_EVENT_CREATED,
    	AWN_VFS_MONITOR_EVENT_DELETED
    } AwnVfsMonitorEvent;

A list of valid monitor event types for use with monitor event emission or retrieving the type of monitor event in the callback. Due to thunar-vfs's limited support for event types, only "changed", "created", and "deleted" are available for use.

`AWN_VFS_MONITOR_EVENT_CHANGED` | Indicates that the path referenced has been changed.
`AWN_VFS_MONITOR_EVENT_CREATED` | Indicates that the path referenced has been created on the filesystem.
`AWN_VFS_MONITOR_EVENT_DELETED` | Indicates that the path referenced has been removed from the filesystem.

### enum AwnVfsMonitorType

    typedef enum {
    	AWN_VFS_MONITOR_FILE,
    	AWN_VFS_MONITOR_DIRECTORY
    } AwnVfsMonitorType;

The type of path that an AwnVfsMonitor instance is monitoring.

`AWN_VFS_MONITOR_FILE` | Indicates that the AwnVfsMonitor instance is monitoring a file.
`AWN_VFS_MONITOR_DIRECTORY` | Indicates that the AwnVfsMonitor instance is monitoring a directory.

### AwnVfsMonitorFunc ()

    void                (*AwnVfsMonitorFunc)                (AwnVfsMonitor *monitor,
                                                             gchar *monitor_path,
                                                             gchar *event_path,
                                                             AwnVfsMonitorEvent event,
                                                             gpointer user_data);

The function template used for callbacks executed when a filesystem event has occurred on a path that is being monitored.

`monitor` : | The monitor structure.
`monitor_path` : | The path that is associated with the monitor structure.
`event_path` : | In the case of a directory monitor, the path inside the folder that triggered the event. Otherwise, it is the same as the `monitor_path`.
`event` : | The filesystem operation that triggered the callback to be executed.
`user_data` : | The data passed to `awn_vfs_monitor_add()` so that it could be used in the callback.

### awn_vfs_monitor_add ()

    AwnVfsMonitor *     awn_vfs_monitor_add                 (gchar *path,
                                                             AwnVfsMonitorType monitor_type,
                                                             AwnVfsMonitorFunc callback,
                                                             gpointer user_data);

Adds a monitor callback to the list of callbacks associated with a file or directory.

`path` : | The path to the file/directory being monitored. The path does not have to exist on the filesystem at the time this function is called.
`monitor_type` : | States whether the path being monitored is a directory or a file.
`callback` : | The function to be executed when an event occurs with regards to the path.
`user_data` : | Extra data to be used by the `callback` function.
Returns : | a reference to a newly created monitor struct. The caller is obligated to free the memory when the struct is no longer needed.

### awn_vfs_monitor_emit ()

    void                awn_vfs_monitor_emit                (AwnVfsMonitor *monitor,
                                                             gchar *path,
                                                             AwnVfsMonitorEvent event);

Emits an artificial monitor event to a monitor.

`monitor` : | The monitor structure.
`path` : | The path on the filesystem that will be passed to the respective callbacks.
`event` : | The type of monitor event to fake.

### awn_vfs_monitor_remove ()

    void                awn_vfs_monitor_remove              (AwnVfsMonitor *monitor);

Removes a monitor structure from monitoring a path.

`monitor` : | The structure to remove from monitoring a path.

### awn_vfs_init ()

    void                awn_vfs_init                        (void);

Starts up the VFS library routines that Awn uses, if necessary.

### awn_vfs_get_pathlist_from_string ()

    GSList *            awn_vfs_get_pathlist_from_string    (gchar *paths,
                                                             GError **err);

Converts a string of type text/uri-list into a GSList of URIs.

`paths` : | A list of strings in a text/uri-list format
`err` : | A pointer to the reference object that is used to determine whether the operation was successful.
Returns : | a list of URIs