Monitoring

## Monitoring Monitoring — watch files for changes, and get called back if they do |

## Synopsis

    typedef             MateVFSMonitorHandle;
    enum                MateVFSMonitorType;
    enum                MateVFSMonitorEventType;
    void                (*MateVFSMonitorCallback)          (MateVFSMonitorHandle *handle,
                                                             const gchar *monitor_uri,
                                                             const gchar *info_uri,
                                                             MateVFSMonitorEventType event_type,
                                                             gpointer user_data);
    MateVFSResult      mate_vfs_monitor_add               (MateVFSMonitorHandle **handle,
                                                             const gchar *text_uri,
                                                             MateVFSMonitorType monitor_type,
                                                             MateVFSMonitorCallback callback,
                                                             gpointer user_data);
    MateVFSResult      mate_vfs_monitor_cancel            (MateVFSMonitorHandle *handle);
    void                mate_vfs_monitor_callback          (MateVFSMethodHandle *method_handle,
                                                             MateVFSURI *info_uri,
                                                             MateVFSMonitorEventType event_type);

## Description

## Details

### MateVFSMonitorHandle

    typedef struct MateVFSMonitorHandle MateVFSMonitorHandle;

a handle representing a file or directory monitor that was registered using `mate_vfs_monitor_add()` and that can be cancelled using `mate_vfs_monitor_cancel()`.

### enum MateVFSMonitorType

    typedef enum {
      MATE_VFS_MONITOR_FILE,
      MATE_VFS_MONITOR_DIRECTORY
    } MateVFSMonitorType;

Type of resources that can be monitored.

`MATE_VFS_MONITOR_FILE` | the monitor is registered for a single file.
`MATE_VFS_MONITOR_DIRECTORY` | the monitor is registered for all files in a directory, and the directory itself.

### enum MateVFSMonitorEventType

    typedef enum {
      MATE_VFS_MONITOR_EVENT_CHANGED,
      MATE_VFS_MONITOR_EVENT_DELETED,
      MATE_VFS_MONITOR_EVENT_STARTEXECUTING,
      MATE_VFS_MONITOR_EVENT_STOPEXECUTING,
      MATE_VFS_MONITOR_EVENT_CREATED,
      MATE_VFS_MONITOR_EVENT_METADATA_CHANGED
    } MateVFSMonitorEventType;

Types of events that can be monitored.

`MATE_VFS_MONITOR_EVENT_CHANGED` | file data changed (FAM, inotify).
`MATE_VFS_MONITOR_EVENT_DELETED` | file deleted event (FAM, inotify).
`MATE_VFS_MONITOR_EVENT_STARTEXECUTING` | file was executed (FAM only).
`MATE_VFS_MONITOR_EVENT_STOPEXECUTING` | executed file isn't executed anymore (FAM only).
`MATE_VFS_MONITOR_EVENT_CREATED` | file created event (FAM, inotify).
`MATE_VFS_MONITOR_EVENT_METADATA_CHANGED` | file metadata changed (inotify only).

### MateVFSMonitorCallback ()

    void                (*MateVFSMonitorCallback)          (MateVFSMonitorHandle *handle,
                                                             const gchar *monitor_uri,
                                                             const gchar *info_uri,
                                                             MateVFSMonitorEventType event_type,
                                                             gpointer user_data);

Function called when a monitor detects a change.

`handle` : | the handle of the monitor that created the event
`monitor_uri` : | the URI of the monitor that was triggered
`info_uri` : | the URI of the actual file this event is concerned with (this can be different from `monitor_uri` if it was a directory monitor)
`event_type` : | what happened to `info_uri`
`user_data` : | user data passed to `mate_vfs_monitor_add()` when the monitor was created

### mate_vfs_monitor_add ()

    MateVFSResult      mate_vfs_monitor_add               (MateVFSMonitorHandle **handle,
                                                             const gchar *text_uri,
                                                             MateVFSMonitorType monitor_type,
                                                             MateVFSMonitorCallback callback,
                                                             gpointer user_data);

Watch the file or directory at `text_uri` for changes (or the creation/deletion of the file) and call `callback` when there is a change. If a directory monitor is added, `callback` is notified when any file in the directory changes.

`handle` : | after the call, `handle` will be a pointer to an operation handle.
`text_uri` : | string representing the uri to monitor.
`monitor_type` : | add a directory or file monitor.
`callback` : | function to call when the monitor is tripped.
`user_data` : | data to pass to `callback`.
Returns : | an integer representing the result of the operation.

### mate_vfs_monitor_cancel ()

    MateVFSResult      mate_vfs_monitor_cancel            (MateVFSMonitorHandle *handle);

Cancel the monitor pointed to be `handle`.

`handle` : | handle of the monitor to cancel.
Returns : | an integer representing the result of the operation.

### mate_vfs_monitor_callback ()

    void                mate_vfs_monitor_callback          (MateVFSMethodHandle *method_handle,
                                                             MateVFSURI *info_uri,
                                                             MateVFSMonitorEventType event_type);

`mate_vfs_monitor_callback()` is used by MateVFSMethods to indicate that a particular resource changed, and will issue the emission of the MateVFSMonitorCallback registered using `mate_vfs_monitor_add()`.

`method_handle` : | Method-specific monitor handle obtained through `mate_vfs_monitor_add()`.
`info_uri` : | URI that triggered the callback.
`event_type` : | The event obtained for `info_uri`.