include/download.h

   1 /*
   2  * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the License);
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an AS IS BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #ifndef __TIZEN_WEB_DOWNLOAD_H__
  18 #define __TIZEN_WEB_DOWNLOAD_H__
  19
  20 #include <tizen.h>
  21
  22 #ifdef __cplusplus
  23 extern "C"
  24 {
  25 #endif
  26
  27  /**
  28  * @addtogroup CAPI_WEB_DOWNLOAD_MODULE
  29  * @{
  30  */
  31
  32 /**
  33  * @brief Name for download service operation. Download Manager application is launched.
  34  */
  35 #define SERVICE_OPERATION_DOWNLOAD "http://tizen.org/appcontrol/operation/download"
  36
  37 /**
  38  * @brief Enumeration of error code for URL download
  39  */
  40 typedef enum
  41 {
  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 */
  66 } download_error_e;
  67
  68
  69 /**
  70  * @brief Enumerations of state of download
  71  */
  72 typedef enum
  73 {
  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. */
  82 } download_state_e;
  83
  84 /**
  85  * @brief Enumerations of network type for download
  86  */
  87 typedef enum
  88 {
  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 ;
  93
  94
  95 /**
  96  * @brief Called when the download status is changed.
  97  *
  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()
 104  */
 105 typedef void (*download_state_changed_cb) (int download_id,
 106         download_state_e state, void *user_data);
 107
 108 /**
 109  * @brief Called when the progress of download changes.
 110  *
 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()
 119  */
 120 typedef void (*download_progress_cb) (int download_id, unsigned long long received, void *user_data);
 121
 122 /**
 123  * @brief Creates a download id.
 124  *
 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()
 136  */
 137 int download_create(int *download_id);
 138
 139
 140 /**
 141  * @brief Unload all data concerning a download id from memory.
 142  *
 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()
 152  */
 153 int download_destroy(int download_id);
 154
 155
 156 /**
 157  * @brief Sets the URL to download.
 158  *
 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()
 171  */
 172 int download_set_url(int download_id, const char *url);
 173
 174
 175 /**
 176  * @brief Gets the URL to download.
 177  *
 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()
 187  */
 188 int download_get_url(int download_id, char **url);
 189
 190
 191 /**
 192  * @brief Sets the allowed network type for the downloaded file
 193  *
 194  * @details The file can be downloaded only under the allowed network.
 195  *
 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
 207  */
 208 int download_set_network_type(int download_id, download_network_type_e net_type);
 209
 210
 211 /**
 212  * @brief Gets the netowork type for the downloaded file
 213  *
 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
 222  */
 223 int download_get_network_type(int download_id, download_network_type_e *net_type);
 224
 225
 226 /**
 227  * @brief Sets the destination for the downloaded file.
 228  *
 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)
 232  *
 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()
 245  */
 246 int download_set_destination(int download_id, const char *path);
 247
 248
 249 /**
 250  * @brief Gets the destination for the downloaded file.
 251  *
 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()
 261  */
 262 int download_get_destination(int download_id, char **path);
 263
 264
 265 /**
 266  * @brief Sets the name for the downloaded file.
 267  *
 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.
 270  *
 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()
 283  */
 284 int download_set_file_name(int download_id, const char *file_name);
 285
 286
 287 /**
 288  * @brief Gets the name which is set by user.
 289  *
 290  * @details If user do not set any name, it retruns NULL.
 291  *
 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()
 301  */
 302 int download_get_file_name(int download_id, char **file_name);
 303
 304
 305 /**
 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
 310  *
 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()
 328  */
 329 int download_set_notification(int download_id, bool enable);
 330
 331 /**
 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()
 340  */
 341 int download_get_notification(int download_id, bool *enable);
 342
 343 /**
 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.
 347  *
 348  * @remarks This function should be called before downloading (See download_start())
 349  *
 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()
 360  */
 361 int download_add_notification_extra_param(int download_id, const char *key, const char **values, const unsigned int length);
 362
 363 /**
 364  * @brief Remove the extra param data which pass by application service data when notification message is clicked
 365  *
 366  * @remarks This function should be called before downloading (See download_start())
 367  *
 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()
 376  */
 377 int download_remove_notification_extra_param(int download_id, const char *key);
 378
 379 /**
 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()
 390  */
 391 int download_get_notification_extra_param(int download_id, const char *key, char ***values, unsigned int *length);
 392
 393 /**
 394  * @brief Gets the absolute path to save the downloaded file
 395  *
 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()
 408  */
 409 int download_get_downloaded_file_path(int download_id, char **path);
 410
 411
 412 /**
 413  * @brief Gets the mime type for downloading a content.
 414  *
 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()
 427  */
 428 int download_get_mime_type(int download_id, char **mime_type);
 429
 430
 431 /**
 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()
 449  *
 450  */
 451 int download_set_auto_download(int download_id, bool enable);
 452
 453
 454 /**
 455  * @brief Gets the value of option for auto download.
 456  *
 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()
 464  */
 465 int download_get_auto_download(int download_id, bool *enable);
 466
 467
 468 /**
 469  * @brief Adds an HTTP header field to the download request
 470  *
 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()
 489  */
 490 int download_add_http_header_field(int download_id, const char *field, const char *value);
 491
 492
 493 /**
 494  * @brief Gets the value associated with given HTTP header field from the download
 495  *
 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()
 510  */
 511 int download_get_http_header_field(int download_id, const char *field, char **value);
 512
 513
 514 /**
 515  * @brief Removes the given HTTP header field from the download
 516  *
 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()
 532  */
 533 int download_remove_http_header_field(int download_id, const char *field);
 534
 535
 536 /**
 537  * @brief Registers a callback function to be invoked when the download state is changed.
 538  *
 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()
 550 */
 551 int download_set_state_changed_cb(int download_id, download_state_changed_cb callback, void* user_data);
 552
 553
 554 /**
 555  * @brief Unregisters the callback function.
 556  *
 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()
 565 */
 566 int download_unset_state_changed_cb(int download_id);
 567
 568
 569 /**
 570  * @brief Registers a callback function to be invoked when progress of the download changes
 571  *
 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()
 584 */
 585 int download_set_progress_cb(int download_id, download_progress_cb callback, void *user_data);
 586
 587
 588 /**
 589  * @brief Unregisters the callback function.
 590  *
 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()
 600 */
 601 int download_unset_progress_cb(int download_id);
 602
 603
 604 /**
 605  * @brief Starts or resumes the download, asynchronously.
 606  *
 607  * @details This function starts to download the current URL, or resumes the download if paused.
 608  *
 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()
 627  */
 628 int download_start(int download_id);
 629
 630
 631 /**
 632  * @brief Pauses the download, asynchronously.
 633  *
 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()
 647  */
 648 int download_pause(int download_id);
 649
 650
 651 /**
 652  * @brief Cancel the download, asynchronously.
 653  *
 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()
 667  */
 668 int download_cancel(int download_id);
 669
 670
 671 /**
 672  * @brief Gets the download's current state.
 673  *
 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
 681  */
 682 int download_get_state(int download_id, download_state_e *state);
 683
 684
 685 /**
 686  * @brief Gets the full path of temporary file for downloading a content.
 687  *
 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()
 698  */
 699 int download_get_temp_path(int download_id, char **temp_path);
 700
 701
 702 /**
 703  * @brief Gets the content name for downloading a file.
 704  *
 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.
 707  *
 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()
 718  */
 719 int download_get_content_name(int download_id, char **content_name);
 720
 721
 722 /**
 723  * @brief Gets the total size for downloading a content.
 724  *
 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.
 726  *
 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()
 737  */
 738 int download_get_content_size(int download_id, unsigned long long *content_size);
 739
 740
 741 /**
 742  * @brief Gets the error value when the download is failed.
 743  *
 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
 756  */
 757 int download_get_error(int download_id, download_error_e *error);
 758
 759
 760 /**
 761  * @brief Gets the http status code when the download error is happened.
 762  *
 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()
 773  */
 774 int download_get_http_status(int download_id, int *http_status);
 775
 776 /**
 777  * @}
 778  */
 779
 780 #ifdef __cplusplus
 781 }
 782 #endif
 783
 784 #endif /* __TIZEN_WEB_DOWNLOAD_H__ */