Songbird / Development / Songbird Add-Ons API Documentation

components/filesystemevents/base/public/sbIFileSystemWatcher.idl

00001 /*
00002 //
00003 // BEGIN SONGBIRD GPL
00004 //
00005 // This file is part of the Songbird web player.
00006 //
00007 // Copyright(c) 2005-2009 POTI, Inc.
00008 // http://songbirdnest.com
00009 //
00010 // This file may be licensed under the terms of of the
00011 // GNU General Public License Version 2 (the "GPL").
00012 //
00013 // Software distributed under the License is distributed
00014 // on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either
00015 // express or implied. See the GPL for the specific language
00016 // governing rights and limitations.
00017 //
00018 // You should have received a copy of the GPL along with this
00019 // program. If not, go to http://www.gnu.org/licenses/gpl.html
00020 // or write to the Free Software Foundation, Inc.,
00021 // 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
00022 //
00023 // END SONGBIRD GPL
00024 //
00025 */
00026 
00027 #include "nsISupports.idl"
00028 
00029 interface sbIFileSystemListener;
00030 
00031 //
00032 // \brief A watcher interface that creates an XPCOM wrapper around filesystem
00033 //        events. Once a watcher instance is created - simply pass in the root
00034 //        path of the fileystem resources that need to be monitored. Callbacks
00035 //        will begin once |startWatching()| has been called.
00036 //
00037 [scriptable, uuid(61D13E2E-4927-4BAB-A327-23607AC4872F)]
00038 interface sbIFileSystemWatcher : nsISupports
00039 {
00040   //
00041   // \brief Initialize a file system watcher with a given path and listnener.
00042   // \param aListener The file sytem listener callback instance.
00043   // \param aRootPath The root file path to listen at.
00044   // \param aIsRecursive If the file path should be recusively watched.
00045   //
00046   void init(in sbIFileSystemListener aListener, 
00047             in AString aRootPath,
00048             in boolean aIsRecursive);
00049 
00050   //
00051   // \brief Initialize a file system watcher from a previous watched 
00052   //        session. Use this method to retreive change information since
00053   //        the watcher was last run. All previous changed callback information
00054   //        will be sent out before |onWatcherStarted()| is called.
00055   // \param aSessionGuid The session GUID to attempt to restore from.
00056   // \param aListener the file system listener callback instance.
00057   //
00058   void initWithSession(in ACString aSessionGuid,
00059                        in sbIFileSystemListener aListener);
00060 
00061   //
00062   // \brief  Start watching the path designated in |init()|.
00063   //         Once the watching has fully initialized, the listener will be
00064   //         informed via |onWatcherStarted()|.
00065   //
00066   void startWatching();
00067   
00068   //
00069   // \brief Stop watching the assigned path with the option to save 
00070   //        information from the watched session.
00071   //        NOTE:
00072   //          Once the watcher has fully stopped, the listener will be informed
00073   //          via |onWatcherStopped()|. 
00074   // \pram aShouldSaveSession If true, the watcher will save information about
00075   //                          the current state of the watched path.
00076   //
00077   void stopWatching(in boolean aShouldSaveSession);
00078 
00079   //
00080   // \brief When a session is saved in |stopWatching()|, serialized data is
00081   //        stored in the users profile. Use this method to remove the stored
00082   //        serialized data when a session is no longer needed.
00083   // \param aSessionGuid The GUID of the session to remove.
00084   //
00085   void deleteSession(in ACString aSessionGuid);
00086 
00087   //
00088   // \brief Find out if the watcher is running.
00089   //
00090   readonly attribute boolean isWatching;
00091   
00092   //
00093   // \brief Get the watch path of this watcher.
00094   //
00095   readonly attribute AString watchPath;
00096 
00097   //
00098   // \brief Get the session GUID of the file system watcher instance.
00099   //        NOTE: Use this value to restore a session and receive callback
00100   //              information about all changes since the session was last run.
00101   //
00102   readonly attribute ACString sessionGuid;
00103 
00104   //
00105   // \brief Find out if the file system watcher is supported on the current OS.
00106   // \return True if file system watcher is supported, false if not.
00107   //
00108   readonly attribute boolean isSupported;
00109 };
00110 

Generated on Tue Mar 10 14:28:54 2009 for Songbird by  doxygen 1.5.2