Monitoring
3
GNOME-VFS-2.0 Library

# Monitoring

watch files for changes, and get called back if they do

## Synopsis

    typedef             GnomeVFSMonitorHandle;
    enum                GnomeVFSMonitorType;
    enum                GnomeVFSMonitorEventType;
    void                (*GnomeVFSMonitorCallback)          (GnomeVFSMonitorHandle *handle,
                                                             const gchar *monitor_uri,
                                                             const gchar *info_uri,
                                                             GnomeVFSMonitorEventType event_type,
                                                             gpointer user_data);
    GnomeVFSResult      gnome_vfs_monitor_add               (GnomeVFSMonitorHandle **handle,
                                                             const gchar *text_uri,
                                                             GnomeVFSMonitorType monitor_type,
                                                             GnomeVFSMonitorCallback callback,
                                                             gpointer user_data);
    GnomeVFSResult      gnome_vfs_monitor_cancel            (GnomeVFSMonitorHandle *handle);
    void                gnome_vfs_monitor_callback          (GnomeVFSMethodHandle *method_handle,
                                                             GnomeVFSURI *info_uri,
                                                             GnomeVFSMonitorEventType event_type);

## Description

## Details

### GnomeVFSMonitorHandle

    typedef struct GnomeVFSMonitorHandle GnomeVFSMonitorHandle;

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

### enum GnomeVFSMonitorType

    typedef enum {
      GNOME_VFS_MONITOR_FILE,
      GNOME_VFS_MONITOR_DIRECTORY
    } GnomeVFSMonitorType;

Type of resources that can be monitored.

`GNOME_VFS_MONITOR_FILE`

  the monitor is registered for a single file.

`GNOME_VFS_MONITOR_DIRECTORY`

  the monitor is registered for all files in a directory, and the directory itself.

### enum GnomeVFSMonitorEventType

    typedef enum {
      GNOME_VFS_MONITOR_EVENT_CHANGED,
      GNOME_VFS_MONITOR_EVENT_DELETED,
      GNOME_VFS_MONITOR_EVENT_STARTEXECUTING,
      GNOME_VFS_MONITOR_EVENT_STOPEXECUTING,
      GNOME_VFS_MONITOR_EVENT_CREATED,
      GNOME_VFS_MONITOR_EVENT_METADATA_CHANGED
    } GnomeVFSMonitorEventType;

Types of events that can be monitored.

`GNOME_VFS_MONITOR_EVENT_CHANGED`

  file data changed (FAM, inotify).

`GNOME_VFS_MONITOR_EVENT_DELETED`

  file deleted event (FAM, inotify).

`GNOME_VFS_MONITOR_EVENT_STARTEXECUTING`

  file was executed (FAM only).

`GNOME_VFS_MONITOR_EVENT_STOPEXECUTING`

  executed file isn't executed anymore (FAM only).

`GNOME_VFS_MONITOR_EVENT_CREATED`

  file created event (FAM, inotify).

`GNOME_VFS_MONITOR_EVENT_METADATA_CHANGED`

  file metadata changed (inotify only).

### GnomeVFSMonitorCallback ()

    void                (*GnomeVFSMonitorCallback)          (GnomeVFSMonitorHandle *handle,
                                                             const gchar *monitor_uri,
                                                             const gchar *info_uri,
                                                             GnomeVFSMonitorEventType 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 `gnome_vfs_monitor_add()` when the monitor was created

### gnome_vfs_monitor_add ()

    GnomeVFSResult      gnome_vfs_monitor_add               (GnomeVFSMonitorHandle **handle,
                                                             const gchar *text_uri,
                                                             GnomeVFSMonitorType monitor_type,
                                                             GnomeVFSMonitorCallback 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.

### gnome_vfs_monitor_cancel ()

    GnomeVFSResult      gnome_vfs_monitor_cancel            (GnomeVFSMonitorHandle *handle);

Cancel the monitor pointed to be `handle`.

`handle` :

  handle of the monitor to cancel.

Returns :

  an integer representing the result of the operation.

### gnome_vfs_monitor_callback ()

    void                gnome_vfs_monitor_callback          (GnomeVFSMethodHandle *method_handle,
                                                             GnomeVFSURI *info_uri,
                                                             GnomeVFSMonitorEventType event_type);

`gnome_vfs_monitor_callback()` is used by GnomeVFSMethods to indicate that a particular resource changed, and will issue the emission of the GnomeVFSMonitorCallback registered using `gnome_vfs_monitor_add()`.

`method_handle` :

  Method-specific monitor handle obtained through `gnome_vfs_monitor_add()`.

`info_uri` :

  URI that triggered the callback.

`event_type` :

  The event obtained for `info_uri`.