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  * #include <FApp.h>
  59  * #include <FBase.h>
  60  * #include <FContent.h>
  61  *
  62  * using namespace Tizen::App;
  63  * using namespace Tizen::Base;
  64  * using namespace Tizen::Content;
  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  *              DownloadRequest request(url);
  83  *              DownloadManager* pManager = DownloadManager::GetInstance();
  84  *
  85  *              RequestId reqId = 0;
  86  *              pManager->SetDownloadListener(this);
  87  *              result r = pManager->Start(request, reqId);
  88  *
  89  *              return r;
  90  * }
  91  *
  92  * void
  93  * MyAppClass::void OnDownloadCompleted(RequestId reqId, const Tizen::Base::String& path)
  94  * {
  95  *              AppLog("Download is completed.");
  96  * }
  97  *
  98  * void
  99  * MyAppClass::OnDownloadFailed(RequestId reqId, result r, const Tizen::Base::String& errorCode)
 100  * {
 101  *              AppLog("Download failed.");
 102  * }
 103  * @endcode
 104  */
 105
 106 class _OSP_EXPORT_ DownloadManager
 107         : public Tizen::Base::Object
 108 {
 109 public:
 110         /**
 111          * Gets the download manager instance of the application.
 112          *
 113          * @since 2.0
 114          *
 115          * @return               A pointer to the %DownloadManager instance, @n
 116          *                               else @c null if it fails
 117          * @exception     E_SUCCESS           The method is successful.
 118          * @exception     E_SYSTEM            The method cannot proceed due to a severe system error.
 119          * @remarks       The specific error code can be accessed using the GetLastResult() method.
 120          */
 121         static DownloadManager* GetInstance(void);
 122
 123         /**
 124          * Starts the download operation. @n
 125          * If this operation succeeds, the IDownloadListener::OnDownloadInProgress() method is called. @n
 126          *
 127          * @since 2.0
 128          * @privlevel   public
 129          * @privilege   %http://tizen.org/privilege/download
 130          *
 131          * @return       An error code
 132          * @param[in]    request              The download request
 133          * @param[out]   reqId                The request ID
 134          * @exception    E_SUCCESS            The method is successful.
 135          * @exception   E_INVALID_ARG            The information of the download request is invalid.
 136          * @exception   E_ILLEGAL_ACCESS         The access to the path of the download request is denied due to insufficient permission.
 137          * @exception   E_PRIVILEGE_DENIED       The application does not have the privilege to call this method.
 138          * @exception   E_USER_NOT_CONSENTED The user has blocked the application from calling this method.
 139          * @exception    E_SYSTEM             The method cannot proceed due to a severe system error.
 140          */
 141         result Start(const DownloadRequest& request, RequestId& reqId);
 142
 143         /**
 144          * Pauses the download operation of the specified request ID. @n
 145          * If this operation succeeds, the IDownloadListener::OnDownloadPaused() method is called.
 146          *
 147          * @since 2.0
 148          *
 149          * @return       An error code
 150          * @param[in]    reqId               The request ID returned by Start()
 151          * @exception    E_SUCCESS           The method is successful.
 152          * @exception   E_INVALID_ARG           There is no download request for the specified @c reqId.
 153          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
 154          *                                                              - The current download state prohibits the execution of this operation.
 155          *                                                              - The download state of the request ID is not downloading.
 156          * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 157          */
 158         result Pause(RequestId reqId);
 159
 160         /**
 161          * Resumes the download operation of the specified request ID. @n
 162          * If this operation succeeds, the IDownloadListener::OnDownloadInProgress() method is called.
 163          *
 164          * @since 2.0
 165          *
 166          * @return       An error code
 167          * @param[in]    reqId               The request ID returned by Start()
 168          * @exception    E_SUCCESS           The method is successful.
 169          * @exception   E_INVALID_ARG           There is no download request for the specified @c reqId.
 170          * @exception   E_INVALID_OPERATION     Either of the following conditions has occurred:
 171          *                                                              - The current download state prohibits the execution of this operation.
 172          *                                                              - The download state for the specified request ID is either not paused or has failed.
 173          * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 174          */
 175         result Resume(RequestId reqId);
 176
 177         /**
 178          * Cancels the download operation of the specified request ID.
 179          *
 180          * @since 2.0
 181          *
 182          * @return       An error code
 183          * @param[in]    reqId               The request ID returned by Start()
 184          * @exception    E_SUCCESS           The method is successful.
 185          * @exception   E_INVALID_ARG           There is no download request for the specified @c reqId.
 186          * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 187          */
 188         result Cancel(RequestId reqId);
 189
 190         /**
 191          * Gets the download request information of the specified request ID.
 192          *
 193          * @since 2.0
 194          *
 195          * @return       The download request @n
 196          *                          The download request information is available for at least the next 24 hours after IDownloadListener::OnDownloadCompleted() is called.
 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          */
 202         DownloadRequest* GetDownloadRequestN(RequestId reqId) const;
 203
 204         /**
 205          * Gets the download state of the given request ID. @n
 206          * If there is no download request for the request ID, @c DOWNLOAD_STATE_NONE is returned.
 207          *
 208          * @since 2.0
 209          *
 210          * @return       The download state @n
 211          *                              The download state information is available for at least the next 24 hours after IDownloadListener::OnDownloadCompleted() is called.
 212          * @param[in]    reqId               The request ID returned by Start()
 213          */
 214         DownloadState GetState(RequestId reqId) const;
 215
 216         /**
 217          * Gets the MIME type of a download request.
 218          *
 219          * @since 2.0
 220          *
 221          * @return       An error code
 222          * @param[in]    reqId               The request ID returned by Start()
 223          * @param[out]   mimeType            The MIME type @n
 224          *                                                                      The MIME type information is available for at least the next 24 hours after IDownloadListener::OnDownloadCompleted()
 225          *                                                                      is called.
 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     Either of the following conditions has occurred:
 229          *                                                              - The current download state prohibits the execution of this operation.
 230          *                                                              - The download operation has not yet started.
 231          * @exception    E_SYSTEM            The method cannot proceed due to a severe system error.
 232          */
 233         result GetMimeType(RequestId reqId, Tizen::Base::String& mimeType) const;
 234
 235         /**
 236          * Sets the 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