Still celebrating National IT Professionals Day with 3 months of free Premium Membership. Use Code ITDAY17

x
?
Solved

Calling API Function ReadDirectoryChangesW

Posted on 1999-07-21
4
Medium Priority
?
1,180 Views
Last Modified: 2010-05-18
I am looking for an example of how to use the ReadDirectoryChangesW API function from within VB.  The function is new and the Declare Syntax is not included in the Win32api.txt file distributed by Microsoft.
0
Comment
Question by:ubsjmg1
[X]
Welcome to Experts Exchange

Add your voice to the tech community where 5M+ people just like you are talking about what matters.

  • Help others & share knowledge
  • Earn cash & points
  • Learn & ask questions
4 Comments
 
LVL 5

Expert Comment

by:yronnen
ID: 1526392
What is the purpose of this API call?
0
 
LVL 8

Accepted Solution

by:
vettranger earned 1600 total points
ID: 1526393
I couldn't find this function in VB for you, so I translated the C definition into a VB declare format for your. Following are the technical specs ... the only tricky part looks to be the callback reference at the end. You will also have to include an Overlap data structure.

You can find the original of the following information at :
http://msdn.microsoft.com/library/sdkdoc/winbase/filesio_3n5f.htm

along with all of the other fileio APIs.
************

Declare function ReadDirectoryChangesW(byval hDirectory as long, _   'handle to the directory to be watched
lpBuffer as string, _     'pointer to the buffer to receive the read results
nBufferLength as long, _   'length of lpBuffer
bWatchSubtree as boolean, _  'flag for monitoring directory or directory tree
dwNotifyFilter as long, _   'filter conditions to watch for
lpBytesReturned as long, _  'number of bytes returned
lpOverlapped as OVERLAPPED, _ 'pointer to structure needed for overlapped I/O
lpCompletionRoutine as LPOVERLAPPED_COMPLETION_ROUTINE _ 'pointer to completion routine
as BOOLEAN

***************
ReadDirectoryChangesW

The ReadDirectoryChangesW function returns information describing the changes occurring within a directory.

BOOL ReadDirectoryChangesW(
  HANDLE hDirectory,    // handle to the directory to be watched
  LPVOID lpBuffer,      // pointer to the buffer to receive the read
                        //  results
  DWORD nBufferLength,  // length of lpBuffer
  BOOL bWatchSubtree,   // flag for monitoring directory or
                        // directory tree
  DWORD dwNotifyFilter, // filter conditions to watch for
  LPDWORD lpBytesReturned,  // number of bytes returned
  LPOVERLAPPED lpOverlapped,
                        // pointer to structure needed for
                        //  overlapped I/O
  LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
                        // pointer to completion routine
);
 
Parameters
hDirectory
Handle to the directory to be watched. This directory must be opened with the FILE_LIST_DIRECTORY access right.
lpBuffer
Specifies the address of the formatted buffer in which the read results are to be returned. The structure of this buffer is defined by the FILE_NOTIFY_INFORMATION structure. This buffer is filled either synchronously or asynchronously, depending on how the directory is opened and what value is given to the lpOverlapped parameter. For more information, see the Remarks section.
nBufferLength
Specifies the length of the buffer pointed to by the lpBuffer parameter.
bWatchSubtree
Specifies whether the ReadDirectoryChangesW function will monitor the directory or the directory tree. If TRUE is specified, the function monitors the directory tree rooted at the specified directory. If FALSE is specified, the function monitors only the directory specified by the hDirectory parameter.
dwNotifyFilter
Specifies filter criteria the function checks to determine if the wait operation has completed. This parameter can be one or more of the following values. Value Meaning
FILE_NOTIFY_CHANGE_FILE_NAME Any file name change in the watched directory or subtree causes a change notification wait operation to return. Changes include renaming, creating, or deleting a file.  
FILE_NOTIFY_CHANGE_DIR_NAME Any directory-name change in the watched directory or subtree causes a change notification wait operation to return. Changes include creating or deleting a directory.
FILE_NOTIFY_CHANGE_ATTRIBUTES Any attribute change in the watched directory or subtree causes a change notification wait operation to return.
FILE_NOTIFY_CHANGE_SIZE Any file-size change in the watched directory or subtree causes a change notification wait operation to return. The operating system detects a change in file size only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed.
FILE_NOTIFY_CHANGE_LAST_WRITE Any change to the last write-time of files in the watched directory or subtree causes a change notification wait operation to return. The operating system detects a change to the last write-time only when the file is written to the disk. For operating systems that use extensive caching, detection occurs only when the cache is sufficiently flushed.
FILE_NOTIFY_CHANGE_LAST_ACCESS Any change to the last access time of files in the watched directory or subtree causes a change notification wait operation to return.
FILE_NOTIFY_CHANGE_CREATION Any change to the creation time of files in the watched directory or subtree causes a change notification wait operation to return.
FILE_NOTIFY_CHANGE_SECURITY Any security-descriptor change in the watched directory or subtree causes a change notification wait operation to return.


lpBytesReturned
For synchronous calls, this parameter specifies the number of bytes transferred into the lpBuffer parameter. For asynchronous calls, this parameter is undefined. You must use an asynchronous notification technique to retrieve the number of bytes transferred.
lpOverlapped
Pointer to an OVERLAPPED structure that supplies data to be used during asynchronous operation. Otherwise, this value is NULL. The Offset and OffsetHigh members of this structure are not used.
lpCompletionRoutine
Pointer to a completion routine to be called when the operation has been completed or canceled and the calling thread is in an alertable wait state. For more information about this completion routine, see FileIOCompletionRoutine.
Return Values
If the function succeeds, the return value is nonzero. For synchronous calls, this means that the operation succeeded. For asynchronous calls, this indicates that the operation was successfully queued.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks
To obtain a handle to a directory, use the CreateFile function with FILE_FLAG_BACKUP_SEMANTICS as follows:

hDir = CreateFile(
  DirName,                            // pointer to the file name
  FILE_LIST_DIRECTORY,                // access (read-write) mode
  FILE_SHARE_READ|FILE_SHARE_DELETE,  // share mode
  NULL,                               // security descriptor
  OPEN_EXISTING,                      // how to create
  FILE_FLAG_BACKUP_SEMANTICS,         // file attributes
  NULL                                // file with attributes to copy
);
 
A call to ReadDirectoryChangesW can be completed synchronously or asynchronously. To specify asynchronous completion, open the directory with CreateFile as shown above, but additionally specify the FILE_FLAG_OVERLAPPED attribute in the dwFlagsAndAttributes parameter. Then specify an OVERLAPPED structure when you call ReadDirectoryChangesW.

Upon successful synchronous completion, the lpBuffer parameter is a formatted buffer and the number of bytes written to the buffer is available in lpBytesReturned. If the number of bytes transferred is zero, the buffer was too small to provide detailed information on all the changes that occurred in the directory or subtree. In this case, you should compute the changes by enumerating the directory or subtree.

For asynchronous completion, you can receive notification in one of three ways:

Using the GetOverlappedResult function. To receive notification through GetOverlappedResult, do not specify a completion routine in the lpCompletionRoutine parameter. Be sure to set the hEvent member of the OVERLAPPED structure to a unique event.
Using the GetQueuedCompletionStatus function. To receive notification through GetQueuedCompletionStatus, do not specify a completion routine in lpCompletionRoutine. Associate the directory handle hDirectory with a completion port by calling the CreateIoCompletionPort function.
Using a completion routine. To receive notification through a completion routine, do not associate the directory with a completion port. Specify a completion routine in lpCompletionRoutine. This routine is called whenever the operation has been completed or canceled while the thread is in an alertable wait state. The hEvent member of the OVERLAPPED structure is not used by the system, so you can use it yourself.
QuickInfo
  Windows NT/2000: Requires Windows NT 3.51 SP3 or later.
  Windows 95/98: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use kernel32.lib.

See Also
File I/O Overview, File Functions, CreateFile, CreateIoCompletionPort, FILE_NOTIFY_INFORMATION, FileIOCompletionRoutine, GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED

Built on Tuesday, March 30, 1999
0
 
LVL 3

Expert Comment

by:Iexpert
ID: 1526394
This will be very hard if not impossible doing directly from VB
how about doing it in a DLL that you call from VB, which
would send the appropriate events back ?
Anyway here's the doc on the function:
-------------------------------------------------------------------
ReadDirectoryChangesW

The ReadDirectoryChangesW function returns information describing the changes occurring within a directory.

BOOL ReadDirectoryChangesW(
  HANDLE hDirectory,    // handle to the directory to be watched
  LPVOID lpBuffer,      // pointer to the buffer to receive the read
                        //  results
  DWORD nBufferLength,  // length of lpBuffer
  BOOL bWatchSubtree,   // flag for monitoring directory or
                        // directory tree
  DWORD dwNotifyFilter, // filter conditions to watch for
  LPDWORD lpBytesReturned,  // number of bytes returned
  LPOVERLAPPED lpOverlapped,
                        // pointer to structure needed for
                        //  overlapped I/O
  LPOVERLAPPED_COMPLETION_ROUTINE lpCompletionRoutine
                        // pointer to completion routine
);
 

Parameters

hDirectory
     Handle to the directory to be watched. This directory must be opened with the FILE_LIST_DIRECTORY access right.
lpBuffer
     Specifies the address of the formatted buffer in which the read results are to be returned. The structure of this buffer is defined by the
     FILE_NOTIFY_INFORMATION structure. This buffer is filled either synchronously or asynchronously, depending on how the directory is opened and
     what value is given to the lpOverlapped parameter. For more information, see the Remarks section.
nBufferLength
     Specifies the length of the buffer pointed to by the lpBuffer parameter.
bWatchSubtree
     Specifies whether the ReadDirectoryChangesW function will monitor the directory or the directory tree. If TRUE is specified, the function monitors the
     directory tree rooted at the specified directory. If FALSE is specified, the function monitors only the directory specified by the hDirectory parameter.
dwNotifyFilter
     Specifies filter criteria the function checks to determine if the wait operation has completed. This parameter can be one or more of the following values.
      Value
                                                                        Meaning
      FILE_NOTIFY_CHANGE_FILE_NAME
                                                                        Any file name change in the watched directory or subtree causes a
                                                                        change notification wait operation to return. Changes include
                                                                        renaming, creating, or deleting a file.
      FILE_NOTIFY_CHANGE_DIR_NAME
                                                                        Any directory-name change in the watched directory or subtree
                                                                        causes a change notification wait operation to return. Changes
                                                                        include creating or deleting a directory.
      FILE_NOTIFY_CHANGE_ATTRIBUTES
                                                                        Any attribute change in the watched directory or subtree causes a
                                                                        change notification wait operation to return.
      FILE_NOTIFY_CHANGE_SIZE
                                                                        Any file-size change in the watched directory or subtree causes a
                                                                        change notification wait operation to return. The operating system
                                                                        detects a change in file size only when the file is written to the disk.
                                                                        For operating systems that use extensive caching, detection occurs
                                                                        only when the cache is sufficiently flushed.
      FILE_NOTIFY_CHANGE_LAST_WRITE
                                                                        Any change to the last write-time of files in the watched directory or
                                                                        subtree causes a change notification wait operation to return. The
                                                                        operating system detects a change to the last write-time only when
                                                                        the file is written to the disk. For operating systems that use
                                                                        extensive caching, detection occurs only when the cache is
                                                                        sufficiently flushed.
      FILE_NOTIFY_CHANGE_LAST_ACCESS
                                                                        Any change to the last access time of files in the watched directory
                                                                        or subtree causes a change notification wait operation to return.
      FILE_NOTIFY_CHANGE_CREATION
                                                                        Any change to the creation time of files in the watched directory or
                                                                        subtree causes a change notification wait operation to return.
      FILE_NOTIFY_CHANGE_SECURITY
                                                                        Any security-descriptor change in the watched directory or subtree
                                                                        causes a change notification wait operation to return.


lpBytesReturned
     For synchronous calls, this parameter specifies the number of bytes transferred into the lpBuffer parameter. For asynchronous calls, this parameter is
     undefined. You must use an asynchronous notification technique to retrieve the number of bytes transferred.
lpOverlapped
     Pointer to an OVERLAPPED structure that supplies data to be used during asynchronous operation. Otherwise, this value is NULL. The Offset and
     OffsetHigh members of this structure are not used.
lpCompletionRoutine
     Pointer to a completion routine to be called when the operation has been completed or canceled and the calling thread is in an alertable wait state. For more
     information about this completion routine, see FileIOCompletionRoutine.

Return Values

If the function succeeds, the return value is nonzero. For synchronous calls, this means that the operation succeeded. For asynchronous calls, this indicates that the
operation was successfully queued.

If the function fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

To obtain a handle to a directory, use the CreateFile function with FILE_FLAG_BACKUP_SEMANTICS as follows:

hDir = CreateFile(
  DirName,                            // pointer to the file name
  FILE_LIST_DIRECTORY,                // access (read-write) mode
  FILE_SHARE_READ|FILE_SHARE_DELETE,  // share mode
  NULL,                               // security descriptor
  OPEN_EXISTING,                      // how to create
  FILE_FLAG_BACKUP_SEMANTICS,         // file attributes
  NULL                                // file with attributes to copy
);
 

A call to ReadDirectoryChangesW can be completed synchronously or asynchronously. To specify asynchronous completion, open the directory with CreateFile
as shown above, but additionally specify the FILE_FLAG_OVERLAPPED attribute in the dwFlagsAndAttributes parameter. Then specify an OVERLAPPED
structure when you call ReadDirectoryChangesW.

Upon successful synchronous completion, the lpBuffer parameter is a formatted buffer and the number of bytes written to the buffer is available in lpBytesReturned.
If the number of bytes transferred is zero, the buffer was too small to provide detailed information on all the changes that occurred in the directory or subtree. In this
case, you should compute the changes by enumerating the directory or subtree.

For asynchronous completion, you can receive notification in one of three ways:

     Using the GetOverlappedResult function. To receive notification through GetOverlappedResult, do not specify a completion routine in the
     lpCompletionRoutine parameter. Be sure to set the hEvent member of the OVERLAPPED structure to a unique event.
     Using the GetQueuedCompletionStatus function. To receive notification through GetQueuedCompletionStatus, do not specify a completion routine in
     lpCompletionRoutine. Associate the directory handle hDirectory with a completion port by calling the CreateIoCompletionPort function.
     Using a completion routine. To receive notification through a completion routine, do not associate the directory with a completion port. Specify a completion
     routine in lpCompletionRoutine. This routine is called whenever the operation has been completed or canceled while the thread is in an alertable wait state.
     The hEvent member of the OVERLAPPED structure is not used by the system, so you can use it yourself.

QuickInfo

  Windows NT/2000: Requires Windows NT 3.51 SP3 or later.
  Windows 95/98: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in winbase.h.
  Import Library: Use kernel32.lib.

See Also

File I/O Overview, File Functions, CreateFile, CreateIoCompletionPort, FILE_NOTIFY_INFORMATION, FileIOCompletionRoutine,
GetOverlappedResult, GetQueuedCompletionStatus, OVERLAPPED
0
 
LVL 14

Expert Comment

by:waty
ID: 4178844
Bough
0

Featured Post

Enroll in September's Course of the Month

This month’s featured course covers 16 hours of training in installation, management, and deployment of VMware vSphere virtualization environments. It's free for Premium Members, Team Accounts, and Qualified Experts!

Question has a verified solution.

If you are experiencing a similar issue, please ask a related question

You can of course define an array to hold data that is of a particular type like an array of Strings to hold customer names or an array of Doubles to hold customer sales, but what do you do if you want to coordinate that data? This article describes…
Since upgrading to Office 2013 or higher installing the Smart Indenter addin will fail. This article will explain how to install it so it will work regardless of the Office version installed.
Get people started with the process of using Access VBA to control Excel using automation, Microsoft Access can control other applications. An example is the ability to programmatically talk to Excel. Using automation, an Access application can laun…
Get people started with the utilization of class modules. Class modules can be a powerful tool in Microsoft Access. They allow you to create self-contained objects that encapsulate functionality. They can easily hide the complexity of a process from…
Suggested Courses

661 members asked questions and received personalized solutions in the past 7 days.

Join the community of 500,000 technology professionals and ask your questions.

Join & Ask a Question