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