2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
17 * @file FCntContentManager.h
18 * @brief This is the header file for the %ContentManager class.
20 * This header file contains the declarations of the %ContentManager class.
23 #ifndef _FCNT_CONTENT_MANAGER_H_
24 #define _FCNT_CONTENT_MANAGER_H_
26 #include <FBaseObject.h>
27 #include <FCntTypes.h>
29 namespace Tizen { namespace Base
34 namespace Tizen { namespace Content
38 class _ContentManagerImpl;
39 class IContentScanListener;
40 class IContentUpdateEventListener;
43 * @class ContentManager
44 * @brief This class provides methods for local content management.
48 * @final This class is not intended for extension.
50 * The %ContentManager class manages the information stored locally on the device's content database. @n
51 * It also allows the user to create, read, update, and delete specific content information in the database.
53 * For more information on managing content on the device, see <a href="../org.tizen.native.appprogramming/html/guide/content/device_content_mgmt.htm">Device Content Management</a>.
55 * The following example demonstrates how to use the %ContentManager class.
60 * #include <FContent.h>
61 * #include <FSystem.h>
63 * using namespace Tizen::Content;
66 * MyClass::TestContentManager(void)
68 * ContentManager contentManager;
69 * result r = contentManager.Construct();
72 * ImageContentInfo imageContentInfo;
73 * r = imageContentInfo.Construct(null);
75 * r = imageContentInfo.SetKeyword(L"platform, tizen");
76 * r = imageContentInfo.SetLocationTag(L"seoul");
78 * Tizen::Base::String sourcePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/flower.jpg";
79 * Tizen::Base::String destPath = Tizen::System::Environment::GetMediaPath() + L"Images/flower.jpg";
81 * ContentId contentId = contentManager.CreateContent(sourcePath, destPath, false, &imageContentInfo);
82 * r = GetLastResult();
85 * ImageContentInfo* pImageContentInfo = dynamic_cast< ImageContentInfo* >(contentManager.GetContentInfoN(contentId));
86 * r = GetLastResult();
88 * pImageContentInfo->GetContentPath();
91 * r = pImageContentInfo->SetKeyword(L"apple, fruit");
92 * r = pImageContentInfo->SetProvider(L"kw1128");
93 * r = contentManager.UpdateContent(*pImageContentInfo);
96 * r = contentManager.DeleteContent(contentId);
98 * delete pImageContentInfo;
103 class _OSP_EXPORT_ ContentManager
104 : virtual public Tizen::Base::Object
109 * The object is not fully constructed after this constructor is called. @n
110 * For full construction, the Construct() method must be called right after calling this constructor.
114 ContentManager(void);
117 * This destructor overrides Tizen::Base::Object::~Object().
121 virtual ~ContentManager(void);
124 * Initializes this instance of %ContentManager.
128 * @return An error code
129 * @exception E_SUCCESS The method is successful.
130 * @exception E_SYSTEM A system error has occurred.
132 result Construct(void);
135 * Creates the content information.
139 * @privilege %http://tizen.org/privilege/content.write
141 * @return The content ID
142 * @param[in] contentInfo An instance of ContentInfo
143 * @exception E_SUCCESS The method is successful.
144 * @exception E_INVALID_ARG Either of the following conditions has occurred:
145 * - The specified input parameter is invalid.
146 * - The specified format is either invalid or not supported on the device.
147 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
148 * @exception E_IO An I/O error has occurred.
149 * @exception E_SYSTEM A system error has occurred.
150 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
151 * @exception E_SERVICE_BUSY The database is busy.
153 * - If the @c E_UNSUPPORTED_FORMAT exception is received from ContentManagerUtil::CheckContentType(),
154 * the file can be created as content only using the OtherContentInfo class.
155 * - The specific error code can be accessed using the GetLastResult() method.
157 ContentId CreateContent(const ContentInfo& contentInfo);
160 * Writes the content in the byte buffer to the destination path and creates the content information.
163 * @brief <i> [Compatibility] </i>
167 * @compatibility This method has compatibility issues with OSP compatible applications. @n
168 * For more information, see @ref CompContentManagerCreateContentPage "here".
171 * @privilege %http://tizen.org/privilege/content.write
173 * @return The content ID
174 * @param[in] byteBuffer The @c byteBuffer of the content to create
175 * @param[in] destinationPath The destination file path formed by the @c byteBuffer @n
176 * The path should start with the directory path returned by either
177 * Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath().
178 * @param[in] pContentInfo A pointer to the ContentInfo instance @n
179 * If the content path exists in %ContentInfo, it gets ignored.
180 * @exception E_SUCCESS The method is successful.
181 * @exception E_INVALID_ARG Either of the following conditions has occurred:
182 * - A specified input parameter is invalid.
183 * - There is a mismatch between the type specified in ContentInfo and the type specified in the actual content.
184 * @exception E_STORAGE_FULL The storage is full.
185 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
186 * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
187 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
188 * @exception E_IO An I/O error has occurred.
189 * @exception E_SYSTEM A system error has occurred.
190 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
191 * @exception E_SERVICE_BUSY The database is busy.
192 * @remarks The specific error code can be accessed using the GetLastResult() method.
194 ContentId CreateContent(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Base::String& destinationPath, const ContentInfo* pContentInfo = null);
197 * Copies or moves the actual content to the destination path and creates the content information.
200 * @brief <i> [Compatibility] </i>
204 * @compatibility This method has compatibility issues with OSP compatible applications. @n
205 * For more information, see @ref CompContentManagerCreateContentPage "here".
208 * @privilege %http://tizen.org/privilege/content.write
210 * @return The content ID
211 * @param[in] sourcePath The source file path @n
212 * The path should start with the directory path returned by either Tizen::App::App::GetAppRootPath()
213 * or Tizen::System::Environment::GetExternalStoragePath().
214 * @param[in] destinationPath The destination file path @n
215 * The path should start with the directory path returned by either Tizen::System::Environment::GetMediaPath()
216 * or Tizen::System::Environment::GetExternalStoragePath().
217 * @param[in] deleteSource Set to @c true in order to delete the source file, @n
219 * @param[in] pContentInfo A pointer to the ContentInfo instance @n
220 * If the content path exists in %ContentInfo, it gets ignored.
221 * @exception E_SUCCESS The method is successful.
222 * @exception E_INVALID_ARG Either of the following conditions has occurred:
223 * - A specified input parameter is invalid.
224 * - There is a mismatch between the type of the source path and the destination path.
225 * - There is a mismatch between the type specified in ContentInfo and the type specified in the actual content.
226 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
227 * @exception E_STORAGE_FULL The storage is full.
228 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
229 * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
230 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
231 * @exception E_IO An I/O error has occurred.
232 * @exception E_SYSTEM A system error has occurred.
233 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
234 * @exception E_SERVICE_BUSY The database is busy.
235 * @remarks The specific error code can be accessed using the GetLastResult() method.
237 ContentId CreateContent(const Tizen::Base::String& sourcePath, const Tizen::Base::String& destinationPath, bool deleteSource, const ContentInfo* pContentInfo = null);
241 * @page CompContentManagerCreateContentPage Compatibility for the file path.
242 * @section CompContentManagerCreateContentPageIssueSection Issues
243 * The content path argument of this method in OSP compatible applications has the following issues: @n
244 * -# The content path should be a path that begins with an allowed path prefix. @n
245 * For example, L"/Media/Images/flower.jpg", L"/Storagecard/Media/Images/flower.jpg".
247 * @section CompContentManagerCreateContentPageSolutionSection Resolutions
248 * This issue has been resolved in Tizen. @n
249 * -# The content path can be a path without a specific allowed path prefix. @n
250 * Applications do not need to know the specific allowed path prefixes. @n
251 * To get the directory path, use the following methods: @n
252 * - For accessing the home directory, use Tizen::App::App::GetInstance()->GetAppRootPath().
253 * - For accessing the media directory, use Tizen::System::Environment::GetMediaPath().
254 * - For accessing the external storage, use Tizen::System::Environment::GetExternalStoragePath().
260 * Gets the content information.
264 * @privilege %http://tizen.org/privilege/content.read
266 * @return A pointer to ContentInfo
267 * @param[in] contentId The content ID
268 * @exception E_SUCCESS The method is successful.
269 * @exception E_INVALID_ARG Either of the following conditions has occurred:
270 * - The specified input parameter is invalid.
271 * - The content information corresponding to @c contentId cannot be found.
272 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
273 * @exception E_SYSTEM A system error has occurred.
274 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
275 * @exception E_SERVICE_BUSY The database is busy.
276 * @remarks The specific error code can be accessed using the GetLastResult() method.
278 ContentInfo* GetContentInfoN(const ContentId& contentId) const;
281 * Updates the content information with the specified instance of ContentInfo.
285 * @privilege %http://tizen.org/privilege/content.write
287 * @return An error code
288 * @param[in] contentInfo An instance of ContentInfo
289 * @exception E_SUCCESS The method is successful.
290 * @exception E_INVALID_ARG The specified input parameter is invalid.
291 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
292 * @exception E_SYSTEM A system error has occurred.
293 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
294 * @exception E_SERVICE_BUSY The database is busy.
296 result UpdateContent(const ContentInfo& contentInfo);
299 * Deletes the content information with the specified content ID.
303 * @privilege %http://tizen.org/privilege/content.write
305 * @return An error code
306 * @param[in] contentId The content ID
307 * @exception E_SUCCESS The method is successful.
308 * @exception E_INVALID_ARG Either of the following conditions has occurred:
309 * - The specified input parameter is invalid.
310 * - The content information corresponding to @c contentId cannot be found.
311 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
312 * @exception E_ILLEGAL_ACCESS The access is denied due to insufficient permission.
313 * @exception E_SYSTEM A system error has occurred.
314 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
315 * @exception E_SERVICE_BUSY The database is busy.
316 * @remarks The physical file corresponding to @c contentId is deleted.
318 result DeleteContent(const ContentId& contentId);
321 * Adds a listener to receive the database change notification.
325 * @return An error code
326 * @param[in] listener The event listener to add
327 * @exception E_SUCCESS The method is successful.
328 * @exception E_OBJ_ALREADY_EXIST The listener has already been added.
329 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
330 * @remarks Only a listener of an instance can be added. If you add more than two listeners, the listener added first receives the notification for the DB change.
332 result AddContentUpdateEventListener(IContentUpdateEventListener& listener);
335 * Removes a listener which is registered to receive the database change notification.
339 * @return An error code
340 * @param[in] listener The event listener to remove
341 * @exception E_SUCCESS The method is successful.
342 * @exception E_OBJ_NOT_FOUND The listener is not found.
343 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
345 result RemoveContentUpdateEventListener(IContentUpdateEventListener& listener);
349 * Requests to synchronize a specified file with the database.
353 * @privilege %http://tizen.org/privilege/content.write
355 * @return An error code
356 * @param[in] contentPath The content path
357 * @exception E_SUCCESS The method is successful.
358 * @exception E_INVALID_ARG The specified input parameter is invalid.
359 * @exception E_SERVICE_BUSY The database is busy.
360 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
361 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
363 static result ScanFile(const Tizen::Base::String& contentPath);
366 * Requests to synchronize files in the specified directory with the database.
370 * @privilege %http://tizen.org/privilege/content.write
372 * @return An error code
373 * @param[in] directoryPath The directory path
374 * @param[in] recursive Set to @c true in order to recursively scan sub directories, @n
376 * @param[in] pListener The scan event listener
377 * @param[out] reqId The request ID
378 * @exception E_SUCCESS The method is successful.
379 * @exception E_INVALID_ARG The specified input parameter is invalid.
380 * @exception E_SERVICE_BUSY The database is busy.
381 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
382 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
383 * @remarks Platform does not have the ownership of the listener.
385 static result ScanDirectory(const Tizen::Base::String& directoryPath, bool recursive, IContentScanListener* pListener, RequestId& reqId);
389 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
391 ContentManager(const ContentManager& rhs);
394 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
396 ContentManager& operator =(const ContentManager& rhs);
399 friend class _ContentManagerImpl;
400 _ContentManagerImpl* __pContentManagerImpl;
406 #endif // _FCNT_CONTENT_MANAGER_H_