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