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 was 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 the 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 methods 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,
  81  * this class will send an event for the directory or file itself, and for sub-files or sub-directories inside the observed directory.
  82  *
  83  * @code
  84  *
  85  * #include <FBase.h>
  86  * #include <FIo.h>
  87  * #include <FApp.h>
  88  *
  89  * using namespace Tizen::Base;
  90  * using namespace Tizen::Io;
  91  * using namespace Tizen::App;
  92  *
  93  * class MyFileEventListener
  94  * : public Tizen::Io::IFileEventListener
  95  * {
  96  * public:
  97  *      void OnFileEventOccured(const unsigned long events, const Tizen::Base::String &path, const unsigned int eventId)
  98  *      {
  99  *              if (events & FILE_EVENT_TYPE_DELETE)
 100  *              {
 101  *                      AppLog(“File path (%ls) is deleted.”, path.GetPointer());
 102  *              }
 103  *      }
 104  * };
 105  *
 106  * void
 107  * MyClass::Initialize(void)
 108  * {
 109  *      MyFileEventListener* pMyFileEventListener = new MyFileEventListener();
 110  *
 111  *      FileEventManager* pFileEventMgr = new FileEventManager();
 112  *      pFileEventMgr->Construct(*pMyFileEventListener);
 113  *
 114  *      String filePath(App::GetInstance()->GetAppDataPath() + L”myFile.txt”);
 115  *      pFileEventMgr->AppPath(filePath, FILE_EVENT_TYPE_DELETE);
 116  * }
 117  *
 118  * @endcode
 119  */
 120 class _OSP_EXPORT_ FileEventManager
 121         : public Tizen::Base::Object
 122 {
 123
 124 public:
 125         /**
 126         * The object is not fully constructed after this constructor is called. @n
 127         * For full construction, the Construct() method must be called right after calling this constructor.
 128         *
 129         * @since                2.0
 130         */
 131         FileEventManager(void);
 132
 133         /**
 134         * This destructor overrides Tizen::Base::Object::~Object().
 135         *
 136         * @since                2.0
 137         */
 138         virtual ~FileEventManager(void);
 139
 140         /**
 141         * Initializes this instance of %FileEventManager.
 142         *
 143         * @since                2.0
 144         *
 145         * @return               An error code
 146         * @param[in]    listener                        The listener to be invoked when monitored files are changed
 147         * @exception    E_SUCCESS                       The method is successful.
 148         * @exception    E_MAX_EXCEEDED          The number of opened files has exceeded the maximum limit.
 149         * @exception    E_IO                            Either of the following conditions has occurred:
 150         *                                                                       - The specified listener cannot be registered in worker thread.
 151         *                                                                       - Detected corruption of a file.
 152         */
 153         result Construct(IFileEventListener& listener);
 154
 155
 156         /**
 157         * Adds the monitor file, or modifies an existing monitor file in the specified path. @n
 158         * The application must have read permission for this @c path. The file event type can be set in @c eventsToMonitor.
 159         *
 160         * @since                2.0
 161         *
 162         * @return               An error code
 163         * @param[in]    path                            The path to the directory or file to monitor
 164         * @param[in]    eventsToMonitor         The kind of event to monitor @n
 165         *                                                                       Multiple event types can be combined using bitwise OR (see Tizen::Io::FileEventType). @n
 166         *                                                                       The ::FILE_EVENT_TYPE_ALL is provided for all file event types. @n
 167         *                                                                       If a specific @c eventsToMonitor is set, the events that have the specified file event are returned.
 168         * @exception    E_SUCCESS                       The method is successful.
 169         * @exception    E_INVALID_ARG           The specified eventsToMonitor contains no valid events.
 170         * @exception    E_FILE_NOT_FOUND        An entry for the specified path could not be found.
 171         * @exception    E_ILLEGAL_ACCESS        The specified path is not permitted.
 172         * @exception    E_IO                            Either of the following conditions has occurred:
 173         *                                                                       - The specified path is outside the process's accessible address space.
 174         *                                                                       - The number of file monitors has exceeded the maximum limit.
 175         *                                                                       - Failed to allocate a needed resource.
 176         *                                                                       - Detected corruption of a file.
 177         * @see                  FileEventType
 178         */
 179         result AddPath(const Tizen::Base::String& path, unsigned long eventsToMonitor);
 180
 181         /**
 182         * Removes the specified monitored file associated with the current instance.
 183         *
 184         * @since                2.0
 185         *
 186         * @return                       An error code
 187         * @param[in]            path                    The path to the directory or file that is monitored
 188         * @exception            E_SUCCESS               The method is successful.
 189         * @exception            E_IO                    The specified path is not monitored.
 190         */
 191         result RemovePath(const Tizen::Base::String& path);
 192
 193 private:
 194         /**
 195         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 196         *
 197         * @since 2.0
 198         */
 199         FileEventManager(const FileEventManager& fileEventManager);
 200
 201         /**
 202         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 203         *
 204         * @since 2.0
 205         */
 206         FileEventManager& operator =(const FileEventManager& fileEventManager);
 207
 208         class _FileEventManagerImpl* __pFileEventManagerImpl;
 209
 210         friend class _FileEventManagerImpl;
 211
 212 }; // FileEventManager
 213
 214 }} // Tizen::Io
 215
 216 #endif //_FIO_FILE_EVENT_MANAGER_H_
 217