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
 181          *                              - If the E_UNSUPPORTED_FORMAT exception is received from ContentManagerUtil::CheckContentType(),
 182          *                                      the file can be created as a content only using the OtherContentInfo class.
 183          *                              - The specific error code can be accessed using the GetLastResult() method.
 184          */
 185         ContentId CreateContent(const ContentInfo& contentInfo);
 186
 187         /**
 188          * Writes the content in the byte buffer to the destination path and creates the content information.
 189          *
 190          * @if OSPCOMPAT
 191          * @brief       <i> [Compatibility] </i>
 192          * @endif
 193          * @since                       2.0
 194          * @if OSPCOMPAT
 195          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 196          *                       For more information, see @ref CompContentManagerCreateContentPage "here".
 197          * @endif
 198          * @privlevel           public
 199          * @privilege           %http://tizen.org/privilege/content.write
 200          *
 201          * @return                      The content ID
 202          * @param[in]   byteBuffer                                              The @c byteBuffer of the content to create
 203          * @param[in]   destinationPath                         The destination file path formed by the @c byteBuffer
 204          * @param[in]   pContentInfo                                    A pointer to the ContentInfo instance @n
 205          *                                                         If the content path exists in %ContentInfo, it gets ignored.
 206          * @exception   E_SUCCESS                                       The method is successful.
 207          * @exception   E_INVALID_ARG                           Either of the following conditions has occurred: @n
 208          *                                                         - A specified input parameter is invalid. @n
 209          *                                                         - There is a mismatch between the type specified in ContentInfo and the type specified in the actual content.
 210          * @exception   E_STORAGE_FULL                  The storage is full.
 211          * @exception   E_FILE_ALREADY_EXIST    The specified file already exists.
 212          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 213          * @exception   E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 214          * @exception   E_IO                                                            An I/O error has occurred.
 215          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 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
 220          *                              - The destination path should start with the directory path returned by either Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath().
 221          *                              - The specific error code can be accessed using the GetLastResult() method.
 222          */
 223         ContentId CreateContent(const Tizen::Base::ByteBuffer& byteBuffer, const Tizen::Base::String& destinationPath, const ContentInfo* pContentInfo = null);
 224
 225         /**
 226          * Copies or moves the actual content to the destination path and creates the content information.
 227          *
 228          * @if OSPCOMPAT
 229          * @brief       <i> [Compatibility] </i>
 230          * @endif
 231          * @since                       2.0
 232          * @if OSPCOMPAT
 233          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 234          *                       For more information, see @ref CompContentManagerCreateContentPage "here".
 235          * @endif
 236          * @privlevel           public
 237          * @privilege           %http://tizen.org/privilege/content.write
 238          *
 239          * @return                      The content ID
 240          * @param[in]   sourcePath                                              The source file path
 241          * @param[in]   destinationPath                         The destination file path
 242          * @param[in]   deleteSource                                    Set to @c true in order to delete the source file, @n
 243          *                                                                                                                      else @c false
 244          * @param[in]   pContentInfo                                    A pointer to the ContentInfo instance @n
 245          *                                                         If the content path exists in %ContentInfo, it gets ignored.
 246          * @exception   E_SUCCESS                                       The method is successful.
 247          * @exception   E_INVALID_ARG                           Either of the following conditions has occurred: @n
 248          *                                                         - A specified input parameter is invalid. @n
 249          *                                                         - There is a mismatch between the type of the source path and destination path. @n
 250          *                                                         - There is a mismatch between the type specified in ContentInfo and the type specified in the actual content.
 251          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 252          * @exception   E_STORAGE_FULL                  The storage is full.
 253          * @exception   E_FILE_ALREADY_EXIST    The specified file already exists.
 254          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 255          * @exception   E_MAX_EXCEEDED                  The number of opened files has exceeded the maximum limit.
 256          * @exception   E_IO                                                            An I/O error has occurred.
 257          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 258          * @exception   E_SYSTEM                                                A system error has occurred.
 259          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 260          * @exception   E_SERVICE_BUSY                  The database is busy.
 261          * @remarks
 262          *                              - The source path should start with the directory path returned by either Tizen::App::App::GetAppRootPath() or Tizen::System::Environment::GetExternalStoragePath(). @n
 263          *                                      The destination path should start with the directory path returned by either Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath().
 264          *                              - The specific error code can be accessed using the GetLastResult() method.
 265          */
 266         ContentId CreateContent(const Tizen::Base::String& sourcePath, const Tizen::Base::String& destinationPath, bool deleteSource, const ContentInfo* pContentInfo = null);
 267
 268         /**
 269          * @if OSPCOMPAT
 270          * @page        CompContentManagerCreateContentPage Compatibility for the file path.
 271          * @section     CompContentManagerCreateContentPageIssueSection Issues
 272          *                 The content path argument of this method in OSP compatible applications has the following issues: @n
 273          *                 -# The content path should be a path that begins with an allowed path prefix. @n
 274          *                     For example, L"/Media/Images/flower.jpg", L"/Storagecard/Media/Images/flower.jpg".
 275          *
 276          * @section     CompContentManagerCreateContentPageSolutionSection Resolutions
 277          *                 This issue has been resolved in Tizen. @n
 278          *                 -# The content path can be a path without a specific allowed path prefix. @n
 279          *                 Application do not need to know the specific allowed path prefixes. @n
 280          *                 To get the directory path, use the following methods: @n
 281          *                 - For accessing the home directory, use Tizen::App::App::GetInstance()->GetAppRootPath().
 282          *                 - For accessing the media directory, use Tizen::System::Environment::GetMediaPath().
 283          *                 - For accessing the external storage, use Tizen::System::Environment::GetExternalStoragePath().
 284          *
 285          * @endif
 286          */
 287
 288         /**
 289          * Gets the content information.
 290          *
 291          * @since                       2.0
 292          * @privlevel           public
 293          * @privilege           %http://tizen.org/privilege/content.read
 294          *
 295          * @return                      A pointer to ContentInfo
 296          * @param[in]   contentId                                               The content ID
 297          * @exception   E_SUCCESS                                       The method is successful.
 298          * @exception   E_INVALID_ARG                           The specified input parameter is invalid, or
 299          *                                          the content information corresponding to @c contentId cannot be found.
 300          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 301          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 302          * @exception   E_SYSTEM                                                A system error has occurred.
 303          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 304          * @exception   E_SERVICE_BUSY                  The database is busy.
 305          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 306          */
 307         ContentInfo* GetContentInfoN(const ContentId& contentId) const;
 308
 309         /**
 310          * Updates the content information with the specified instance of ContentInfo.
 311          *
 312          * @since                       2.0
 313          * @privlevel           public
 314          * @privilege           %http://tizen.org/privilege/content.write
 315          *
 316          * @return                      An error code
 317          * @param[in]   contentInfo                                             An instance of ContentInfo
 318          * @exception   E_SUCCESS                                       The method is successful.
 319          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 320          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 321          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 322          * @exception   E_SYSTEM                                                A system error has occurred.
 323          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 324          * @exception   E_SERVICE_BUSY                  The database is busy.
 325          */
 326         result UpdateContent(const ContentInfo& contentInfo);
 327
 328         /**
 329          * Deletes the content information with the specified content ID.
 330          *
 331          * @since                       2.0
 332          * @privlevel           public
 333          * @privilege           %http://tizen.org/privilege/content.write
 334          *
 335          * @return                      An error code
 336          * @param[in]   contentId                                               The content ID
 337          * @exception   E_SUCCESS                                       The method is successful.
 338          * @exception   E_INVALID_ARG                           The specified input parameter is invalid, or
 339          *                                          the content information corresponding to @c contentId cannot be found.
 340          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 341          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 342          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 343          * @exception   E_SYSTEM                                                A system error has occurred.
 344          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 345          * @exception   E_SERVICE_BUSY                  The database is busy.
 346          * @remarks             The physical file corresponding to @c contentId is deleted.
 347          */
 348         result DeleteContent(const ContentId& contentId);
 349
 350         /**
 351          * Adds a listener to receive the database change notification.
 352          *
 353          * @since                       2.1
 354          *
 355          * @return                      An error code
 356          * @param[in]           listener                                The event listener
 357          * @exception           E_SUCCESS                               The method is successful.
 358          * @exception           E_OBJ_ALREADY_EXIST     The listener has already been added.
 359          * @exception           E_SYSTEM                                The method cannot proceed due to a severe system error.
 360          * @remarks             Only a listener of an instance can be added.
 361          *                                      If you add more than two listeners, the listener added first will receive notification for the DB change.
 362          */
 363         result AddContentUpdateEventListener(IContentUpdateEventListener& listener);
 364
 365         /**
 366          * Removes a listener.
 367          *
 368          * @since           2.1
 369          *
 370          * @return                      An error code
 371          * @param[in]           listener                        The event listener
 372          * @exception           E_SUCCESS                       The method is successful.
 373          * @exception           E_OBJ_NOT_FOUND The listener is not found.
 374          * @exception           E_SYSTEM                        The method cannot proceed due to a severe system error.
 375          */
 376         result RemoveContentUpdateEventListener(IContentUpdateEventListener& listener);
 377
 378
 379         /**
 380          * Requests to scan a file.
 381          *
 382          * @since                       2.1
 383          * @privlevel           public
 384          * @privilege           %http://tizen.org/privilege/content.write
 385          *
 386          * @return              An error code
 387          * @param[in]   contentPath                     The content path
 388          * @exception   E_SUCCESS                       The method is successful.
 389          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 390          * @exception   E_SERVICE_BUSY          The database is busy.
 391          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 392          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 393          */
 394         static result ScanFile(const Tizen::Base::String& contentPath);
 395
 396         /**
 397          * Requests to scan a directory.
 398          *
 399          * @since                       2.1
 400          * @privlevel           public
 401          * @privilege           %http://tizen.org/privilege/content.write
 402          *
 403          * @return                      An error code
 404          * @param[in]           directoryPath                   The directory path
 405          * @param[in]           recursive                               Set to @c true in order to recursively scan sub directories, @n
 406          *                                          else @c false
 407          * @param[in]           pListener                               The scan event listener
 408          * @param[out]          reqId                                   The request ID
 409          * @exception           E_SUCCESS                               The method is successful.
 410          * @exception           E_INVALID_ARG                   The specified input parameter is invalid.
 411          * @exception           E_SERVICE_BUSY                  The database is busy.
 412          * @exception           E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 413          * @exception           E_SYSTEM                                The method cannot proceed due to a severe system error.
 414          * @remark                      Platform does not have the ownership of the listener.
 415          */
 416         static result ScanDirectory(const Tizen::Base::String& directoryPath, bool recursive, IContentScanListener* pListener, RequestId& reqId);
 417
 418 private:
 419         /**
 420          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 421          */
 422         ContentManager(const ContentManager& rhs);
 423
 424         /**
 425          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 426          */
 427         ContentManager& operator =(const ContentManager& rhs);
 428
 429 private:
 430         friend class _ContentManagerImpl;
 431         _ContentManagerImpl* __pImpl;
 432
 433 };  // Class ContentManager
 434
 435 }}  // Tizen::Content
 436
 437 #endif  // _FCNT_CONTENT_MANAGER_H_