doc/xml/gnome-vfs-monitor.xml

   1 <refentry id="gnome-vfs-20-gnome-vfs-monitor">
   2 <refmeta>
   3 <refentrytitle>Monitoring</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>GNOME-VFS-2.0 Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Monitoring</refname><refpurpose>
  10 watch files for changes, and get called back if they do</refpurpose>
  11 </refnamediv>
  12
  13 <refsynopsisdiv><title>Synopsis</title>
  14
  15 <synopsis>
  16
  17
  18
  19 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-monitor-add">gnome_vfs_monitor_add</link>        (<link linkend="GnomeVFSMonitorHandle">GnomeVFSMonitorHandle</link> **handle,
  20                                              const <link linkend="gchar">gchar</link> *text_uri,
  21                                              <link linkend="GnomeVFSMonitorType">GnomeVFSMonitorType</link> monitor_type,
  22                                              <link linkend="GnomeVFSMonitorCallback">GnomeVFSMonitorCallback</link> callback,
  23                                              <link linkend="gpointer">gpointer</link> user_data);
  24 <link linkend="GnomeVFSResult">GnomeVFSResult</link> <link linkend="gnome-vfs-monitor-cancel">gnome_vfs_monitor_cancel</link>     (<link linkend="GnomeVFSMonitorHandle">GnomeVFSMonitorHandle</link> *handle);
  25 enum        <link linkend="GnomeVFSMonitorType">GnomeVFSMonitorType</link>;
  26 enum        <link linkend="GnomeVFSMonitorEventType">GnomeVFSMonitorEventType</link>;
  27 <link linkend="void">void</link>        (<link linkend="GnomeVFSMonitorCallback">*GnomeVFSMonitorCallback</link>)      (<link linkend="GnomeVFSMonitorHandle">GnomeVFSMonitorHandle</link> *handle,
  28                                              const <link linkend="gchar">gchar</link> *monitor_uri,
  29                                              const <link linkend="gchar">gchar</link> *info_uri,
  30                                              <link linkend="GnomeVFSMonitorEventType">GnomeVFSMonitorEventType</link> event_type,
  31                                              <link linkend="gpointer">gpointer</link> user_data);
  32 </synopsis>
  33 </refsynopsisdiv>
  34
  35
  36
  37
  38
  39
  40
  41
  42
  43 <refsect1>
  44 <title>Description</title>
  45 <para>
  46
  47 </para>
  48 </refsect1>
  49
  50 <refsect1>
  51 <title>Details</title>
  52 <refsect2>
  53 <title><anchor id="gnome-vfs-monitor-add"/>gnome_vfs_monitor_add ()</title>
  54 <indexterm><primary>gnome_vfs_monitor_add</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_monitor_add        (<link linkend="GnomeVFSMonitorHandle">GnomeVFSMonitorHandle</link> **handle,
  55                                              const <link linkend="gchar">gchar</link> *text_uri,
  56                                              <link linkend="GnomeVFSMonitorType">GnomeVFSMonitorType</link> monitor_type,
  57                                              <link linkend="GnomeVFSMonitorCallback">GnomeVFSMonitorCallback</link> callback,
  58                                              <link linkend="gpointer">gpointer</link> user_data);</programlisting>
  59 <para>
  60 Watch the file or directory at <parameter>text_uri</parameter> for changes (or the creation/deletion of the file)
  61 and call <parameter>callback</parameter> when there is a change. If a directory monitor is added, <parameter>callback</parameter> is
  62 notified when any file in the directory changes.</para>
  63 <para>
  64
  65 </para><variablelist role="params">
  66 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
  67 <listitem><simpara> after the call, <parameter>handle</parameter> will be a pointer to an operation handle
  68 </simpara></listitem></varlistentry>
  69 <varlistentry><term><parameter>text_uri</parameter>&nbsp;:</term>
  70 <listitem><simpara> URI to monitor
  71 </simpara></listitem></varlistentry>
  72 <varlistentry><term><parameter>monitor_type</parameter>&nbsp;:</term>
  73 <listitem><simpara> add a directory or file monitor
  74 </simpara></listitem></varlistentry>
  75 <varlistentry><term><parameter>callback</parameter>&nbsp;:</term>
  76 <listitem><simpara> function to call when the monitor is tripped
  77 </simpara></listitem></varlistentry>
  78 <varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
  79 <listitem><simpara> data to pass to <parameter>callback</parameter>
  80 </simpara></listitem></varlistentry>
  81 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> an integer representing the success of the operation
  82 </simpara></listitem></varlistentry>
  83 </variablelist></refsect2>
  84 <refsect2>
  85 <title><anchor id="gnome-vfs-monitor-cancel"/>gnome_vfs_monitor_cancel ()</title>
  86 <indexterm><primary>gnome_vfs_monitor_cancel</primary></indexterm><programlisting><link linkend="GnomeVFSResult">GnomeVFSResult</link> gnome_vfs_monitor_cancel     (<link linkend="GnomeVFSMonitorHandle">GnomeVFSMonitorHandle</link> *handle);</programlisting>
  87 <para>
  88 Cancel the monitor pointed to be <parameter>handle</parameter>.</para>
  89 <para>
  90
  91 </para><variablelist role="params">
  92 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
  93 <listitem><simpara> handle of the monitor to cancel
  94 </simpara></listitem></varlistentry>
  95 <varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> an integer representing the success of the operation
  96 </simpara></listitem></varlistentry>
  97 </variablelist></refsect2>
  98 <refsect2>
  99 <title><anchor id="GnomeVFSMonitorType"/>enum GnomeVFSMonitorType</title>
 100 <indexterm><primary>GnomeVFSMonitorType</primary></indexterm><programlisting>typedef enum {
 101   GNOME_VFS_MONITOR_FILE,
 102   GNOME_VFS_MONITOR_DIRECTORY
 103 } GnomeVFSMonitorType;
 104 </programlisting>
 105 <para>
 106 Type of resources that can be monitored.</para>
 107 <para>
 108
 109 </para></refsect2>
 110 <refsect2>
 111 <title><anchor id="GnomeVFSMonitorEventType"/>enum GnomeVFSMonitorEventType</title>
 112 <indexterm><primary>GnomeVFSMonitorEventType</primary></indexterm><programlisting>typedef enum {
 113   GNOME_VFS_MONITOR_EVENT_CHANGED,
 114   GNOME_VFS_MONITOR_EVENT_DELETED,
 115   GNOME_VFS_MONITOR_EVENT_STARTEXECUTING,
 116   GNOME_VFS_MONITOR_EVENT_STOPEXECUTING,
 117   GNOME_VFS_MONITOR_EVENT_CREATED,
 118   GNOME_VFS_MONITOR_EVENT_METADATA_CHANGED
 119 } GnomeVFSMonitorEventType;
 120 </programlisting>
 121 <para>
 122 Types of events that can be monitored.</para>
 123 <para>
 124
 125 </para><variablelist role="enum">
 126 <varlistentry>
 127 <term><literal>GNOME_VFS_MONITOR_EVENT_CHANGED</literal></term>
 128 <listitem><simpara> file data changed
 129 </simpara></listitem>
 130 </varlistentry>
 131 <varlistentry>
 132 <term><literal>GNOME_VFS_MONITOR_EVENT_DELETED</literal></term>
 133 <listitem><simpara> file deleted event
 134 </simpara></listitem>
 135 </varlistentry>
 136 <varlistentry>
 137 <term><literal>GNOME_VFS_MONITOR_EVENT_STARTEXECUTING</literal></term>
 138 <listitem><simpara>
 139 </simpara></listitem>
 140 </varlistentry>
 141 <varlistentry>
 142 <term><literal>GNOME_VFS_MONITOR_EVENT_STOPEXECUTING</literal></term>
 143 <listitem><simpara>
 144 </simpara></listitem>
 145 </varlistentry>
 146 <varlistentry>
 147 <term><literal>GNOME_VFS_MONITOR_EVENT_CREATED</literal></term>
 148 <listitem><simpara> file created event
 149 </simpara></listitem>
 150 </varlistentry>
 151 <varlistentry>
 152 <term><literal>GNOME_VFS_MONITOR_EVENT_METADATA_CHANGED</literal></term>
 153 <listitem><simpara> file metadata changed
 154 </simpara></listitem>
 155 </varlistentry>
 156 </variablelist></refsect2>
 157 <refsect2>
 158 <title><anchor id="GnomeVFSMonitorCallback"/>GnomeVFSMonitorCallback ()</title>
 159 <indexterm><primary>GnomeVFSMonitorCallback</primary></indexterm><programlisting><link linkend="void">void</link>        (*GnomeVFSMonitorCallback)      (<link linkend="GnomeVFSMonitorHandle">GnomeVFSMonitorHandle</link> *handle,
 160                                              const <link linkend="gchar">gchar</link> *monitor_uri,
 161                                              const <link linkend="gchar">gchar</link> *info_uri,
 162                                              <link linkend="GnomeVFSMonitorEventType">GnomeVFSMonitorEventType</link> event_type,
 163                                              <link linkend="gpointer">gpointer</link> user_data);</programlisting>
 164 <para>
 165 Function called when a monitor detects a change.</para>
 166 <para>
 167
 168 </para><variablelist role="params">
 169 <varlistentry><term><parameter>handle</parameter>&nbsp;:</term>
 170 <listitem><simpara> the handle of the monitor that created the event
 171 </simpara></listitem></varlistentry>
 172 <varlistentry><term><parameter>monitor_uri</parameter>&nbsp;:</term>
 173 <listitem><simpara> the URI of the monitor that was triggered
 174 </simpara></listitem></varlistentry>
 175 <varlistentry><term><parameter>info_uri</parameter>&nbsp;:</term>
 176 <listitem><simpara> the URI of the actual file this event is concerned with (this can be different
 177 from <parameter>monitor_uri</parameter> if it was a directory monitor)
 178 </simpara></listitem></varlistentry>
 179 <varlistentry><term><parameter>event_type</parameter>&nbsp;:</term>
 180 <listitem><simpara> what happened to <parameter>info_uri</parameter>
 181 </simpara></listitem></varlistentry>
 182 <varlistentry><term><parameter>user_data</parameter>&nbsp;:</term>
 183 <listitem><simpara> user data passed to <link linkend="gnome-vfs-monitor-add"><function>gnome_vfs_monitor_add()</function></link> when the monitor was created
 184 </simpara></listitem></varlistentry>
 185 </variablelist></refsect2>
 186
 187 </refsect1>
 188
 189
 190
 191
 192 </refentry>