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