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  * The %ContentManager class manages the information stored locally on the device's content database. @n
  49  * It also allows you to create, read, update, and delete specific content information in the database.
  50  *
  51  * 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>.
  52  *
  53  * The following example demonstrates how to use the %ContentManager class.
  54  *
  55  * @code
  56  * result
  57  * MyClass::TestContentManager(void)
  58  * {
  59  *              result r = E_SUCCESS;
  60  *              ContentId contentId;
  61  *              ContentManager contentManager;
  62  *              r = contentManager.Construct();
  63  *              TryReturn(!IsFailed(r), r, "Construct failed.");
  64  *
  65  *              // Creates
  66  *              ImageContentInfo imageContentInfo;
  67  *              r = imageContentInfo.Construct(null);
  68  *              TryReturn(!IsFailed(r), r, "Construct failed.");
  69  *
  70  *              r = imageContentInfo.SetKeyword(L"platform, tizen");
  71  *              if (IsFailed(r))
  72  *              {
  73  *                      return r;
  74  *              }
  75  *
  76  *              r = imageContentInfo.SetLocationTag(L"seoul");
  77  *              if (IsFailed(r))
  78  *              {
  79  *                      return r;
  80  *              }
  81  *
  82  *              Tizen::Base::String sourcePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/flower.jpg";
  83  *              Tizen::Base::String destPath = Tizen::System::Environment::GetMediaPath() + L"Images/flower.jpg";
  84  *
  85  *              contentId = contentManager.CreateContent(sourcePath, destPath, false, &imageContentInfo);
  86  *              TryReturn(Tizen::Base::UuId::GetInvalidUuId() != contentId, GetLastResult(), "CreateContent failed.");
  87  *
  88  *              // Gets
  89  *              ImageContentInfo* pImageContentInfo = null;
  90  *              pImageContentInfo = dynamic_cast<ImageContentInfo*>(contentManager.GetContentInfoN(contentId));
  91  *              TryReturn(pImageContentInfo != null, GetLastResult(), "GetContentInfoN failed.");
  92  *
  93  *              pImageContentInfo->GetContentPath();
  94  *
  95  *              // Updates
  96  *              r = pImageContentInfo->SetKeyword(L"apple, fruit");
  97  *              if (IsFailed(r))
  98  *              {
  99  *                      delete pImageContentInfo;
 100  *                      return r;
 101  *              }
 102  *              r = pImageContentInfo->SetProvider(L"kw1128");
 103  *              if (IsFailed(r))
 104  *              {
 105  *                      delete pImageContentInfo;
 106  *                      return r;
 107  *              }
 108  *              r = contentManager.UpdateContent(*pImageContentInfo);
 109  *              if (IsFailed(r))
 110  *              {
 111  *                      delete pImageContentInfo;
 112  *                      return r;
 113  *              }
 114  *
 115  *              // Deletes
 116  *              r = contentManager.DeleteContent(contentId);
 117  *              if (IsFailed(r))
 118  *              {
 119  *                      delete pImageContentInfo;
 120  *                      return r;
 121  *              }
 122  *
 123  *              delete pImageContentInfo;
 124  *              return r;
 125  * }
 126  * @endcode
 127  */
 128 class _OSP_EXPORT_ ContentManager
 129         : virtual public Tizen::Base::Object
 130 {
 131
 132 public:
 133         /**
 134          * The object is not fully constructed after this constructor is called. @n
 135          * For full construction, the Construct() method must be called right after calling this constructor.
 136          *
 137          * @since               2.0
 138          */
 139         ContentManager(void);
 140
 141         /**
 142          * This destructor overrides Tizen::Base::Object::~Object().
 143          *
 144          * @since               2.0
 145          */
 146         virtual ~ContentManager(void);
 147
 148         /**
 149          * Initializes this instance of %ContentManager.
 150          *
 151          * @since                       2.0
 152          *
 153          * @return                      An error code
 154          * @exception   E_SUCCESS                                       The method is successful.
 155          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 156          * @exception   E_SYSTEM                                        A system error has occurred.
 157          */
 158         result Construct(void);
 159
 160         /**
 161          * Creates the content information.
 162          *
 163          * @since                       2.0
 164          * @privlevel           public
 165          * @privilege           %http://tizen.org/privilege/content.write
 166          *
 167          * @return                      The content ID
 168          * @param[in]   contentInfo                                             An instance of ContentInfo
 169          * @exception   E_SUCCESS                                       The method is successful.
 170          * @exception   E_INVALID_ARG                           The specified input parameter is invalid, or
 171          *                                                      the specified format is invalid or not supported on the device.
 172          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 173          * @exception   E_IO                                                            An I/O error has occurred.
 174          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 175          * @exception   E_SYSTEM                                                A system error has occurred.
 176          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 177          * @exception   E_SERVICE_BUSY                  The database is busy.
 178          * @remarks
 179          *                              - If the @c E_UNSUPPORTED_FORMAT exception is received from ContentManagerUtil::CheckContentType(),
 180          *                                      the file can be created as a content only using the OtherContentInfo class.
 181          *                              - The specific error code can be accessed using the GetLastResult() method.
 182          */
 183         ContentId CreateContent(const ContentInfo& contentInfo);
 184
 185         /**
 186          * Writes the content in the byte buffer to the destination path and creates the content information.
 187          *
 188          * @if OSPCOMPAT
 189          * @brief       <i> [Compatibility] </i>
 190          * @endif
 191          * @since                       2.0
 192          * @if OSPCOMPAT
 193          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 194          *                       For more information, see @ref CompContentManagerCreateContentPage "here".
 195          * @endif
 196          * @privlevel           public
 197          * @privilege           %http://tizen.org/privilege/content.write
 198          *
 199          * @return                      The content ID
 200          * @param[in]   byteBuffer                                              The @c byteBuffer of the content to create
 201          * @param[in]   destinationPath                         The destination file path formed by the @c byteBuffer
 202          * @param[in]   pContentInfo                                    A pointer to the ContentInfo instance @n
 203          *                                                         If the content path exists in %ContentInfo, it gets ignored.
 204          * @exception   E_SUCCESS                                       The method is successful.
 205          * @exception   E_INVALID_ARG                           Either of the following conditions has occurred: @n
 206          *                                                         - A specified input parameter is invalid. @n
 207          *                                                         - There is a mismatch between the type specified in ContentInfo and the type specified in the actual content.
 208          * @exception   E_STORAGE_FULL                  The storage is full.
 209          * @exception   E_FILE_ALREADY_EXIST    The specified file already exists.
 210          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 211          * @exception   E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 212          * @exception   E_IO                                                            An I/O error has occurred.
 213          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 214          * @exception   E_SYSTEM                                                A system error has occurred.
 215          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 216          * @exception   E_SERVICE_BUSY                  The database is busy.
 217          * @remarks
 218          *                              - The destination path should start with the directory path returned by either Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath().
 219          *                              - 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
 239          * @param[in]   destinationPath                         The destination file path
 240          * @param[in]   deleteSource                                    Set to @c true in order to delete the source file, @n
 241          *                                                                                                                      else @c false
 242          * @param[in]   pContentInfo                                    A pointer to the ContentInfo instance @n
 243          *                                                         If the content path exists in %ContentInfo, it gets ignored.
 244          * @exception   E_SUCCESS                                       The method is successful.
 245          * @exception   E_INVALID_ARG                           Either of the following conditions has occurred: @n
 246          *                                                         - A specified input parameter is invalid. @n
 247          *                                                         - There is a mismatch between the type of the source path and destination path. @n
 248          *                                                         - There is a mismatch between the type specified in ContentInfo and the type specified in the actual content.
 249          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 250          * @exception   E_STORAGE_FULL                  The storage is full.
 251          * @exception   E_FILE_ALREADY_EXIST    The specified file already exists.
 252          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 253          * @exception   E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 254          * @exception   E_IO                                                            An I/O error has occurred.
 255          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 256          * @exception   E_SYSTEM                                                A system error has occurred.
 257          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 258          * @exception   E_SERVICE_BUSY                  The database is busy.
 259          * @remarks
 260          *                              - The source path should start with the directory path returned by either Tizen::App::App::GetAppRootPath() or Tizen::System::Environment::GetExternalStoragePath().
 261          *                              - The destination path should start with the directory path returned by either Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath().
 262          *                              - 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          *                 Application 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                           The specified input parameter is invalid, or
 297          *                                          the content information corresponding to @c contentId cannot be found.
 298          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 299          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 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_OUT_OF_MEMORY         The memory is insufficient.
 320          * @exception   E_SYSTEM                                                A system error has occurred.
 321          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 322          * @exception   E_SERVICE_BUSY                  The database is busy.
 323          */
 324         result UpdateContent(const ContentInfo& contentInfo);
 325
 326         /**
 327          * Deletes the content information with the specified content ID.
 328          *
 329          * @since                       2.0
 330          * @privlevel           public
 331          * @privilege           %http://tizen.org/privilege/content.write
 332          *
 333          * @return                      An error code
 334          * @param[in]   contentId                                               The content ID
 335          * @exception   E_SUCCESS                                       The method is successful.
 336          * @exception   E_INVALID_ARG                           The specified input parameter is invalid, or
 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                Access is denied due to insufficient permission.
 340          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 341          * @exception   E_SYSTEM                                                A system error has occurred.
 342          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 343          * @exception   E_SERVICE_BUSY                  The database is busy.
 344          * @remarks             The physical file corresponding to @c contentId is deleted.
 345          */
 346         result DeleteContent(const ContentId& contentId);
 347
 348         /**
 349          * Adds a listener to receive the database change notification.
 350          *
 351          * @since                       2.1
 352          *
 353          * @return                      An error code
 354          * @param[in]           listener                                The event listener to add
 355          * @exception           E_SUCCESS                               The method is successful.
 356          * @exception           E_OBJ_ALREADY_EXIST     The listener has already been added.
 357          * @exception           E_SYSTEM                                The method cannot proceed due to a severe system error.
 358          * @remarks             Only a listener of an instance can be added.
 359          *                                      If you add more than two listeners, the listener added first will receive notification for the DB change.
 360          */
 361         result AddContentUpdateEventListener(IContentUpdateEventListener& listener);
 362
 363         /**
 364          * Removes a listener.
 365          *
 366          * @since           2.1
 367          *
 368          * @return                      An error code
 369          * @param[in]           listener                        The event listener to remove
 370          * @exception           E_SUCCESS                       The method is successful.
 371          * @exception           E_OBJ_NOT_FOUND The listener is not found.
 372          * @exception           E_SYSTEM                        The method cannot proceed due to a severe system error.
 373          */
 374         result RemoveContentUpdateEventListener(IContentUpdateEventListener& listener);
 375
 376
 377         /**
 378          * Requests to scan a file.
 379          *
 380          * @since                       2.1
 381          * @privlevel           public
 382          * @privilege           %http://tizen.org/privilege/content.write
 383          *
 384          * @return              An error code
 385          * @param[in]   contentPath                     The content path
 386          * @exception   E_SUCCESS                       The method is successful.
 387          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 388          * @exception   E_SERVICE_BUSY          The database is busy.
 389          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 390          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 391          */
 392         static result ScanFile(const Tizen::Base::String& contentPath);
 393
 394         /**
 395          * Requests to scan a directory.
 396          *
 397          * @since                       2.1
 398          * @privlevel           public
 399          * @privilege           %http://tizen.org/privilege/content.write
 400          *
 401          * @return                      An error code
 402          * @param[in]           directoryPath                   The directory path
 403          * @param[in]           recursive                               Set to @c true in order to recursively scan sub directories, @n
 404          *                                          else @c false
 405          * @param[in]           pListener                               The scan event listener
 406          * @param[out]          reqId                                   The request ID
 407          * @exception           E_SUCCESS                               The method is successful.
 408          * @exception           E_INVALID_ARG                   The specified input parameter is invalid.
 409          * @exception           E_SERVICE_BUSY                  The database is busy.
 410          * @exception           E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 411          * @exception           E_SYSTEM                                The method cannot proceed due to a severe system error.
 412          * @remarks                     Platform does not have the ownership of the listener.
 413          */
 414         static result ScanDirectory(const Tizen::Base::String& directoryPath, bool recursive, IContentScanListener* pListener, RequestId& reqId);
 415
 416 private:
 417         /**
 418          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 419          */
 420         ContentManager(const ContentManager& rhs);
 421
 422         /**
 423          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 424          */
 425         ContentManager& operator =(const ContentManager& rhs);
 426
 427 private:
 428         friend class _ContentManagerImpl;
 429         _ContentManagerImpl* __pImpl;
 430
 431 };  // Class ContentManager
 432
 433 }}  // Tizen::Content
 434
 435 #endif  // _FCNT_CONTENT_MANAGER_H_