<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
[
  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
]>
<refentry id="ZeitgeistMonitor">
<refmeta>
<refentrytitle role="top_of_page" id="ZeitgeistMonitor.top_of_page">ZeitgeistMonitor</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  ZEITGEIST-2.0 Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ZeitgeistMonitor</refname>
<refpurpose>Listens for updates to the Zeitgeist event log</refpurpose>
</refnamediv>

<refsynopsisdiv id="ZeitgeistMonitor.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>#define             <link linkend="ZEITGEIST-TYPE-MONITOR:CAPS">ZEITGEIST_TYPE_MONITOR</link>
<link linkend="GPtrArray"><returnvalue>GPtrArray</returnvalue></link> *         <link linkend="zeitgeist-monitor-get-templates">zeitgeist_monitor_get_templates</link>     (<parameter><link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> *self</parameter>);
<link linkend="char"><returnvalue>char</returnvalue></link> *              <link linkend="zeitgeist-monitor-get-path">zeitgeist_monitor_get_path</link>          (<parameter><link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> *self</parameter>);
<link linkend="ZeitgeistMonitor"><returnvalue>ZeitgeistMonitor</returnvalue></link> *  <link linkend="zeitgeist-monitor-new">zeitgeist_monitor_new</link>               (<parameter><link linkend="ZeitgeistTimeRange"><type>ZeitgeistTimeRange</type></link> *time_range</parameter>,
                                                         <parameter><link linkend="GPtrArray"><type>GPtrArray</type></link> *event_templates</parameter>);
