.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Win32::ChangeNotify 3"
.TH Win32::ChangeNotify 3 "2008-04-23" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Win32::ChangeNotify \- Monitor events related to files and directories
.SH "VERSION"
.IX Header "VERSION"
This document describes version 1.07 of Win32::ChangeNotify, released April 16, 2008 as part of Win32\-IPC version 1.07.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&        require Win32::ChangeNotify;
\&
\&        $notify = Win32::ChangeNotify\->new($Path,$WatchSubTree,$Events);
\&        $notify\->wait or warn "Something failed: $!\en";
\&        # There has been a change.
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module allows the user to use a Win32 change notification event
object from Perl.  This allows the Perl program to monitor events
relating to files and directory trees.
.PP
Unfortunately, the Win32 \s-1API\s0 which implements this feature does not
provide any indication of \fIwhat\fR triggered the notification (as far
as I know).  If you're monitoring a directory for file changes, and
you need to know \fIwhich\fR file changed, you'll have to find some other
way of determining that.  Depending on exactly what you're trying to
do, you may be able to check file timestamps to find recently changed
files.  Or, you may need to cache the directory contents somewhere and
compare the current contents to your cached copy when you receive a
change notification.
.PP
The \f(CW\*(C`wait\*(C'\fR method and \f(CW\*(C`wait_all\*(C'\fR & \f(CW\*(C`wait_any\*(C'\fR functions are
inherited from the Win32::IPC module.
.Sh "Methods"
.IX Subsection "Methods"
.ie n .IP "$notify\fR = Win32::ChangeNotify\->new($path, \f(CW$subtree\fR, \f(CW$filter)" 4
.el .IP "\f(CW$notify\fR = Win32::ChangeNotify\->new($path, \f(CW$subtree\fR, \f(CW$filter\fR)" 4
.IX Item "$notify = Win32::ChangeNotify->new($path, $subtree, $filter)"
Constructor for a new ChangeNotification object.  \f(CW$path\fR is the
directory to monitor.  If \f(CW$subtree\fR is true, then all directories
under \f(CW$path\fR will be monitored.  \f(CW$filter\fR indicates what events
should trigger a notification.  It should be a string containing any
of the following flags (separated by whitespace and/or \f(CW\*(C`|\*(C'\fR).
.Sp
.Vb 6
\&   ATTRIBUTES   Any attribute change
\&   DIR_NAME     Any directory name change
\&   FILE_NAME    Any file name change (creating/deleting/renaming)
\&   LAST_WRITE   Any change to a file\*(Aqs last write time
\&   SECURITY     Any security descriptor change
\&   SIZE         Any change in a file\*(Aqs size
.Ve
.Sp
(\f(CW$filter\fR can also be an integer composed from the
\&\f(CW\*(C`FILE_NOTIFY_CHANGE_*\*(C'\fR constants.)
.Sp
Under Cygwin, \f(CW$path\fR must be a Windows pathname, not a Cygwin
Unix-like pathname.
.ie n .IP "$notify\->close" 4
.el .IP "\f(CW$notify\fR\->close" 4
.IX Item "$notify->close"
Shut down monitoring.  You could just \f(CW\*(C`undef $notify\*(C'\fR instead (but
\&\f(CW\*(C`close\*(C'\fR works even if there are other copies of the object).  This
happens automatically when your program exits.
.ie n .IP "$notify\->reset" 4
.el .IP "\f(CW$notify\fR\->reset" 4
.IX Item "$notify->reset"
Resets the ChangeNotification object after a change has been detected.
The object will become signalled again after the next change.  (It is
\&\s-1OK\s0 to call this immediately after \f(CW\*(C`new\*(C'\fR, but it is not required.)
Returns true if successful, or zero if it fails (additional error
information can be found in \f(CW$^E\fR).
.ie n .IP "$notify\->wait" 4
.el .IP "\f(CW$notify\fR\->wait" 4
.IX Item "$notify->wait"
See Win32::IPC.  Remember to call \f(CW\*(C`reset\*(C'\fR afterwards if you want
to continue monitoring.
.Sh "Deprecated Functions and Methods"
.IX Subsection "Deprecated Functions and Methods"
\&\fBWin32::ChangeNotify\fR still supports the ActiveWare syntax, but its
use is deprecated.
.IP "FindFirst($Obj,$PathName,$WatchSubTree,$Filter)" 4
.IX Item "FindFirst($Obj,$PathName,$WatchSubTree,$Filter)"
Use
.Sp
.Vb 1
\&  $Obj = Win32::ChangeNotify\->new($PathName,$WatchSubTree,$Filter)
.Ve
.Sp
instead.
.ie n .IP "$obj\fR\->\fIFindNext()" 4
.el .IP "\f(CW$obj\fR\->\fIFindNext()\fR" 4
.IX Item "$obj->FindNext()"
Use \f(CW\*(C`$obj\->reset\*(C'\fR instead.
.ie n .IP "$obj\fR\->\fIClose()" 4
.el .IP "\f(CW$obj\fR\->\fIClose()\fR" 4
.IX Item "$obj->Close()"
Use \f(CW\*(C`$obj\->close\*(C'\fR instead.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
None.
.SH "CONFIGURATION AND ENVIRONMENT"
.IX Header "CONFIGURATION AND ENVIRONMENT"
Win32::ChangeNotify requires no configuration files or environment variables.
.PP
It runs under 32\-bit or 64\-bit Microsoft Windows, either natively or
under Cygwin.
.SH "DEPENDENCIES"
.IX Header "DEPENDENCIES"
Win32::IPC
.SH "INCOMPATIBILITIES"
.IX Header "INCOMPATIBILITIES"
Prior to version 1.06, Win32::ChangeNotify treated \f(CW\*(C`undef\*(C'\fR values
differently.  In version 1.06 and later, passing \f(CW\*(C`undef\*(C'\fR as the value
of an optional parameter is the same as omitting that parameter.  In
previous versions, \f(CW\*(C`undef\*(C'\fR was interpreted as either the empty string
or 0 (along with a warning about \*(L"Use of uninitialized value...\*(R").
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
No bugs have been reported.
.SH "AUTHOR"
.IX Header "AUTHOR"
Christopher J. Madsen <\fIperl \s-1AT\s0 cjmweb.net\fR>
.PP
Please report any bugs or feature requests to
\&\f(CW\*(C`<bug\-Win32\-IPC\ AT\ rt.cpan.org>\*(C'\fR,
or through the web interface at
<http://rt.cpan.org/Public/Bug/Report.html?Queue=Win32\-IPC>
.PP
Loosely based on the original module by ActiveWare Internet Corp.,
<http://www.ActiveState.com>
.SH "LICENSE AND COPYRIGHT"
.IX Header "LICENSE AND COPYRIGHT"
Copyright 1998\-2008 Christopher J. Madsen
.PP
Created: 3 Feb 1998 from the ActiveWare version
  (c) 1995 Microsoft Corporation. All rights reserved.
      Developed by ActiveWare Internet Corp., http://www.ActiveState.com
.PP
.Vb 1
\&  Other modifications (c) 1997 by Gurusamy Sarathy <gsar@cpan.org>
.Ve
.PP
This module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself. See perlartistic.
.SH "DISCLAIMER OF WARRANTY"
.IX Header "DISCLAIMER OF WARRANTY"
\&\s-1BECAUSE\s0 \s-1THIS\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1LICENSED\s0 \s-1FREE\s0 \s-1OF\s0 \s-1CHARGE\s0, \s-1THERE\s0 \s-1IS\s0 \s-1NO\s0 \s-1WARRANTY\s0
\&\s-1FOR\s0 \s-1THE\s0 \s-1SOFTWARE\s0, \s-1TO\s0 \s-1THE\s0 \s-1EXTENT\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0. \s-1EXCEPT\s0 \s-1WHEN\s0
\&\s-1OTHERWISE\s0 \s-1STATED\s0 \s-1IN\s0 \s-1WRITING\s0 \s-1THE\s0 \s-1COPYRIGHT\s0 \s-1HOLDERS\s0 \s-1AND/OR\s0 \s-1OTHER\s0 \s-1PARTIES\s0
\&\s-1PROVIDE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R" \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EITHER\s0
\&\s-1EXPRESSED\s0 \s-1OR\s0 \s-1IMPLIED\s0, \s-1INCLUDING\s0, \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0, \s-1THE\s0 \s-1IMPLIED\s0
\&\s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0 \s-1AND\s0 \s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0. \s-1THE\s0
\&\s-1ENTIRE\s0 \s-1RISK\s0 \s-1AS\s0 \s-1TO\s0 \s-1THE\s0 \s-1QUALITY\s0 \s-1AND\s0 \s-1PERFORMANCE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1WITH\s0
\&\s-1YOU\s0. \s-1SHOULD\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1PROVE\s0 \s-1DEFECTIVE\s0, \s-1YOU\s0 \s-1ASSUME\s0 \s-1THE\s0 \s-1COST\s0 \s-1OF\s0 \s-1ALL\s0
\&\s-1NECESSARY\s0 \s-1SERVICING\s0, \s-1REPAIR\s0, \s-1OR\s0 \s-1CORRECTION\s0.
.PP
\&\s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1UNLESS\s0 \s-1REQUIRED\s0 \s-1BY\s0 \s-1APPLICABLE\s0 \s-1LAW\s0 \s-1OR\s0 \s-1AGREED\s0 \s-1TO\s0 \s-1IN\s0 \s-1WRITING\s0
\&\s-1WILL\s0 \s-1ANY\s0 \s-1COPYRIGHT\s0 \s-1HOLDER\s0, \s-1OR\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1WHO\s0 \s-1MAY\s0 \s-1MODIFY\s0 \s-1AND/OR\s0
\&\s-1REDISTRIBUTE\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1AS\s0 \s-1PERMITTED\s0 \s-1BY\s0 \s-1THE\s0 \s-1ABOVE\s0 \s-1LICENSE\s0, \s-1BE\s0
\&\s-1LIABLE\s0 \s-1TO\s0 \s-1YOU\s0 \s-1FOR\s0 \s-1DAMAGES\s0, \s-1INCLUDING\s0 \s-1ANY\s0 \s-1GENERAL\s0, \s-1SPECIAL\s0, \s-1INCIDENTAL\s0,
\&\s-1OR\s0 \s-1CONSEQUENTIAL\s0 \s-1DAMAGES\s0 \s-1ARISING\s0 \s-1OUT\s0 \s-1OF\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1INABILITY\s0 \s-1TO\s0 \s-1USE\s0
\&\s-1THE\s0 \s-1SOFTWARE\s0 (\s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1LOSS\s0 \s-1OF\s0 \s-1DATA\s0 \s-1OR\s0 \s-1DATA\s0 \s-1BEING\s0
\&\s-1RENDERED\s0 \s-1INACCURATE\s0 \s-1OR\s0 \s-1LOSSES\s0 \s-1SUSTAINED\s0 \s-1BY\s0 \s-1YOU\s0 \s-1OR\s0 \s-1THIRD\s0 \s-1PARTIES\s0 \s-1OR\s0 A
\&\s-1FAILURE\s0 \s-1OF\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1TO\s0 \s-1OPERATE\s0 \s-1WITH\s0 \s-1ANY\s0 \s-1OTHER\s0 \s-1SOFTWARE\s0), \s-1EVEN\s0 \s-1IF\s0
\&\s-1SUCH\s0 \s-1HOLDER\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1PARTY\s0 \s-1HAS\s0 \s-1BEEN\s0 \s-1ADVISED\s0 \s-1OF\s0 \s-1THE\s0 \s-1POSSIBILITY\s0 \s-1OF\s0
\&\s-1SUCH\s0 \s-1DAMAGES\s0.