inc/FCntContentTransfer.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                FCntContentTransfer.h
  19  * @brief               This is the header file for the %ContentTransfer class.
  20  *
  21  * This header file contains the declarations of the %ContentTransfer class.
  22  */
  23
  24 #ifndef _FCNT_CONTENT_TRANSFER_H_
  25 #define _FCNT_CONTENT_TRANSFER_H_
  26
  27 #include <FBaseObject.h>
  28
  29 namespace Tizen { namespace Base { namespace Collection
  30 {
  31 class IList;
  32 }}}
  33
  34 namespace Tizen { namespace Base { namespace Utility
  35 {
  36 class Uri;
  37 }}}
  38
  39 namespace Tizen { namespace Content
  40 {
  41
  42 class _ContentTransferImpl;
  43 class IContentTransferListener;
  44
  45 /**
  46  * @if OSPDEPREC
  47  * @class       ContentTransfer
  48  * @brief       <i> [Deprecated] </i> This class provides methods to download the content.
  49  *
  50  * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
  51  * @since       2.0
  52  *
  53  * The %ContentTransfer class provides the following features:
  54  * - Downloading the content from the servers that support HTTP access.
  55  * - Cancelling a download operation.
  56  *
  57  * HTTP download (ContentTransfer::Download()) is a standard HTTP transaction using the HTTP GET request and response methods.
  58  *
  59  * The following example demonstrates how to use the %ContentTransfer class.
  60  *
  61  *      @code
  62  *      class  MyClass
  63  *              :public Tizen::Content::IContentTransferListener
  64  *      {
  65  *      public:
  66  *              MyClass(void);
  67  *              virtual ~MyClass(void);
  68  *
  69  *      public:
  70  *              void OnContentTransferInProgress(RequestId requestID, int totalReceivedSize);
  71  *              void OnContentDownloadCompleted(RequestId requestID, ContentId contentID, result res, const Tizen::Base::String& errorCode, const Tizen::Base::String& errorMessage);
  72  *              void OnContentDownloadToBufferCompleted(RequestId reqId, Tizen::Base::ByteBuffer* pBuffer, result r, const Tizen::Base::String& errorCode, const Tizen::Base::String& errorMessage);
  73  *              void OnContentTransferCanceled(RequestId reqId, result res, const Tizen::Base::String& errorCode, const Tizen::Base::String& errorMessage);
  74  *      };
  75  *
  76  *      // Implementation for the listener function and Implementation of other listener function is
  77  *      void MyClass::OnContentDownloadCompleted(RequestId requestID, ContentId contentID, result res, const Tizen::Base::String& errorCode, const Tizen::Base::String& errorMessage)
  78  *      {
  79  *              result r = E_SUCCESS;
  80  *              ContentManager contentManager;
  81  *              ContentInfo* pContentInfo = null;
  82  *
  83  *              // Error check
  84  *              TryCatch(!IsFailed(res), r, "Download Error [%s]", GetErrorMessage(res));
  85  *
  86  *              // Do something
  87  *              r = contentManager.Construct();
  88  *              TryCatch(!IsFailed(r), r, "Construct failed.");
  89  *
  90  *              // Get ContentInfo
  91  *              pContentInfo = contentManager.GetContentInfoN(contentID);
  92  *      CATCH:
  93  *              if (pContentInfo)
  94  *                      delete pContentInfo;
  95  *      }
  96  *
  97  *      result
  98  *      MyClass::RequestDownload(void)
  99  *      {
 100  *              ContentTransfer contentTransfer;
 101  *              RequestId requestId;
 102  *              Tizen::Base::Utility::Uri contentUri;
 103  *              int contentSize;
 104  *              Tizen::Base::String downloadPath;
 105  *
 106  *              result r = contentTransfer.Construct(*this);
 107  *              TryReturn(!IsFailed(r), r, ("Construct is failed.\n"));
 108  *
 109  *              // TODO: set uri and download path
 110  *
 111  *              r = contentTransfer.Download(contentUri, downloadPath, requestId, false);
 112  *              TryReturn(!IsFailed(r), r, ("Download Request is failed.\n"));
 113  *      }
 114  *      @endcode
 115  *      @endif
 116  */
 117 class _OSP_EXPORT_ ContentTransfer
 118         : virtual public Tizen::Base::Object
 119 {
 120 public:
 121         /**
 122          * The object is not fully constructed after this constructor is called. For full construction, the Construct(IContentTransferListener&) method must be called right after calling this constructor.
 123          *
 124          * @brief       <i> [Deprecated] </i>
 125          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 126          * @since               2.0
 127          *
 128          * @remarks             After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
 129          */
 130         ContentTransfer(void);
 131
 132         /**
 133          * This destructor overrides Tizen::Base::Object::~Object().
 134          *
 135          * @brief       <i> [Deprecated] </i>
 136          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 137          *
 138          * @since               2.0
 139          */
 140         virtual ~ContentTransfer(void);
 141
 142         /**
 143          * Initializes this instance of %ContentTransfer with the specified parameter. @n
 144          * This method should be called after every instance of %ContentTransfer is constructed.
 145          *
 146          * @brief       <i> [Deprecated] </i>
 147          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 148          * @since               2.0
 149          *
 150          * @return              An error code
 151          * @param[in]   listener                A reference to IContentTransferListener
 152          * @exception   E_SUCCESS               The method is successful.
 153          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 154          * @exception   E_SYSTEM                A system error has occurred.
 155          */
 156         result Construct(IContentTransferListener& listener);
 157
 158         /**
 159         * Downloads a content file from the content provider's server. @n
 160         * The @c filesize parameter is used to check the limitation of the local volume. If this parameter is set to @c 0, this method will not check the volume. @n
 161         * An application should set the full destination path for the downloaded contents. When the content is downloaded to one of the following paths, this method internally registers the content using ContentManager.
 162         * - /Media/
 163         * - /Storagecard/Media/ @n
 164         *
 165         * When the download is completed, the application is notified using the IContentTransferListener::OnContentDownloadCompleted() method. @n
 166         * When the data is being downloaded, the application is notified of the progress using the IContentTransferListener::OnContentTransferInProgress() method.
 167         *
 168         * @brief        <i> [Deprecated] </i>
 169         * @deprecated This method is deprecated due to the operation policy of the Tizen Server.
 170         * When downloading the contents from a third party server, it is recommended to use the Download(const Tizen::Base::Utility::Uri&, const Tizen::Base::String&, RequestId&, bool, int, int) method.
 171         * @since                                 2.0
 172         * @privlevel    public
 173         * @privilege    %http://tizen.org/privilege/download
 174         *
 175         * @return       An error code
 176         * @param[in]    uri                                     The content URL
 177         * @param[in]    fileSize                        The content file size in bytes @n
 178         *                                                                       If set to @c 0, the method does not check the storage limitation.
 179         * @param[in]    destFilePath            The full destination path
 180         * @param[in]    replace                         The replace option of the destination file @n
 181         *                                                                       Set to @c true to replace the file, @n
 182         *                                                                       else @c false.
 183         * @param[out]   reqId                           The request ID
 184         * @param[in]    pListener                       A pointer to the IContentTransferListener instance
 185         * @param[in]    sec                                     The timeout period in seconds
 186         * @exception    E_SUCCESS                               The method is successful.
 187         * @exception    E_INVALID_ARG                   A specified input parameter is invalid.
 188         * @exception    E_INVALID_STATE         This method is invalid for the current state of this instance.
 189         * @exception    E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 190         * @exception    E_FILE_ALREADY_EXIST    The specified file already exists.
 191         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 192         * @exception    E_IN_PROGRESS                   A previous request is in progress.
 193         * @exception    E_OUT_OF_MEMORY The memory is insufficient.
 194         * @see  IContentTransferListener::OnContentDownloadCompleted()
 195         * @see  IContentTransferListener::OnContentTransferInProgress()
 196         */
 197         result Download(const Tizen::Base::Utility::Uri& uri, int fileSize, const Tizen::Base::String& destFilePath, bool replace, RequestId& reqId, IContentTransferListener* pListener = null, int sec = 0);
 198
 199         /**
 200          * Downloads a content file from the content provider's server. @n
 201          * An application should set the destination path for the downloaded contents.
 202          * The path of the downloaded file should use Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath().
 203          *
 204          * When the content is downloaded to the path using Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath(), this method internally registers the content in the content database. @n
 205          * When the download is completed, the application is notified using the IContentTransferListener::OnContentDownloadCompleted() method. @n
 206          * When the data is being downloaded, the application is notified of the progress using the IContentTransferListener::OnContentTransferInProgress() method.
 207          *
 208          * @brief       <i> [Deprecated] </i>
 209          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 210          * @if OSPCOMPAT
 211          * @brief <i> [Compatibility] </i>
 212          * @endif
 213          * @since                       2.0
 214          * @if OSPCOMPAT
 215          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 216          *                       For more information, see @ref CompContentTransferDownloadPage3 "here".
 217          * @endif
 218          * @privlevel           public
 219          * @privilege           %http://tizen.org/privilege/download
 220          *
 221          * @return                      An error code
 222          * @param[in]   uri                                             The content URL
 223          * @param[in]   filePath                                The destination file path @n
 224          *                                                      Use Tizen::System::Environment::GetMediaPath(), Tizen::System::Environment::GetExternalStoragePath() and Tizen::App::App::GetInstance()->GetAppRootPath().
 225          * @param[out]  reqId                   The request ID
 226          * @param[in]   replace                 The replace option of the destination file @n
 227          *                                       Set to @c true to replace the file, @n
 228          *                                                                              else @c false.
 229          * @param[in]   timeout                 The timeout period in seconds
 230          * @param[in]   progressInterval        The progress period interval as a percentage value
 231          * @exception   E_SUCCESS                               The method is successful.
 232          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 233          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 234          * @exception   E_INVALID_STATE         This method is invalid for the current state of this instance.
 235          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 236          * @exception   E_FILE_ALREADY_EXIST    The specified file already exists.
 237          * @exception   E_IN_PROGRESS                   A previous request is in progress.
 238          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 239          * @exception   E_SYSTEM                                A system error has occurred.
 240          * @remarks             The @c progressInterval is the interval of the progress for each download request. If the value of the @c progressInterval is @c 0, the @c progressInterval uses the value set by the ContentTransfer::SetProgressIntervalByPercent(int). The @c progressInterval is a percentage value between @c 0 and @c 100.
 241          *                              The @c timeout is the value of the response timeout for each download request. If the value of the @c timeout is @c 0, the value for the @c timeout uses the value set by the ContentTransfer::SetDefaultTimeout(int).
 242          * @see  IContentTransferListener::OnContentDownloadCompleted()
 243          * @see  IContentTransferListener::OnContentTransferInProgress()
 244          */
 245         result Download(const Tizen::Base::Utility::Uri& uri, const Tizen::Base::String& filePath, RequestId& reqId, bool replace = false, int timeout = 0, int progressInterval = 0);
 246
 247         /**
 248          * @if OSPCOMPAT
 249          * @page                CompContentTransferDownloadPage3 Compatibility for the file path.
 250          * @section     CompContentTransferDownloadPageIssueSection Issues
 251          *                 The content path argument of this method in OSP compatible applications has the following issues: @n
 252          *                 -# The content path should be a path that begins with an allowed path prefix. @n
 253          *                    For example, L"/Media/Images/flower.jpg", "/Storagecard/Media/Images/flower.jpg".
 254          *
 255          * @section     CompImageContentInfoConstructPageSolutionSection Resolutions
 256          *                 This issue has been resolved in Tizen. @n
 257          *                 -# The content path can be a path without a specific allowed path prefix. @n
 258          *                 Application do not need to know the specific allowed path prefixes. @n
 259          *                 To get the directory path, use the following methods: @n
 260          *                 - For accessing the media directory, use Tizen::System::Environment::GetMediaPath().
 261          *                 - For accessing the external storage, use Tizen::System::Environment::GetExternalStoragePath().
 262          *
 263          * @endif
 264          */
 265
 266         /**
 267         * Downloads a content file to a buffer from the content provider's servers. @n
 268         * This method does not register the content. @n
 269         * When the download is completed, the application is notified using the IContentTransferListener::OnContentDownloadToBufferCompleted() method. @n
 270         * When the data is being downloaded, the application is notified of the progress using the IContentTransferListener::OnContentTransferInProgress() method.
 271         *
 272         * @brief        <i> [Deprecated] </i>
 273         * @deprecated This method is deprecated due to the operation policy of the Tizen Server.
 274         * When downloading the contents to a buffer from a third party server, it is recommended to use the DownloadToBuffer(const Tizen::Base::Utility::Uri&, RequestId&, int, int) method.
 275         * @since                                 2.0
 276         * @privlevel    public
 277         * @privilege    %http://tizen.org/privilege/download
 278         *
 279         * @return       An error code
 280         * @param[in]    uri                                     The content URL
 281         * @param[in]    fileSize                        The content file size in bytes @n
 282         *                                                                       If set to @c 0, the method does not check the storage limitation.
 283         * @param[out]   reqId                           The request ID
 284         * @param[in]    pListener                       A pointer to the IContentTransferListener instance
 285         * @param[in]    sec                                     The timeout period in seconds
 286         * @exception    E_SUCCESS                               The method is successful.
 287         * @exception    E_INVALID_ARG                   A specified input parameter is invalid.
 288         * @exception    E_INVALID_STATE         This method is invalid for the current state of this instance.
 289         * @exception    E_OUT_OF_MEMORY         The memory is insufficient.
 290         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 291         * @see  IContentTransferListener::OnContentDownloadToBufferCompleted()
 292         * @see  IContentTransferListener::OnContentTransferInProgress()
 293         */
 294         result DownloadToBuffer(const Tizen::Base::Utility::Uri& uri, int fileSize, RequestId& reqId, IContentTransferListener* pListener = null, int sec = 0);
 295
 296         /**
 297          * Downloads a content file to a buffer from the content provider's servers. @n
 298          * This method does not register the content. @n
 299          * When the download is completed, the application is notified using the IContentTransferListener::OnContentDownloadToBufferCompleted() method. @n
 300          * When the data is being downloaded, the application is notified of the progress using the IContentTransferListener::OnContentTransferInProgress() method.
 301          *
 302          * @brief       <i> [Deprecated] </i>
 303          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 304          * @since                       2.0
 305          * @privlevel           public
 306          * @privilege           %http://tizen.org/privilege/download
 307          *
 308          * @return                      An error code
 309          * @param[in]   uri                                             The content URL
 310          * @param[out]  reqId                                   The request ID
 311          * @param[in]   timeout                                 The timeout period in seconds
 312          * @param[in]   progressInterval        The progress period interval as a percentage value
 313          * @exception   E_SUCCESS                               The method is successful.
 314          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 315          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 316          * @exception   E_INVALID_STATE         This method is invalid for the current state of this instance.
 317          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 318          * @exception   E_IN_PROGRESS                   A previous request is in progress.
 319          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 320          * @remarks             The @c progressInterval is the interval of the progress for each download request. If the value of the @c progressInterval is @c 0, the @c progressInterval uses the value set by the ContentTransfer::SetProgressIntervalByPercent(int). The @c progressInterval is a percentage value between @c 0 and @c 100.
 321          *                              The @c timeout is the value of the response timeout for each download request. If the value of the @c timeout is @c 0, the value for the @c timeout uses the value set by the ContentTransfer::SetDefaultTimeout(int).
 322          * @see  IContentTransferListener::OnContentDownloadToBufferCompleted()
 323          * @see  IContentTransferListener::OnContentTransferInProgress()
 324          */
 325         result DownloadToBuffer(const Tizen::Base::Utility::Uri& uri, RequestId& reqId, int timeout = 0, int progressInterval = 0);
 326
 327         /**
 328          * Sets the default timeout period. @n
 329          * If the server does not respond during the timeout period, the network connection is closed.
 330          * @c 0 or minus second means unlimited period.
 331          *
 332          * @brief       <i> [Deprecated] </i>
 333          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 334          * @since               2.0
 335          *
 336          * @param[in]   sec                     The default timeout period in seconds @n
 337          *                          The default value is @c 0.
 338          */
 339         void SetDefaultTimeout(int sec);
 340
 341         /**
 342          * Gets the default timeout period.
 343          *
 344          * @brief       <i> [Deprecated] </i>
 345          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 346          * @since               2.0
 347          *
 348          * @return              The default timeout period
 349          */
 350         int GetDefaultTimeout(void) const;
 351
 352         /**
 353          * Removes a transfer operation. @n
 354          * This operation removes a request for multiple downloads.
 355          * A download operation in progress is not removed by this operation.
 356          *
 357          * @brief       <i> [Deprecated] </i>
 358          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 359          * @since               2.0
 360          *
 361          * @return              An error code
 362          * @param[in]   reqId The request ID
 363          * @exception   E_SUCCESS                       The method is successful.
 364          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 365          * @exception   E_OBJ_NOT_FOUND The specified @c reqId is not found.
 366          * @exception   E_INVALID_STATE This method is invalid for the current state of this instance.
 367          * @remarks     To stop an on-going transfer, use the Cancel() method.
 368          */
 369         result Remove(RequestId reqId);
 370
 371         /**
 372          * Removes all the transfer operations. @n
 373          * This operation removes all the requests for multiple downloads.
 374          * The download operations in progress are not removed by this operation.
 375          *
 376          * @brief       <i> [Deprecated] </i>
 377          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 378          * @since               2.0
 379          *
 380          * @return              An error code
 381          * @exception   E_SUCCESS                       The method is successful.
 382          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 383          * @exception   E_INVALID_STATE This method is invalid for the current state of this instance.
 384          * @remarks     To stop an on-going transfer, use the Cancel() method.
 385          */
 386         result RemoveAll(void);
 387
 388         /**
 389          * Cancels a transfer operation. @n
 390          * The downloaded file is deleted from the file system. @n
 391          * When a transfer download operation is canceled, the application is notified via the IContentTransferListener::OnContentTransferCanceled() method.
 392          *
 393          * @brief       <i> [Deprecated] </i>
 394          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 395          * @since               2.0
 396          *
 397          * @return              An error code
 398          * @param[in]   reqId                   The request ID
 399          * @exception   E_SUCCESS                       The method is successful.
 400          * @exception   E_OBJ_NOT_FOUND         The specified @c reqId is not found.
 401          * @exception   E_INVALID_ARG           The specified input parameter is invalid.
 402          * @exception   E_INVALID_STATE This method is invalid for the current state of this instance.
 403          * @see IContentTransferListener::OnContentTransferCanceled()
 404          */
 405         result Cancel(RequestId reqId);
 406
 407         /**
 408          * Cancels all the operations in progress.
 409          *
 410          * @brief       <i> [Deprecated] </i>
 411          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 412          * @since               2.0
 413          *
 414          * @return              An error code
 415          * @exception   E_SUCCESS                       The method is successful.
 416          * @exception   E_OUT_OF_MEMORY The memory is insufficient.
 417          * @exception   E_INVALID_STATE This method is invalid for the current state of this instance.
 418          */
 419         result CancelAll(void);
 420
 421         /**
 422          * Gets the content transfer information list.
 423          *
 424          * @brief       <i> [Deprecated] </i>
 425          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 426          * @since               2.0
 427          *
 428          * @return              A pointer to a list containing the ContentTransferInfo instances, @n
 429          *                              else an empty list if there is no result and no error
 430          */
 431         Tizen::Base::Collection::IList* GetContentTransferInfoListN(void) const;
 432
 433         /**
 434          * Gets the list of transfers that are in progress.
 435          *
 436          * @brief       <i> [Deprecated] </i>
 437          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 438          * @since               2.0
 439          *
 440          * @return              A pointer to a list containing the ContentTransferInfo instances, @n
 441          *                              else an empty list if there is no result and no error
 442          */
 443         Tizen::Base::Collection::IList* GetContentTransferInfoListInProgressN(void) const;
 444
 445         /**
 446          * Sets the interval of the progress. @n
 447          * The input is a percentage value between @c 0 and @c 100. The default value is @c 0.
 448          * @c 0 means the application would not receive progress events.
 449          *
 450          * @brief       <i> [Deprecated] </i>
 451          * @deprecated  This class is deprecated. Instead of using this class, use DownloadManager class.
 452          * @since               2.0
 453          *
 454          * @param[in]   percent         The progress period interval as a percentage value
 455          * @remarks     If a server does not provide the information about the content size, then the content module cannot verify the information. @n
 456          *              In that case, progress event will occur randomly.
 457          */
 458         void SetProgressIntervalByPercent(int percent);
 459
 460 private:
 461         /**
 462          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 463          */
 464         ContentTransfer(const ContentTransfer& rhs);
 465
 466         /**
 467          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 468          */
 469         ContentTransfer& operator =(const ContentTransfer& rhs);
 470
 471 private:
 472         friend class _ContentTransferImpl;
 473         _ContentTransferImpl* __pImpl;
 474
 475 };  // class ContentTransfer
 476
 477 }}  // Tizen::Content
 478
 479 #endif  // _FCNT_CONTENT_TRANSFER_H_