<link linkend="ZeitgeistTimeRange"><returnvalue>ZeitgeistTimeRange</returnvalue></link> * <link linkend="zeitgeist-monitor-get-time-range">zeitgeist_monitor_get_time_range</link>   (<parameter><link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> *self</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="zeitgeist-monitor-set-time-range">zeitgeist_monitor_set_time_range</link>    (<parameter><link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> *self</parameter>,
                                                         <parameter><link linkend="ZeitgeistTimeRange"><type>ZeitgeistTimeRange</type></link> *value</parameter>);
<link linkend="GPtrArray"><returnvalue>GPtrArray</returnvalue></link> *         <link linkend="zeitgeist-monitor-get-event-templates">zeitgeist_monitor_get_event_templates</link>
                                                        (<parameter><link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> *self</parameter>);
<link linkend="void"><returnvalue>void</returnvalue></link>                <link linkend="zeitgeist-monitor-set-event-templates">zeitgeist_monitor_set_event_templates</link>
                                                        (<parameter><link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> *self</parameter>,
                                                         <parameter><link linkend="GPtrArray"><type>GPtrArray</type></link> *value</parameter>);
struct              <link linkend="ZeitgeistMonitor-struct">ZeitgeistMonitor</link>;
struct              <link linkend="ZeitgeistMonitorClass">ZeitgeistMonitorClass</link>;
</synopsis>
</refsynopsisdiv>
<refsect1 id="ZeitgeistMonitor.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<synopsis>
  <link linkend="GObject">GObject</link>
   +----ZeitgeistMonitor
</synopsis>
</refsect1>
<refsect1 id="ZeitgeistMonitor.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
ZeitgeistMonitor implements
 <link linkend="ZeitgeistRemoteMonitor">ZeitgeistRemoteMonitor</link>.</para>
</refsect1>
<refsect1 id="ZeitgeistMonitor.properties" role="properties">
<title role="properties.title">Properties</title>
<synopsis>
  &quot;<link linkend="ZeitgeistMonitor--event-templates">event-templates</link>&quot;          <link linkend="GPtrArray"><type>GPtrArray</type></link>*            : Read / Write / Construct
  &quot;<link linkend="ZeitgeistMonitor--time-range">time-range</link>&quot;               <link linkend="ZeitgeistTimeRange"><type>ZeitgeistTimeRange</type></link>*   : Read / Write / Construct
</synopsis>
</refsect1>
<refsect1 id="ZeitgeistMonitor.signals" role="signal_proto">
<title role="signal_proto.title">Signals</title>
<synopsis>
  &quot;<link linkend="ZeitgeistMonitor-events-deleted">events-deleted</link>&quot;                                 : <link linkend="G-SIGNAL-RUN-LAST:CAPS"><literal>Run Last</literal></link>
  &quot;<link linkend="ZeitgeistMonitor-events-inserted">events-inserted</link>&quot;                                : <link linkend="G-SIGNAL-RUN-LAST:CAPS"><literal>Run Last</literal></link>
</synopsis>
</refsect1>

<refsect1 id="ZeitgeistMonitor.description" role="desc">
<title role="desc.title">Description</title>
<para>
<para>A <link linkend="Monitor"><type>Monitor</type></link> listens for updates to the Zeitgeist event log matching a given set of templates and with timestamps in some predefined time range.</para><para>A monitor must be installed into the running Zeitgeist daemon by calling <link linkend="zeitgeist-log-install-monitor"><function>zeitgeist_log_install_monitor()</function></link>. The monitor will not emit any of the ::events-added or ::events-deleted signals before this.</para>
</para>
</refsect1>
<refsect1 id="ZeitgeistMonitor.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="ZEITGEIST-TYPE-MONITOR:CAPS" role="macro">
<title>ZEITGEIST_TYPE_MONITOR</title>
<indexterm zone="ZEITGEIST-TYPE-MONITOR:CAPS"><primary>ZEITGEIST_TYPE_MONITOR</primary></indexterm>
<programlisting>#define ZEITGEIST_TYPE_MONITOR (zeitgeist_monitor_get_type ())
</programlisting>
<para>
The type for <link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link>.
</para></refsect2>
<refsect2 id="zeitgeist-monitor-get-templates" role="function">
<title>zeitgeist_monitor_get_templates ()</title>
<indexterm zone="zeitgeist-monitor-get-templates"><primary>zeitgeist_monitor_get_templates</primary></indexterm>
<programlisting><link linkend="GPtrArray"><returnvalue>GPtrArray</returnvalue></link> *         zeitgeist_monitor_get_templates     (<parameter><link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> *self</parameter>);</programlisting>
<variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> instance</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="zeitgeist-monitor-get-path" role="function">
<title>zeitgeist_monitor_get_path ()</title>
<indexterm zone="zeitgeist-monitor-get-path"><primary>zeitgeist_monitor_get_path</primary></indexterm>
<programlisting><link linkend="char"><returnvalue>char</returnvalue></link> *              zeitgeist_monitor_get_path          (<parameter><link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> *self</parameter>);</programlisting>
<variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> instance</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="zeitgeist-monitor-new" role="function">
<title>zeitgeist_monitor_new ()</title>
<indexterm zone="zeitgeist-monitor-new"><primary>zeitgeist_monitor_new</primary></indexterm>
<programlisting><link linkend="ZeitgeistMonitor"><returnvalue>ZeitgeistMonitor</returnvalue></link> *  zeitgeist_monitor_new               (<parameter><link linkend="ZeitgeistTimeRange"><type>ZeitgeistTimeRange</type></link> *time_range</parameter>,
                                                         <parameter><link linkend="GPtrArray"><type>GPtrArray</type></link> *event_templates</parameter>);</programlisting>
<para>
zeitgeist_monitor_new
</para>
<para>
<para>Create a new monitor. Before you can receive signals from the monitor you need to install it in the running Zeitgeist daemon by calling <link linkend="zeitgeist-log-install-monitor"><function>zeitgeist_log_install_monitor()</function></link>.</para>
</para><variablelist role="params">
<varlistentry><term><parameter>time_range</parameter>&#160;:</term>
<listitem><simpara>&nbsp;.  The monitor will only listen for events with timestamps within this time range. Note that it is legal for applications to insert events that are &quot;in the past&quot;. <emphasis role="annotation">[<acronym>in</acronym>]</emphasis></simpara></listitem></varlistentry>
<varlistentry><term><parameter>event_templates</parameter>&#160;:</term>
<listitem><simpara>&nbsp;.  A <link linkend="GPtrArray"><type>GPtrArray</type></link> of <link linkend="ZeitgeistEvent"><type>ZeitgeistEvent</type></link>&lt;!-- --&gt;s. Only listen for events that match any of these templates. <emphasis role="annotation">[<acronym>in</acronym>][<acronym>transfer full</acronym>]</emphasis></simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>A reference to a newly allocated monitor</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="zeitgeist-monitor-get-time-range" role="function">
<title>zeitgeist_monitor_get_time_range ()</title>
<indexterm zone="zeitgeist-monitor-get-time-range"><primary>zeitgeist_monitor_get_time_range</primary></indexterm>
<programlisting><link linkend="ZeitgeistTimeRange"><returnvalue>ZeitgeistTimeRange</returnvalue></link> * zeitgeist_monitor_get_time_range   (<parameter><link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> *self</parameter>);</programlisting>
<para>
Get and return the current value of the <link linkend="ZeitgeistMonitor--time-range"><type>"time-range"</type></link> property.
</para><variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> instance to query</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the value of the <link linkend="ZeitgeistMonitor--time-range"><type>"time-range"</type></link> property</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="zeitgeist-monitor-set-time-range" role="function">
<title>zeitgeist_monitor_set_time_range ()</title>
<indexterm zone="zeitgeist-monitor-set-time-range"><primary>zeitgeist_monitor_set_time_range</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                zeitgeist_monitor_set_time_range    (<parameter><link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> *self</parameter>,
                                                         <parameter><link linkend="ZeitgeistTimeRange"><type>ZeitgeistTimeRange</type></link> *value</parameter>);</programlisting>
<para>
Set the value of the <link linkend="ZeitgeistMonitor--time-range"><type>"time-range"</type></link> property to <parameter>value</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> instance to modify</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara>the new value of the <link linkend="ZeitgeistMonitor--time-range"><type>"time-range"</type></link> property</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="zeitgeist-monitor-get-event-templates" role="function">
<title>zeitgeist_monitor_get_event_templates ()</title>
<indexterm zone="zeitgeist-monitor-get-event-templates"><primary>zeitgeist_monitor_get_event_templates</primary></indexterm>
<programlisting><link linkend="GPtrArray"><returnvalue>GPtrArray</returnvalue></link> *         zeitgeist_monitor_get_event_templates
                                                        (<parameter><link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> *self</parameter>);</programlisting>
<para>
Get and return the current value of the <link linkend="ZeitgeistMonitor--event-templates"><type>"event-templates"</type></link> property.
</para><variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> instance to query</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the value of the <link linkend="ZeitgeistMonitor--event-templates"><type>"event-templates"</type></link> property</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="zeitgeist-monitor-set-event-templates" role="function">
<title>zeitgeist_monitor_set_event_templates ()</title>
<indexterm zone="zeitgeist-monitor-set-event-templates"><primary>zeitgeist_monitor_set_event_templates</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                zeitgeist_monitor_set_event_templates
                                                        (<parameter><link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> *self</parameter>,
                                                         <parameter><link linkend="GPtrArray"><type>GPtrArray</type></link> *value</parameter>);</programlisting>
<para>
Set the value of the <link linkend="ZeitgeistMonitor--event-templates"><type>"event-templates"</type></link> property to <parameter>value</parameter>.
</para><variablelist role="params">
<varlistentry><term><parameter>self</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> instance to modify</simpara></listitem></varlistentry>
<varlistentry><term><parameter>value</parameter>&#160;:</term>
<listitem><simpara>the new value of the <link linkend="ZeitgeistMonitor--event-templates"><type>"event-templates"</type></link> property</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="ZeitgeistMonitor-struct" role="struct">
<title>struct ZeitgeistMonitor</title>
<indexterm zone="ZeitgeistMonitor-struct"><primary>ZeitgeistMonitor</primary></indexterm>
<programlisting>struct ZeitgeistMonitor;</programlisting>
<para>
Listens for updates to the Zeitgeist event log
</para>
<para>
<para>A <link linkend="Monitor"><type>Monitor</type></link> listens for updates to the Zeitgeist event log matching a given set of templates and with timestamps in some predefined time range.</para><para>A monitor must be installed into the running Zeitgeist daemon by calling <link linkend="zeitgeist-log-install-monitor"><function>zeitgeist_log_install_monitor()</function></link>. The monitor will not emit any of the ::events-added or ::events-deleted signals before this.</para>
</para></refsect2>
<refsect2 id="ZeitgeistMonitorClass" role="struct">
<title>struct ZeitgeistMonitorClass</title>
<indexterm zone="ZeitgeistMonitorClass"><primary>ZeitgeistMonitorClass</primary></indexterm>
<programlisting>struct ZeitgeistMonitorClass {
	GObjectClass parent_class;
};
</programlisting>
<para>
The class structure for <link linkend="ZEITGEIST-TYPE-MONITOR:CAPS"><literal>ZEITGEIST_TYPE_MONITOR</literal></link>. All the fields in this structure are private and should never be accessed directly.
</para><variablelist role="struct">
<varlistentry><term><link linkend="GObjectClass"><type>GObjectClass</type></link>&#160;<structfield id="ZeitgeistMonitorClass.parent-class">parent_class</structfield>;</term>
<listitem><simpara>the parent class structure</simpara></listitem>
</varlistentry>
</variablelist></refsect2>

</refsect1>
<refsect1 id="ZeitgeistMonitor.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="ZeitgeistMonitor--event-templates" role="property"><title>The <literal>&quot;event-templates&quot;</literal> property</title>
<indexterm zone="ZeitgeistMonitor--event-templates"><primary>ZeitgeistMonitor:event-templates</primary></indexterm>
<programlisting>  &quot;event-templates&quot;          <link linkend="GPtrArray"><type>GPtrArray</type></link>*            : Read / Write / Construct</programlisting>
<para>event-templates.</para></refsect2>
<refsect2 id="ZeitgeistMonitor--time-range" role="property"><title>The <literal>&quot;time-range&quot;</literal> property</title>
<indexterm zone="ZeitgeistMonitor--time-range"><primary>ZeitgeistMonitor:time-range</primary></indexterm>
<programlisting>  &quot;time-range&quot;               <link linkend="ZeitgeistTimeRange"><type>ZeitgeistTimeRange</type></link>*   : Read / Write / Construct</programlisting>
<para>time-range.</para></refsect2>
</refsect1>
<refsect1 id="ZeitgeistMonitor.signal-details" role="signals">
<title role="signals.title">Signal Details</title>
<refsect2 id="ZeitgeistMonitor-events-deleted" role="signal"><title>The <literal>&quot;events-deleted&quot;</literal> signal</title>
<indexterm zone="ZeitgeistMonitor-events-deleted"><primary>ZeitgeistMonitor::events-deleted</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                user_function                      (<link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link>   *monitor,
                                                        <link linkend="ZeitgeistTimeRange"><type>ZeitgeistTimeRange</type></link> *event_ids_length1,
                                                        <link linkend="gpointer"><type>gpointer</type></link>            time_range,
                                                        <link linkend="gint"><type>gint</type></link>                event_ids,
                                                        <link linkend="gpointer"><type>gpointer</type></link>            user_data)              : <link linkend="G-SIGNAL-RUN-LAST:CAPS"><literal>Run Last</literal></link></programlisting>
<para>
ZeitgeistMonitor::events-deleted:
</para>
<para>
<para>Emitted when events with timestamps within the time range of this monitor have been deleted from the log. Note that the deleted events may not match the event templates for the monitor.</para>
</para><variablelist role="params">
<varlistentry><term><parameter>monitor</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> instance that received the signal</simpara></listitem></varlistentry>
<varlistentry><term><parameter>event_ids_length1</parameter>&#160;:</term>
<listitem><simpara>length of the <parameter>event_ids</parameter> array</simpara></listitem></varlistentry>
<varlistentry><term><parameter>time_range</parameter>&#160;:</term>
<listitem><simpara>&nbsp;.  A <link linkend="ZeitgeistTimeRange"><type>ZeitgeistTimeRange</type></link> that specifies the minimum and maximum timestamps of the deleted events <para></para></simpara></listitem></varlistentry>
<varlistentry><term><parameter>event_ids</parameter>&#160;:</term>
<listitem><simpara>&nbsp;.  A <link linkend="GArray"><type>GArray</type></link> of <link linkend="guint32"><type>guint32</type></link>&lt;!-- --&gt;s holding the IDs of the deleted events <para></para></simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
</variablelist></refsect2><refsect2 id="ZeitgeistMonitor-events-inserted" role="signal"><title>The <literal>&quot;events-inserted&quot;</literal> signal</title>
<indexterm zone="ZeitgeistMonitor-events-inserted"><primary>ZeitgeistMonitor::events-inserted</primary></indexterm>
<programlisting><link linkend="void"><returnvalue>void</returnvalue></link>                user_function                      (<link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link>   *monitor,
                                                        <link linkend="ZeitgeistTimeRange"><type>ZeitgeistTimeRange</type></link> *time_range,
                                                        <link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> *events,
                                                        <link linkend="gpointer"><type>gpointer</type></link>            user_data)       : <link linkend="G-SIGNAL-RUN-LAST:CAPS"><literal>Run Last</literal></link></programlisting>
<para>
ZeitgeistMonitor::events-inserted:
</para>
<para>
<para>Emitted when events matching the event templates and with timestamps within the time range of the monitor has been inserted into the log.</para>
</para><variablelist role="params">
<varlistentry><term><parameter>monitor</parameter>&#160;:</term>
<listitem><simpara>the <link linkend="ZeitgeistMonitor"><type>ZeitgeistMonitor</type></link> instance that received the signal</simpara></listitem></varlistentry>
<varlistentry><term><parameter>time_range</parameter>&#160;:</term>
<listitem><simpara>&nbsp;.  A <link linkend="ZeitgeistTimeRange"><type>ZeitgeistTimeRange</type></link> that specifies the minimum and maximum of the timestamps in <parameter>events</parameter> <para></para></simpara></listitem></varlistentry>
<varlistentry><term><parameter>events</parameter>&#160;:</term>
<listitem><simpara>&nbsp;.  A <link linkend="ZeitgeistResultSet"><type>ZeitgeistResultSet</type></link> holding the &quot;ZeitgeistEvent&quot;s that have been inserted into the log <para></para></simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara>user data set when the signal handler was connected.</simpara></listitem></varlistentry>
</variablelist></refsect2>
</refsect1>

</refentry>
