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__
28 * @addtogroup CAPI_WEB_DOWNLOAD_MODULE
33 * @brief Name for download service operation. Download Manager application is launched.
35 #define SERVICE_OPERATION_DOWNLOAD "http://tizen.org/appcontrol/operation/download"
38 * @brief Enumeration of error code for URL download
42 DOWNLOAD_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
43 DOWNLOAD_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
44 DOWNLOAD_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
45 DOWNLOAD_ERROR_NETWORK_UNREACHABLE = TIZEN_ERROR_NETWORK_UNREACHABLE, /**< Network is unreachable */
46 DOWNLOAD_ERROR_CONNECTION_TIMED_OUT = TIZEN_ERROR_CONNECTION_TIME_OUT, /**< Http session time-out */
47 DOWNLOAD_ERROR_NO_SPACE = TIZEN_ERROR_FILE_NO_SPACE_ON_DEVICE, /**< No space left on device */
48 DOWNLOAD_ERROR_FIELD_NOT_FOUND = TIZEN_ERROR_KEY_NOT_AVAILABLE, /**< Specified field not found */
49 DOWNLOAD_ERROR_INVALID_STATE = TIZEN_ERROR_WEB_CLASS | 0x21, /**< Invalid state */
50 DOWNLOAD_ERROR_CONNECTION_FAILED = TIZEN_ERROR_WEB_CLASS | 0x22, /**< Connection failed */
51 DOWNLOAD_ERROR_INVALID_URL = TIZEN_ERROR_WEB_CLASS | 0x24, /**< Invalid URL */
52 DOWNLOAD_ERROR_INVALID_DESTINATION = TIZEN_ERROR_WEB_CLASS | 0x25, /**< Invalid destination */
53 DOWNLOAD_ERROR_TOO_MANY_DOWNLOADS = TIZEN_ERROR_WEB_CLASS | 0x26, /**< Full of available simultaneous downloads */
54 DOWNLOAD_ERROR_QUEUE_FULL = TIZEN_ERROR_WEB_CLASS | 0x27, /**< Full of available downloading items from server*/
55 DOWNLOAD_ERROR_ALREADY_COMPLETED = TIZEN_ERROR_WEB_CLASS | 0x28, /**< The download is already completed */
56 DOWNLOAD_ERROR_FILE_ALREADY_EXISTS = TIZEN_ERROR_WEB_CLASS | 0x29, /**< It is failed to rename the downloaded file */
57 DOWNLOAD_ERROR_CANNOT_RESUME = TIZEN_ERROR_WEB_CLASS | 0x2a, /**< It cannot resume */
58 DOWNLOAD_ERROR_TOO_MANY_REDIRECTS = TIZEN_ERROR_WEB_CLASS | 0x30, /**< In case of too may redirects from http response header*/
59 DOWNLOAD_ERROR_UNHANDLED_HTTP_CODE = TIZEN_ERROR_WEB_CLASS | 0x31, /**< The download cannot handle the http status value */
60 DOWNLOAD_ERROR_REQUEST_TIMEOUT = TIZEN_ERROR_WEB_CLASS | 0x32, /**< There are no action after client create a download id*/
61 DOWNLOAD_ERROR_RESPONSE_TIMEOUT = TIZEN_ERROR_WEB_CLASS | 0x33, /**< It does not call start API in some time although the download is created*/
62 DOWNLOAD_ERROR_SYSTEM_DOWN = TIZEN_ERROR_WEB_CLASS | 0x34, /**< There are no response from client after rebooting download daemon*/
63 DOWNLOAD_ERROR_ID_NOT_FOUND = TIZEN_ERROR_WEB_CLASS | 0x35, /**< The download id is not existed in download service module*/
64 DOWNLOAD_ERROR_NO_DATA = TIZEN_ERROR_NO_DATA, /**< No data because the set API is not called */
65 DOWNLOAD_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR , /**< Internal I/O error */
70 * @brief Enumerations of state of download
74 DOWNLOAD_STATE_NONE, /**< It is ready to download */
75 DOWNLOAD_STATE_READY, /**< It is ready to download */
76 DOWNLOAD_STATE_QUEUED, /**< It is queued to start downloading */
77 DOWNLOAD_STATE_DOWNLOADING, /**< The download is currently running */
78 DOWNLOAD_STATE_PAUSED, /**< The download is waiting to resume */
79 DOWNLOAD_STATE_COMPLETED, /**< The download is completed. */
80 DOWNLOAD_STATE_FAILED, /**< The download failed. */
81 DOWNLOAD_STATE_CANCELED, /**< User cancel the download item. */
85 * @brief Enumerations of network type for download
89 DOWNLOAD_NETWORK_DATA_NETWORK, /**< Download is available through data network */
90 DOWNLOAD_NETWORK_WIFI, /**< Download is available through Wi-Fi */
91 DOWNLOAD_NETWORK_ALL /**< Download is available through either data network or Wi-Fi */
92 } download_network_type_e ;
96 * @brief Called when the download status is changed.
98 * @param [in] download The download id
99 * @param [in] state The state of download
100 * @param [in] user_data The user data passed from download_set_state_changed_cb()
101 * @pre download_start() will cause this callback if you register this callback using download_set_state_changed_cb()
102 * @see download_set_state_changed_cb()
103 * @see download_unset_state_changed_cb()
105 typedef void (*download_state_changed_cb) (int download_id,
106 download_state_e state, void *user_data);
109 * @brief Called when the progress of download changes.
111 * @remarks This callback function is only invoked in the downloading state.
112 * @param [in] download The download id
113 * @param [in] received The size of the data received in bytes
114 * @param [in] user_data The user data passed from download_set_progress_cb()
115 * @pre This callback function is invoked if you register this callback using download_set_progress_cb().
116 * @see download_cancel()
117 * @see download_set_progress_cb()
118 * @see download_unset_progress_cb()
120 typedef void (*download_progress_cb) (int download_id, unsigned long long received, void *user_data);
123 * @brief Creates a download id.
125 * @remarks The @a download must be released with download_destroy() by you.\n
126 * The g_type_init() should be called when creating a main loop by user side. \n
127 * Because the libsoup, which is http stack library of download module, use gobject internally.
128 * @param [out] download A download id to be newly created on success
129 * @return 0 on success, otherwise a negative error value.
130 * @retval #DOWNLOAD_ERROR_NONE Successful
131 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
132 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
133 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
134 * @post The download state will be #DOWNLOAD_STATE_READY
135 * @see download_destroy()
137 int download_create(int *download_id);
141 * @brief Unload all data concerning a download id from memory.
143 * @detail After calling this API, a download ID is existed at DB in certain time.\n
144 * Within that time, it is able to use the other API with the download ID.
145 * @remark If #DOWNLOAD_ERROR_ID_NOT_FOUND is returned, it means that the download ID is completely removed from DB.
146 * @param [in] download The download id
147 * @return 0 on success, otherwise a negative error value.
148 * @retval #DOWNLOAD_ERROR_NONE Successful
149 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
150 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
151 * @see download_create()
153 int download_destroy(int download_id);
157 * @brief Sets the URL to download.
159 * @remarks This function should be called before downloading (See download_start())
160 * @param [in] download The download id
161 * @param [in] url The URL to download \n
162 * If the @a url is NULL, it clears the previous value.
163 * @return 0 on success, otherwise a negative error value.
164 * @retval #DOWNLOAD_ERROR_NONE Successful
165 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
166 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
167 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
168 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
169 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
170 * @see download_get_url()
172 int download_set_url(int download_id, const char *url);
176 * @brief Gets the URL to download.
178 * @remarks The @a url must be released with free() by you.
179 * @param [in] download The download id
180 * @param [out] url The URL to download
181 * @return 0 on success, otherwise a negative error value.
182 * @retval #DOWNLOAD_ERROR_NONE Successful
183 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
184 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
185 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
186 * @see download_set_url()
188 int download_get_url(int download_id, char **url);
192 * @brief Sets the allowed network type for the downloaded file
194 * @details The file can be downloaded only under the allowed network.
196 * @remarks This function should be called before downloading (see download_start())
197 * @param [in] download The download id
198 * @param [in] net_type The network type which the client prefer
199 * @return 0 on success, otherwise a negative error value.
200 * @retval #DOWNLOAD_ERROR_NONE Successful
201 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
202 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
203 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
204 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
205 * @see download_get_network_type()
206 * @see #download_network_type_e
208 int download_set_network_type(int download_id, download_network_type_e net_type);
212 * @brief Gets the netowork type for the downloaded file
214 * @param [in] download The download id
215 * @param [out] net_type The network type which is defined by client.
216 * @return 0 on success, otherwise a negative error value.
217 * @retval #DOWNLOAD_ERROR_NONE Successful
218 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
219 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
220 * @see download_set_network_type()
221 * @see #download_network_type_e
223 int download_get_network_type(int download_id, download_network_type_e *net_type);
227 * @brief Sets the destination for the downloaded file.
229 * @details The file will be downloaded to the specified destination.
230 * The downloaded file is saved to an auto-generated file name in the destination.
231 * If the destination is not specified, the file will be downloaded to default storage. (See the @ref CAPI_STORAGE_MODULE API)
233 * @remarks This function should be called before downloading (see download_start())
234 * @param [in] download The download id
235 * @param [in] path The absolute path to the downloaded file
236 * If the @a path is NULL, it clears the previous value.
237 * @return 0 on success, otherwise a negative error value.
238 * @retval #DOWNLOAD_ERROR_NONE Successful
239 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
240 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
241 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
242 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
243 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
244 * @see download_get_destination()
246 int download_set_destination(int download_id, const char *path);
250 * @brief Gets the destination for the downloaded file.
252 * @remarks The @a path must be released with free() by you.
253 * @param [in] download The download id
254 * @param [out] path The absolute path to the downloaded file
255 * @return 0 on success, otherwise a negative error value.
256 * @retval #DOWNLOAD_ERROR_NONE Successful
257 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
258 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
259 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
260 * @see download_set_destination()
262 int download_get_destination(int download_id, char **path);
266 * @brief Sets the name for the downloaded file.
268 * @details The file will be downloaded to the specified destination as the given file name.
269 * If the file name is not specified, the downloaded file is saved to an auto-generated file name in the destination.
271 * @remarks This function should be called before downloading (see download_start())
272 * @param [in] download The download id
273 * @param [in] file_name The file name for the downloaded file
274 * If the @a name is NULL, it clears the previous value.
275 * @return 0 on success, otherwise a negative error value.
276 * @retval #DOWNLOAD_ERROR_NONE Successful
277 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
278 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
279 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
280 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
281 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
282 * @see download_get_file_name()
284 int download_set_file_name(int download_id, const char *file_name);
288 * @brief Gets the name which is set by user.
290 * @details If user do not set any name, it retruns NULL.
292 * @remarks The @a file_name must be released with free() by you.
293 * @param [in] download The download id
294 * @param [out] file_name The file name which is set by user.
295 * @return 0 on success, otherwise a negative error value.
296 * @retval #DOWNLOAD_ERROR_NONE Successful
297 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
298 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
299 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
300 * @see download_set_file_name()
302 int download_get_file_name(int download_id, char **file_name);
306 * @brief Sets the option value to register notification messages by download service module.
307 * @details The tree types of notification message can be posted. Those are completion, failed and ongoing type.
308 * When the notification message of failed and ongoing types from the notification tray, \n
309 * the client application which call this API will be launched. \n
311 * @remarks The extra param should be set together (See download_set_notification_extra_param()). \n
312 * The downloading and failed notification can be registerd only if the extra param for noticiation message is set. \n
313 * If it is not, the client application can not know who request to launch itself. \n
314 * It should be necessary to understand the action operation of notification click event.
315 * @remarks If the competition notification message is selected from the notification tray,\n
316 * the proper player application is launched automatically.
317 * @remarks The default value is false. So if the client don't enable it, any notification messages are not registered.
318 * @remarks This function should be called before downloading (See download_start())
319 * @param[in] download The download id
320 * @param[in] enable The boolean type. The true or false value is available.
321 * @return 0 on success, otherwise a negative error value.
322 * @retval #DOWNLOAD_ERROR_NONE Successful
323 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
324 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
325 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
326 * @see download_get_notification()
327 * @see service_get_operation()
329 int download_set_notification(int download_id, bool enable);
332 * @brief Gets the option value to register notification messages by download service module.
333 * @param[in] download The download id
334 * @param[out] enable The boolean type. The true or false value is retruned
335 * @return 0 on success, otherwise a negative error value.
336 * @retval #DOWNLOAD_ERROR_NONE Successful
337 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
338 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
339 * @see download_set_notification()
341 int download_get_notification(int download_id, bool *enable);
344 * @brief Sets the extra param data which pass by application service data when notification message is clicked
345 * @details When client set the extra param data for ongoing notificaiton action, \n
346 * it can get the data through service_get_extra_data() when client application is launched by notification action.
348 * @remarks This function should be called before downloading (See download_start())
350 * @param[in] download The download id
351 * @param[in] key The character pointer type. The extra param has a pair of key and value
352 * @param[in] values The character pointer array type. The extra param has a pair of key and value array
353 * @param[in] length The length of value array
354 * @return 0 on success, otherwise a negative error value.
355 * @retval #DOWNLOAD_ERROR_NONE Successful
356 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
357 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
358 * @see download_get_notification_extra_param()
359 * @see download_remove_notification_extra_param()
361 int download_add_notification_extra_param(int download_id, const char *key, const char **values, const unsigned int length);
364 * @brief Remove the extra param data which pass by application service data when notification message is clicked
366 * @remarks This function should be called before downloading (See download_start())
368 * @param[in] download The download id
369 * @param[in] key The character pointer type. The extra param has a pair of key and value
370 * @return 0 on success, otherwise a negative error value.
371 * @retval #DOWNLOAD_ERROR_NONE Successful
372 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
373 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
374 * @see download_add_notification_extra_param()
375 * @see download_get_notification_extra_param()
377 int download_remove_notification_extra_param(int download_id, const char *key);
380 * @brief Gets the extra param value to set by download_set_notification_extra_param
381 * @param[in] download The download id
382 * @param[out] key The character pointer type. The extra param has a pair of key and value
383 * @param[out] values param The character pointer array type. The extra param has a pair of key and value array
384 * @param[out] length The length of value array
385 * @return 0 on success, otherwise a negative error value.
386 * @retval #DOWNLOAD_ERROR_NONE Successful
387 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
388 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
389 * @see download_set_notification_extra_param()
391 int download_get_notification_extra_param(int download_id, const char *key, char ***values, unsigned int *length);
394 * @brief Gets the absolute path to save the downloaded file
396 * @remarks This function returns #DOWNLOAD_ERROR_INVALID_STATE if the download is not completed. \n
397 * The @a path must be released with free() by you.
398 * @param [in] download The download id
399 * @param [out] path The absolute path to the downloaded file
400 * @return 0 on success, otherwise a negative error value.
401 * @retval #DOWNLOAD_ERROR_NONE Successful
402 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
403 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
404 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
405 * @pre The download state must be #DOWNLOAD_STATE_COMPLETED.
406 * @see download_set_file_name()
407 * @see download_set_destination()
409 int download_get_downloaded_file_path(int download_id, char **path);
413 * @brief Gets the mime type for downloading a content.
415 * @remarks This function returns #DOWNLOAD_ERROR_INVALID_STATE if the download has not been started. \n
416 * The @a mime_type must be released with free() by you.
417 * @param [in] download The download id
418 * @param [out] mime_type The MIME type of the downloaded file
419 * @return 0 on success, otherwise a negative error value.
420 * @retval #DOWNLOAD_ERROR_NONE Successful
421 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
422 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
423 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
424 * @see download_set_file_name()
425 * @see download_set_destination()
426 * @see download_get_downloaded_file_path()
428 int download_get_mime_type(int download_id, char **mime_type);
432 * @brief Sets the option for auto download.
433 * @details If this option is enabled, \n
434 * the previous downloading item is restarted automatically as soon as the download daemon is restarted. \n
435 * And the download progress keep going after the client process is terminated. \n
436 * @remarks The client should call download_set_notification() and download_set_notification_extra_param() after call this API. \n
437 * If it is not, user do not receive the download result in case the client process is not alive.
438 * @remarks The default value is false.
439 * @param[in] download The download id
440 * @param[in] enable The boolean value for auto download which is defined by clinet.
441 * @return 0 on success, otherwise a negative error value.
442 * @retval #DOWNLOAD_ERROR_NONE Successful
443 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
444 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
445 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
446 * @see download_get_auto_download()
447 * @see download_set_ongoing_notification()
448 * @see download_set_notification_extra_param()
451 int download_set_auto_download(int download_id, bool enable);
455 * @brief Gets the value of option for auto download.
457 * @param [in] download The download id
458 * @param [out] enable The boolean value for auto download which is defined by clinet.
459 * @return 0 on success, otherwise a negative error value.
460 * @retval #DOWNLOAD_ERROR_NONE Successful
461 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
462 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
463 * @see download_set_auto_download()
465 int download_get_auto_download(int download_id, bool *enable);
469 * @brief Adds an HTTP header field to the download request
471 * @details The given HTTP header field will be included with the HTTP request of the download request. \n
472 * Refer to the <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2">HTTP/1.1: HTTP Message Headers</a>
473 * @remarks This function should be called before downloading (see download_start()) \n
474 * This function replaces any existing value for the given key. \n
475 * This function returns #DOWNLOAD_ERROR_INVALID_PARAMETER if field or value is zero-length string.
476 * @param [in] download The download id
477 * @param [in] field The name of the HTTP header field
478 * @param [in] value The value associated with given field
479 * @return 0 on success, otherwise a negative error value.
480 * @retval #DOWNLOAD_ERROR_NONE Successful
481 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
482 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
483 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
484 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
485 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
486 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
487 * @see download_get_http_header_field()
488 * @see download_remove_http_header_field()
490 int download_add_http_header_field(int download_id, const char *field, const char *value);
494 * @brief Gets the value associated with given HTTP header field from the download
496 * @remarks This function returns #DOWNLOAD_ERROR_INVALID_PARAMETER if field is zero-length string. \n
497 * The @a value must be released with free() by you.
498 * @param [in] download The download id
499 * @param [in] field The name of the HTTP header field
500 * @param [out] value The value associated with given field
501 * @return 0 on success, otherwise a negative error value.
502 * @retval #DOWNLOAD_ERROR_NONE Successful
503 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
504 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
505 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
506 * @retval #DOWNLOAD_ERROR_FIELD_NOT_FOUND Specified field not found
507 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
508 * @see download_add_http_header_field()
509 * @see download_remove_http_header_field()
511 int download_get_http_header_field(int download_id, const char *field, char **value);
515 * @brief Removes the given HTTP header field from the download
517 * @remarks This function should be called before downloading (see download_start()) \n
518 * This function returns #DOWNLOAD_ERROR_INVALID_PARAMETER if field is zero-length string.
519 * @param [in] download The download id
520 * @param [in] field The name of the HTTP header field
521 * @return 0 on success, otherwise a negative error value.
522 * @retval #DOWNLOAD_ERROR_NONE Successful
523 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
524 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
525 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
526 * @retval #DOWNLOAD_ERROR_FIELD_NOT_FOUND Specified field not found
527 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
528 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
529 * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
530 * @see download_add_http_header_field()
531 * @see download_get_http_header_field()
533 int download_remove_http_header_field(int download_id, const char *field);
537 * @brief Registers a callback function to be invoked when the download state is changed.
539 * @remarks This function should be called before downloading (see download_start())
540 * @param [in] download The download id
541 * @param [in] callback The callback function to register
542 * @param [in] user_data The user data to be passed to the callback function
543 * @return 0 on success, otherwise a negative error value.
544 * @retval #DOWNLOAD_ERROR_NONE Successful
545 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
546 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
547 * @post download_state_changed_cb() will be invoked.
548 * @see download_unset_state_changed_cb()
549 * @see download_state_changed_cb()
551 int download_set_state_changed_cb(int download_id, download_state_changed_cb callback, void* user_data);
555 * @brief Unregisters the callback function.
557 * @remarks This function should be called before downloading (see download_start())
558 * @param [in] download The download id
559 * @return 0 on success, otherwise a negative error value.
560 * @retval #DOWNLOAD_ERROR_NONE Successful
561 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
562 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
563 * @see download_set_state_changed_cb()
564 * @see download_state_changed_cb()
566 int download_unset_state_changed_cb(int download_id);
570 * @brief Registers a callback function to be invoked when progress of the download changes
572 * @remarks This function should be called before downloading (see download_start())
573 * @param [in] download The download id
574 * @param [in] callback The callback function to register
575 * @param [in] user_data The user data to be passed to the callback function
576 * @return 0 on success, otherwise a negative error value.
577 * @retval #DOWNLOAD_ERROR_NONE Successful
578 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
579 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
580 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
581 * @post download_progress_cb() will be invoked.
582 * @see download_unset_progress_cb()
583 * @see download_progress_cb()
585 int download_set_progress_cb(int download_id, download_progress_cb callback, void *user_data);
589 * @brief Unregisters the callback function.
591 * @remarks This function should be called before downloading (see download_start())
592 * @param [in] download The download id
593 * @return 0 on success, otherwise a negative error value.
594 * @retval #DOWNLOAD_ERROR_NONE Successful
595 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
596 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
597 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
598 * @see download_set_progress_cb()
599 * @see download_progress_cb()
601 int download_unset_progress_cb(int download_id);
605 * @brief Starts or resumes the download, asynchronously.
607 * @details This function starts to download the current URL, or resumes the download if paused.
609 * @remarks The URL is the mandatory information to start the download.
610 * @remarks It should call download_set_progress_cb() and download_set_state_changed_cb() again \n
611 * after the client process is restarted or download_destry() is called
612 * @param [in] download The download id
613 * @return 0 on success, otherwise a negative error value.
614 * @retval #DOWNLOAD_ERROR_NONE Successful
615 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
616 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
617 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
618 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
619 * @retval #DOWNLOAD_ERROR_URL Invalid URL
620 * @retval #DOWNLOAD_ERROR_DESTINATION Invalid destination
621 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
622 * @pre The download state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_PAUSED, #DOWNLOAD_STATE_CANCELED, #DOWNLOAD_STATE_FAILED.
623 * @post The download state will be #DOWNLOAD_STATE_QUEUED or #DOWNLOAD_STATE_DOWNLOADING
624 * @see download_set_url()
625 * @see download_pause()
626 * @see download_cancel()
628 int download_start(int download_id);
632 * @brief Pauses the download, asynchronously.
634 * @remarks The paused download can be restarted with download_start() or canceled with download_cancel()
635 * @param [in] download The download id
636 * @return 0 on success, otherwise a negative error value.
637 * @retval #DOWNLOAD_ERROR_NONE Successful
638 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
639 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
640 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
641 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
642 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
643 * @pre The download state must be #DOWNLOAD_STATE_DOWNLOADING.
644 * @post The download state will be #DOWNLOAD_STATE_PAUSED.
645 * @see download_start()
646 * @see download_cancel()
648 int download_pause(int download_id);
652 * @brief Cancel the download, asynchronously.
654 * @details This function cancels the running download and its state will be #DOWNLOAD_STATE_READY
655 * @remarks The cancelled download can be restarted with download_start().
656 * @param [in] download The download id
657 * @return 0 on success, otherwise a negative error value.
658 * @retval #DOWNLOAD_ERROR_NONE Successful
659 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
660 * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
661 * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
662 * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
663 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
664 * @pre The download state must be #DOWNLOAD_STATE_QUEUED, #DOWNLOAD_STATE_DOWNLOADING, #DOWNLOAD_STATE_PAUSED.
665 * @post The download state will be #DOWNLOAD_STATE_CANCELED.
666 * @see download_start()
668 int download_cancel(int download_id);
672 * @brief Gets the download's current state.
674 * @param [in] download The download id
675 * @param [out] state The current state of the download
676 * @return 0 on success, otherwise a negative error value.
677 * @retval #DOWNLOAD_ERROR_NONE Successful
678 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
679 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
680 * @see #download_state_e
682 int download_get_state(int download_id, download_state_e *state);
686 * @brief Gets the full path of temporary file for downloading a content.
688 * @param [in] download The download id
689 * @param [out] temp_path The full path of temporary file
690 * @return 0 on success, otherwise a negative error value.
691 * @retval #DOWNLOAD_ERROR_NONE Successful
692 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
693 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
694 * @pre The download state must be one of state after #DOWNLOAD_STATE_DOWNLOADING.
695 * @see #download_set_state_changed_cb()
696 * @see #download_unset_state_changed_cb()
697 * @see download_start()
699 int download_get_temp_path(int download_id, char **temp_path);
703 * @brief Gets the content name for downloading a file.
705 * @details This can be defined with referense of HTTP response header data.
706 * The content name can be received when HTTP response header is received.
708 * @param [in] download The download id
709 * @param [out] content_name The content name for displaying to user
710 * @return 0 on success, otherwise a negative error value.
711 * @retval #DOWNLOAD_ERROR_NONE Successful
712 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
713 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
714 * @pre The download state must be one of state after #DOWNLOAD_STATE_DOWNLOADING.
715 * @see #download_set_state_changed_cb()
716 * @see #download_unset_state_changed_cb()
717 * @see download_start()
719 int download_get_content_name(int download_id, char **content_name);
723 * @brief Gets the total size for downloading a content.
725 * @details This data receive from content server. If the content sever don't send total size of the content, the value set as zero.
727 * @param [in] download The download id
728 * @param [out] content_size The content size for displaying to user
729 * @return 0 on success, otherwise a negative error value.
730 * @retval #DOWNLOAD_ERROR_NONE Successful
731 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
732 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
733 * @pre The download state must be one of state after #DOWNLOAD_STATE_DOWNLOADING.
734 * @see #download_set_state_changed_cb()
735 * @see #download_unset_state_changed_cb()
736 * @see download_start()
738 int download_get_content_size(int download_id, unsigned long long *content_size);
742 * @brief Gets the error value when the download is failed.
744 * @param [in] download The download id
745 * @param [out] error The error value
746 * @return 0 on success, otherwise a negative error value.
747 * @retval #DOWNLOAD_ERROR_NONE Successful
748 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
749 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
750 * @pre The download state must be #DOWNLOAD_STATE_FAILED.
751 * @pre The download state must be #DOWNLOAD_STATE_CANCELED.
752 * @see #download_set_state_changed_cb()
753 * @see #download_unset_state_changed_cb()
754 * @see download_start()
755 * @see download_error_e
757 int download_get_error(int download_id, download_error_e *error);
761 * @brief Gets the http status code when the download error is happened.
763 * @param [in] download The download id
764 * @param [out] http_status The http status code which is defined in RFC 2616
765 * @return 0 on success, otherwise a negative error value.
766 * @retval #DOWNLOAD_ERROR_NONE Successful
767 * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
768 * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
769 * @pre The download state must be #DOWNLOAD_STATE_FAILED.
770 * @see #download_set_download_status_cb()
771 * @see #download_unset_download_status_cb()
772 * @see download_start()
774 int download_get_http_status(int download_id, int *http_status);
784 #endif /* __TIZEN_WEB_DOWNLOAD_H__ */