Merge from tizen_2.2.1
[platform/framework/native/appfw.git] / 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