2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0
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.
18 * @file FCntContentTransfer.h
19 * @brief This is the header file for the %ContentTransfer class.
21 * This header file contains the declarations of the %ContentTransfer class.
24 #ifndef _FCNT_CONTENT_TRANSFER_H_
25 #define _FCNT_CONTENT_TRANSFER_H_
27 #include <FBaseObject.h>
29 namespace Tizen { namespace Base { namespace Collection
34 namespace Tizen { namespace Base { namespace Utility
39 namespace Tizen { namespace Content
42 class _ContentTransferImpl;
43 class IContentTransferListener;
47 * @class ContentTransfer
48 * @brief <i> [Deprecated] </i> This class provides methods to download the content.
50 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
53 * The %ContentTransfer class provides the following features:
54 * - Downloading the content from the servers that support HTTP access.
55 * - Cancelling a download operation.
57 * HTTP download (ContentTransfer::Download()) is a standard HTTP transaction using the HTTP GET request and response methods.
59 * The following example demonstrates how to use the %ContentTransfer class.
63 * :public Tizen::Content::IContentTransferListener
67 * virtual ~MyClass(void);
70 * void OnContentTransferInProgress(RequestId requestID, int totalReceivedSize);
71 * void OnContentDownloadCompleted(RequestId requestID, ContentId contentID, result res, const Tizen::Base::String& errorCode, const Tizen::Base::String& errorMessage);
72 * void OnContentDownloadToBufferCompleted(RequestId reqId, Tizen::Base::ByteBuffer* pBuffer, result r, const Tizen::Base::String& errorCode, const Tizen::Base::String& errorMessage);
73 * void OnContentTransferCanceled(RequestId reqId, result res, const Tizen::Base::String& errorCode, const Tizen::Base::String& errorMessage);
76 * // Implementation for the listener function and Implementation of other listener function is
77 * void MyClass::OnContentDownloadCompleted(RequestId requestID, ContentId contentID, result res, const Tizen::Base::String& errorCode, const Tizen::Base::String& errorMessage)
79 * result r = E_SUCCESS;
80 * ContentManager contentManager;
81 * ContentInfo* pContentInfo = null;
84 * TryCatch(!IsFailed(res), r, "Download Error [%s]", GetErrorMessage(res));
87 * r = contentManager.Construct();
88 * TryCatch(!IsFailed(r), r, "Construct failed.");
91 * pContentInfo = contentManager.GetContentInfoN(contentID);
94 * delete pContentInfo;
98 * MyClass::RequestDownload(void)
100 * ContentTransfer contentTransfer;
101 * RequestId requestId;
102 * Tizen::Base::Utility::Uri contentUri;
104 * Tizen::Base::String downloadPath;
106 * result r = contentTransfer.Construct(*this);
107 * TryReturn(!IsFailed(r), r, ("Construct is failed.\n"));
109 * // TODO: set uri and download path
111 * r = contentTransfer.Download(contentUri, downloadPath, requestId, false);
112 * TryReturn(!IsFailed(r), r, ("Download Request is failed.\n"));
117 class _OSP_EXPORT_ ContentTransfer
118 : virtual public Tizen::Base::Object
122 * The object is not fully constructed after this constructor is called. @n
123 * For full construction, the Construct(IContentTransferListener&) method must be called right after calling this constructor.
125 * @brief <i> [Deprecated] </i>
126 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
129 * @remarks After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
131 ContentTransfer(void);
134 * This destructor overrides Tizen::Base::Object::~Object().
136 * @brief <i> [Deprecated] </i>
137 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
141 virtual ~ContentTransfer(void);
144 * Initializes this instance of %ContentTransfer with the specified parameter. @n
145 * The %Construct() method should be called after every instance of %ContentTransfer is constructed.
147 * @brief <i> [Deprecated] </i>
148 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
151 * @return An error code
152 * @param[in] listener A reference to IContentTransferListener
153 * @exception E_SUCCESS The method is successful.
154 * @exception E_OUT_OF_MEMORY The memory is insufficient.
155 * @exception E_SYSTEM A system error has occurred.
157 result Construct(IContentTransferListener& listener);
160 * Downloads a content file from the content provider's server. @n
161 * The @c filesize parameter is used to check the limitation of the local volume. If this parameter is set to @c 0, the %Download() method will not check the volume. @n
162 * An application should set the full destination path for the downloaded contents. When the content is downloaded to one of the following paths, this method internally registers the content using ContentManager.
164 * - /Storagecard/Media/ @n
166 * When the download is completed, the application is notified using the IContentTransferListener::OnContentDownloadCompleted() method. @n
167 * When the data is being downloaded, the application is notified of the progress using the IContentTransferListener::OnContentTransferInProgress() method.
169 * @brief <i> [Deprecated] </i>
170 * @deprecated This method is deprecated due to the operation policy of the Tizen Server.
171 * When downloading the contents from a third party server, it is recommended to use the Download(const Tizen::Base::Utility::Uri&, const Tizen::Base::String&, RequestId&, bool, int, int) method.
174 * @privilege %http://tizen.org/privilege/download
176 * @return An error code
177 * @param[in] uri The content URL
178 * @param[in] fileSize The content file size in bytes @n
179 * If set to @c 0, the method does not check the storage limitation.
180 * @param[in] destFilePath The full destination path
181 * @param[in] replace The replace option of the destination file @n
182 * Set to @c true to replace the file, @n
184 * @param[out] reqId The request ID
185 * @param[in] pListener A pointer to the IContentTransferListener instance
186 * @param[in] sec The timeout period in seconds
187 * @exception E_SUCCESS The method is successful.
188 * @exception E_INVALID_ARG A specified input parameter is invalid.
189 * @exception E_INVALID_STATE This method is invalid for the current state of this instance.
190 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
191 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
192 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
193 * @exception E_IN_PROGRESS A previous request is in progress.
194 * @exception E_OUT_OF_MEMORY The memory is insufficient.
195 * @exception E_USER_NOT_CONSENTED The user blocks an application from calling this method. @b Since: @b 2.1
196 * @see IContentTransferListener::OnContentDownloadCompleted()
197 * @see IContentTransferListener::OnContentTransferInProgress()
199 result Download(const Tizen::Base::Utility::Uri& uri, int fileSize, const Tizen::Base::String& destFilePath, bool replace, RequestId& reqId, IContentTransferListener* pListener = null, int sec = 0);
202 * Downloads a content file from the content provider's server. @n
203 * An application should set the destination path for the downloaded contents.
204 * The path of the downloaded file should use Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath().
206 * When the content is downloaded to the path using Tizen::System::Environment::GetMediaPath() or Tizen::System::Environment::GetExternalStoragePath(), the %Download() method internally registers the content in the content database. @n
207 * When the download is completed, the application is notified using the IContentTransferListener::OnContentDownloadCompleted() method. @n
208 * When the data is being downloaded, the application is notified of the progress using the IContentTransferListener::OnContentTransferInProgress() method.
210 * @brief <i> [Deprecated] </i>
211 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
213 * @brief <i> [Compatibility] </i>
217 * @compatibility This method has compatibility issues with OSP compatible applications. @n
218 * For more information, see @ref CompContentTransferDownloadPage3 "here".
221 * @privilege %http://tizen.org/privilege/download
223 * @return An error code
224 * @param[in] uri The content URL
225 * @param[in] filePath The destination file path @n
226 * Use Tizen::System::Environment::GetMediaPath(), Tizen::System::Environment::GetExternalStoragePath() and Tizen::App::App::GetInstance()->GetAppRootPath().
227 * @param[out] reqId The request ID
228 * @param[in] replace The replace option of the destination file @n
229 * Set to @c true to replace the file, @n
231 * @param[in] timeout The timeout period in seconds
232 * @param[in] progressInterval The progress period interval as a percentage value
233 * @exception E_SUCCESS The method is successful.
234 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
235 * @exception E_INVALID_ARG A specified input parameter is invalid.
236 * @exception E_INVALID_STATE This method is invalid for the current state of this instance.
237 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
238 * @exception E_FILE_ALREADY_EXIST The specified file already exists.
239 * @exception E_IN_PROGRESS A previous request is in progress.
240 * @exception E_OUT_OF_MEMORY The memory is insufficient.
241 * @exception E_SYSTEM A system error has occurred.
242 * @exception E_USER_NOT_CONSENTED The user blocks an application from calling this method. @b Since: @b 2.1
244 * - The @c progressInterval is the interval of the progress for each download request. If the value of the @c progressInterval is @c 0, the @c progressInterval uses the value set by the ContentTransfer::SetProgressIntervalByPercent(int). The @c progressInterval is a percentage value between @c 0 and @c 100.
245 * - The @c timeout is the value of the response timeout for each download request. If the value of the @c timeout is @c 0, the value for the @c timeout uses the value set by the ContentTransfer::SetDefaultTimeout(int).
246 * @see IContentTransferListener::OnContentDownloadCompleted()
247 * @see IContentTransferListener::OnContentTransferInProgress()
249 result Download(const Tizen::Base::Utility::Uri& uri, const Tizen::Base::String& filePath, RequestId& reqId, bool replace = false, int timeout = 0, int progressInterval = 0);
253 * @page CompContentTransferDownloadPage3 Compatibility for the file path.
254 * @section CompContentTransferDownloadPageIssueSection Issues
255 * The content path argument of this method in OSP compatible applications has the following issues: @n
256 * -# The content path should be a path that begins with an allowed path prefix. @n
257 * For example, L"/Media/Images/flower.jpg", "/Storagecard/Media/Images/flower.jpg".
259 * @section CompImageContentInfoConstructPageSolutionSection Resolutions
260 * This issue has been resolved in Tizen. @n
261 * -# The content path can be a path without a specific allowed path prefix. @n
262 * Application do not need to know the specific allowed path prefixes. @n
263 * To get the directory path, use the following methods: @n
264 * - For accessing the media directory, use Tizen::System::Environment::GetMediaPath().
265 * - For accessing the external storage, use Tizen::System::Environment::GetExternalStoragePath().
271 * Downloads a content file to a buffer from the content provider's servers. @n
272 * The %DownloadToBuffer() method does not register the content. @n
273 * When the download is completed, the application is notified using the IContentTransferListener::OnContentDownloadToBufferCompleted() method. @n
274 * When the data is being downloaded, the application is notified of the progress using the IContentTransferListener::OnContentTransferInProgress() method.
276 * @brief <i> [Deprecated] </i>
277 * @deprecated This method is deprecated due to the operation policy of the Tizen Server.
278 * When downloading the contents to a buffer from a third party server, it is recommended to use the DownloadToBuffer(const Tizen::Base::Utility::Uri&, RequestId&, int, int) method.
281 * @privilege %http://tizen.org/privilege/download
283 * @return An error code
284 * @param[in] uri The content URL
285 * @param[in] fileSize The content file size in bytes @n
286 * If set to @c 0, the method does not check the storage limitation.
287 * @param[out] reqId The request ID
288 * @param[in] pListener A pointer to the IContentTransferListener instance
289 * @param[in] sec The timeout period in seconds
290 * @exception E_SUCCESS The method is successful.
291 * @exception E_INVALID_ARG A specified input parameter is invalid.
292 * @exception E_INVALID_STATE This method is invalid for the current state of this instance.
293 * @exception E_OUT_OF_MEMORY The memory is insufficient.
294 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
295 * @exception E_USER_NOT_CONSENTED The user blocks an application from calling this method. @b Since: @b 2.1
296 * @see IContentTransferListener::OnContentDownloadToBufferCompleted()
297 * @see IContentTransferListener::OnContentTransferInProgress()
299 result DownloadToBuffer(const Tizen::Base::Utility::Uri& uri, int fileSize, RequestId& reqId, IContentTransferListener* pListener = null, int sec = 0);
302 * Downloads a content file to a buffer from the content provider's servers. @n
303 * The %DownloadToBuffer() method does not register the content. @n
304 * When the download is completed, the application is notified using the IContentTransferListener::OnContentDownloadToBufferCompleted() method. @n
305 * When the data is being downloaded, the application is notified of the progress using the IContentTransferListener::OnContentTransferInProgress() method.
307 * @brief <i> [Deprecated] </i>
308 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
311 * @privilege %http://tizen.org/privilege/download
313 * @return An error code
314 * @param[in] uri The content URL
315 * @param[out] reqId The request ID
316 * @param[in] timeout The timeout period in seconds
317 * @param[in] progressInterval The progress period interval as a percentage value
318 * @exception E_SUCCESS The method is successful.
319 * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
320 * @exception E_INVALID_ARG A specified input parameter is invalid.
321 * @exception E_INVALID_STATE This method is invalid for the current state of this instance.
322 * @exception E_ILLEGAL_ACCESS Access is denied due to insufficient permission.
323 * @exception E_IN_PROGRESS A previous request is in progress.
324 * @exception E_OUT_OF_MEMORY The memory is insufficient.
325 * @exception E_USER_NOT_CONSENTED The user blocks an application from calling this method. @b Since: @b 2.1
327 * - The @c progressInterval is the interval of the progress for each download request. If the value of the @c progressInterval is @c 0, the @c progressInterval uses the value set by the ContentTransfer::SetProgressIntervalByPercent(int). The @c progressInterval is a percentage value between @c 0 and @c 100.
328 * - The @c timeout is the value of the response timeout for each download request. If the value of the @c timeout is @c 0, the value for the @c timeout uses the value set by the ContentTransfer::SetDefaultTimeout(int).
329 * @see IContentTransferListener::OnContentDownloadToBufferCompleted()
330 * @see IContentTransferListener::OnContentTransferInProgress()
332 result DownloadToBuffer(const Tizen::Base::Utility::Uri& uri, RequestId& reqId, int timeout = 0, int progressInterval = 0);
335 * Sets the default timeout period. @n
336 * If the server does not respond during the timeout period, the network connection is closed.
337 * @c 0 or minus second means unlimited period.
339 * @brief <i> [Deprecated] </i>
340 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
343 * @param[in] sec The default timeout period in seconds @n
344 * The default value is @c 0.
346 void SetDefaultTimeout(int sec);
349 * Gets the default timeout period.
351 * @brief <i> [Deprecated] </i>
352 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
355 * @return The default timeout period
357 int GetDefaultTimeout(void) const;
360 * Removes a transfer operation. @n
361 * This operation removes a request for multiple downloads.
362 * A download operation in progress is not removed by this operation.
364 * @brief <i> [Deprecated] </i>
365 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
368 * @return An error code
369 * @param[in] reqId The request ID
370 * @exception E_SUCCESS The method is successful.
371 * @exception E_OUT_OF_MEMORY The memory is insufficient.
372 * @exception E_OBJ_NOT_FOUND The specified @c reqId is not found.
373 * @exception E_INVALID_STATE This method is invalid for the current state of this instance.
374 * @remarks To stop an on-going transfer, use the Cancel() method.
376 result Remove(RequestId reqId);
379 * Removes all the transfer operations. @n
380 * This operation removes all the requests for multiple downloads.
381 * The download operations in progress are not removed by this operation.
383 * @brief <i> [Deprecated] </i>
384 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
387 * @return An error code
388 * @exception E_SUCCESS The method is successful.
389 * @exception E_OUT_OF_MEMORY The memory is insufficient.
390 * @exception E_INVALID_STATE This method is invalid for the current state of this instance.
391 * @remarks To stop an on-going transfer, use the Cancel() method.
393 result RemoveAll(void);
396 * Cancels a transfer operation. @n
397 * The downloaded file is deleted from the file system. @n
398 * When a transfer download operation is canceled, the application is notified via the IContentTransferListener::OnContentTransferCanceled() method.
400 * @brief <i> [Deprecated] </i>
401 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
404 * @return An error code
405 * @param[in] reqId The request ID
406 * @exception E_SUCCESS The method is successful.
407 * @exception E_OBJ_NOT_FOUND The specified @c reqId is not found.
408 * @exception E_INVALID_ARG The specified input parameter is invalid.
409 * @exception E_INVALID_STATE This method is invalid for the current state of this instance.
410 * @see IContentTransferListener::OnContentTransferCanceled()
412 result Cancel(RequestId reqId);
415 * Cancels all the operations in progress.
417 * @brief <i> [Deprecated] </i>
418 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
421 * @return An error code
422 * @exception E_SUCCESS The method is successful.
423 * @exception E_OUT_OF_MEMORY The memory is insufficient.
424 * @exception E_INVALID_STATE This method is invalid for the current state of this instance.
426 result CancelAll(void);
429 * Gets the content transfer information list.
431 * @brief <i> [Deprecated] </i>
432 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
435 * @return A pointer to a list containing the ContentTransferInfo instances, @n
436 * else an empty list if there is no result and no error
438 Tizen::Base::Collection::IList* GetContentTransferInfoListN(void) const;
441 * Gets the list of transfers that are in progress.
443 * @brief <i> [Deprecated] </i>
444 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
447 * @return A pointer to a list containing the ContentTransferInfo instances, @n
448 * else an empty list if there is no result and no error
450 Tizen::Base::Collection::IList* GetContentTransferInfoListInProgressN(void) const;
453 * Sets the interval of the progress. @n
454 * The input is a percentage value between @c 0 and @c 100. The default value is @c 0.
455 * @c 0 means the application would not receive progress events.
457 * @brief <i> [Deprecated] </i>
458 * @deprecated This class is deprecated. Instead of using this class, use DownloadManager class.
461 * @param[in] percent The progress period interval as a percentage value
462 * @remarks If a server does not provide the information about the content size, then the content module cannot verify the information. @n
463 * In that case, progress event will occur randomly.
465 void SetProgressIntervalByPercent(int percent);
469 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
471 ContentTransfer(const ContentTransfer& rhs);
474 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
476 ContentTransfer& operator =(const ContentTransfer& rhs);
479 friend class _ContentTransferImpl;
480 _ContentTransferImpl* __pImpl;
482 }; // class ContentTransfer
486 #endif // _FCNT_CONTENT_TRANSFER_H_