2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
17 #ifndef __TIZEN_WEB_DOWNLOAD_H__
18 #define __TIZEN_WEB_DOWNLOAD_H__
21 #include <app_control.h>
24 #define DEPRECATED __attribute__((deprecated))
37 * @addtogroup CAPI_WEB_DOWNLOAD_MODULE
42 * @brief Enumeration for error codes of URL download.
46 DOWNLOAD_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
47 DOWNLOAD_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
48 DOWNLOAD_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
49 DOWNLOAD_ERROR_NETWORK_UNREACHABLE = TIZEN_ERROR_NETWORK_UNREACHABLE, /**< Network is unreachable */
50 DOWNLOAD_ERROR_CONNECTION_TIMED_OUT = TIZEN_ERROR_CONNECTION_TIME_OUT, /**< HTTP session time-out */
51 DOWNLOAD_ERROR_NO_SPACE = TIZEN_ERROR_FILE_NO_SPACE_ON_DEVICE, /**< No space left on device */
52 DOWNLOAD_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
53 DOWNLOAD_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
54 DOWNLOAD_ERROR_INVALID_STATE = TIZEN_ERROR_DOWNLOAD | 0x21, /**< Invalid state */
55 DOWNLOAD_ERROR_CONNECTION_FAILED = TIZEN_ERROR_DOWNLOAD | 0x22, /**< Connection failed */
56 DOWNLOAD_ERROR_INVALID_URL = TIZEN_ERROR_DOWNLOAD | 0x24, /**< Invalid URL */
57 DOWNLOAD_ERROR_INVALID_DESTINATION = TIZEN_ERROR_DOWNLOAD | 0x25, /**< Invalid destination */
58 DOWNLOAD_ERROR_TOO_MANY_DOWNLOADS = TIZEN_ERROR_DOWNLOAD | 0x26, /**< Too many simultaneous downloads */
59 DOWNLOAD_ERROR_QUEUE_FULL = TIZEN_ERROR_DOWNLOAD | 0x27, /**< Download server queue is full*/
60 DOWNLOAD_ERROR_ALREADY_COMPLETED = TIZEN_ERROR_DOWNLOAD | 0x28, /**< The download is already completed */
61 DOWNLOAD_ERROR_FILE_ALREADY_EXISTS = TIZEN_ERROR_DOWNLOAD | 0x29, /**< Failed to rename the downloaded file */
62 DOWNLOAD_ERROR_CANNOT_RESUME = TIZEN_ERROR_DOWNLOAD | 0x2a, /**< Cannot resume */
63 DOWNLOAD_ERROR_FIELD_NOT_FOUND = TIZEN_ERROR_DOWNLOAD | 0x2b, /**< Specified field not found */
64 DOWNLOAD_ERROR_TOO_MANY_REDIRECTS = TIZEN_ERROR_DOWNLOAD | 0x30, /**< Too many redirects from HTTP response header*/
65 DOWNLOAD_ERROR_UNHANDLED_HTTP_CODE = TIZEN_ERROR_DOWNLOAD | 0x31, /**< The download cannot handle the HTTP status value */
66 DOWNLOAD_ERROR_REQUEST_TIMEOUT = TIZEN_ERROR_DOWNLOAD | 0x32, /**< No action after client creates a download ID*/
67 DOWNLOAD_ERROR_RESPONSE_TIMEOUT = TIZEN_ERROR_DOWNLOAD | 0x33, /**< No call to start API for some time although the download is created*/
68 DOWNLOAD_ERROR_SYSTEM_DOWN = TIZEN_ERROR_DOWNLOAD | 0x34, /**< No response from client after rebooting download daemon*/
69 DOWNLOAD_ERROR_ID_NOT_FOUND = TIZEN_ERROR_DOWNLOAD | 0x35, /**< Download ID does not exist in download service module*/
70 DOWNLOAD_ERROR_INVALID_NETWORK_TYPE = TIZEN_ERROR_DOWNLOAD | 0x36, /**< Network bonding is set but network type is not set as DOWNLOAD_NETWORK_ALL*/
71 DOWNLOAD_ERROR_NO_DATA = TIZEN_ERROR_NO_DATA, /**< No data because the set API is not called */
72 DOWNLOAD_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR , /**< Internal I/O error */
77 * @brief Enumeration for download states.
81 DOWNLOAD_STATE_NONE, /**< Unhandled exception */
82 DOWNLOAD_STATE_READY, /**< Ready to download */
83 DOWNLOAD_STATE_QUEUED, /**< Queued to start downloading */
84 DOWNLOAD_STATE_DOWNLOADING, /**< Currently downloading */
85 DOWNLOAD_STATE_PAUSED, /**< The download is waiting to resume */
86 DOWNLOAD_STATE_COMPLETED, /**< The download is completed */
87 DOWNLOAD_STATE_FAILED, /**< The download failed */
88 DOWNLOAD_STATE_CANCELED, /**< User canceled the download item */
92 * @brief Enumeration for network type for downloading.
96 DOWNLOAD_NETWORK_DATA_NETWORK, /**< Download is available through data network */
97 DOWNLOAD_NETWORK_WIFI, /**< Download is available through WiFi */
98 DOWNLOAD_NETWORK_WIFI_DIRECT, /**< Download is available through WiFi-Direct */
99 DOWNLOAD_NETWORK_ALL /**< Download is available through either data network or WiFi */
100 } download_network_type_e;
104 * @brief Enumeration for notification types when a client wants to register.
107 * @see download_set_notification_type()
108 * @see download_get_notification_type()
111 DOWNLOAD_NOTIFICATION_TYPE_NONE = 0, /**< Do not register notification */
112 DOWNLOAD_NOTIFICATION_TYPE_COMPLETE_ONLY, /**< Completion notification for success state and failed state */
113 DOWNLOAD_NOTIFICATION_TYPE_ALL /**< All download notifications for ongoing state, success state and failed state */
114 } download_notification_type_e;
118 * @brief Enumeration for the type of notification app control action which the client wants to set when registering notification.
121 * @see download_set_notification_app_control()
122 * @see download_get_notification_app_control()
125 DOWNLOAD_NOTIFICATION_APP_CONTROL_TYPE_ONGOING = 0, /**< App control action for failed and ongoing notification */
126 DOWNLOAD_NOTIFICATION_APP_CONTROL_TYPE_COMPLETE, /**< App control action for completed notification */
127 DOWNLOAD_NOTIFICATION_APP_CONTROL_TYPE_FAILED /**< App control action for failed notification*/
128 } download_notification_app_control_type_e;
131 * @brief Called when a download state is changed.
135 * @param[in] download_id The download ID
136 * @param[in] state The state of download
137 * @param[in] user_data The user data passed from download_set_state_changed_cb()
139 * @pre download_start() will invoke this callback if you register this callback using download_set_state_changed_cb().
141 * @see download_set_state_changed_cb()
142 * @see download_unset_state_changed_cb()
144 typedef void (*download_state_changed_cb) (int download_id,
145 download_state_e state, void *user_data);
148 * @brief Called when the progress of download changes.
152 * @remarks This callback function is only invoked in the downloading state.
154 * @param[in] download_id The download ID
155 * @param[in] received The size of the data received in bytes
156 * @param[in] user_data The user data passed from download_set_progress_cb()
158 * @pre This callback function is invoked if you register this callback using download_set_progress_cb().
160 * @see download_cancel()
161 * @see download_set_progress_cb()
162 * @see download_unset_progress_cb()
164 typedef void (*download_progress_cb) (int download_id, unsigned long long received, void *user_data);
167 * @brief Creates a new download request and return its download ID.
171 * @privilege %http://tizen.org/privilege/download
173 * @remarks The @a download_id is released with download_destroy() by client.
175 * @param[out] download_id The download ID that is newly created on success
177 * @return @c 0 on success,
178 * otherwise a negative error value
180 * @retval #DOWNLOAD_ERROR_NONE Successful
181 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
182 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
183 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
184 * @retval #DOWNLOAD_ERROR_QUEUE_FULL Download server queue is full
185 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
186 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
188 * @post The download state will be #DOWNLOAD_STATE_READY.
190 * @see download_destroy()
192 int download_create(int *download_id);
196 * @brief Unloads all data concerning a download ID from memory.
198 * @details After calling this API, a download ID is existed at DB in certain time.
199 * Within that time, it is able to use the other API with the download ID.
203 * @privilege %http://tizen.org/privilege/download
206 * @remarks If #DOWNLOAD_ERROR_ID_NOT_FOUND is returned, it means that the download ID is completely removed from DB.
208 * @param[in] download_id The download ID
210 * @return @c 0 on success,
211 * otherwise a negative error value
213 * @retval #DOWNLOAD_ERROR_NONE Successful
214 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
215 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
216 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
217 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
219 * @see download_create()
221 int download_destroy(int download_id);
225 * @brief Sets the URL to download.
229 * @privilege %http://tizen.org/privilege/download
231 * @remarks This function should be called before downloading (see download_start()).
233 * @param[in] download_id The download ID
234 * @param[in] url The URL to download \n
235 * If @a url is @c NULL, it clears the previous value.
237 * @return @c 0 on success,
238 * otherwise a negative error value
240 * @retval #DOWNLOAD_ERROR_NONE Successful
241 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
242 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
243 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
244 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
245 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
246 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
248 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
250 * @see download_get_url()
252 int download_set_url(int download_id, const char *url);
256 * @brief Gets the URL to download.
260 * @privilege %http://tizen.org/privilege/download
262 * @remarks You must release @a url using free().
264 * @param[in] download_id The download ID
265 * @param[out] url The URL to download
267 * @return @c 0 on success,
268 * otherwise a negative error value
270 * @retval #DOWNLOAD_ERROR_NONE Successful
271 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
272 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
273 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
274 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
275 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
277 * @see download_set_url()
279 int download_get_url(int download_id, char **url);
283 * @brief Sets the allowed network type for the downloaded file.
285 * @details The file can be downloaded only under the allowed network.
289 * @privilege %http://tizen.org/privilege/download
291 * @remarks This function should be called before downloading (see download_start()).
293 * @param[in] download_id The download ID
294 * @param[in] net_type The network type that the client prefers
296 * @return @c 0 on success,
297 * otherwise a negative error value
299 * @retval #DOWNLOAD_ERROR_NONE Successful
300 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
301 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
302 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
303 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
304 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
306 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
308 * @see download_get_network_type()
309 * @see #download_network_type_e
311 int download_set_network_type(int download_id, download_network_type_e net_type);
315 * @brief Gets the network type for the downloaded file.
319 * @privilege %http://tizen.org/privilege/download
321 * @param[in] download_id The download ID
322 * @param[out] net_type The network type that is defined by client
324 * @return @c 0 on success,
325 * otherwise a negative error value
327 * @retval #DOWNLOAD_ERROR_NONE Successful
328 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
329 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
330 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
331 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
333 * @see download_set_network_type()
334 * @see #download_network_type_e
336 int download_get_network_type(int download_id, download_network_type_e *net_type);
339 * @brief Sets the destination for the downloaded file.
341 * @details The file will be downloaded to the specified destination.
342 * The downloaded file is saved to an auto-generated file name in the destination.
343 * If the destination is not specified, the file will be downloaded to default storage (see the @ref CAPI_SYSTEM_STORAGE_MODULE API).
347 * @privilege %http://tizen.org/privilege/download
349 * @remarks This function should be called before downloading (see download_start()). \n
350 * The mediastorage privilege %http://tizen.org/privilege/mediastorage is needed if @a path is relevant to media storage.\n
351 * The externalstorage privilege %http://tizen.org/privilege/externalstorage is needed if @a path is relevant to external storage.
353 * @param[in] download_id The download ID
354 * @param[in] path The absolute path to the downloaded file \n
355 * If @a path is @c NULL, it clears the previous value.
357 * @return @c 0 on success,
358 * otherwise a negative error value
360 * @retval #DOWNLOAD_ERROR_NONE Successful
361 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
362 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
363 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
364 * @retval #DOWNLOAD_ERROR_INVALID_DESTINATION Invalid destination
365 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
366 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
367 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
369 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
371 * @see download_get_destination()
373 int download_set_destination(int download_id, const char *path);
377 * @brief Gets the destination path for the downloaded file.
381 * @privilege %http://tizen.org/privilege/download
383 * @remarks You must release @a path using free().
385 * @param[in] download_id The download ID
386 * @param[out] path The absolute path to the downloaded file
388 * @return @c 0 on success,
389 * otherwise a negative error value
391 * @retval #DOWNLOAD_ERROR_NONE Successful
392 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
393 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
394 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
395 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
396 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
398 * @see download_set_destination()
400 int download_get_destination(int download_id, char **path);
404 * @brief Sets the name for the downloaded file.
406 * @details The file will be saved in the specified destination with the given file name.
407 * If the file name is not specified, the downloaded file will be saved with an auto-generated file name in the destination.
411 * @privilege %http://tizen.org/privilege/download
413 * @remarks This function should be called before downloading (see download_start()).
415 * @param[in] download_id The download ID
416 * @param[in] file_name The file name for the downloaded file \n
417 * If @a name is @c NULL it clears the previous value.
419 * @return @c 0 on success,
420 * otherwise a negative error value
422 * @retval #DOWNLOAD_ERROR_NONE Successful
423 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
424 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
425 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
426 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
427 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
428 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
430 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
432 * @see download_get_file_name()
434 int download_set_file_name(int download_id, const char *file_name);
437 * @brief Gets the name of the downloaded file set previously by download_set_file_name().
439 * @details If the name is not set, @c NULL is returned.
443 * @privilege %http://tizen.org/privilege/download
445 * @remarks You must release @a file_name using free().
447 * @param[in] download_id The download ID
448 * @param[out] file_name The file name which is set by user
450 * @return @c 0 on success,
451 * otherwise a negative error value
453 * @retval #DOWNLOAD_ERROR_NONE Successful
454 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
455 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
456 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
457 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
458 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
460 * @see download_set_file_name()
462 int download_get_file_name(int download_id, char **file_name);
466 * @brief Gets the absolute path to save the downloaded file.
470 * @privilege %http://tizen.org/privilege/download
472 * @remarks This function returns #DOWNLOAD_ERROR_INVALID_STATE if the download is not completed.
473 * You must release @a path using free().
475 * @param[in] download_id The download ID
476 * @param[out] path The absolute path to the downloaded file
478 * @return @c 0 on success,
479 * otherwise a negative error value
481 * @retval #DOWNLOAD_ERROR_NONE Successful
482 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
483 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
484 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
485 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
486 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
488 * @pre The download state must be #DOWNLOAD_STATE_COMPLETED.
490 * @see download_set_file_name()
491 * @see download_set_destination()
493 int download_get_downloaded_file_path(int download_id, char **path);
497 * @brief Gets the MIME type of the downloaded content.
501 * @privilege %http://tizen.org/privilege/download
503 * @remarks This function returns #DOWNLOAD_ERROR_INVALID_STATE if the download has not been started.
504 * You must release @a mime_type using free().
506 * @param[in] download_id The download ID
507 * @param[out] mime_type The MIME type of the downloaded file
509 * @return @c 0 on success,
510 * otherwise a negative error value
512 * @retval #DOWNLOAD_ERROR_NONE Successful
513 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
514 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
515 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
516 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
517 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
519 * @see download_set_file_name()
520 * @see download_set_destination()
521 * @see download_get_downloaded_file_path()
523 int download_get_mime_type(int download_id, char **mime_type);
527 * @brief Enables or disables auto download.
528 * @details If this option is enabled,
529 * the previous downloading item is restarted automatically as soon as the download daemon is restarted.
530 * The download progress continues after the client process is terminated.
534 * @privilege %http://tizen.org/privilege/download
536 * @remarks The default value is @c false.
538 * @param[in] download_id The download ID
539 * @param[in] enable Set @c true to enable auto download,
540 * otherwise set @c false to disable auto download
542 * @return @c 0 on success,
543 * otherwise a negative error value
545 * @retval #DOWNLOAD_ERROR_NONE Successful
546 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
547 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
548 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
549 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
551 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
553 * @see download_get_auto_download()
556 int download_set_auto_download(int download_id, bool enable);
560 * @brief Checks whether auto download is enabled.
564 * @privilege %http://tizen.org/privilege/download
566 * @param[in] download_id The download ID
567 * @param[out] enable @c true if auto download is enabled,
568 * otherwise @c false if auto download is disabled
570 * @return @c 0 on success,
571 * otherwise a negative error value
573 * @retval #DOWNLOAD_ERROR_NONE Successful
574 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
575 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
576 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
577 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
579 * @see download_set_auto_download()
581 int download_get_auto_download(int download_id, bool *enable);
585 * @brief Adds a HTTP header field to the download request.
587 * @details The given HTTP header field will be included with the HTTP request of the download request.
588 * For more information, see <a href="HTTP://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2">HTTP/1.1: HTTP Message Headers</a>.
592 * @privilege %http://tizen.org/privilege/download
594 * @remarks This function should be called before downloading (see download_start()).
595 * This function replaces any existing value for the given key.
596 * This function returns #DOWNLOAD_ERROR_INVALID_PARAMETER if @a field or @a value is a zero-length string.
598 * @param[in] download_id The download ID
599 * @param[in] field The name of the HTTP header field
600 * @param[in] value The value associated with given field
602 * @return @c 0 on success,
603 * otherwise a negative error value
605 * @retval #DOWNLOAD_ERROR_NONE Successful
606 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
607 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
608 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
609 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
610 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
611 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
612 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
614 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
616 * @see download_get_http_header_field()
617 * @see download_remove_http_header_field()
619 int download_add_http_header_field(int download_id, const char *field, const char *value);
623 * @brief Gets a value associated with a given HTTP header field from the download.
627 * @privilege %http://tizen.org/privilege/download
629 * @remarks This function returns #DOWNLOAD_ERROR_INVALID_PARAMETER if @a field is zero-length string.
630 * You must release @a value using free().
632 * @param[in] download_id The download ID
633 * @param[in] field The name of the HTTP header field
634 * @param[out] value The value associated with given field
636 * @return @c 0 on success,
637 * otherwise a negative error value
639 * @retval #DOWNLOAD_ERROR_NONE Successful
640 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
641 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
642 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
643 * @retval #DOWNLOAD_ERROR_FIELD_NOT_FOUND Specified field not found
644 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
645 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
646 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
648 * @see download_add_http_header_field()
649 * @see download_remove_http_header_field()
651 int download_get_http_header_field(int download_id, const char *field, char **value);
654 * @brief Gets all the HTTP header fields added to the download request.
658 * @privilege %http://tizen.org/privilege/download
660 * @remarks You must release @a value using free().
662 * @param[in] download_id The download ID
663 * @param[out] fields The array of the HTTP header fields
664 * @param[out] length The number of the HTTP header fields
666 * @return @c 0 on success,
667 * otherwise a negative error value
669 * @retval #DOWNLOAD_ERROR_NONE Successful
670 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
671 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
672 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
673 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
674 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
675 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
677 * @see download_add_http_header_field()
678 * @see download_remove_http_header_field()
680 int download_get_http_header_field_list(int download_id, char ***fields, int *length);
683 * @brief Removes a given HTTP header field from the download.
687 * @privilege %http://tizen.org/privilege/download
689 * @remarks This function should be called before downloading (see download_start()).
690 * This function returns #DOWNLOAD_ERROR_INVALID_PARAMETER if field is zero-length string.
692 * @param[in] download_id The download ID
693 * @param[in] field The name of the HTTP header field
695 * @return @c 0 on success,
696 * otherwise a negative error value
698 * @retval #DOWNLOAD_ERROR_NONE Successful
699 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
700 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
701 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
702 * @retval #DOWNLOAD_ERROR_FIELD_NOT_FOUND Specified field not found
703 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
704 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
705 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
706 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
708 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
710 * @see download_add_http_header_field()
711 * @see download_get_http_header_field()
713 int download_remove_http_header_field(int download_id, const char *field);
717 * @brief Registers a callback function to be invoked when a download state is changed.
721 * @privilege %http://tizen.org/privilege/download
723 * @remarks This function should be called before downloading (see download_start()).
725 * @param[in] download_id The download ID
726 * @param[in] callback The callback function to register
727 * @param[in] user_data The user data to be passed to the callback function
729 * @return @c 0 on success,
730 * otherwise a negative error value
732 * @retval #DOWNLOAD_ERROR_NONE Successful
733 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
734 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
735 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
736 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
738 * @post download_state_changed_cb() will be invoked.
740 * @see download_unset_state_changed_cb()
741 * @see download_state_changed_cb()
743 int download_set_state_changed_cb(int download_id, download_state_changed_cb callback, void* user_data);
747 * @brief Unregisters the download state change callback function.
751 * @privilege %http://tizen.org/privilege/download
753 * @remarks This function should be called before downloading (see download_start()).
755 * @param[in] download_id The download ID
757 * @return @c 0 on success,
758 * otherwise a negative error value
760 * @retval #DOWNLOAD_ERROR_NONE Successful
761 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
762 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
763 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
764 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
766 * @see download_set_state_changed_cb()
767 * @see download_state_changed_cb()
769 int download_unset_state_changed_cb(int download_id);
773 * @brief Registers a callback function to be invoked when progress of the download changes.
777 * @privilege %http://tizen.org/privilege/download
779 * @remarks This function should be called before downloading (see download_start()).
781 * @param[in] download_id The download ID
782 * @param[in] callback The callback function to register
783 * @param[in] user_data The user data to be passed to the callback function
785 * @return @c 0 on success,
786 * otherwise a negative error value
788 * @retval #DOWNLOAD_ERROR_NONE Successful
789 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
790 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
791 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
792 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
793 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
795 * @post download_progress_cb() will be invoked.
797 * @see download_unset_progress_cb()
798 * @see download_progress_cb()
800 int download_set_progress_cb(int download_id, download_progress_cb callback, void *user_data);
804 * @brief Unregisters the download progress change callback function.
808 * @privilege %http://tizen.org/privilege/download
810 * @remarks This function should be called before downloading (see download_start()).
812 * @param[in] download_id The download ID
814 * @return @c 0 on success,
815 * otherwise a negative error value
817 * @retval #DOWNLOAD_ERROR_NONE Successful
818 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
819 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
820 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
821 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
822 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
824 * @see download_set_progress_cb()
825 * @see download_progress_cb()
827 int download_unset_progress_cb(int download_id);
831 * @brief Starts or resumes the download, asynchronously.
833 * @details This function starts to download the current URL, or resumes the download if paused.
837 * @privilege %http://tizen.org/privilege/download
839 * @remarks The URL is the mandatory information to start the download.
840 * @remarks It should call download_set_progress_cb() and download_set_state_changed_cb() again
841 * after the client process is restarted or download_destroy() is called.
843 * @param[in] download_id The download ID
845 * @return @c 0 on success,
846 * otherwise a negative error value
848 * @retval #DOWNLOAD_ERROR_NONE Successful
849 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
850 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
851 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
852 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
853 * @retval #DOWNLOAD_ERROR_INVALID_URL Invalid URL
854 * @retval #DOWNLOAD_ERROR_INVALID_DESTINATION Invalid destination
855 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
856 * @retval #DOWNLOAD_ERROR_QUEUE_FULL Download server queue is full
857 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
858 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
860 * @pre The download state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_PAUSED, #DOWNLOAD_STATE_CANCELED, or #DOWNLOAD_STATE_FAILED.
861 * @post The download state will be #DOWNLOAD_STATE_QUEUED or #DOWNLOAD_STATE_DOWNLOADING.
863 * @see download_set_url()
864 * @see download_pause()
865 * @see download_cancel()
867 int download_start(int download_id);
871 * @brief Pauses the download, asynchronously.
875 * @privilege %http://tizen.org/privilege/download
877 * @remarks The paused download can be restarted with download_start() or cancelled with download_cancel().
879 * @param[in] download_id The download ID
881 * @return @c 0 on success,
882 * otherwise a negative error value
884 * @retval #DOWNLOAD_ERROR_NONE Successful
885 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
886 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
887 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
888 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
889 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
890 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
891 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
893 * @pre The download state must be #DOWNLOAD_STATE_DOWNLOADING.
894 * @post The download state will be #DOWNLOAD_STATE_PAUSED.
896 * @see download_start()
897 * @see download_cancel()
899 int download_pause(int download_id);
903 * @brief Cancels the download, asynchronously.
905 * @details This function cancels the running download and its state will be #DOWNLOAD_STATE_READY.
909 * @privilege %http://tizen.org/privilege/download
911 * @remarks The canceled download can be restarted with download_start().
913 * @param[in] download_id The download ID
915 * @return @c 0 on success,
916 * otherwise a negative error value
918 * @retval #DOWNLOAD_ERROR_NONE Successful
919 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
920 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
921 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
922 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
923 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
924 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
925 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
927 * @pre The download state must be #DOWNLOAD_STATE_QUEUED, #DOWNLOAD_STATE_DOWNLOADING, or #DOWNLOAD_STATE_PAUSED.
928 * @post The download state will be #DOWNLOAD_STATE_CANCELED.
930 * @see download_start()
932 int download_cancel(int download_id);
936 * @brief Gets the current state of the download.
940 * @privilege %http://tizen.org/privilege/download
942 * @param[in] download_id The download ID
943 * @param[out] state The current state of the download
945 * @return @c 0 on success,
946 * otherwise a negative error value
948 * @retval #DOWNLOAD_ERROR_NONE Successful
949 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
950 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
951 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
952 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
954 * @see #download_state_e
956 int download_get_state(int download_id, download_state_e *state);
960 * @brief Gets the full path of the temporary file to store downloaded content.
964 * @privilege %http://tizen.org/privilege/download
966 * @param[in] download_id The download ID
967 * @param[out] temp_path The full path of temporary file
969 * @return @c 0 on success,
970 * otherwise a negative error value
972 * @retval #DOWNLOAD_ERROR_NONE Successful
973 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
974 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
975 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
976 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
978 * @pre The download state must be one of the states after #DOWNLOAD_STATE_DOWNLOADING.
980 * @see download_set_state_changed_cb()
981 * @see download_unset_state_changed_cb()
982 * @see download_start()
984 int download_get_temp_path(int download_id, char **temp_path);
988 * @brief Sets the directory path of the temporary file used in the previous download request.
989 * @details This is only useful when resuming download to make HTTP request header at the client side.
990 * Otherwise, the path should be ignored internally.
994 * @privilege %http://tizen.org/privilege/download
996 * @remarks If the etag value is not present in the download database, it is useless to set the temporary path. \n
997 * When resuming download, the data is attached at the end of this temporary file. \n
998 * The mediastorage privilege %http://tizen.org/privilege/mediastorage is needed if @a path is relevant to media storage.\n
999 * The externalstorage privilege %http://tizen.org/privilege/externalstorage is needed if @a path is relevant to external storage.
1002 * @param[in] download_id The download ID
1003 * @param[out] path The full path of temporary file
1005 * @return @c 0 on success,
1006 * otherwise a negative error value
1008 * @retval #DOWNLOAD_ERROR_NONE Successful
1009 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1010 * @retval #DOWNLOAD_ERROR_INVALID_DESTINATION Invalid destination
1011 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1012 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1013 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1015 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
1017 * @see download_get_etag()
1019 int download_set_temp_file_path(int download_id, char *path);
1023 * @brief Gets the content name of downloaded file.
1025 * @details This can be defined with reference of HTTP response header data.
1026 * The content name can be received when HTTP response header is received.
1030 * @privilege %http://tizen.org/privilege/download
1032 * @param[in] download_id The download ID
1033 * @param[out] content_name The content name for displaying to user
1035 * @return @c 0 on success,
1036 * otherwise a negative error value
1038 * @retval #DOWNLOAD_ERROR_NONE Successful
1039 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1040 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1041 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1042 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1044 * @pre The download state must be one of the states after #DOWNLOAD_STATE_DOWNLOADING.
1046 * @see download_set_state_changed_cb()
1047 * @see download_unset_state_changed_cb()
1048 * @see download_start()
1050 int download_get_content_name(int download_id, char **content_name);
1054 * @brief Gets the total size of downloaded content.
1056 * @details This information is received from the server. If the server does not send the total size of the content, @a content_size is set to zero.
1060 * @privilege %http://tizen.org/privilege/download
1062 * @param[in] download_id The download ID
1063 * @param[out] content_size The content size for displaying to user
1065 * @return @c 0 on success,
1066 * otherwise a negative error value
1068 * @retval #DOWNLOAD_ERROR_NONE Successful
1069 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1070 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1071 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1072 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1074 * @pre The download state must be one of the states after #DOWNLOAD_STATE_DOWNLOADING.
1076 * @see download_set_state_changed_cb()
1077 * @see download_unset_state_changed_cb()
1078 * @see download_start()
1080 int download_get_content_size(int download_id, unsigned long long *content_size);
1084 * @brief Gets an error value when the download fails.
1088 * @privilege %http://tizen.org/privilege/download
1090 * @param[in] download_id The download ID
1091 * @param[out] error The error value
1093 * @return @c 0 on success,
1094 * otherwise a negative error value
1096 * @retval #DOWNLOAD_ERROR_NONE Successful
1097 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1098 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1099 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1100 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1102 * @pre The download state must be #DOWNLOAD_STATE_FAILED.
1103 * @pre The download state must be #DOWNLOAD_STATE_CANCELED.
1105 * @see download_set_state_changed_cb()
1106 * @see download_unset_state_changed_cb()
1107 * @see download_start()
1108 * @see download_error_e
1110 int download_get_error(int download_id, download_error_e *error);
1114 * @brief Gets a HTTP status code when a download error occurs.
1118 * @privilege %http://tizen.org/privilege/download
1120 * @param[in] download_id The download ID
1121 * @param[out] HTTP_status The HTTP status code defined in RFC 2616
1123 * @return @c 0 on success,
1124 * otherwise a negative error value
1126 * @retval #DOWNLOAD_ERROR_NONE Successful
1127 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1128 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1129 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1130 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1132 * @pre The download state must be #DOWNLOAD_STATE_FAILED.
1134 * @see download_start()
1136 int download_get_http_status(int download_id, int *HTTP_status);
1140 * @brief Sets an app control handle to register notification messages.
1141 * @details Three types of notification message can be posted: completion, failed and ongoing type.
1145 * @privilege %http://tizen.org/privilege/download
1147 * @remarks When the notification message is clicked, the action to take is decided by the app control handle. \n
1148 * If the app control handle is not set, the following default operation is executed when the notification message is clicked: \n
1149 * 1) download completed state - the viewer application is executed according to extension name of downloaded content, \n
1150 * 2) download failed state and ongoing state - the client application is executed. \n
1151 * This function should be called before starting the download. \n
1152 * The app control handle MUST BE FREED by the client when it is not used any more.
1154 * @param[in] download_id The download ID
1155 * @param[in] type The enumeration type \n
1156 * See #download_notification_app_control_type_e.
1157 * @param[in] handle The app control handle pointer value
1159 * @return @c 0 on success,
1160 * otherwise a negative error value
1162 * @retval #DOWNLOAD_ERROR_NONE Successful
1163 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1164 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1165 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1166 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1168 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
1170 * @see download_set_notification_type()
1171 * @see download_get_notification_app_control()
1173 int download_set_notification_app_control(int download_id, download_notification_app_control_type_e type, app_control_h handle);
1177 * @brief Gets the app control handle (used previously to register notification messages) which is set by download_set_notification_app_control().
1179 * @details When the notification message is clicked, the action is decided by the app control handle.
1183 * @privilege %http://tizen.org/privilege/download
1185 * @remarks The app control handle MUST BE FREED by the client when it is not used any more.
1187 * @param[in] download_id The download ID
1188 * @param[in] type The enumeration type \n
1189 * See #download_notification_app_control_type_e.
1190 * @param[out] handle The app control handle pointer value
1192 * @return @c 0 on success,
1193 * otherwise a negative error value
1195 * @retval #DOWNLOAD_ERROR_NONE Successful
1196 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1197 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1198 * @retval #DOWNLOAD_ERROR_NO_DATA The app control handle has not been set
1199 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1200 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1202 * @see download_set_notification_app_control()
1204 int download_get_notification_app_control(int download_id, download_notification_app_control_type_e type, app_control_h *handle);
1208 * @brief Sets the title of a notification.
1210 * @details When registering a notification, the title is displayed in the title area of the notification message.
1214 * @privilege %http://tizen.org/privilege/download
1216 * @param[in] download_id The download ID
1217 * @param[in] title The title for displaying to user
1219 * @return @c 0 on success,
1220 * otherwise a negative error value
1222 * @retval #DOWNLOAD_ERROR_NONE Successful
1223 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1224 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1225 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1226 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1228 * @pre If a notification option is not enabled, this title is not shown to user.
1230 * @see download_set_notification_type()
1231 * @see download_get_notification_title()
1233 int download_set_notification_title(int download_id, const char *title);
1237 * @brief Gets the title of the notification set by download_set_notification_title().
1239 * @details When registering a notification, the title is displayed in the title area of the notification message.
1243 * @privilege %http://tizen.org/privilege/download
1245 * @param[in] download_id The download ID
1246 * @param[out] title The title for displaying to user
1248 * @return @c 0 on success,
1249 * otherwise a negative error value
1251 * @retval #DOWNLOAD_ERROR_NONE Successful
1252 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1253 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1254 * @retval #DOWNLOAD_ERROR_NO_DATA The title has not been set
1255 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1256 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1258 * @pre It can get the title value before calling this API.
1260 * @see download_set_notification_title()
1262 int download_get_notification_title(int download_id, char **title);
1266 * @brief Sets the description of a notification.
1268 * @details When registering a notification, the description is displayed in the description area of the notification message.
1272 * @privilege %http://tizen.org/privilege/download
1274 * @param[in] download_id The download ID
1275 * @param[in] description The description for displaying to user
1277 * @return @c 0 on success,
1278 * otherwise a negative error value
1280 * @retval #DOWNLOAD_ERROR_NONE Successful
1281 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1282 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1283 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1284 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1286 * @pre If the notification option is not enabled, this description is not shown to user.
1288 * @see download_set_notification_type()
1289 * @see download_get_notification_description()
1291 int download_set_notification_description(int download_id, const char *description);
1295 * @brief Gets the description of a notification set by download_set_notification_description().
1297 * @details When registering a notification, the description is displayed in the description area of the notification message.
1301 * @privilege %http://tizen.org/privilege/download
1303 * @param[in] download_id The download ID
1304 * @param[out] description The description for displaying to user
1306 * @return @c 0 on success,
1307 * otherwise a negative error value
1309 * @retval #DOWNLOAD_ERROR_NONE Successful
1310 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1311 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1312 * @retval #DOWNLOAD_ERROR_NO_DATA The description has not been set
1313 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1314 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1316 * @pre It can get the title value before calling this API.
1318 * @see download_set_notification_description()
1320 int download_get_notification_description(int download_id, char **description);
1324 * @brief Sets an option value to register notification messages.
1325 * @details Three types of notification message can be posted: completion, failed and ongoing type.
1329 * @privilege %http://tizen.org/privilege/download
1331 * @remarks When the notification message is clicked, the action to take is decided by the app control handle (set by download_set_notification_app_control()). \n
1332 * If the app control is not set, the following default operation is executed when the notification message is clicked: \n
1333 * 1) download completed state - the viewer application is executed according to extension name of downloaded content, \n
1334 * 2) download failed state and ongoing state - the client application is executed. \n
1335 * The default type is #DOWNLOAD_NOTIFICATION_TYPE_NONE. \n
1336 * This function should be called before starting the download.
1338 * @param[in] download_id The download ID
1339 * @param[in] type The enumeration type \n
1340 * See #download_notification_type_e.
1342 * @return @c 0 on success,
1343 * otherwise a negative error value
1345 * @retval #DOWNLOAD_ERROR_NONE Successful
1346 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1347 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1348 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1349 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1351 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
1353 * @see download_set_notification_app_control()
1354 * @see download_get_notification_type()
1356 int download_set_notification_type(int download_id, download_notification_type_e type);
1360 * @brief Gets an option value to register notification messages set by download_set_notification_type().
1364 * @privilege %http://tizen.org/privilege/download
1366 * @remarks When the notification message is clicked, the action is decided by the app control from download_set_notification_app_control(). \n
1367 * The default type is #DOWNLOAD_NOTIFICATION_TYPE_NONE.
1369 * @param[in] download_id The download ID
1370 * @param[out] type The enumeration type \n
1371 * See #download_notification_type_e.
1373 * @return @c 0 on success,
1374 * otherwise a negative error value
1376 * @retval #DOWNLOAD_ERROR_NONE Successful
1377 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1378 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1379 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1380 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1382 * @see download_set_notification_type()
1384 int download_get_notification_type(int download_id, download_notification_type_e *type);
1388 * @brief Gets an etag value from the HTTP response header when making a HTTP request for resume.
1392 * @privilege %http://tizen.org/privilege/download
1394 * @remarks The etag value is available or not depending on the web server. \n
1395 * After download is started, it can get the etag value.
1397 * @param[in] download_id The download ID
1398 * @param[out] etag The etag value
1400 * @return @c 0 on success,
1401 * otherwise a negative error value
1403 * @retval #DOWNLOAD_ERROR_NONE Successful
1404 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1405 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1406 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1407 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1409 * @see download_set_temp_file_path()
1411 int download_get_etag(int download_id, char **etag);
1415 * @brief Sets the 'enabled' state of the cache feature.
1419 * @privilege %http://tizen.org/privilege/download
1421 * @param[in] download_id The download id
1422 * @param[in] enable The enable value
1424 * @return 0 on success, otherwise a negative error value
1426 * @retval #DOWNLOAD_ERROR_NONE Successful
1427 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1428 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1429 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1430 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1431 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
1433 * @see download_get_cache()
1435 int download_set_cache(int download_id, bool enable);
1439 * @brief Gets the 'enabled' state of the cache feature.
1443 * @privilege %http://tizen.org/privilege/download
1445 * @param[in] download_id The download id
1446 * @param[out] enable The enable value
1448 * @return 0 on success, otherwise a negative error value
1450 * @retval #DOWNLOAD_ERROR_NONE Successful
1451 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1452 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1453 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
1454 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No download ID
1455 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
1457 * @see download_set_cache()
1459 int download_get_cache(int download_id, bool *enable);
1463 * @brief Clears the cache.
1467 * @privilege %http://tizen.org/privilege/download
1469 * @return 0 on success, otherwise a negative error value
1471 * @retval #DOWNLOAD_ERROR_NONE Successful
1472 * @retval #DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
1473 * @retval #DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied
1474 * @retval #DOWNLOAD_ERROR_TOO_MANY_DOWNLOADS Too many simultaneous downloads
1475 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
1477 int download_reset_cache(void);
1488 #endif /* __TIZEN_WEB_DOWNLOAD_H__ */