2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FCntContentManager.h
19 * @brief This is the header file for the %ContentManager class.
21 * This header file contains the declarations of the %ContentManager class.
24 #ifndef _FCNT_CONTENT_MANAGER_H_
25 #define _FCNT_CONTENT_MANAGER_H_
27 #include <FBaseObject.h>
28 #include <FCntTypes.h>
30 namespace Tizen { namespace Base
35 namespace Tizen { namespace Content
39 class _ContentManagerImpl;
40 class IContentScanListener;
41 class IContentUpdateEventListener;
44 * @class ContentManager
45 * @brief This class provides methods for local content management.
49 * The %ContentManager class manages the information stored locally on the device's content database. @n
50 * It also allows you to create, read, update, and delete specific content information in the database.
52 * 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>.
54 * The following example demonstrates how to use the %ContentManager class.
58 * MyClass::TestContentManager(void)
60 * result r = E_SUCCESS;
61 * ContentId contentId;
62 * ContentManager contentManager;
63 * r = contentManager.Construct();
64 * TryReturn(!IsFailed(r), r, "Construct failed.");
67 * ImageContentInfo imageContentInfo;
68 * r = imageContentInfo.Construct(null);
69 * TryReturn(!IsFailed(r), r, "Construct failed.");
71 * r = imageContentInfo.SetKeyword(L"platform, tizen");
77 * r = imageContentInfo.SetLocationTag(L"seoul");
83 * Tizen::Base::String sourcePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/flower.jpg";
84 * Tizen::Base::String destPath = Tizen::System::Environment::GetMediaPath() + L"Images/flower.jpg";
86 * contentId = contentManager.CreateContent(sourcePath, destPath, false, &imageContentInfo);
87 * TryReturn(Tizen::Base::UuId::GetInvalidUuId() != contentId, GetLastResult(), "CreateContent failed.");
90 * ImageContentInfo* pImageContentInfo = null;
91 * pImageContentInfo = dynamic_cast<ImageContentInfo*>(contentManager.GetContentInfoN(contentId));
92 * TryReturn(pImageContentInfo != null, GetLastResult(), "GetContentInfoN failed.");
94 * pImageContentInfo->GetContentPath();
97 * r = pImageContentInfo->SetKeyword(L"apple, fruit");
100 * delete pImageContentInfo;
103 * r = pImageContentInfo->SetProvider(L"kw1128");
106 * delete pImageContentInfo;
109 * r = contentManager.UpdateContent(*pImageContentInfo);
112 * delete pImageContentInfo;
117 * r = contentManager.DeleteContent(contentId);
120 * delete pImageContentInfo;
124 * delete pImageContentInfo;
129 class _OSP_EXPORT_ ContentManager
130 : virtual public Tizen::Base::Object
135 * 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.
139 * @remarks After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
141 ContentManager(void);
144 * This destructor overrides Tizen::Base::Object::~Object().
148 virtual ~ContentManager(void);
151 * Initializes this instance of %ContentManager.
155 * @return An error code
156 * @exception E_SUCCESS The method is successful.
157 * @exception E_OUT_OF_MEMORY The memory is insufficient.
158 * @exception E_SYSTEM A system error has occurred.
160 result Construct(void);
163 * Creates the content information.
167 * @privilege http://tizen.org/privilege/content.write
169 * @return The content ID
170 * @param[in] contentInfo An instance of ContentInfo
171 * @exception E_SUCCESS The method is successful.
172 * @exception E_INVALID_ARG The specified input parameter is invalid, or
173 * the specified format is invalid or not supported on the device.
174 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
175 * @exception E_IO An I/O error has occurred.
176 * @exception E_OUT_OF_MEMORY The memory is insufficient.
177 * @exception E_SYSTEM A system error has occurred.
178 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
179 * @exception E_SERVICE_BUSY The database is busy.
180 * @remarks If the E_UNSUPPORTED_FORMAT exception is received from ContentManagerUtil::CheckContentType(),
181 * the file can be created as a content only using the OtherContentInfo class. @n
182 * The specific error code can be accessed using the GetLastResult() method.
184 ContentId CreateContent(const ContentInfo& contentInfo);
187 * Writes the content in the byte buffer to the destination path and creates the content information.
190 * @brief <i> [Compatibility] </i>
194 * @compatibility This method has compatibility issues with OSP compatible applications. @n
195 * For more information, see @ref CompContentManagerCreateContentPage "here".
198 * @privilege http://tizen.org/privilege/content.write
200 * @return The content ID
201 * @param[in] byteBuffer The @c byteBuffer of the content to create
202 * @param[in] destinationPath The destination file path formed by the @c byteBuffer
203 * @param[in] pContentInfo A pointer to the ContentInfo instance @n
204 * If the content path exists in %ContentInfo, it gets ignored.
205 * @exception E_SUCCESS The method is successful.
206 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
207 * - A specified input parameter is invalid. @n
208 * - There is a mismatch between the type specified in ContentInfo and the type specified in the actual content.
209 * @exception E_STORAGE_FULL The storage is full.
210 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
211 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
212 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
213 * @exception E_IO An I/O error has occurred.
214 * @exception E_OUT_OF_MEMORY The memory is insufficient.
215 * @exception E_SYSTEM A system error has occurred.
216 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
217 * @exception E_SERVICE_BUSY The database is busy.
218 * @remarks The destination path should start with the directory path returned by either Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath(). @n
219 * The specific error code can be accessed using the GetLastResult() method. @n
220 * For using CreateContent(), check @ref CreateContentUsage "here".
222 ContentId CreateContent(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Base::String& destinationPath, const ContentInfo* pContentInfo = null);
225 * Copies or moves the actual content to the destination path and creates the content information.
228 * @brief <i> [Compatibility] </i>
232 * @compatibility This method has compatibility issues with OSP compatible applications. @n
233 * For more information, see @ref CompContentManagerCreateContentPage "here".
236 * @privilege http://tizen.org/privilege/content.write
238 * @return The content ID
239 * @param[in] sourcePath The source file path
240 * @param[in] destinationPath The destination file path
241 * @param[in] deleteSource Set to @c true in order to delete the source file, @n
243 * @param[in] pContentInfo A pointer to the ContentInfo instance @n
244 * If the content path exists in %ContentInfo, it gets ignored.
245 * @exception E_SUCCESS The method is successful.
246 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
247 * - A specified input parameter is invalid. @n
248 * - There is a mismatch between the type of the source path and destination path. @n
249 * - There is a mismatch between the type specified in ContentInfo and the type specified in the actual content.
250 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
251 * @exception E_STORAGE_FULL The storage is full.
252 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
253 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
254 * @exception E_MAX_EXCEEDED The number of opened files has exceeded the maximum limit.
255 * @exception E_IO An I/O error has occurred.
256 * @exception E_OUT_OF_MEMORY The memory is insufficient.
257 * @exception E_SYSTEM A system error has occurred.
258 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
259 * @exception E_SERVICE_BUSY The database is busy.
260 * @remarks The source path should start with the directory path returned by either Tizen::App::App::GetAppRootPath() or Tizen::System::Environment::GetExternalStoragePath(). @n
261 * The destination path should start with the directory path returned by either Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath(). @n
262 * The specific error code can be accessed using the GetLastResult() method. @n
263 * For using CreateContent(), check @ref CreateContentUsage "here".
265 ContentId CreateContent(const Tizen::Base::String& sourcePath, const Tizen::Base::String& destinationPath, bool deleteSource, const ContentInfo* pContentInfo = null);
269 * @page CompContentManagerCreateContentPage Compatibility for the file path.
270 * @section CompContentManagerCreateContentPageIssueSection Issues
271 * The content path argument of this method in OSP compatible applications has the following issues: @n
272 * -# The content path should be a path that begins with an allowed path prefix. @n
273 * For example, L"/Media/Images/flower.jpg", L"/Storagecard/Media/Images/flower.jpg".
275 * @section CompContentManagerCreateContentPageSolutionSection Resolutions
276 * This issue has been resolved in Tizen. @n
277 * -# The content path can be a path without a specific allowed path prefix. @n
278 * Application do not need to know the specific allowed path prefixes. @n
279 * To get the directory path, use the following methods: @n
280 * - For accessing the home directory, use Tizen::App::App::GetInstance()->GetAppRootPath().
281 * - For accessing the media directory, use Tizen::System::Environment::GetMediaPath().
282 * - For accessing the external storage, use Tizen::System::Environment::GetExternalStoragePath().
288 * @page CreateContentUsage How To Use CreateContent()
289 * @section CreateContentUsageFirst 1. CreateContent(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Base::String& destinationPath, const ContentInfo* pContentInfo = null)
291 * <b> // The first usage </b> @n
292 * result r = E_SUCCESS; @n
293 * Tizen::Base::ByteBuffer byteBuffer; @n
294 * byteBuffer.Construct(1024); @n
296 * // Set the data to byteBuffer @n
298 * ContentId contentId; @n
299 * ContentManager contentManager; @n
300 * r = contentManager.Construct(); @n
301 * TryReturn(!IsFailed(r), r, "Construct failed."); @n
303 * Tizen::Base::String contentPath = Tizen::System::Environment::GetMediaPath() + L"Images/flower.jpg"; @n
304 * contentId = contentManager.CreateContent(byteBuffer, contentPath); @n
305 * TryReturn(contentId != Tizen::Base::UuId::GetInvalidUuId(), GetLastResult(), "CreateContent failed."); @n
307 * @n <b> // The second usage </b> @n
308 * result r = E_SUCCESS; @n
309 * Tizen::Base::ByteBuffer byteBuffer; @n
310 * byteBuffer.Construct(1024); @n
312 * // Set the data to byteBuffer @n
314 * ContentId contentId; @n
315 * ContentManager contentManager; @n
316 * r = contentManager.Construct(); @n
317 * TryReturn(!IsFailed(r), r, "Construct failed."); @n
319 * ImageContentInfo imageContentInfo; @n
320 * r = imageContentInfo.Construct(null); @n
321 * TryReturn(!IsFailed(r), r, "Construct failed."); @n
323 * r = imageContentInfo.SetKeyword(L"apple, fruit"); @n
324 * TryReturn(!IsFailed(r), r, "SetKeyword failed."); @n
326 * r = imageContentInfo.SetProvider(L"kw1128"); @n
327 * TryReturn(!IsFailed(r), r, "SetProvider failed."); @n
329 * Tizen::Base::String contentPath = Tizen::System::Environment::GetMediaPath() + L"Images/flower.jpg"; @n
330 * contentId = contentManager.CreateContent(byteBuffer, contentPath, &imageContentInfo); @n
331 * TryReturn(contentId != Tizen::Base::UuId::GetInvalidUuId(), GetLastResult(), "CreateContent failed."); @n
333 * @section CreateContentUsageSecond 2. CreateContent(const Tizen::Base::String& sourcePath, const Tizen::Base::String& destinationPath, bool deleteSource, const ContentInfo* pContentInfo = null);
335 * <b> // The first usage </b> @n
336 * result r = E_SUCCESS; @n
337 * ContentId contentId; @n
338 * ContentManager contentManager; @n
339 * r = contentManager.Construct(); @n
340 * TryReturn(!IsFailed(r), r, "Construct failed."); @n
342 * Tizen::Base::String sourcePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/flower.jpg"; @n
343 * Tizen::Base::String destPath = Tizen::System::Environment::GetMediaPath() + L"Images/flower.jpg"; @n
345 * contentId = contentManager.CreateContent(sourcePath, destPath, false); @n
346 * TryReturn(Tizen::Base::UuId::GetInvalidUuId() != contentId, GetLastResult(), "CreateContent failed."); @n
348 * @n <b> // The second usage </b> @n
349 * result r = E_SUCCESS; @n
350 * ContentId contentId; @n
351 * ContentManager contentManager; @n
352 * r = contentManager.Construct(); @n
353 * TryReturn(!IsFailed(r), r, "Construct failed."); @n
355 * ImageContentInfo imageContentInfo; @n
356 * r = imageContentInfo.Construct(null); @n
357 * TryReturn(!IsFailed(r), r, "Construct failed."); @n
359 * r = imageContentInfo.SetKeyword(L"apple, fruit"); @n
360 * TryReturn(!IsFailed(r), r, "SetKeyword failed."); @n
362 * r = imageContentInfo.SetProvider(L"kw1128"); @n
363 * TryReturn(!IsFailed(r), r, "SetProvider failed."); @n
365 * Tizen::Base::String sourcePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/flower.jpg"; @n
366 * Tizen::Base::String destPath = Tizen::System::Environment::GetMediaPath() + L"Images/flower.jpg"; @n
368 * contentId = contentManager.CreateContent(sourcePath, destPath, false, &imageContentInfo); @n
369 * TryReturn(Tizen::Base::UuId::GetInvalidUuId() != contentId, GetLastResult(), "CreateContent failed."); @n
373 * Gets the content information.
377 * @privilege http://tizen.org/privilege/content.read
379 * @return A pointer to ContentInfo
380 * @param[in] contentId The content ID
381 * @exception E_SUCCESS The method is successful.
382 * @exception E_INVALID_ARG The specified input parameter is invalid, or
383 * the content information corresponding to @c contentId cannot be found.
384 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
385 * @exception E_OUT_OF_MEMORY The memory is insufficient.
386 * @exception E_SYSTEM A system error has occurred.
387 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
388 * @exception E_SERVICE_BUSY The database is busy.
389 * @remarks The specific error code can be accessed using the GetLastResult() method.
391 ContentInfo* GetContentInfoN(const ContentId& contentId) const;
394 * Updates the content information with the specified instance of ContentInfo.
398 * @privilege http://tizen.org/privilege/content.write
400 * @return An error code
401 * @param[in] contentInfo An instance of ContentInfo
402 * @exception E_SUCCESS The method is successful.
403 * @exception E_INVALID_ARG The specified input parameter is invalid.
404 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
405 * @exception E_OUT_OF_MEMORY The memory is insufficient.
406 * @exception E_SYSTEM A system error has occurred.
407 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
408 * @exception E_SERVICE_BUSY The database is busy.
410 result UpdateContent(const ContentInfo& contentInfo);
413 * Deletes the content information with the specified content ID.
417 * @privilege http://tizen.org/privilege/content.write
419 * @return An error code
420 * @param[in] contentId The content ID
421 * @exception E_SUCCESS The method is successful.
422 * @exception E_INVALID_ARG The specified input parameter is invalid, or
423 * the content information corresponding to @c contentId cannot be found.
424 * @exception E_FILE_NOT_FOUND The specified file cannot be found or accessed.
425 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
426 * @exception E_OUT_OF_MEMORY The memory is insufficient.
427 * @exception E_SYSTEM A system error has occurred.
428 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
429 * @exception E_SERVICE_BUSY The database is busy.
430 * @remarks The physical file corresponding to @c contentId is deleted.
432 result DeleteContent(const ContentId& contentId);
435 * Adds a listener to receive the database change notification
439 * @return An error code
440 * @param[in] listener The event listener
441 * @exception E_SUCCESS The method is successful.
442 * @exception E_OBJ_ALREADY_EXIST The listener has already been added.
443 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
445 result AddContentUpdateEventListener(IContentUpdateEventListener& listener);
452 * @return An error code
453 * @param[in] listener The event listener
454 * @exception E_SUCCESS The method is successful.
455 * @exception E_OBJ_NOT_FOUND The listener is not found.
456 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
458 result RemoveContentUpdateEventListener(IContentUpdateEventListener& listener);
462 * Requests to scan a file
466 * @privilege http://tizen.org/privilege/content.write
468 * @return An error code
469 * @param[in] contentPath The content path
470 * @exception E_SUCCESS The method is successful.
471 * @exception E_INVALID_ARG The specified input parameter is invalid.
472 * @exception E_SERVICE_BUSY The database is busy.
473 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
474 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
476 static result ScanFile(const Tizen::Base::String& contentPath);
479 * Requests to scan a directory
483 * @privilege http://tizen.org/privilege/content.write
485 * @return An error code
486 * @param[in] directoryPath The directory path
487 * @param[in] recursive Set to @c true in order to scan recursively sub directories, @n
489 * @param[in] pListener The scan event listener
490 * @param[out] reqId The request ID
491 * @exception E_SUCCESS The method is successful.
492 * @exception E_INVALID_ARG The specified input parameter is invalid.
493 * @exception E_SERVICE_BUSY The database is busy.
494 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
495 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
496 * @remark Platform does not have the ownership of the listener.
498 static result ScanDirectory(const Tizen::Base::String& directoryPath, bool recursive, IContentScanListener* pListener, RequestId& reqId);
502 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
504 ContentManager(const ContentManager& rhs);
507 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
509 ContentManager& operator =(const ContentManager& rhs);
512 friend class _ContentManagerImpl;
513 _ContentManagerImpl* __pImpl;
515 }; // Class ContentManager
519 #endif // _FCNT_CONTENT_MANAGER_H_