Monitoring

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.