inc/FIoFileEventManager.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16
  17 /**
  18  * @file        FIoFileEventManager.h
  19  * @brief       This is the header file for the %FileEventManager class.
  20  *
  21  * This header file contains the declarations of the %FileEventManager class.
  22  */
  23
  24 #ifndef _FIO_FILE_EVENT_MANAGER_H_
  25 #define _FIO_FILE_EVENT_MANAGER_H_
  26
  27 #include <FBaseObject.h>
  28
  29 namespace Tizen { namespace Base
  30 {
  31 class String;
  32 }}
  33
  34 namespace Tizen { namespace Io
  35 {
  36
  37 class IFileEventListener;
  38 class _FileEventManagerImpl;
  39
  40 /**
  41  * @enum FileEventType
  42  *
  43  * Defines the file event type.
  44  *
  45  * @since       2.0
  46  */
  47 enum FileEventType
  48 {
  49         FILE_EVENT_TYPE_ACCESS = 0x01, /**<%File was accessed (read)*/
  50         FILE_EVENT_TYPE_ATTRIBUTE = 0x04, /**<Metadata changed*/
  51         FILE_EVENT_TYPE_CLOSE_WRITE = 0x08, /**<%File opened for writing was closed*/
  52         FILE_EVENT_TYPE_CLOSE_NOWRITE = 0x10, /**<%File not opened for writing was closed*/
  53         FILE_EVENT_TYPE_CREATE = 0x100, /**<%File/directory created in monitored directory*/
  54         FILE_EVENT_TYPE_DELETE = 0x200, /**<%File/directory deleted from monitored directory*/
  55         FILE_EVENT_TYPE_DELETE_SELF = 0x400, /**<Monitored file/directory was itself deleted.*/
  56         FILE_EVENT_TYPE_MODIFY = 0x02, /**<%File was modified*/
  57         FILE_EVENT_TYPE_MOVE_SELF = 0x800, /**<Monitored file/directory was itself moved.*/
  58         FILE_EVENT_TYPE_MOVED_FROM = 0x40, /**<%File moved out of monitored directory. */
  59         FILE_EVENT_TYPE_MOVED_TO = 0x80, /**<%File moved into monitored directory. */
  60         FILE_EVENT_TYPE_OPEN = 0x20 /**<%File was opened. */
  61 };
  62
  63 /**
  64  * All file event types.
  65  *
  66  * @since 2.0
  67  */
  68 static const unsigned long FILE_EVENT_TYPE_ALL = FILE_EVENT_TYPE_ACCESS | FILE_EVENT_TYPE_ATTRIBUTE | FILE_EVENT_TYPE_CLOSE_WRITE |
  69                 FILE_EVENT_TYPE_CLOSE_NOWRITE | FILE_EVENT_TYPE_CREATE | FILE_EVENT_TYPE_DELETE | FILE_EVENT_TYPE_DELETE_SELF |
  70                 FILE_EVENT_TYPE_MODIFY | FILE_EVENT_TYPE_MOVE_SELF | FILE_EVENT_TYPE_MOVED_FROM | FILE_EVENT_TYPE_MOVED_TO | FILE_EVENT_TYPE_OPEN;
  71
  72 /**
  73  * @class       FileEventManager
  74  * @brief       This class provides a mechanism for monitoring file system events.
  75  *
  76  * @since       2.0
  77  *
  78  * @final       This class is not intended for extension.
  79  *
  80  * The %FileEventManager class can be used to monitor individual files or directories. When a directory is monitored, this class will send an event for the directory or file itself, and for sub-files or sub-directories inside the observed directory.
  81  *
  82  * @code
  83  *
  84  * #include <FBase.h>
  85  * #include <FIo.h>
  86  * #include <FApp.h>
  87  *
  88  * using namespace Tizen::Base;
  89  * using namespace Tizen::Io;
  90  * using namespace Tizen::App;
  91  *
  92  * class MyFileEventListener
  93  * : public Tizen::Io::IFileEventListener
  94  * {
  95  * public:
  96  *      void OnFileEventOccured(const unsigned long events, const Tizen::Base::String &path, const unsigned int eventId)
  97  *      {
  98  *              if (events & FILE_EVENT_TYPE_DELETE)
  99  *              {
 100  *                      AppLog(“File path (%ls) is deleted.”, path.GetPointer());
 101  *              }
 102  *      }
 103  * };
 104  *
 105  * void
 106  * MyClass::Initialize(void)
 107  * {
 108  *      MyFileEventListener* pMyFileEventListener = new MyFileEventListener();
 109  *
 110  *      FileEventManager* pFileEventMgr = new FileEventManager();
 111  *      pFileEventMgr->Construct(*pMyFileEventListener);
 112  *
 113  *      String filePath(App::GetInstance()->GetAppDataPath() + L”myFile.txt”);
 114  *      pFileEventMgr->AppPath(filePath, FILE_EVENT_TYPE_DELETE);
 115  * }
 116  *
 117  * @endcode
 118  */
 119 class _OSP_EXPORT_ FileEventManager
 120         : public Tizen::Base::Object
 121 {
 122
 123 public:
 124         /**
 125         * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 126         *
 127         * @since                2.0
 128         */
 129         FileEventManager(void);
 130
 131         /**
 132         * This destructor overrides Tizen::Base::Object::~Object().
 133         *
 134         * @since                2.0
 135         */
 136         virtual ~FileEventManager(void);
 137
 138         /**
 139         * Initializes this instance of %FileEventManager. @n
 140         *
 141         * @since                2.0
 142         *
 143         * @return               An error code
 144         * @param[in]    listener                        A listener invoked when monitored files are changed.
 145         * @exception    E_SUCCESS                       The method is successful.
 146         * @exception    E_MAX_EXCEEDED          The number of opened files has exceeded the maximum limit.
 147         * @exception    E_IO                            Either of the following conditions has occurred: @n
 148         *                                                                       - The specified listener cannot be registered in worker thread.
 149         *                                                                       - Detected corruption of a file.
 150         */
 151         result Construct(IFileEventListener& listener);
 152
 153
 154         /**
 155         * Adds a new monitor file, or modifies an existing monitor file, for the file whose location is specified in path; the application has to have read permission for this %path. %File event type can be set in %eventsToMonitor.
 156         *
 157         * @since                2.0
 158         *
 159         * @return               An error code
 160         * @param[in]    path                            The path to the directory or file to monitor
 161         * @param[in]    eventsToMonitor         The kind of event to monitor @n
 162         *                                                                       Multiple event type can be combined using bitwise OR (see Tizen::Io::FileEventType). @n
 163         *                                                                       The Tizen::Io::FILE_EVENT_TYPE_ALL is provided for all file event type @n
 164         *                                                                       If a specific eventsToMonitor is set, the events that have the specified file event are returned.
 165         * @exception    E_SUCCESS                       The method is successful.
 166         * @exception    E_INVALID_ARG           The specified eventsToMonitor contains no valid events.
 167         * @exception    E_FILE_NOT_FOUND        An entry for the specified path could not be found.
 168         * @exception    E_ILLEGAL_ACCESS        The specified path is not permitted.
 169         * @exception    E_IO                            Either of the following conditions has occurred: @n
 170         *                                                                       - The specified path outside of the process's accessible address space. @n
 171         *                                                                       - The number of file monitor has been exceeded the maximum limit or
 172         *                                                                         the failed to allocate a needed resource. @n
 173         *                                                                       - Detected corruption of a file.
 174         * @see                  FileEventType
 175         */
 176         result AddPath(const Tizen::Base::String& path, unsigned long eventsToMonitor);
 177
 178         /**
 179         * Removes the monitored file associated with the current instance.
 180         *
 181         * @since                2.0
 182         *
 183         * @return               An error code
 184         * @param[in]            path                    The path to the directory or file that is monitored
 185         * @exception            E_SUCCESS               The method is successful.
 186         * @exception            E_IO                    The specified path is not monitored.
 187         */
 188         result RemovePath(const Tizen::Base::String& path);
 189
 190 private:
 191         /**
 192         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 193         *
 194         * @since 2.0
 195         */
 196         FileEventManager(const FileEventManager& fileEventManager);
 197
 198         /**
 199         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 200         *
 201         * @since 2.0
 202         */
 203         FileEventManager& operator =(const FileEventManager& fileEventManager);
 204
 205         class _FileEventManagerImpl* __pFileEventManagerImpl;
 206
 207         friend class _FileEventManagerImpl;
 208
 209 }; // FileEventManager
 210
 211 }} // Tizen::Io
 212
 213 #endif //_FIO_FILE_EVENT_MANAGER_H_
 214