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::GetDownloadPath() 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_OUT_OF_MEMORY     The memory is insufficient.
 123         * @exception     E_SYSTEM            The method cannot proceed due to a severe system error.
 124         * @remarks       The specific error code can be accessed using the GetLastResult() method.
 125         */
 126         static DownloadManager* GetInstance(void);
 127
 128         /**
 129         * Starts the download operation. @n
 130         * If this operation succeeds, the IDownloadListener::OnDownloadInProgress() method is called. @n
 131         *
 132         * @since 2.0
 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 URL 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_OUT_OF_MEMORY     The memory is insufficient.
 143         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 144         */
 145         result Start(const DownloadRequest& request, RequestId& reqId);
 146
 147         /**
 148         * Pauses the download operation of the specified request ID. @n
 149         * If this operation succeeds, the IDownloadListener::OnDownloadPaused() method is called.
 150         *
 151         * @since 2.0
 152         *
 153         * @return       An error code
 154         * @param[in]    reqId               The request ID returned by Start()
 155         * @exception    E_SUCCESS           The method is successful.
 156         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 157         * @exception    E_INVALID_OPERATION     The current download state prohibits the execution of this operation. @n
 158         *                                                                       The download state of the request ID is not downloading.
 159         * @exception    E_OUT_OF_MEMORY     The memory is insufficient.
 160         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 161         */
 162         result Pause(RequestId reqId);
 163
 164         /**
 165         * Resumes the download operation of the specified request ID. @n
 166         * If this operation succeeds, the IDownloadListener::OnDownloadInProgress() method is called.
 167         *
 168         * @since 2.0
 169         *
 170         * @return       An error code
 171         * @param[in]    reqId               The request ID returned by Start()
 172         * @exception    E_SUCCESS           The method is successful.
 173         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 174         * @exception    E_INVALID_OPERATION     The current download state prohibits the execution of this operation. @n
 175         *                                                                       The download operation of the request ID is not paused.
 176         * @exception    E_OUT_OF_MEMORY     The memory is insufficient.
 177         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 178         */
 179         result Resume(RequestId reqId);
 180
 181         /**
 182         * Cancels the download operation of the specified request ID.
 183         *
 184         * @since 2.0
 185         *
 186         * @return       An error code
 187         * @param[in]    reqId               The request ID returned by Start()
 188         * @exception    E_SUCCESS           The method is successful.
 189         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 190         * @exception    E_OUT_OF_MEMORY     The memory is insufficient.
 191         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 192         */
 193         result Cancel(RequestId reqId);
 194
 195         /**
 196         * Gets the download request information of the specified request ID.
 197         *
 198         * @since 2.0
 199         *
 200         * @return       The download request
 201         * @param[in]    reqId               The request ID returned by Start()
 202         * @exception    E_SUCCESS           The method is successful.
 203         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 204         * @exception    E_OUT_OF_MEMORY     The memory is insufficient.
 205         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 206         */
 207         DownloadRequest* GetDownloadRequestN(RequestId reqId) const;
 208
 209         /**
 210         * Gets the download state of the given request ID. @n
 211         * If there is no download request for the request ID, DOWNLOAD_STATE_NONE will be returned.
 212         *
 213         * @since 2.0
 214         *
 215         * @return       The download state
 216         * @param[in]    reqId               The request ID returned by Start()
 217         */
 218         DownloadState GetState(RequestId reqId) const;
 219
 220         /**
 221         * Gets the MIME type of a download request.
 222         *
 223         * @since 2.0
 224         *
 225         * @return       An error code
 226         * @param[in]    reqId               The request ID returned by Start()
 227         * @param[out]   mimeType            The MIME type
 228         * @exception    E_SUCCESS           The method is successful.
 229         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 230         * @exception    E_INVALID_OPERATION     The current download state prohibits the execution of this operation. @n
 231         *                                                                       The download state of the request ID is not downloading or paused.
 232         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 233         */
 234         result GetMimeType(RequestId reqId, Tizen::Base::String& mimeType) const;
 235
 236         /**
 237         * Sets a download listener.
 238         *
 239         * @since 2.0
 240         *
 241         * @param[in]    pListener           The download listener @n
 242         *                               If this is @c null, it unsets the download listener.
 243         */
 244         void SetDownloadListener(IDownloadListener* pListener);
 245
 246 private:
 247         /**
 248         * This default constructor is intentionally declared as private to implement the Singleton semantic.
 249         */
 250         DownloadManager(void);
 251
 252         /**
 253         * This destructor is intentionally declared as private to implement the Singleton semantic.
 254         */
 255         virtual ~DownloadManager(void);
 256
 257         /**
 258         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 259         */
 260         DownloadManager(const DownloadManager& downloadManager);
 261
 262         /**
 263         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 264         */
 265         DownloadManager& operator =(const DownloadManager& downloadManager);
 266
 267         friend class _DownloadManagerImpl;
 268         class _DownloadManagerImpl * __pDownloadManagerImpl;
 269
 270 }; // DownloadManager
 271
 272 } } // Tizen::Content
 273
 274 #endif //_FCNT_DOWNLOAD_MANAGER_H_
 275