.. highlightlang:: us

.. index:: FS_ReadDirectoryChanges_Create

.. _fs_readdirectorychanges_create:

FS_ReadDirectoryChanges_Create
==============================

.. us.tag  FS_ReadDirectoryChanges_Create NOTREADYENGLISH New550 FILE_MISC

:ref:`FS_ReadDirectoryChanges_Create` starts watching a directory. Any changes
(renaming, creating, or deleting a file) will be logged. The changes can be
received calling the :ref:`FS_ReadDirectoryChanges_Get` function.

.. function::  dc = FS_ReadDirectoryChanges_Create(ssDir)
    dc = FS_ReadDirectoryChanges_Create(ssDir, svFileFilter)
    dc = FS_ReadDirectoryChanges_Create(ssDir, svFileFilter, nNotify)
    dc = FS_ReadDirectoryChanges_Create(ssDir, svFileFilter, nNotify, bWatchSubtree)
    dc = FS_ReadDirectoryChanges_Create(ssDir, svFileFilter, nNotify, bWatchSubtree, bIncludeFilter)

.. us.return

**Return Value**

*dc* is an object of type DIRWATCHITEM or 0 is an error occurred.

.. us.params

**Parameters**

.. uparam:: ssDir

   *ssDir* is the directory to be monitored.

.. uparam:: svFileFilter

   Is a vector of strings with file filters, see example.
   Default filter is "\*.\*".

.. uparam:: nNotify

   *nNotify* can be one or more of the following values:

   .. list-table::
      :header-rows: 1

      * - 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.

   Default value is FILE_NOTIFY_CHANGE_FILE_NAME.

.. uparam:: bWatchSubtree

   If this parameter is TRUE, the function monitors the directory tree rooted at 
   the specified directory. If this parameter is FALSE, the function monitors
   only the directory specified by the *ssDir* parameter. Default value is
   TRUE (1).

.. uparam:: bIncludeFilter

   If this parameter is set to TRUE (1) the *svFileFilter* is used as an include
   filter. If this parameter is set to FALSE (0) the *svFileFilter* is used as an
   exclude filter. Default value is TRUE (1).

.. us.example

**Example**

::

   def MonitorDirectory()
   {
       global __g__dwi;
       AppKillTimer();
       ssDir = "d:/test/";
       if (__g__dwi == 0) {
           __g__dwi = FS_ReadDirectoryChanges_Create(ssDir, ["*.utx", "*.nc"]);
           if (__g__dwi == 0) {
               MessageBoxError("Cannot watch directory: %s", ssDir);
               return FALSE;
           }
       }
       smFiles = FS_ReadDirectoryChanges_Get(__g__dwi);
       if (smFiles[1] != "") {
           idx = find(smFiles[;2] == "a"); // only added
           svFiles = ssDir + smFiles[idx;1];
           //
           // do something with the files.
           // 
       }
       AppSetTimer(MonitorDirectory, 60*1000);
       return TRUE;
   }
   MonitorDirectory()

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - 5.5.0
     - New

.. seealso::
   :ref:`overview-files`,
   :ref:`FS_ReadDirectoryChanges_Get`,
   :ref:`AppSetTimer`

:sub:`id-826916`