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 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 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 has been 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 an 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        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 blocks an 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     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
 201         *                               - The specific error code can be accessed using the GetLastResult() method.
 202         *                               - The download request information is available for at least the next 24 hours after IDownloadListener::OnDownloadCompleted() has been called.
 203         */
 204         DownloadRequest* GetDownloadRequestN(RequestId reqId) const;
 205
 206         /**
 207         * Gets the download state of the given request ID. @n
 208         * If there is no download request for the request ID, @c DOWNLOAD_STATE_NONE is returned.
 209         *
 210         * @since 2.0
 211         *
 212         * @return       The download state
 213         * @param[in]    reqId               The request ID returned by Start()
 214         * @remarks      The download state information is available for at least the next 24 hours after IDownloadListener::OnDownloadCompleted() has been called.
 215         */
 216         DownloadState GetState(RequestId reqId) const;
 217
 218         /**
 219         * Gets the MIME type of a download request.
 220         *
 221         * @since 2.0
 222         *
 223         * @return       An error code
 224         * @param[in]    reqId               The request ID returned by Start()
 225         * @param[out]   mimeType            The MIME type
 226         * @exception    E_SUCCESS           The method is successful.
 227         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 228         * @exception    E_INVALID_OPERATION     The current download state prohibits the execution of this operation. @n
 229         *                                                                       The download operation has not yet started.
 230         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 231         * @remarks      The MIME type information is available for at least the next 24 hours after IDownloadListener::OnDownloadCompleted() has been called.
 232         */
 233         result GetMimeType(RequestId reqId, Tizen::Base::String& mimeType) const;
 234
 235         /**
 236         * Sets a download listener.
 237         *
 238         * @since 2.0
 239         *
 240         * @param[in]    pListener           The download listener @n
 241         *                               If this is @c null, it unsets the download listener.
 242         */
 243         void SetDownloadListener(IDownloadListener* pListener);
 244
 245 private:
 246         /**
 247         * This default constructor is intentionally declared as private to implement the Singleton semantic.
 248         */
 249         DownloadManager(void);
 250
 251         /**
 252         * This destructor is intentionally declared as private to implement the Singleton semantic.
 253         */
 254         virtual ~DownloadManager(void);
 255
 256         /**
 257         * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 258         */
 259         DownloadManager(const DownloadManager& downloadManager);
 260
 261         /**
 262         * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 263         */
 264         DownloadManager& operator =(const DownloadManager& downloadManager);
 265
 266         friend class _DownloadManagerImpl;
 267         class _DownloadManagerImpl * __pDownloadManagerImpl;
 268
 269 }; // DownloadManager
 270
 271 } } // Tizen::Content
 272
 273 #endif //_FCNT_DOWNLOAD_MANAGER_H_
 274