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 @n
 202          *                                                                      The path should be started with the directory path returned by either
 203          *                                                                      Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath().
 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     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 be started 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: @n
 250          *                                                         - A specified input parameter is invalid. @n
 251          *                                                         - There is a mismatch between the type of the source path and destination path. @n
 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                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_OUT_OF_MEMORY         The memory is insufficient.
 260          * @exception   E_SYSTEM                                                A system error has occurred.
 261          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 262          * @exception   E_SERVICE_BUSY                  The database is busy.
 263          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 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          * Gets the content information.
 289          *
 290          * @since                       2.0
 291          * @privlevel           public
 292          * @privilege           %http://tizen.org/privilege/content.read
 293          *
 294          * @return                      A pointer to ContentInfo
 295          * @param[in]   contentId                                               The content ID
 296          * @exception   E_SUCCESS                                       The method is successful.
 297          * @exception   E_INVALID_ARG                           The specified input parameter is invalid, or
 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_OUT_OF_MEMORY         The memory is insufficient.
 301          * @exception   E_SYSTEM                                                A system error has occurred.
 302          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 303          * @exception   E_SERVICE_BUSY                  The database is busy.
 304          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 305          */
 306         ContentInfo* GetContentInfoN(const ContentId& contentId) const;
 307
 308         /**
 309          * Updates the content information with the specified instance of ContentInfo.
 310          *
 311          * @since                       2.0
 312          * @privlevel           public
 313          * @privilege           %http://tizen.org/privilege/content.write
 314          *
 315          * @return                      An error code
 316          * @param[in]   contentInfo                                             An instance of ContentInfo
 317          * @exception   E_SUCCESS                                       The method is successful.
 318          * @exception   E_INVALID_ARG                           The specified input parameter is invalid.
 319          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 320          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 321          * @exception   E_SYSTEM                                                A system error has occurred.
 322          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 323          * @exception   E_SERVICE_BUSY                  The database is busy.
 324          */
 325         result UpdateContent(const ContentInfo& contentInfo);
 326
 327         /**
 328          * Deletes the content information with the specified content ID.
 329          *
 330          * @since                       2.0
 331          * @privlevel           public
 332          * @privilege           %http://tizen.org/privilege/content.write
 333          *
 334          * @return                      An error code
 335          * @param[in]   contentId                                               The content ID
 336          * @exception   E_SUCCESS                                       The method is successful.
 337          * @exception   E_INVALID_ARG                           The specified input parameter is invalid, or
 338          *                                          the content information corresponding to @c contentId cannot be found.
 339          * @exception   E_FILE_NOT_FOUND                The specified file cannot be found or accessed.
 340          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 341          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 342          * @exception   E_SYSTEM                                                A system error has occurred.
 343          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 344          * @exception   E_SERVICE_BUSY                  The database is busy.
 345          * @remarks             The physical file corresponding to @c contentId is deleted.
 346          */
 347         result DeleteContent(const ContentId& contentId);
 348
 349         /**
 350          * Adds a listener to receive the database change notification.
 351          *
 352          * @since                       2.1
 353          *
 354          * @return                      An error code
 355          * @param[in]           listener                                The event listener to add
 356          * @exception           E_SUCCESS                               The method is successful.
 357          * @exception           E_OBJ_ALREADY_EXIST     The listener has already been added.
 358          * @exception           E_SYSTEM                                The method cannot proceed due to a severe system error.
 359          * @remarks             Only a listener of an instance can be added.
 360          *                                      If you add more than two listeners, the listener added first will receive notification for the DB change.
 361          */
 362         result AddContentUpdateEventListener(IContentUpdateEventListener& listener);
 363
 364         /**
 365          * Removes a listener.
 366          *
 367          * @since           2.1
 368          *
 369          * @return                      An error code
 370          * @param[in]           listener                        The event listener to remove
 371          * @exception           E_SUCCESS                       The method is successful.
 372          * @exception           E_OBJ_NOT_FOUND The listener is not found.
 373          * @exception           E_SYSTEM                        The method cannot proceed due to a severe system error.
 374          */
 375         result RemoveContentUpdateEventListener(IContentUpdateEventListener& listener);
 376
 377
 378         /**
 379          * Requests to scan a file.
 380          *
 381          * @since                       2.1
 382          * @privlevel           public
 383          * @privilege           %http://tizen.org/privilege/content.write
 384          *
 385          * @return              An error code
 386          * @param[in]   contentPath                     The content path
 387          * @exception   E_SUCCESS                       The method is successful.
 388          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 389          * @exception   E_SERVICE_BUSY          The database is busy.
 390          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 391          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.
 392          */
 393         static result ScanFile(const Tizen::Base::String& contentPath);
 394
 395         /**
 396          * Requests to scan a directory.
 397          *
 398          * @since                       2.1
 399          * @privlevel           public
 400          * @privilege           %http://tizen.org/privilege/content.write
 401          *
 402          * @return                      An error code
 403          * @param[in]           directoryPath                   The directory path
 404          * @param[in]           recursive                               Set to @c true in order to recursively scan sub directories, @n
 405          *                                          else @c false
 406          * @param[in]           pListener                               The scan event listener
 407          * @param[out]          reqId                                   The request ID
 408          * @exception           E_SUCCESS                               The method is successful.
 409          * @exception           E_INVALID_ARG                   The specified input parameter is invalid.
 410          * @exception           E_SERVICE_BUSY                  The database is busy.
 411          * @exception           E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.
 412          * @exception           E_SYSTEM                                The method cannot proceed due to a severe system error.
 413          * @remarks                     Platform does not have the ownership of the listener.
 414          */
 415         static result ScanDirectory(const Tizen::Base::String& directoryPath, bool recursive, IContentScanListener* pListener, RequestId& reqId);
 416
 417 private:
 418         /**
 419          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 420          */
 421         ContentManager(const ContentManager& rhs);
 422
 423         /**
 424          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 425          */
 426         ContentManager& operator =(const ContentManager& rhs);
 427
 428 private:
 429         friend class _ContentManagerImpl;
 430         _ContentManagerImpl* __pImpl;
 431
 432 };  // Class ContentManager
 433
 434 }}  // Tizen::Content
 435
 436 #endif  // _FCNT_CONTENT_MANAGER_H_