//******************************************************************************************************//  SafeFileWatcher.cs - Gbtc////  Copyright © 2015, Grid Protection Alliance.  All Rights Reserved.////  Licensed to the Grid Protection Alliance (GPA) under one or more contributor license agreements. See//  the NOTICE file distributed with this work for additional information regarding copyright ownership.//  The GPA licenses this file to you under the MIT License (MIT), the "License"; you may//  not use this file except in compliance with the License. You may obtain a copy of the License at:////      http://opensource.org/licenses/MIT////  Unless agreed to in writing, the subject software distributed under the License is distributed on an//  "AS-IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. Refer to the//  License for the specific language governing permissions and limitations.////  Code Modification History://  ----------------------------------------------------------------------------------------------------//  07/28/2015 - J. Ritchie Carroll//       Generated original version of source code.////****************************************************************************************************** using System;using System.ComponentModel;using System.Diagnostics.CodeAnalysis;using System.IO;using System.Security; namespace GSF.IO{    /// <summary>    /// Represents a wrapper around the native .NET <see cref="FileSystemWatcher"/> that avoids problems with    /// dangling references when using a file watcher instance as a class member that never gets disposed.    /// </summary>    /// <remarks>    /// <para>    /// The design goal of the SafeFileWatcher is to avoid accidental memory leaks caused by use of .NET's native    /// file system watcher when used as a member of a class that consumers fail to properly dispose. If a class    /// has a reference to a file watcher as a member variable and attaches to the file watcher's events, the    /// file watcher will maintain a reference the parent class so it can call its event handler. If the parent    /// class is not disposed properly, the file watcher will thusly not be disposed and will maintain the    /// reference to the parent class - the garbage collector will never collect the parent because it has a    /// valid reference and no collection means the parent finalizer will never get called and the file system    /// watcher will never get disposed. Creating multiple instances of parent class and not disposing of them    /// will cause a memory leak even with a properly designed disposable pattern. Using the SafeFileWatcher    /// instead of directly using the FileSystemWatcher will resolve this potential issue.    /// </para>    /// <para>    /// Note that component model implementation is not fully replicated - if you are using a file system watcher    /// on a design surface, this safety wrapper will usually not be needed. This class has benefit when a class    /// will dynamically use a file watcher and needs to make sure any unmanaged resources get properly released    /// even if a consumer neglects to call the dispose function.    /// </para>    /// </remarks>    [SecurityCritical]    public class SafeFileWatcher : IDisposable    {        #region [ Members ]         // Events         /// <summary>        /// Occurs when a file or directory in the specified <see cref="SafeFileWatcher.Path"/> is changed.        /// </summary>        public event FileSystemEventHandler Changed;         /// <summary>        /// Occurs when a file or directory in the specified <see cref="SafeFileWatcher.Path"/> is created.        /// </summary>        public event FileSystemEventHandler Created;         /// <summary>        /// Occurs when a file or directory in the specified <see cref="SafeFileWatcher.Path"/> is deleted.        /// </summary>        public event FileSystemEventHandler Deleted;         /// <summary>        /// Occurs when a file or directory in the specified <see cref="SafeFileWatcher.Path"/> is renamed.        /// </summary>        public event RenamedEventHandler Renamed;         /// <summary>        /// Occurs when the internal buffer overflows.        /// </summary>        public event ErrorEventHandler Error;         // Fields        private readonly FileSystemWatcher m_fileSystemWatcher;        private bool m_disposed;         #endregion         #region [ Constructors ]         /// <summary>        /// Initializes a new instance of the <see cref="SafeFileWatcher"/> class.        /// </summary>        public SafeFileWatcher()        {            m_fileSystemWatcher = new FileSystemWatcher();            InitializeFileSystemWatcher();        }         /// <summary>        /// Initializes a new instance of the <see cref="SafeFileWatcher"/> class, given the specified directory to monitor.        /// </summary>        /// <param name="path">The directory to monitor, in standard or Universal Naming Convention (UNC) notation.        /// </param>        /// <exception cref="ArgumentNullException">The <paramref name="path"/> parameter is null.</exception>        /// <exception cref="ArgumentException">        /// The <paramref name="path"/> parameter is an empty string (""). -or-        /// The path specified through the <paramref name="path"/> parameter does not exist.        /// </exception>        public SafeFileWatcher(string path)        {            m_fileSystemWatcher = new FileSystemWatcher(path);            InitializeFileSystemWatcher();        }         /// <summary>        /// Initializes a new instance of the <see cref="SafeFileWatcher"/> class, given the specified directory and type of files to monitor.        /// </summary>        /// <param name="path">The directory to monitor, in standard or Universal Naming Convention (UNC) notation.</param>        /// <param name="filter">The type of files to watch. For example, "*.txt" watches for changes to all text files.</param>        /// <exception cref="ArgumentNullException">        /// The <paramref name="path"/> parameter is null. -or-        /// The <paramref name="filter"/> parameter is null.        /// </exception>        /// <exception cref="ArgumentException">        /// The <paramref name="path"/> parameter is an empty string (""). -or-        /// The path specified through the <paramref name="path"/> parameter does not exist.        /// </exception>        public SafeFileWatcher(string path, string filter)        {            m_fileSystemWatcher = new FileSystemWatcher(path, filter);            InitializeFileSystemWatcher();        }         // Attach to file system watcher events via lambda function using a weak reference to this class instance        // connected through static method so that file watcher cannot hold onto a reference to this class - this        // way even if consumer neglects to dispose this class, it will get properly garbage collected and finalized        // because there will be no remaining references to this class instance. Also, even though the following        // intermediate lambda classes that get created will be attached to the file system watcher event handlers,        // they will also be freed because this class will make sure the file system watcher instance is handled        // like an unmanaged resource, i.e., it always gets disposed, via the finalizer if need be.        private void InitializeFileSystemWatcher()        {            WeakReference<SafeFileWatcher> reference = new WeakReference<SafeFileWatcher>(this);             m_fileSystemWatcher.Changed += (_, e) => OnChanged(reference, e);            m_fileSystemWatcher.Created += (_, e) => OnCreated(reference, e);            m_fileSystemWatcher.Deleted += (_, e) => OnDeleted(reference, e);            m_fileSystemWatcher.Renamed += (_, e) => OnRenamed(reference, e);            m_fileSystemWatcher.Error += (_, e) => OnError(reference, e);        }         /// <summary>        /// Terminates <see cref="SafeFileWatcher"/> instance making sure to release unmanaged resources.        /// </summary>        ~SafeFileWatcher()        {            // Finalizer desired because we want to dispose FileSystemWatcher to force release of pinned buffers            // and thus release reference to any associated event delegates allowing garbage collection            Dispose(false);        }         #endregion         #region [ Properties ]         /// <summary>        /// Gets or sets the path of the directory to watch.        /// </summary>        /// <returns>        /// The path to monitor. The default is an empty string ("").        /// </returns>        /// <exception cref="ArgumentException">        /// The specified path does not exist or could not be found. -or-        /// The specified path contains wildcard characters. -or-        /// The specified path contains invalid path characters.        /// </exception>        public string Path        {            get => m_fileSystemWatcher.Path;            set => m_fileSystemWatcher.Path = value;        }         /// <summary>        /// Gets or sets the filter string used to determine what files are monitored in a directory.        /// </summary>        /// <returns>        /// The filter string. The default is "*.*" (Watches all files.)         /// </returns>        public string Filter        {            get => m_fileSystemWatcher.Filter;            set => m_fileSystemWatcher.Filter = value;        }         /// <summary>        /// Gets or sets the type of changes to watch for.        /// </summary>        /// <returns>        /// One of the <see cref="NotifyFilters"/> values. The default is the bitwise OR combination of LastWrite, FileName, and DirectoryName.</returns>        /// <exception cref="ArgumentException">The value is not a valid bitwise OR combination of the <see cref="NotifyFilters"/> values.</exception>        /// <exception cref="InvalidEnumArgumentException">The value that is being set is not valid.</exception>        public NotifyFilters NotifyFilter        {            get => m_fileSystemWatcher.NotifyFilter;            set => m_fileSystemWatcher.NotifyFilter = value;        }         /// <summary>        /// Gets or sets a value indicating whether the component is enabled.        /// </summary>        /// <returns>        /// true if the component is enabled; otherwise, false. The default is false. If you are using the component on a designer in Visual Studio 2005, the default is true.</returns>        /// <exception cref="ObjectDisposedException">The <see cref="FileSystemWatcher"/> object has been disposed.</exception>        /// <exception cref="PlatformNotSupportedException">The current operating system is not Microsoft Windows NT or later.</exception>        /// <exception cref="FileNotFoundException">The directory specified in <see cref="SafeFileWatcher.Path"/> could not be found.</exception>        /// <exception cref="ArgumentException"><see cref="SafeFileWatcher.Path"/> has not been set or is invalid.</exception>        public bool EnableRaisingEvents        {            get => m_fileSystemWatcher.EnableRaisingEvents;            set => m_fileSystemWatcher.EnableRaisingEvents = value;        }         /// <summary>        /// Gets or sets a value indicating whether subdirectories within the specified path should be monitored.        /// </summary>        /// <returns>        /// true if you want to monitor subdirectories; otherwise, false. The default is false.        /// </returns>        public bool IncludeSubdirectories        {            get => m_fileSystemWatcher.IncludeSubdirectories;            set => m_fileSystemWatcher.IncludeSubdirectories = value;        }         /// <summary>        /// Gets or sets the size of the internal buffer.        /// </summary>        /// <returns>        /// The internal buffer size. The default is 8192 (8K).        /// </returns>        public int InternalBufferSize        {            get => m_fileSystemWatcher.InternalBufferSize;            set => m_fileSystemWatcher.InternalBufferSize = value;        }         /// <summary>        /// Gets or sets the object used to marshal the event handler calls issued as a result of a directory change.        /// </summary>        /// <returns>        /// The <see cref="ISynchronizeInvoke"/> that represents the object used to marshal the event handler calls issued as a result of a directory change. The default is null.        /// </returns>        public ISynchronizeInvoke SynchronizingObject        {            get => m_fileSystemWatcher.SynchronizingObject;            set => m_fileSystemWatcher.SynchronizingObject = value;        }         /// <summary>        /// Gets or sets an <see cref="ISite"/> for the <see cref="SafeFileWatcher"/>.        /// </summary>        /// <returns>        /// An <see cref="ISite"/> for the <see cref="SafeFileWatcher"/>.        /// </returns>        public ISite Site        {            get => m_fileSystemWatcher.Site;            set => m_fileSystemWatcher.Site = value;        }         #endregion         #region [ Methods ]         /// <summary>        /// Releases all the resources used by the <see cref="SafeFileWatcher"/> object.        /// </summary>        public void Dispose()        {            Dispose(true);            GC.SuppressFinalize(this);        }         /// <summary>        /// Releases the unmanaged resources used by the <see cref="SafeFileWatcher"/> object and optionally releases the managed resources.        /// </summary>        /// <param name="disposing">true to release both managed and unmanaged resources; false to release only unmanaged resources.</param>        [SuppressMessage("Microsoft.Usage", "CA2213:DisposableFieldsShouldBeDisposed", MessageId = "m_fileSystemWatcher")]        protected virtual void Dispose(bool disposing)        {            if (m_disposed)                return;             try            {                // Treating file system watcher like an unmanaged resource                m_fileSystemWatcher?.Dispose();            }            finally            {                m_disposed = true;            }        }         /// <summary>        /// A synchronous method that returns a structure that contains specific information on the change that occurred, given the type of change you want to monitor.        /// </summary>        /// <returns>A <see cref="WaitForChangedResult"/> that contains specific information on the change that occurred.</returns>        /// <param name="changeType">The <see cref="WatcherChangeTypes"/> to watch for.</param>        public WaitForChangedResult WaitForChanged(WatcherChangeTypes changeType) =>             m_fileSystemWatcher.WaitForChanged(changeType);         /// <summary>        /// A synchronous method that returns a structure that contains specific information on the change that occurred, given the type of change you want to monitor and the time (in milliseconds) to wait before timing out.        /// </summary>        /// <returns>A <see cref="WaitForChangedResult"/> that contains specific information on the change that occurred.</returns>        /// <param name="changeType">The <see cref="WatcherChangeTypes"/> to watch for.</param>        /// <param name="timeout">The time (in milliseconds) to wait before timing out.</param>        public WaitForChangedResult WaitForChanged(WatcherChangeTypes changeType, int timeout) =>             m_fileSystemWatcher.WaitForChanged(changeType, timeout);         /// <summary>        /// Begins the initialization of a <see cref="SafeFileWatcher"/> used on a form or used by another component. The initialization occurs at run time.        /// </summary>        public void BeginInit() =>             m_fileSystemWatcher.BeginInit();         /// <summary>        /// Ends the initialization of a <see cref="SafeFileWatcher"/> used on a form or used by another component. The initialization occurs at run time.        /// </summary>        public void EndInit() =>             m_fileSystemWatcher.EndInit();         private void OnChanged(FileSystemEventArgs e) =>             Changed?.Invoke(this, e);         private void OnCreated(FileSystemEventArgs e) =>             Created?.Invoke(this, e);         private void OnDeleted(FileSystemEventArgs e) =>             Deleted?.Invoke(this, e);         private void OnRenamed(RenamedEventArgs e) =>             Renamed?.Invoke(this, e);         private void OnError(ErrorEventArgs e) =>             Error?.Invoke(this, e);         #endregion         #region [ Static ]         // Static Methods        private static void OnChanged(WeakReference<SafeFileWatcher> reference, FileSystemEventArgs e)        {            if (reference.TryGetTarget(out SafeFileWatcher instance))                instance.OnChanged(e);        }         private static void OnCreated(WeakReference<SafeFileWatcher> reference, FileSystemEventArgs e)        {            if (reference.TryGetTarget(out SafeFileWatcher instance))                instance.OnCreated(e);        }         private static void OnDeleted(WeakReference<SafeFileWatcher> reference, FileSystemEventArgs e)        {            if (reference.TryGetTarget(out SafeFileWatcher instance))                instance.OnDeleted(e);        }         private static void OnRenamed(WeakReference<SafeFileWatcher> reference, RenamedEventArgs e)        {            if (reference.TryGetTarget(out SafeFileWatcher instance))                instance.OnRenamed(e);        }         private static void OnError(WeakReference<SafeFileWatcher> reference, ErrorEventArgs e)        {            if (reference.TryGetTarget(out SafeFileWatcher instance))                instance.OnError(e);        }         #endregion    }}