<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>edelib: DirWatch Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">edelib
 <span id="projectnumber">2.0.0</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.7.6.1 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li class="current"><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="navrow2" class="tabs2">
<ul class="tablist">
<li><a href="annotated.html"><span>Class List</span></a></li>
<li><a href="hierarchy.html"><span>Class Hierarchy</span></a></li>
<li><a href="functions.html"><span>Class Members</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="namespaceedelib.html">edelib</a> </li>
<li class="navelem"><a class="el" href="classedelib_1_1DirWatch.html">DirWatch</a> </li>
</ul>
</div>
</div>
<div class="header">
<div class="summary">
<a href="#pub-methods">Public Member Functions</a> |
<a href="#pub-static-methods">Static Public Member Functions</a> </div>
<div class="headertitle">
<div class="title">DirWatch Class Reference</div> </div>
</div><!--header-->
<div class="contents">
<!-- doxytag: class="edelib::DirWatch" -->
<p>Directory changes notifier.
<a href="classedelib_1_1DirWatch.html#details">More...</a></p>
<p><code>#include <<a class="el" href="DirWatch_8h_source.html">edelib/DirWatch.h</a>></code></p>
<p><a href="classedelib_1_1DirWatch-members.html">List of all members.</a></p>
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classedelib_1_1DirWatch.html#ab53aec61e71ba14486b5ae387236d2a2">DirWatch</a> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top"> </td><td class="memItemRight" valign="bottom"><a class="el" href="classedelib_1_1DirWatch.html#acec0ba09c7600c6b8edd25640c4ad2b5">~DirWatch</a> ()</td></tr>
<tr><td colspan="2"><h2><a name="pub-static-methods"></a>
Static Public Member Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">static bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classedelib_1_1DirWatch.html#ab1b186899d9a4ce0173d4f64f723e0e4">init</a> (void)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">static void </td><td class="memItemRight" valign="bottom"><a class="el" href="classedelib_1_1DirWatch.html#af80085e2fde103b0fcdf58fcab027e47">shutdown</a> (void)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">static bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classedelib_1_1DirWatch.html#a79821de8e5cc62b3daa22a107c427a96">add</a> (const char *dir, int flags)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">static bool </td><td class="memItemRight" valign="bottom"><a class="el" href="classedelib_1_1DirWatch.html#a6d445c71ec465379045407d1f66c68e6">remove</a> (const char *dir)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">static void </td><td class="memItemRight" valign="bottom"><a class="el" href="classedelib_1_1DirWatch.html#a8e61e694f9dd8df760876a208bad4e71">callback</a> (DirWatchCallback &cb, void *data=0)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">static <a class="el" href="namespaceedelib.html#a74c565325075c0a87254e283b9bbcef3">DirWatchNotifier</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="classedelib_1_1DirWatch.html#a4ec77659d167cbfd18521bb6a6f19430">notifier</a> (void)</td></tr>
</table>
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<div class="textblock"><p>Directory changes notifier. </p>
<p><a class="el" href="classedelib_1_1DirWatch.html" title="Directory changes notifier.">DirWatch</a> can be used to monitor certain directories for their content changes (their files). Those changes can be creating, removing, altering or attributes changes.</p>
<dl class="note"><dt><b>Note:</b></dt><dd><a class="el" href="classedelib_1_1DirWatch.html" title="Directory changes notifier.">DirWatch</a> <em>can't</em> be used to monitor files directly; use directory where file belongs to.</dd></dl>
<p>To accept events, you should initialize <a class="el" href="classedelib_1_1DirWatch.html" title="Directory changes notifier.">DirWatch</a>, add appropriate directories with desired notification flags and register callback. That callback will be called when event occured on target directory with appropriate filled parameters. Some of the parameters can be NULL or -1, depending if <a class="el" href="classedelib_1_1DirWatch.html" title="Directory changes notifier.">DirWatch</a> was able to figure out what was happened.</p>
<p>After initialization, application should go into loop state so it can listen and receive events. This is not a problem for GUI applications since they already use event loops.</p>
<dl class="note"><dt><b>Note:</b></dt><dd><a class="el" href="classedelib_1_1DirWatch.html" title="Directory changes notifier.">DirWatch</a> relies on FLTK loop, and in case of non GUI application, <em>Fl::wait()</em> still has to be used.</dd></dl>
<p>This is sample: </p>
<div class="fragment"><pre class="fragment"> <span class="comment">// our callback</span>
<span class="keywordtype">void</span> notify_cb(<span class="keyword">const</span> <span class="keywordtype">char</span>* dir, <span class="keyword">const</span> <span class="keywordtype">char</span>* what_changed, <span class="keywordtype">int</span> flags, <span class="keywordtype">void</span>*) {
<span class="keywordflow">if</span>(what_changed && flag != -1)
printf(<span class="stringliteral">"Content of %s changed: %s was changed with %i flag\n"</span>, dir, what_changed, flag);
<span class="keywordflow">else</span>
printf(<span class="stringliteral">"Content of %s changed"</span>, dir);
}
<span class="comment">// somewhere in the code</span>
<a class="code" href="classedelib_1_1DirWatch.html#ab1b186899d9a4ce0173d4f64f723e0e4">DirWatch::init</a>();
<span class="comment">// check creating/deleting</span>
<span class="keywordflow">if</span>(!<a class="code" href="classedelib_1_1DirWatch.html#a79821de8e5cc62b3daa22a107c427a96">DirWatch::add</a>(<span class="stringliteral">"/some/directory1"</span>, <a class="code" href="namespaceedelib.html#ab35849a6627668de02a0a2c9807f2e17aa1fb79af2ab6ccc8fc9c1653a16dbab7" title="In directory item created.">DW_CREATE</a> | <a class="code" href="namespaceedelib.html#ab35849a6627668de02a0a2c9807f2e17a186b014a1f2615d19cf5e4cd7c66be5c" title="In directory item is deleted.">DW_DELETE</a>))
printf(<span class="stringliteral">"Fatal, can't monitor /some/directory1\n"</span>);
<span class="comment">// check any modify</span>
<span class="keywordflow">if</span>(!<a class="code" href="classedelib_1_1DirWatch.html#a79821de8e5cc62b3daa22a107c427a96">DirWatch::add</a>(<span class="stringliteral">"/some/directory2"</span>, <a class="code" href="namespaceedelib.html#ab35849a6627668de02a0a2c9807f2e17a1a3676da67752a5f27d218327bd5fc92" title="In directory item modified.">DW_MODIFY</a>))
printf(<span class="stringliteral">"Fatal, can't monitor /some/directory2\n"</span>);
<span class="comment">// callback called when something was changed</span>
<a class="code" href="classedelib_1_1DirWatch.html#a8e61e694f9dd8df760876a208bad4e71">DirWatch::callback</a>(notify_cb);
<span class="comment">// go into loop</span>
<span class="keywordflow">while</span>(1) {
<span class="comment">// here we restart loop each 5 seconds</span>
Fl::wait(5);
}
<span class="comment">//... and when application is done, shutdown() will clear allocated data</span>
<a class="code" href="classedelib_1_1DirWatch.html#af80085e2fde103b0fcdf58fcab027e47">DirWatch::shutdown</a>();
</pre></div><p>You <b>must</b> call <a class="el" href="classedelib_1_1DirWatch.html#ab1b186899d9a4ce0173d4f64f723e0e4">init()</a> before further calls or assertion will pop up.</p>
<p>Events can be reported multiple times, one after one (thus calling callback) depending what DirWatchFlags is selected. For example, selecting <em>DW_CREATE|DW_ATTRIB</em> will call callback probably three times when new file in watched directory is created; one for creating and other two for attributes changes. This mostly depends on the way how file is created. Final application should be prepared for this.</p>
<p>When <a class="el" href="classedelib_1_1DirWatch.html" title="Directory changes notifier.">DirWatch</a> was not able to figure out what was changed, <em>what_changed</em> could be set to NULL or <em>flag</em> could be set -1, like: </p>
<div class="fragment"><pre class="fragment"> <span class="keywordtype">void</span> notify_cb(<span class="keyword">const</span> <span class="keywordtype">char</span>* dir, <span class="keyword">const</span> <span class="keywordtype">char</span>* what_changed, <span class="keywordtype">int</span> flag) {
<span class="comment">// what_changed can be NULL or name of changed file if succeded</span>
<span class="comment">// flag can be -1 if failed or one of DirWatchFlags if succeded</span>
...
}
</pre></div><p>When tracking events, at first sight some reports will look odd or maybe wrong; this is related to program/whatever that cause this event. Eg. when you open some file for editing with vim (probably other editors), you will often get DW_CREATE/DW_DELETE events since vim creates another temporary file, copy old content in it, modify it and move it to file you supposed to edit.</p>
<p>Removing registered directories is done with <a class="el" href="classedelib_1_1DirWatch.html#a6d445c71ec465379045407d1f66c68e6">remove()</a>, but given directory name must be equal to one passed to <a class="el" href="classedelib_1_1DirWatch.html#a79821de8e5cc62b3daa22a107c427a96">add()</a>, like: </p>
<div class="fragment"><pre class="fragment"> <a class="code" href="classedelib_1_1DirWatch.html#a79821de8e5cc62b3daa22a107c427a96">DirWatch::add</a>(<span class="stringliteral">"/home/baz"</span>);
<span class="comment">// fine, remove it</span>
<a class="code" href="classedelib_1_1DirWatch.html#a6d445c71ec465379045407d1f66c68e6">DirWatch::remove</a>(<span class="stringliteral">"/home/baz"</span>);
<span class="comment">// note ending slash, it will not be removed since does not matches original</span>
<a class="code" href="classedelib_1_1DirWatch.html#a6d445c71ec465379045407d1f66c68e6">DirWatch::remove</a>(<span class="stringliteral">"/home/baz/"</span>);
</pre></div><p>After directory is removed from notifier, further change events in it will not be delivered.</p>
<p>If you want to deliver some data in callback, you can use <em>void*</em> parameter. To remind: </p>
<div class="fragment"><pre class="fragment"> <span class="keywordtype">void</span> notify_cb(<span class="keyword">const</span> <span class="keywordtype">char</span>* dir, <span class="keyword">const</span> <span class="keywordtype">char</span>* what_changed, <span class="keywordtype">int</span> flags, <span class="keywordtype">void</span>* d) {
MySampleWidget* w = (MySampleWidget*)d;
w->write_in_widget(dir);
}
MySampleWidget* w = <span class="keyword">new</span> MySampleWidget(...);
<a class="code" href="classedelib_1_1DirWatch.html#a8e61e694f9dd8df760876a208bad4e71">DirWatch::callback</a>(notify_cb, mywidget);
</pre></div><p><a class="el" href="classedelib_1_1DirWatch.html" title="Directory changes notifier.">DirWatch</a> can report what backend it use for notification via <a class="el" href="classedelib_1_1DirWatch.html#a4ec77659d167cbfd18521bb6a6f19430">notifier()</a> member which will return one of the DirWatchNotifier elements. Then application can choose special case for some backend when is compiled in. </p>
</div><hr/><h2>Constructor & Destructor Documentation</h2>
<a class="anchor" id="ab53aec61e71ba14486b5ae387236d2a2"></a><!-- doxytag: member="edelib::DirWatch::DirWatch" ref="ab53aec61e71ba14486b5ae387236d2a2" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="classedelib_1_1DirWatch.html">DirWatch</a> </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Empty constructor </p>
</div>
</div>
<a class="anchor" id="acec0ba09c7600c6b8edd25640c4ad2b5"></a><!-- doxytag: member="edelib::DirWatch::~DirWatch" ref="acec0ba09c7600c6b8edd25640c4ad2b5" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">~<a class="el" href="classedelib_1_1DirWatch.html">DirWatch</a> </td>
<td>(</td>
<td class="paramname"></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Clean internal data </p>
</div>
</div>
<hr/><h2>Member Function Documentation</h2>
<a class="anchor" id="a79821de8e5cc62b3daa22a107c427a96"></a><!-- doxytag: member="edelib::DirWatch::add" ref="a79821de8e5cc62b3daa22a107c427a96" args="(const char *dir, int flags)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">static bool <a class="el" href="classedelib_1_1DirWatch.html#a79821de8e5cc62b3daa22a107c427a96">add</a> </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>dir</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>flags</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td><code> [static]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Add directory to be watched. Directory <b>must</b> exists or will be ignored. It will return true if addition was succesfull or false if not. </p>
</div>
</div>
<a class="anchor" id="a8e61e694f9dd8df760876a208bad4e71"></a><!-- doxytag: member="edelib::DirWatch::callback" ref="a8e61e694f9dd8df760876a208bad4e71" args="(DirWatchCallback &cb, void *data=0)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">static void <a class="el" href="classedelib_1_1DirWatch.html#a8e61e694f9dd8df760876a208bad4e71">callback</a> </td>
<td>(</td>
<td class="paramtype">DirWatchCallback & </td>
<td class="paramname"><em>cb</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"><em>data</em> = <code>0</code> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td><code> [static]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Register callback called when content of one of added directories was changed. </p>
</div>
</div>
<a class="anchor" id="ab1b186899d9a4ce0173d4f64f723e0e4"></a><!-- doxytag: member="edelib::DirWatch::init" ref="ab1b186899d9a4ce0173d4f64f723e0e4" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">static bool <a class="el" href="classedelib_1_1DirWatch.html#ab1b186899d9a4ce0173d4f64f723e0e4">init</a> </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td><td>)</td>
<td><code> [static]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Prepare internal data. This <b>must</b> be called before any further <a class="el" href="classedelib_1_1DirWatch.html#a79821de8e5cc62b3daa22a107c427a96">add()</a> </p>
</div>
</div>
<a class="anchor" id="a4ec77659d167cbfd18521bb6a6f19430"></a><!-- doxytag: member="edelib::DirWatch::notifier" ref="a4ec77659d167cbfd18521bb6a6f19430" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">static <a class="el" href="namespaceedelib.html#a74c565325075c0a87254e283b9bbcef3">DirWatchNotifier</a> <a class="el" href="classedelib_1_1DirWatch.html#a4ec77659d167cbfd18521bb6a6f19430">notifier</a> </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td><td>)</td>
<td><code> [static]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return current notifier used, or DW_NONE if none of them. </p>
</div>
</div>
<a class="anchor" id="a6d445c71ec465379045407d1f66c68e6"></a><!-- doxytag: member="edelib::DirWatch::remove" ref="a6d445c71ec465379045407d1f66c68e6" args="(const char *dir)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">static bool <a class="el" href="classedelib_1_1DirWatch.html#a6d445c71ec465379045407d1f66c68e6">remove</a> </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"><em>dir</em></td><td>)</td>
<td><code> [static]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Remove added entry. </p>
</div>
</div>
<a class="anchor" id="af80085e2fde103b0fcdf58fcab027e47"></a><!-- doxytag: member="edelib::DirWatch::shutdown" ref="af80085e2fde103b0fcdf58fcab027e47" args="(void)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">static void <a class="el" href="classedelib_1_1DirWatch.html#af80085e2fde103b0fcdf58fcab027e47">shutdown</a> </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td><td>)</td>
<td><code> [static]</code></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Shutdown watcher and clean data. Any further <a class="el" href="classedelib_1_1DirWatch.html#a79821de8e5cc62b3daa22a107c427a96">add()</a> call after this will trigger assertion. </p>
</div>
</div>
<hr/>The documentation for this class was generated from the following file:<ul>
<li>edelib/<a class="el" href="DirWatch_8h_source.html">DirWatch.h</a></li>
</ul>
</div><!-- contents -->
<hr class="footer"/><address class="footer"><small>
Generated on Tue Jun 5 2012 17:49:02 for edelib by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.7.6.1
</small></address>
</body>
</html>
