inc/FIoFileEventManager.h

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