inc/FCntContentManager.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  * @file                        FCntContentManager.h
  18  * @brief               This is the header file for the %ContentManager class.
  19  *
  20  * This header file contains the declarations of the %ContentManager class.
  21  */
  22
  23 #ifndef _FCNT_CONTENT_MANAGER_H_
  24 #define _FCNT_CONTENT_MANAGER_H_
  25
  26 #include <FBaseObject.h>
  27 #include <FCntTypes.h>
  28
  29 namespace Tizen { namespace Base
  30 {
  31 class ByteBuffer;
  32 }}
  33
  34 namespace Tizen { namespace Content
  35 {
  36
  37 class ContentInfo;
  38 class _ContentManagerImpl;
  39 class IContentScanListener;
  40 class IContentUpdateEventListener;
  41
  42 /**
  43  * @class       ContentManager
  44  * @brief       This class provides methods for local content management.
  45  *
  46  * @since       2.0
  47  *
  48  * @final   This class is not intended for extension.
  49  *
  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.
  52  *
  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>.
  54  *
  55  * The following example demonstrates how to use the %ContentManager class.
  56  *
  57  * @code
  58  * result
  59  * MyClass::TestContentManager(void)
  60  * {
  61  *              result r = E_SUCCESS;
  62  *              ContentId contentId;
  63  *              ContentManager contentManager;
  64  *              r = contentManager.Construct();
  65  *              TryReturn(!IsFailed(r), r, "Construct failed.");
  66  *
  67  *              // Creates
  68  *              ImageContentInfo imageContentInfo;
  69  *              r = imageContentInfo.Construct(null);
  70  *              TryReturn(!IsFailed(r), r, "Construct failed.");
  71  *
  72  *              r = imageContentInfo.SetKeyword(L"platform, tizen");
  73  *              if (IsFailed(r))
  74  *              {
  75  *                      return r;
  76  *              }
  77  *
  78  *              r = imageContentInfo.SetLocationTag(L"seoul");
  79  *              if (IsFailed(r))
  80  *              {
  81  *                      return r;
  82  *              }
  83  *
  84  *              Tizen::Base::String sourcePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/flower.jpg";
  85  *              Tizen::Base::String destPath = Tizen::System::Environment::GetMediaPath() + L"Images/flower.jpg";
  86  *
  87  *              contentId = contentManager.CreateContent(sourcePath, destPath, false, &imageContentInfo);
  88  *              TryReturn(Tizen::Base::UuId::GetInvalidUuId() != contentId, GetLastResult(), "CreateContent failed.");
  89  *
  90  *              // Gets
  91  *              ImageContentInfo* pImageContentInfo = null;
  92  *              pImageContentInfo = dynamic_cast<ImageContentInfo*>(contentManager.GetContentInfoN(contentId));
  93  *              TryReturn(pImageContentInfo != null, GetLastResult(), "GetContentInfoN failed.");
  94  *
  95  *              pImageContentInfo->GetContentPath();
  96  *
  97  *              // Updates
  98  *              r = pImageContentInfo->SetKeyword(L"apple, fruit");
  99  *              if (IsFailed(r))
 100  *              {
 101  *                      delete pImageContentInfo;
 102  *                      return r;
 103  *              }
 104  *              r = pImageContentInfo->SetProvider(L"kw1128");
 105  *              if (IsFailed(r))
 106  *              {
 107  *                      delete pImageContentInfo;
 108  *                      return r;
 109  *              }
 110  *              r = contentManager.UpdateContent(*pImageContentInfo);
 111  *              if (IsFailed(r))
 112  *              {
 113  *                      delete pImageContentInfo;
 114  *                      return r;
 115  *              }
 116  *
 117  *              // Deletes
 118  *              r = contentManager.DeleteContent(contentId);
 119  *              if (IsFailed(r))
 120  *              {
 121  *                      delete pImageContentInfo;
 122  *                      return r;
 123  *              }
 124  *
 125  *              delete pImageContentInfo;
 126  *              return r;
 127  * }
 128  * @endcode
 129  */
 130 class _OSP_EXPORT_ ContentManager
 131         : virtual public Tizen::Base::Object
 132 {
 133
 134 public:
 135         /**
 136          * The object is not fully constructed after this constructor is called. @n
 137          * For full construction, the Construct() method must be called right after calling this constructor.
 138          *
 139          * @since               2.0
 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_SYSTEM                                        A system error has occurred.
 158          */
 159         result Construct(void);
 160
 161         /**
 162          * Creates the content information.
 163          *
 164          * @since               2.0
 165          * @privlevel   public
 166          * @privilege   %http://tizen.org/privilege/content.write
 167          *
 168          * @return              The content ID
 169          * @param[in]   contentInfo                             An instance of ContentInfo
 170          * @exception   E_SUCCESS                               The method is successful.
 171          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred:
 172          *                                                                      - The specified input parameter is invalid.
 173          *                                                                      - The specified format is either 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_SYSTEM                                A system error has occurred.
 177          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 178          * @exception   E_SERVICE_BUSY                  The database is busy.
 179          * @remarks
 180          *                      - If the @c E_UNSUPPORTED_FORMAT exception is received from ContentManagerUtil::CheckContentType(),
 181          *                      the file can be created as content only using the OtherContentInfo class.
 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 @n
 203          *                                                                         The path should start with the directory path returned by either
 204          *                                                                         Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath().
 205          * @param[in]   pContentInfo               A pointer to the ContentInfo instance @n
 206          *                                     If the content path exists in %ContentInfo, it gets ignored.
 207          * @exception   E_SUCCESS                          The method is successful.
 208          * @exception   E_INVALID_ARG              Either of the following conditions has occurred:
 209          *                                                              - A specified input parameter is invalid.
 210          *                                                              - There is a mismatch between the type specified in ContentInfo and the type specified in the actual content.
 211          * @exception   E_STORAGE_FULL             The storage is full.
 212          * @exception   E_FILE_ALREADY_EXIST   The specified file already exists.
 213          * @exception   E_ILLEGAL_ACCESS           The access is denied due to insufficient permission.
 214          * @exception   E_MAX_EXCEEDED             The number of opened files has exceeded the maximum limit.
 215          * @exception   E_IO                               An I/O error has occurred.
 216          * @exception   E_SYSTEM                           A system error has occurred.
 217          * @exception   E_PRIVILEGE_DENIED         The application does not have the privilege to call this method.
 218          * @exception   E_SERVICE_BUSY         The database is busy.
 219          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 220          */
 221         ContentId CreateContent(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Base::String& destinationPath, const ContentInfo* pContentInfo = null);
 222
 223         /**
 224          * Copies or moves the actual content to the destination path and creates the content information.
 225          *
 226          * @if OSPCOMPAT
 227          * @brief                 <i> [Compatibility] </i>
 228          * @endif
 229          * @since                  2.0
 230          * @if OSPCOMPAT
 231          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 232          *                For more information, see @ref CompContentManagerCreateContentPage "here".
 233          * @endif
 234          * @privlevel   public
 235          * @privilege   %http://tizen.org/privilege/content.write
 236          *
 237          * @return              The content ID
 238          * @param[in]   sourcePath                              The source file path @n
 239          *                                                                              The path should start with the directory path returned by either Tizen::App::App::GetAppRootPath()
 240          *                                                                              or Tizen::System::Environment::GetExternalStoragePath().
 241          * @param[in]   destinationPath                 The destination file path @n
 242          *                                                                          The path should start with the directory path returned by either Tizen::System::Environment::GetMediaPath()
 243          *                                                                          or Tizen::System::Environment::GetExternalStoragePath().
 244          * @param[in]   deleteSource                    Set to @c true in order to delete the source file, @n
 245          *                                                                              else @c false
 246          * @param[in]   pContentInfo                    A pointer to the ContentInfo instance @n
 247          *                                      If the content path exists in %ContentInfo, it gets ignored.
 248          * @exception   E_SUCCESS                               The method is successful.
 249          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred:
 250          *                                                              - A specified input parameter is invalid.
 251          *                                                              - There is a mismatch between the type of the source path and the destination path.
 252          *                                                              - There is a mismatch between the type specified in ContentInfo and the type specified in the actual content.
 253          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 254          * @exception   E_STORAGE_FULL                  The storage is full.
 255          * @exception   E_FILE_ALREADY_EXIST    The specified file already exists.
 256          * @exception   E_ILLEGAL_ACCESS                The access is denied due to insufficient permission.
 257          * @exception   E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 258          * @exception   E_IO                                    An I/O error has occurred.
 259          * @exception   E_SYSTEM                                A system error has occurred.
 260          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 261          * @exception   E_SERVICE_BUSY                  The database is busy.
 262          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 263          */
 264         ContentId CreateContent(const Tizen::Base::String& sourcePath, const Tizen::Base::String& destinationPath, bool deleteSource, const ContentInfo* pContentInfo = null);
 265
 266         /**
 267          * @if OSPCOMPAT
 268          * @page        CompContentManagerCreateContentPage Compatibility for the file path.
 269          * @section     CompContentManagerCreateContentPageIssueSection Issues
 270          *          The content path argument of this method in OSP compatible applications has the following issues: @n
 271          *          -# The content path should be a path that begins with an allowed path prefix. @n
 272          *             For example, L"/Media/Images/flower.jpg", L"/Storagecard/Media/Images/flower.jpg".
 273          *
 274          * @section     CompContentManagerCreateContentPageSolutionSection Resolutions
 275          *          This issue has been resolved in Tizen. @n
 276          *          -# The content path can be a path without a specific allowed path prefix. @n
 277          *             Applications do not need to know the specific allowed path prefixes. @n
 278          *             To get the directory path, use the following methods: @n
 279          *             - For accessing the home directory, use Tizen::App::App::GetInstance()->GetAppRootPath().
 280          *             - For accessing the media directory, use Tizen::System::Environment::GetMediaPath().
 281          *             - For accessing the external storage, use Tizen::System::Environment::GetExternalStoragePath().
 282          *
 283          * @endif
 284          */
 285
 286         /**
 287          * Gets the content information.
 288          *
 289          * @since               2.0
 290          * @privlevel   public
 291          * @privilege   %http://tizen.org/privilege/content.read
 292          *
 293          * @return              A pointer to ContentInfo
 294          * @param[in]   contentId                               The content ID
 295          * @exception   E_SUCCESS                               The method is successful.
 296          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred:
 297          *                                                                      - The specified input parameter is invalid.
 298          *                                                                      - The content information corresponding to @c contentId cannot be found.
 299          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 300          * @exception   E_SYSTEM                                A system error has occurred.
 301          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 302          * @exception   E_SERVICE_BUSY                  The database is busy.
 303          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 304          */
 305         ContentInfo* GetContentInfoN(const ContentId& contentId) const;
 306
 307         /**
 308          * Updates the content information with the specified instance of ContentInfo.
 309          *
 310          * @since               2.0
 311          * @privlevel   public
 312          * @privilege   %http://tizen.org/privilege/content.write
 313          *
 314          * @return              An error code
 315          * @param[in]   contentInfo                             An instance of ContentInfo
 316          * @exception   E_SUCCESS                               The method is successful.
 317          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.
 318          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 319          * @exception   E_SYSTEM                                A system error has occurred.
 320          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 321          * @exception   E_SERVICE_BUSY                  The database is busy.
 322          */
 323         result UpdateContent(const ContentInfo& contentInfo);
 324
 325         /**
 326          * Deletes the content information with the specified content ID.
 327          *
 328          * @since               2.0
 329          * @privlevel   public
 330          * @privilege   %http://tizen.org/privilege/content.write
 331          *
 332          * @return              An error code
 333          * @param[in]   contentId                               The content ID
 334          * @exception   E_SUCCESS                               The method is successful.
 335          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred:
 336          *                                                                      - The specified input parameter is invalid.
 337          *                                                                      - The content information corresponding to @c contentId cannot be found.
 338          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 339          * @exception   E_ILLEGAL_ACCESS                The access is denied due to insufficient permission.
 340          * @exception   E_SYSTEM                                A system error has occurred.
 341          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 342          * @exception   E_SERVICE_BUSY                  The database is busy.
 343          * @remarks             The physical file corresponding to @c contentId is deleted.
 344          */
 345         result DeleteContent(const ContentId& contentId);
 346
 347         /**
 348          * Adds a listener to receive the database change notification.
 349          *
 350          * @since                       2.1
 351          *
 352          * @return                      An error code
 353          * @param[in]           listener                                The event listener to add
 354          * @exception           E_SUCCESS                               The method is successful.
 355          * @exception           E_OBJ_ALREADY_EXIST         The listener has already been added.
 356          * @exception           E_SYSTEM                                The method cannot proceed due to a severe system error.
 357          * @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.
 358          */
 359         result AddContentUpdateEventListener(IContentUpdateEventListener& listener);
 360
 361         /**
 362          * Removes a listener which is registered to receive the database change notification.
 363          *
 364          * @since           2.1
 365          *
 366          * @return                      An error code
 367          * @param[in]           listener                        The event listener to remove
 368          * @exception           E_SUCCESS                       The method is successful.
 369          * @exception           E_OBJ_NOT_FOUND     The listener is not found.
 370          * @exception           E_SYSTEM                        The method cannot proceed due to a severe system error.
 371          */
 372         result RemoveContentUpdateEventListener(IContentUpdateEventListener& listener);
 373
 374
 375         /**
 376          * Requests to synchronize a specified file with the database.
 377          *
 378          * @since               2.1
 379          * @privlevel   public
 380          * @privilege   %http://tizen.org/privilege/content.write
 381          *
 382          * @return              An error code
 383          * @param[in]   contentPath                     The content path
 384          * @exception   E_SUCCESS                       The method is successful.
 385          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 386          * @exception   E_SERVICE_BUSY          The database is busy.
 387          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 388          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 389          */
 390         static result ScanFile(const Tizen::Base::String& contentPath);
 391
 392         /**
 393          * Requests to synchronize files in the specified directory with the database.
 394          *
 395          * @since                       2.1
 396          * @privlevel           public
 397          * @privilege           %http://tizen.org/privilege/content.write
 398          *
 399          * @return                      An error code
 400          * @param[in]           directoryPath                   The directory path
 401          * @param[in]           recursive                               Set to @c true in order to recursively scan sub directories, @n
 402          *                                          else @c false
 403          * @param[in]           pListener                               The scan event listener
 404          * @param[out]          reqId                                   The request ID
 405          * @exception           E_SUCCESS                               The method is successful.
 406          * @exception           E_INVALID_ARG                   The specified input parameter is invalid.
 407          * @exception           E_SERVICE_BUSY                  The database is busy.
 408          * @exception           E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 409          * @exception           E_SYSTEM                                The method cannot proceed due to a severe system error.
 410          * @remarks                     Platform does not have the ownership of the listener.
 411          */
 412         static result ScanDirectory(const Tizen::Base::String& directoryPath, bool recursive, IContentScanListener* pListener, RequestId& reqId);
 413
 414 private:
 415         /**
 416          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 417          */
 418         ContentManager(const ContentManager& rhs);
 419
 420         /**
 421          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 422          */
 423         ContentManager& operator =(const ContentManager& rhs);
 424
 425 private:
 426         friend class _ContentManagerImpl;
 427         _ContentManagerImpl* __pContentManagerImpl;
 428
 429 };  // ContentManager
 430
 431 }}  // Tizen::Content
 432
 433 #endif  // _FCNT_CONTENT_MANAGER_H_