inc/FCntDownloadManager.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                FCntDownloadManager.h
  19  * @brief               This is the header file for the %DownloadManager class.
  20  *
  21  * This header file contains the declarations of the %DownloadManager class.
  22  */
  23 #ifndef _FCNT_DOWNLOAD_MANAGER_H_
  24 #define _FCNT_DOWNLOAD_MANAGER_H_
  25
  26 #include <FBaseResult.h>
  27 #include <FBaseString.h>
  28 #include <FCntTypes.h>
  29
  30
  31 namespace Tizen { namespace Content
  32 {
  33
  34 class DownloadRequest;
  35 class IDownloadListener;
  36
  37 /**
  38 * @class    DownloadManager
  39 * @brief    This class provides methods to handle HTTP downloads.
  40 *
  41 * @since 2.0
  42 *
  43 * @final        This class is not intended for extension.
  44 *
  45 * The %DownloadManager class provides methods to handle HTTP downloads. A download request consists of a URL and a destination path; of which the URL is mandatory for downloading content. If the destination path is not specified, the content is downloaded to a default download storage that can be obtained with the System::Environment::GetDefaultDownloadPath() method.
  46 * This class conducts the download in the background and calls the Start() method that takes care of HTTP connections. @n
  47 * The download operation can be:
  48 * - Paused by calling the Pause() method
  49 * - Resumed by calling the Resume() method
  50 * - Cancelled by calling the Cancel() method
  51 * Depending on how the download operation is terminated the following methods are called:
  52 * - IDownloadListener::OnDownloadCanceled() when the download is cancelled
  53 * - IDownloadListener::OnDownloadCompleted() when the download is completed without any errors
  54 * - IDownloadListener::OnDownloadFailed() when the download has been stopped because of an error
  55 *
  56 * The following example demonstrates how to use the %DownloadManager class.
  57 *
  58 * @code
  59 *
  60 * #include <FBase.h>
  61 * #include <FContent.h>
  62 *
  63 * using namespace Tizen::Base;
  64 * using namespace Tizen::Content;
  65 * using namespace Tizen::App;
  66 *
  67 * class MyAppClass
  68 *       : public Tizen::Content::IDownloadListener
  69 * {
  70 * public:
  71 *       result Download(const String& url);
  72 *       virtual void OnDownloadCanceled(RequestId reqId) {}
  73 *       virtual void OnDownloadCompleted(RequestId reqId, const Tizen::Base::String& path);
  74 *       virtual void OnDownloadFailed(RequestId reqId, result r, const Tizen::Base::String& errorCode);
  75 *       virtual void OnDownloadPaused(RequestId reqId) {}
  76 *       virtual void OnDownloadInProgress(RequestId reqId, unsigned long long receivedSize, unsigned long long totalSize) {}
  77 *
  78 * };
  79 *
  80 * result
  81 * MyAppClass::Download(const String& url)
  82 * {
  83 *       result r = E_SUCCESS;
  84 *       RequestId reqId = 0;
  85 *
  86 *       DownloadRequest request(url);
  87 *       DownloadManager* pManager = DownloadManager::GetInstance();
  88 *
  89 *       pManager->SetDownloadListener(this);
  90 *       pManager->Start(request, reqId);
  91 *
  92 *       return r;
  93 * }
  94 *
  95 * void
  96 * MyAppClass::void OnDownloadCompleted(RequestId reqId, const Tizen::Base::String& path)
  97 * {
  98 *       AppLog("Download is completed.");
  99 * }
 100 *
 101 * void
 102 * MyAppClass::OnDownloadFailed(RequestId reqId, result r, const Tizen::Base::String& errorCode)
 103 * {
 104 *       AppLog("Download failed.");
 105 * }
 106 *
 107 * @endcode
 108 */
 109
 110 class _OSP_EXPORT_ DownloadManager
 111         : public Tizen::Base::Object
 112 {
 113 public:
 114         /**
 115         * Gets the download manager instance of an application.
 116         *
 117         * @since 2.0
 118         *
 119         * @return               A pointer to the %DownloadManager instance, @n
 120         *                               else @c null if it fails
 121         * @exception     E_SUCCESS           The method is successful.
 122         * @exception     E_SYSTEM            The method cannot proceed due to a severe system error.
 123         * @remarks       The specific error code can be accessed using the GetLastResult() method.
 124         */
 125         static DownloadManager* GetInstance(void);
 126
 127         /**
 128         * Starts the download operation. @n
 129         * If this operation succeeds, the IDownloadListener::OnDownloadInProgress() method is called. @n
 130         *
 131         * @since 2.0
 132         * @privlevel    public
 133         * @privilege    %http://tizen.org/privilege/download
 134         *
 135         * @return       An error code
 136         * @param[in]    request             The download request
 137         * @param[out]   reqId               The request ID
 138         * @exception    E_SUCCESS           The method is successful.
 139         * @exception    E_INVALID_ARG           The information of the download request is invalid.
 140         * @exception    E_ILLEGAL_ACCESS        Access to the path of the download request is denied due to insufficient permission.
 141         * @exception    E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.
 142         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 143         */
 144         result Start(const DownloadRequest& request, RequestId& reqId);
 145
 146         /**
 147         * Pauses the download operation of the specified request ID. @n
 148         * If this operation succeeds, the IDownloadListener::OnDownloadPaused() method is called.
 149         *
 150         * @since 2.0
 151         *
 152         * @return       An error code
 153         * @param[in]    reqId               The request ID returned by Start()
 154         * @exception    E_SUCCESS           The method is successful.
 155         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 156         * @exception    E_INVALID_OPERATION     The current download state prohibits the execution of this operation. @n
 157         *                                                                       The download state of the request ID is not downloading.
 158         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 159         */
 160         result Pause(RequestId reqId);
 161
 162         /**
 163         * Resumes the download operation of the specified request ID. @n
 164         * If this operation succeeds, the IDownloadListener::OnDownloadInProgress() method is called.
 165         *
 166         * @since 2.0
 167         *
 168         * @return       An error code
 169         * @param[in]    reqId               The request ID returned by Start()
 170         * @exception    E_SUCCESS           The method is successful.
 171         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 172         * @exception    E_INVALID_OPERATION     The current download state prohibits the execution of this operation. @n
 173         *                                                                       The download state for the specified request ID is either not paused or has failed.
 174         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 175         */
 176         result Resume(RequestId reqId);
 177
 178         /**
 179         * Cancels the download operation of the specified request ID.
 180         *
 181         * @since 2.0
 182         *
 183         * @return       An error code
 184         * @param[in]    reqId               The request ID returned by Start()
 185         * @exception    E_SUCCESS           The method is successful.
 186         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 187         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 188         */
 189         result Cancel(RequestId reqId);
 190
 191         /**
 192         * Gets the download request information of the specified request ID.
 193         *
 194         * @since 2.0
 195         *
 196         * @return       The download request
 197         * @param[in]    reqId               The request ID returned by Start()
 198         * @exception    E_SUCCESS           The method is successful.
 199         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 200         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 201         * @remarks      The download request information will be available at least 24 hours after IDownloadListener::OnDownloadCompleted() is called.
 202         */
 203         DownloadRequest* GetDownloadRequestN(RequestId reqId) const;
 204
 205         /**
 206         * Gets the download state of the given request ID. @n
 207         * If there is no download request for the request ID, DOWNLOAD_STATE_NONE will be returned.
 208         *
 209         * @since 2.0
 210         *
 211         * @return       The download state
 212         * @param[in]    reqId               The request ID returned by Start()
 213         * @remarks      The download state information will be available at least 24 hours after IDownloadListener::OnDownloadCompleted() is called.
 214         */
 215         DownloadState GetState(RequestId reqId) const;
 216
 217         /**
 218         * Gets the MIME type of a download request.
 219         *
 220         * @since 2.0
 221         *
 222         * @return       An error code
 223         * @param[in]    reqId               The request ID returned by Start()
 224         * @param[out]   mimeType            The MIME type
 225         * @exception    E_SUCCESS           The method is successful.
 226         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 227         * @exception    E_INVALID_OPERATION     The current download state prohibits the execution of this operation. @n
 228         *                                                                       The download operation has not yet started.
 229         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 230         * @remarks      The MIME type information will be available at least 24 hours after IDownloadListener::OnDownloadCompleted() is called.
 231         */
 232         result GetMimeType(RequestId reqId, Tizen::Base::String& mimeType) const;
 233
 234         /**
 235         * Sets a download listener.
 236         *
 237         * @since 2.0
 238         *
 239         * @param[in]    pListener           The download listener @n
 240         *                               If this is @c null, it unsets the download listener.
 241         */
 242         void SetDownloadListener(IDownloadListener* pListener);
 243
 244 private:
 245         /**
 246         * This default constructor is intentionally declared as private to implement the Singleton semantic.
 247         */
 248         DownloadManager(void);
 249
 250         /**
 251         * This destructor is intentionally declared as private to implement the Singleton semantic.
 252         */
 253         virtual ~DownloadManager(void);
 254
 255         /**
 256         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 257         */
 258         DownloadManager(const DownloadManager& downloadManager);
 259
 260         /**
 261         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 262         */
 263         DownloadManager& operator =(const DownloadManager& downloadManager);
 264
 265         friend class _DownloadManagerImpl;
 266         class _DownloadManagerImpl * __pDownloadManagerImpl;
 267
 268 }; // DownloadManager
 269
 270 } } // Tizen::Content
 271
 272 #endif //_FCNT_DOWNLOAD_MANAGER_H_
 273