sbIFileSystemWatcher.idl

Go to the documentation of this file.

/*
//
// BEGIN SONGBIRD GPL
//
// This file is part of the Songbird web player.
//
// Copyright(c) 2005-2009 POTI, Inc.
// http://songbirdnest.com
//
// This file may be licensed under the terms of of the
// GNU General Public License Version 2 (the "GPL").
//
// Software distributed under the License is distributed
// on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
// express or implied. See the GPL for the specific language
// governing rights and limitations.
//
// You should have received a copy of the GPL along with this
// program. If not, go to http://www.gnu.org/licenses/gpl.html
// or write to the Free Software Foundation, Inc.,
// 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
//
// END SONGBIRD GPL
//
*/

#include "nsISupports.idl"

interface sbIFileSystemListener;

//
// \brief A watcher interface that creates an XPCOM wrapper around filesystem
//        events. Once a watcher instance is created - simply pass in the root
//        path of the fileystem resources that need to be monitored. Callbacks
//        will begin once |startWatching()| has been called.
//
[scriptable, uuid(61D13E2E-4927-4BAB-A327-23607AC4872F)]
interface sbIFileSystemWatcher : nsISupports
{
  //
  // \brief Initialize a file system watcher with a given path and listnener.
  // \param aListener The file sytem listener callback instance.
  // \param aRootPath The root file path to listen at.
  // \param aIsRecursive If the file path should be recusively watched.
  //
  void init(in sbIFileSystemListener aListener, 
            in AString aRootPath,
            in boolean aIsRecursive);

  //
  // \brief Initialize a file system watcher from a previous watched 
  //        session. Use this method to retreive change information since
  //        the watcher was last run. All previous changed callback information
  //        will be sent out before |onWatcherStarted()| is called.
  // \param aSessionGuid The session GUID to attempt to restore from.
  // \param aListener the file system listener callback instance.
  //
  void initWithSession(in ACString aSessionGuid,
                       in sbIFileSystemListener aListener);

  //
  // \brief  Start watching the path designated in |init()|.
  //         Once the watching has fully initialized, the listener will be
  //         informed via |onWatcherStarted()|.
  //
  void startWatching();
  
  //
  // \brief Stop watching the assigned path with the option to save 
  //        information from the watched session.
  //        NOTE:
  //          Once the watcher has fully stopped, the listener will be informed
  //          via |onWatcherStopped()|. 
  // \pram aShouldSaveSession If true, the watcher will save information about
  //                          the current state of the watched path.
  //
  void stopWatching(in boolean aShouldSaveSession);

  //
  // \brief When a session is saved in |stopWatching()|, serialized data is
  //        stored in the users profile. Use this method to remove the stored
  //        serialized data when a session is no longer needed.
  // \param aSessionGuid The GUID of the session to remove.
  //
  void deleteSession(in ACString aSessionGuid);

  //
  // \brief Find out if the watcher is running.
  //
  readonly attribute boolean isWatching;
  
  //
  // \brief Get the watch path of this watcher.
  //
  readonly attribute AString watchPath;

  //
  // \brief Get the session GUID of the file system watcher instance.
  //        NOTE: Use this value to restore a session and receive callback
  //              information about all changes since the session was last run.
  //
  readonly attribute ACString sessionGuid;

  //
  // \brief Find out if the file system watcher is supported on the current OS.
  // \return True if file system watcher is supported, false if not.
  //
  readonly attribute boolean isSupported;
};