Merge "Change the way to Convert UTF8 to wchar_t, and vice versa" into tizen_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 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