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_USER_NOT_CONSENTED    The user blocks an application from calling this method.
 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_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     The current download state prohibits the execution of this operation. @n
 174         *                                                                       The download state for the specified request ID is either not paused or has failed.
 175         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 176         */
 177         result Resume(RequestId reqId);
 178
 179         /**
 180         * Cancels the download operation of the specified request ID.
 181         *
 182         * @since 2.0
 183         *
 184         * @return       An error code
 185         * @param[in]    reqId               The request ID returned by Start()
 186         * @exception    E_SUCCESS           The method is successful.
 187         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 188         * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 189         */
 190         result Cancel(RequestId reqId);
 191
 192         /**
 193         * Gets the download request information of the specified request ID.
 194         *
 195         * @since 2.0
 196         *
 197         * @return       The download request
 198         * @param[in]    reqId               The request ID returned by Start()
 199         * @exception    E_SUCCESS           The method is successful.
 200         * @exception    E_INVALID_ARG           There is no download request for the specified @c reqId.
 201         * @remarks              The specific error code can be accessed using the GetLastResult() method.
 202         * @remarks      The download request information will be available at least 24 hours after IDownloadListener::OnDownloadCompleted() is 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, DOWNLOAD_STATE_NONE will be 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 will be available at least 24 hours after IDownloadListener::OnDownloadCompleted() is 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 will be available at least 24 hours after IDownloadListener::OnDownloadCompleted() is 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