[content] Reflection of inspected header files
[platform/framework/native/content.git] / inc / FCntContentManager.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  * @file                        FCntContentManager.h
19  * @brief               This is the header file for the %ContentManager class.
20  *
21  * This header file contains the declarations of the %ContentManager class.
22  */
23
24 #ifndef _FCNT_CONTENT_MANAGER_H_
25 #define _FCNT_CONTENT_MANAGER_H_
26
27 #include <FBaseObject.h>
28 #include <FCntTypes.h>
29
30 namespace Tizen { namespace Base
31 {
32 class ByteBuffer;
33 }}
34
35 namespace Tizen { namespace Content
36 {
37
38 class ContentInfo;
39 class _ContentManagerImpl;
40 class IContentScanListener;
41 class IContentUpdateEventListener;
42
43 /**
44  * @class       ContentManager
45  * @brief       This class provides methods for local content management.
46  *
47  * @since       2.0
48  *
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.
51  *
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>.
53  *
54  * The following example demonstrates how to use the %ContentManager class.
55  *
56  * @code
57  * result
58  * MyClass::TestContentManager(void)
59  * {
60  *              result r = E_SUCCESS;
61  *              ContentId contentId;
62  *              ContentManager contentManager;
63  *              r = contentManager.Construct();
64  *              TryReturn(!IsFailed(r), r, "Construct failed.");
65  *
66  *              // Creates
67  *              ImageContentInfo imageContentInfo;
68  *              r = imageContentInfo.Construct(null);
69  *              TryReturn(!IsFailed(r), r, "Construct failed.");
70  *
71  *              r = imageContentInfo.SetKeyword(L"platform, tizen");
72  *              if (IsFailed(r))
73  *              {
74  *                      return r;
75  *              }
76  *
77  *              r = imageContentInfo.SetLocationTag(L"seoul");
78  *              if (IsFailed(r))
79  *              {
80  *                      return r;
81  *              }
82  *
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";
85  *
86  *              contentId = contentManager.CreateContent(sourcePath, destPath, false, &imageContentInfo);
87  *              TryReturn(Tizen::Base::UuId::GetInvalidUuId() != contentId, GetLastResult(), "CreateContent failed.");
88  *
89  *              // Gets
90  *              ImageContentInfo* pImageContentInfo = null;
91  *              pImageContentInfo = dynamic_cast<ImageContentInfo*>(contentManager.GetContentInfoN(contentId));
92  *              TryReturn(pImageContentInfo != null, GetLastResult(), "GetContentInfoN failed.");
93  *
94  *              pImageContentInfo->GetContentPath();
95  *
96  *              // Updates
97  *              r = pImageContentInfo->SetKeyword(L"apple, fruit");
98  *              if (IsFailed(r))
99  *              {
100  *                      delete pImageContentInfo;
101  *                      return r;
102  *              }
103  *              r = pImageContentInfo->SetProvider(L"kw1128");
104  *              if (IsFailed(r))
105  *              {
106  *                      delete pImageContentInfo;
107  *                      return r;
108  *              }
109  *              r = contentManager.UpdateContent(*pImageContentInfo);
110  *              if (IsFailed(r))
111  *              {
112  *                      delete pImageContentInfo;
113  *                      return r;
114  *              }
115  *
116  *              // Deletes
117  *              r = contentManager.DeleteContent(contentId);
118  *              if (IsFailed(r))
119  *              {
120  *                      delete pImageContentInfo;
121  *                      return r;
122  *              }
123  *
124  *              delete pImageContentInfo;
125  *              return r;
126  * }
127  * @endcode
128  */
129 class _OSP_EXPORT_ ContentManager
130         : virtual public Tizen::Base::Object
131 {
132
133 public:
134         /**
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.
136          *
137          * @since               2.0
138          *
139          * @remarks     After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
140          */
141         ContentManager(void);
142
143         /**
144          * This destructor overrides Tizen::Base::Object::~Object().
145          *
146          * @since               2.0
147          */
148         virtual ~ContentManager(void);
149
150         /**
151          * Initializes this instance of %ContentManager.
152          *
153          * @since                       2.0
154          *
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.
159          */
160         result Construct(void);
161
162         /**
163          * Creates the content information.
164          *
165          * @since                       2.0
166          * @privlevel           public
167          * @privilege           http://tizen.org/privilege/content.write
168          *
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.
183          */
184         ContentId CreateContent(const ContentInfo& contentInfo);
185
186         /**
187          * Writes the content in the byte buffer to the destination path and creates the content information.
188          *
189          * @if OSPCOMPAT
190          * @brief       <i> [Compatibility] </i>
191          * @endif
192          * @since                       2.0
193          * @if OSPCOMPAT
194          * @compatibility This method has compatibility issues with OSP compatible applications. @n
195          *                       For more information, see @ref CompContentManagerCreateContentPage "here".
196          * @endif
197          * @privlevel           public
198          * @privilege           http://tizen.org/privilege/content.write
199          *
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".
221          */
222         ContentId CreateContent(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Base::String& destinationPath, const ContentInfo* pContentInfo = null);
223
224         /**
225          * Copies or moves the actual content to the destination path and creates the content information.
226          *
227          * @if OSPCOMPAT
228          * @brief       <i> [Compatibility] </i>
229          * @endif
230          * @since                       2.0
231          * @if OSPCOMPAT
232          * @compatibility This method has compatibility issues with OSP compatible applications. @n
233          *                       For more information, see @ref CompContentManagerCreateContentPage "here".
234          * @endif
235          * @privlevel           public
236          * @privilege           http://tizen.org/privilege/content.write
237          *
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
242          *                                                                                                                      else @c false
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".
264          */
265         ContentId CreateContent(const Tizen::Base::String& sourcePath, const Tizen::Base::String& destinationPath, bool deleteSource, const ContentInfo* pContentInfo = null);
266
267         /**
268          * @if OSPCOMPAT
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".
274          *
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().
283          *
284          * @endif
285          */
286
287         /**
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)
290          *
291          *                      <b> // The first usage </b> @n
292          *                      result r = E_SUCCESS; @n
293          *                      Tizen::Base::ByteBuffer byteBuffer; @n
294          *                      byteBuffer.Construct(1024); @n
295          *
296          *                      // Set the data to byteBuffer @n
297          *
298          *                      ContentId contentId; @n
299          *                      ContentManager contentManager; @n
300          *                      r = contentManager.Construct(); @n
301          *                      TryReturn(!IsFailed(r), r, "Construct failed."); @n
302          *
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
306          *
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
311          *
312          *                      // Set the data to byteBuffer @n
313          *
314          *                      ContentId contentId; @n
315          *                      ContentManager contentManager; @n
316          *                      r = contentManager.Construct(); @n
317          *                      TryReturn(!IsFailed(r), r, "Construct failed."); @n
318          *
319          *                      ImageContentInfo imageContentInfo; @n
320          *                      r = imageContentInfo.Construct(null); @n
321          *                      TryReturn(!IsFailed(r), r, "Construct failed."); @n
322          *
323          *                      r = imageContentInfo.SetKeyword(L"apple, fruit"); @n
324          *                      TryReturn(!IsFailed(r), r, "SetKeyword failed."); @n
325          *
326          *                      r = imageContentInfo.SetProvider(L"kw1128"); @n
327          *                      TryReturn(!IsFailed(r), r, "SetProvider failed."); @n
328          *
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
332          *
333          * @section  CreateContentUsageSecond 2. CreateContent(const Tizen::Base::String& sourcePath, const Tizen::Base::String& destinationPath, bool deleteSource, const ContentInfo* pContentInfo = null);
334          *
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
341          *
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
344          *
345          *                      contentId = contentManager.CreateContent(sourcePath, destPath, false); @n
346          *                      TryReturn(Tizen::Base::UuId::GetInvalidUuId() != contentId, GetLastResult(), "CreateContent failed."); @n
347          *
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
354          *
355          *                      ImageContentInfo imageContentInfo; @n
356          *                      r = imageContentInfo.Construct(null); @n
357          *                      TryReturn(!IsFailed(r), r, "Construct failed."); @n
358          *
359          *                      r = imageContentInfo.SetKeyword(L"apple, fruit"); @n
360          *                      TryReturn(!IsFailed(r), r, "SetKeyword failed."); @n
361          *
362          *                      r = imageContentInfo.SetProvider(L"kw1128"); @n
363          *                      TryReturn(!IsFailed(r), r, "SetProvider failed."); @n
364          *
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
367          *
368          *                      contentId = contentManager.CreateContent(sourcePath, destPath, false, &imageContentInfo); @n
369          *                      TryReturn(Tizen::Base::UuId::GetInvalidUuId() != contentId, GetLastResult(), "CreateContent failed."); @n
370          */
371
372         /**
373          * Gets the content information.
374          *
375          * @since                       2.0
376          * @privlevel           public
377          * @privilege           http://tizen.org/privilege/content.read
378          *
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.
390          */
391         ContentInfo* GetContentInfoN(const ContentId& contentId) const;
392
393         /**
394          * Updates the content information with the specified instance of ContentInfo.
395          *
396          * @since                       2.0
397          * @privlevel           public
398          * @privilege           http://tizen.org/privilege/content.write
399          *
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.
409          */
410         result UpdateContent(const ContentInfo& contentInfo);
411
412         /**
413          * Deletes the content information with the specified content ID.
414          *
415          * @since                       2.0
416          * @privlevel           public
417          * @privilege           http://tizen.org/privilege/content.write
418          *
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.
431          */
432         result DeleteContent(const ContentId& contentId);
433
434         /**
435          * Adds a listener to receive the database change notification.
436          *
437          * @since                       2.1
438          *
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.
444          */
445         result AddContentUpdateEventListener(IContentUpdateEventListener& listener);
446
447         /**
448          * Removes a listener.
449          *
450          * @since           2.1
451          *
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.
457          */
458         result RemoveContentUpdateEventListener(IContentUpdateEventListener& listener);
459
460
461         /**
462          * Requests to scan a file.
463          *
464          * @since                       2.1
465          * @privlevel           public
466          * @privilege           http://tizen.org/privilege/content.write
467          *
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.
475          */
476         static result ScanFile(const Tizen::Base::String& contentPath);
477
478         /**
479          * Requests to scan a directory.
480          *
481          * @since                       2.1
482          * @privlevel           public
483          * @privilege           http://tizen.org/privilege/content.write
484          *
485          * @return                      An error code
486          * @param[in]           directoryPath                   The directory path
487          * @param[in]           recursive                               Set to @c true in order to recursively scan sub directories, @n
488          *                                          else @c false
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.
497          */
498         static result ScanDirectory(const Tizen::Base::String& directoryPath, bool recursive, IContentScanListener* pListener, RequestId& reqId);
499
500 private:
501         /**
502          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
503          */
504         ContentManager(const ContentManager& rhs);
505
506         /**
507          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
508          */
509         ContentManager& operator =(const ContentManager& rhs);
510
511 private:
512         friend class _ContentManagerImpl;
513         _ContentManagerImpl* __pImpl;
514
515 };  // Class ContentManager
516
517 }}  // Tizen::Content
518
519 #endif  // _FCNT_CONTENT_MANAGER_H_