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 #include <app_control.h>
  22
  23 #ifndef DEPRECATED
  24         #define DEPRECATED __attribute__((deprecated))
  25 #endif
  26
  27 #ifdef __cplusplus
  28 extern "C"
  29 {
  30 #endif
  31
  32 /**
  33  * @file download.h
  34  */
  35
  36  /**
  37  * @addtogroup CAPI_WEB_DOWNLOAD_MODULE
  38  * @{
  39  */
  40
  41 /**
  42  * @brief Enumeration for error codes of URL download.
  43  * @since_tizen 2.3
  44  */
  45 typedef enum {
  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 */
  73 } download_error_e;
  74
  75
  76 /**
  77  * @brief Enumeration for download states.
  78  * @since_tizen 2.3
  79  */
  80 typedef enum {
  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 */
  89 } download_state_e;
  90
  91 /**
  92  * @brief Enumeration for network type for downloading.
  93  * @since_tizen 2.3
  94  */
  95 typedef enum {
  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;
 101
 102
 103 /**
 104  * @brief Enumeration for notification types when a client wants to register.
 105  * @since_tizen 2.3
 106  *
 107  * @see download_set_notification_type()
 108  * @see download_get_notification_type()
 109  */
 110 typedef enum {
 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;
 115
 116
 117 /**
 118  * @brief Enumeration for the type of notification app control action which the client wants to set when registering notification.
 119  * @since_tizen 2.3
 120  *
 121  * @see download_set_notification_app_control()
 122  * @see download_get_notification_app_control()
 123  */
 124 typedef enum {
 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;
 129
 130 /**
 131  * @brief Called when a download state is changed.
 132  *
 133  * @since_tizen 2.3
 134  *
 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()
 138  *
 139  * @pre download_start() will invoke this callback if you register this callback using download_set_state_changed_cb().
 140  *
 141  * @see download_set_state_changed_cb()
 142  * @see download_unset_state_changed_cb()
 143  */
 144 typedef void (*download_state_changed_cb) (int download_id,
 145                 download_state_e state, void *user_data);
 146
 147 /**
 148  * @brief Called when the progress of download changes.
 149  *
 150  * @since_tizen 2.3
 151  *
 152  * @remarks This callback function is only invoked in the downloading state.
 153  *
 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()
 157  *
 158  * @pre This callback function is invoked if you register this callback using download_set_progress_cb().
 159  *
 160  * @see download_cancel()
 161  * @see download_set_progress_cb()
 162  * @see download_unset_progress_cb()
 163  */
 164 typedef void (*download_progress_cb) (int download_id, unsigned long long received, void *user_data);
 165
 166 /**
 167  * @brief Creates a new download request and return its download ID.
 168  *
 169  * @since_tizen 2.3
 170  * @privlevel public
 171  * @privilege %http://tizen.org/privilege/download
 172  *
 173  * @remarks The @a download_id is released with download_destroy() by client.
 174  *
 175  * @param[out] download_id The download ID that is newly created on success
 176  *
 177  * @return @c 0 on success,
 178  *         otherwise a negative error value
 179  *
 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
 187  *
 188  * @post The download state will be #DOWNLOAD_STATE_READY.
 189  *
 190  * @see download_destroy()
 191  */
 192 int download_create(int *download_id);
 193
 194
 195 /**
 196  * @brief Unloads all data concerning a download ID from memory.
 197  *
 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.
 200  *
 201  * @since_tizen 2.3
 202  * @privlevel public
 203  * @privilege %http://tizen.org/privilege/download
 204  *
 205  *
 206  * @remarks If #DOWNLOAD_ERROR_ID_NOT_FOUND is returned, it means that the download ID is completely removed from DB.
 207  *
 208  * @param[in] download_id The download ID
 209  *
 210  * @return @c 0 on success,
 211  *         otherwise a negative error value
 212  *
 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
 218  *
 219  * @see download_create()
 220  */
 221 int download_destroy(int download_id);
 222
 223
 224 /**
 225  * @brief Sets the URL to download.
 226  *
 227  * @since_tizen 2.3
 228  * @privlevel public
 229  * @privilege %http://tizen.org/privilege/download
 230  *
 231  * @remarks This function should be called before downloading (see download_start()).
 232  *
 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.
 236  *
 237  * @return @c 0 on success,
 238  *         otherwise a negative error value
 239  *
 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
 247  *
 248  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
 249  *
 250  * @see download_get_url()
 251  */
 252 int download_set_url(int download_id, const char *url);
 253
 254
 255 /**
 256  * @brief Gets the URL to download.
 257  *
 258  * @since_tizen 2.3
 259  * @privlevel public
 260  * @privilege %http://tizen.org/privilege/download
 261  *
 262  * @remarks You must release @a url using free().
 263  *
 264  * @param[in]  download_id  The download ID
 265  * @param[out] url          The URL to download
 266  *
 267  * @return @c 0 on success,
 268  *         otherwise a negative error value
 269  *
 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
 276  *
 277  * @see download_set_url()
 278  */
 279 int download_get_url(int download_id, char **url);
 280
 281
 282 /**
 283  * @brief Sets the allowed network type for the downloaded file.
 284  *
 285  * @details The file can be downloaded only under the allowed network.
 286  *
 287  * @since_tizen 2.3
 288  * @privlevel public
 289  * @privilege %http://tizen.org/privilege/download
 290  *
 291  * @remarks This function should be called before downloading (see download_start()).
 292  *
 293  * @param[in] download_id  The download ID
 294  * @param[in] net_type     The network type that the client prefers
 295  *
 296  * @return @c 0 on success,
 297  *         otherwise a negative error value
 298  *
 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
 305  *
 306  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
 307  *
 308  * @see download_get_network_type()
 309  * @see #download_network_type_e
 310  */
 311 int download_set_network_type(int download_id, download_network_type_e net_type);
 312
 313
 314 /**
 315  * @brief Gets the network type for the downloaded file.
 316  *
 317  * @since_tizen 2.3
 318  * @privlevel public
 319  * @privilege %http://tizen.org/privilege/download
 320  *
 321  * @param[in] download_id  The download ID
 322  * @param[out] net_type    The network type that is defined by client
 323  *
 324  * @return @c 0 on success,
 325  *         otherwise a negative error value
 326  *
 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
 332  *
 333  * @see download_set_network_type()
 334  * @see #download_network_type_e
 335  */
 336 int download_get_network_type(int download_id, download_network_type_e *net_type);
 337
 338 /**
 339  * @brief Sets the destination for the downloaded file.
 340  *
 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).
 344  *
 345  * @since_tizen 2.3
 346  * @privlevel public
 347  * @privilege %http://tizen.org/privilege/download
 348  *
 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.
 352  *
 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.
 356  *
 357  * @return @c 0 on success,
 358  *         otherwise a negative error value
 359  *
 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
 368  *
 369  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
 370  *
 371  * @see download_get_destination()
 372  */
 373 int download_set_destination(int download_id, const char *path);
 374
 375
 376 /**
 377  * @brief Gets the destination path for the downloaded file.
 378  *
 379  * @since_tizen 2.3
 380  * @privlevel public
 381  * @privilege %http://tizen.org/privilege/download
 382  *
 383  * @remarks You must release @a path using free().
 384  *
 385  * @param[in]  download_id  The download ID
 386  * @param[out] path         The absolute path to the downloaded file
 387  *
 388  * @return @c 0 on success,
 389  *         otherwise a negative error value
 390  *
 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
 397  *
 398  * @see download_set_destination()
 399  */
 400 int download_get_destination(int download_id, char **path);
 401
 402
 403 /**
 404  * @brief Sets the name for the downloaded file.
 405  *
 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.
 408  *
 409  * @since_tizen 2.3
 410  * @privlevel public
 411  * @privilege %http://tizen.org/privilege/download
 412  *
 413  * @remarks This function should be called before downloading (see download_start()).
 414  *
 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.
 418  *
 419  * @return @c 0 on success,
 420  *         otherwise a negative error value
 421  *
 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
 429  *
 430  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
 431  *
 432  * @see download_get_file_name()
 433  */
 434 int download_set_file_name(int download_id, const char *file_name);
 435
 436 /**
 437  * @brief Gets the name of the downloaded file set previously by download_set_file_name().
 438  *
 439  * @details If the name is not set, @c NULL is returned.
 440  *
 441  * @since_tizen 2.3
 442  * @privlevel public
 443  * @privilege %http://tizen.org/privilege/download
 444  *
 445  * @remarks You must release @a file_name using free().
 446  *
 447  * @param[in]  download_id  The download ID
 448  * @param[out] file_name    The file name which is set by user
 449  *
 450  * @return @c 0 on success,
 451  *         otherwise a negative error value
 452  *
 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
 459  *
 460  * @see download_set_file_name()
 461  */
 462 int download_get_file_name(int download_id, char **file_name);
 463
 464
 465 /**
 466  * @brief Gets the absolute path to save the downloaded file.
 467  *
 468  * @since_tizen 2.3
 469  * @privlevel public
 470  * @privilege %http://tizen.org/privilege/download
 471  *
 472  * @remarks This function returns #DOWNLOAD_ERROR_INVALID_STATE if the download is not completed.
 473  *          You must release @a path using free().
 474  *
 475  * @param[in]  download_id  The download ID
 476  * @param[out] path         The absolute path to the downloaded file
 477  *
 478  * @return @c 0 on success,
 479  *         otherwise a negative error value
 480  *
 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
 487  *
 488  * @pre The download state must be #DOWNLOAD_STATE_COMPLETED.
 489  *
 490  * @see download_set_file_name()
 491  * @see download_set_destination()
 492  */
 493 int download_get_downloaded_file_path(int download_id, char **path);
 494
 495
 496 /**
 497  * @brief Gets the MIME type of the downloaded content.
 498  *
 499  * @since_tizen 2.3
 500  * @privlevel public
 501  * @privilege %http://tizen.org/privilege/download
 502  *
 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().
 505  *
 506  * @param[in]  download_id  The download ID
 507  * @param[out] mime_type    The MIME type of the downloaded file
 508  *
 509  * @return @c 0 on success,
 510  *         otherwise a negative error value
 511  *
 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
 518  *
 519  * @see download_set_file_name()
 520  * @see download_set_destination()
 521  * @see download_get_downloaded_file_path()
 522  */
 523 int download_get_mime_type(int download_id, char **mime_type);
 524
 525
 526 /**
 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.
 531  *
 532  * @since_tizen 2.3
 533  * @privlevel public
 534  * @privilege %http://tizen.org/privilege/download
 535  *
 536  * @remarks The default value is @c false.
 537  *
 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
 541  *
 542  * @return @c 0 on success,
 543  *         otherwise a negative error value
 544  *
 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
 550  *
 551  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
 552  *
 553  * @see download_get_auto_download()
 554  *
 555  */
 556 int download_set_auto_download(int download_id, bool enable);
 557
 558
 559 /**
 560  * @brief Checks whether auto download is enabled.
 561  *
 562  * @since_tizen 2.3
 563  * @privlevel public
 564  * @privilege %http://tizen.org/privilege/download
 565  *
 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
 569  *
 570  * @return @c 0 on success,
 571  *         otherwise a negative error value
 572  *
 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
 578  *
 579  * @see download_set_auto_download()
 580  */
 581 int download_get_auto_download(int download_id, bool *enable);
 582
 583
 584 /**
 585  * @brief Adds a HTTP header field to the download request.
 586  *
 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>.
 589  *
 590  * @since_tizen 2.3
 591  * @privlevel public
 592  * @privilege %http://tizen.org/privilege/download
 593  *
 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.
 597  *
 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
 601  *
 602  * @return @c 0 on success,
 603  *         otherwise a negative error value
 604  *
 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
 613  *
 614  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
 615  *
 616  * @see download_get_http_header_field()
 617  * @see download_remove_http_header_field()
 618  */
 619 int download_add_http_header_field(int download_id, const char *field, const char *value);
 620
 621
 622 /**
 623  * @brief Gets a value associated with a given HTTP header field from the download.
 624  *
 625  * @since_tizen 2.3
 626  * @privlevel public
 627  * @privilege %http://tizen.org/privilege/download
 628  *
 629  * @remarks This function returns #DOWNLOAD_ERROR_INVALID_PARAMETER if @a field is zero-length string.
 630  *          You must release @a value using free().
 631  *
 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
 635  *
 636  * @return @c 0 on success,
 637  *         otherwise a negative error value
 638  *
 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
 647  *
 648  * @see download_add_http_header_field()
 649  * @see download_remove_http_header_field()
 650  */
 651 int download_get_http_header_field(int download_id, const char *field, char **value);
 652
 653 /**
 654  * @brief Gets all the HTTP header fields added to the download request.
 655  *
 656  * @since_tizen 2.3
 657  * @privlevel public
 658  * @privilege %http://tizen.org/privilege/download
 659  *
 660  * @remarks You must release @a value using free().
 661  *
 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
 665  *
 666  * @return @c 0 on success,
 667  *         otherwise a negative error value
 668  *
 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
 676  *
 677  * @see download_add_http_header_field()
 678  * @see download_remove_http_header_field()
 679  */
 680 int download_get_http_header_field_list(int download_id, char ***fields, int *length);
 681
 682 /**
 683  * @brief Removes a given HTTP header field from the download.
 684  *
 685  * @since_tizen 2.3
 686  * @privlevel public
 687  * @privilege %http://tizen.org/privilege/download
 688  *
 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.
 691  *
 692  * @param[in] download_id  The download ID
 693  * @param[in] field        The name of the HTTP header field
 694  *
 695  * @return @c 0 on success,
 696  *         otherwise a negative error value
 697  *
 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
 707  *
 708  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
 709  *
 710  * @see download_add_http_header_field()
 711  * @see download_get_http_header_field()
 712  */
 713 int download_remove_http_header_field(int download_id, const char *field);
 714
 715
 716 /**
 717  * @brief Registers a callback function to be invoked when a download state is changed.
 718  *
 719  * @since_tizen 2.3
 720  * @privlevel public
 721  * @privilege %http://tizen.org/privilege/download
 722  *
 723  * @remarks This function should be called before downloading (see download_start()).
 724  *
 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
 728  *
 729  * @return @c 0 on success,
 730  *         otherwise a negative error value
 731  *
 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
 737  *
 738  * @post download_state_changed_cb() will be invoked.
 739  *
 740  * @see download_unset_state_changed_cb()
 741  * @see download_state_changed_cb()
 742 */
 743 int download_set_state_changed_cb(int download_id, download_state_changed_cb callback, void* user_data);
 744
 745
 746 /**
 747  * @brief Unregisters the download state change callback function.
 748  *
 749  * @since_tizen 2.3
 750  * @privlevel public
 751  * @privilege %http://tizen.org/privilege/download
 752  *
 753  * @remarks This function should be called before downloading (see download_start()).
 754  *
 755  * @param[in] download_id The download ID
 756  *
 757  * @return @c 0 on success,
 758  *         otherwise a negative error value
 759  *
 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
 765  *
 766  * @see download_set_state_changed_cb()
 767  * @see download_state_changed_cb()
 768 */
 769 int download_unset_state_changed_cb(int download_id);
 770
 771
 772 /**
 773  * @brief Registers a callback function to be invoked when progress of the download changes.
 774  *
 775  * @since_tizen 2.3
 776  * @privlevel public
 777  * @privilege %http://tizen.org/privilege/download
 778  *
 779  * @remarks This function should be called before downloading (see download_start()).
 780  *
 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
 784  *
 785  * @return @c 0 on success,
 786  *          otherwise a negative error value
 787  *
 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
 794  *
 795  * @post download_progress_cb() will be invoked.
 796  *
 797  * @see download_unset_progress_cb()
 798  * @see download_progress_cb()
 799 */
 800 int download_set_progress_cb(int download_id, download_progress_cb callback, void *user_data);
 801
 802
 803 /**
 804  * @brief Unregisters the download progress change callback function.
 805  *
 806  * @since_tizen 2.3
 807  * @privlevel public
 808  * @privilege %http://tizen.org/privilege/download
 809  *
 810  * @remarks This function should be called before downloading (see download_start()).
 811  *
 812  * @param[in] download_id The download ID
 813  *
 814  * @return @c 0 on success,
 815  *         otherwise a negative error value
 816  *
 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
 823  *
 824  * @see download_set_progress_cb()
 825  * @see download_progress_cb()
 826 */
 827 int download_unset_progress_cb(int download_id);
 828
 829
 830 /**
 831  * @brief Starts or resumes the download, asynchronously.
 832  *
 833  * @details This function starts to download the current URL, or resumes the download if paused.
 834  *
 835  * @since_tizen 2.3
 836  * @privlevel public
 837  * @privilege %http://tizen.org/privilege/download
 838  *
 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.
 842  *
 843  * @param[in] download_id The download ID
 844  *
 845  * @return  @c 0 on success,
 846  *          otherwise a negative error value
 847  *
 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
 859  *
 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.
 862  *
 863  * @see download_set_url()
 864  * @see download_pause()
 865  * @see download_cancel()
 866  */
 867 int download_start(int download_id);
 868
 869
 870 /**
 871  * @brief Pauses the download, asynchronously.
 872  *
 873  * @since_tizen 2.3
 874  * @privlevel public
 875  * @privilege %http://tizen.org/privilege/download
 876  *
 877  * @remarks The paused download can be restarted with download_start() or cancelled with download_cancel().
 878  *
 879  * @param[in] download_id The download ID
 880  *
 881  * @return  @c 0 on success,
 882  *          otherwise a negative error value
 883  *
 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
 892  *
 893  * @pre  The download state must be #DOWNLOAD_STATE_DOWNLOADING.
 894  * @post The download state will be #DOWNLOAD_STATE_PAUSED.
 895  *
 896  * @see download_start()
 897  * @see download_cancel()
 898  */
 899 int download_pause(int download_id);
 900
 901
 902 /**
 903  * @brief Cancels the download, asynchronously.
 904  *
 905  * @details This function cancels the running download and its state will be #DOWNLOAD_STATE_READY.
 906  *
 907  * @since_tizen 2.3
 908  * @privlevel public
 909  * @privilege %http://tizen.org/privilege/download
 910  *
 911  * @remarks The canceled download can be restarted with download_start().
 912  *
 913  * @param[in] download_id The download ID
 914  *
 915  * @return  @c 0 on success,
 916  *          otherwise a negative error value
 917  *
 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
 926  *
 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.
 929  *
 930  * @see download_start()
 931  */
 932 int download_cancel(int download_id);
 933
 934
 935 /**
 936  * @brief Gets the current state of the download.
 937  *
 938  * @since_tizen 2.3
 939  * @privlevel public
 940  * @privilege %http://tizen.org/privilege/download
 941  *
 942  * @param[in]  download_id  The download ID
 943  * @param[out] state        The current state of the download
 944  *
 945  * @return  @c 0 on success,
 946  *          otherwise a negative error value
 947  *
 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
 953  *
 954  * @see #download_state_e
 955  */
 956 int download_get_state(int download_id, download_state_e *state);
 957
 958
 959 /**
 960  * @brief Gets the full path of the temporary file to store downloaded content.
 961  *
 962  * @since_tizen 2.3
 963  * @privlevel public
 964  * @privilege %http://tizen.org/privilege/download
 965  *
 966  * @param[in]  download_id  The download ID
 967  * @param[out] temp_path    The full path of temporary file
 968  *
 969  * @return @c 0 on success,
 970  *          otherwise a negative error value
 971  *
 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
 977  *
 978  * @pre The download state must be one of the states after #DOWNLOAD_STATE_DOWNLOADING.
 979  *
 980  * @see download_set_state_changed_cb()
 981  * @see download_unset_state_changed_cb()
 982  * @see download_start()
 983  */
 984 int download_get_temp_path(int download_id, char **temp_path);
 985
 986
 987 /**
 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.
 991  *
 992  * @since_tizen 2.3
 993  * @privlevel public
 994  * @privilege %http://tizen.org/privilege/download
 995  *
 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.
1000
1001  *
1002  * @param[in]  download_id  The download ID
1003  * @param[out] path         The full path of temporary file
1004  *
1005  * @return  @c 0 on success,
1006  *          otherwise a negative error value
1007  *
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
1014  *
1015  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
1016  *
1017  * @see download_get_etag()
1018  */
1019 int download_set_temp_file_path(int download_id, char *path);
1020
1021
1022 /**
1023  * @brief Gets the content name of downloaded file.
1024  *
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.
1027  *
1028  * @since_tizen 2.3
1029  * @privlevel public
1030  * @privilege %http://tizen.org/privilege/download
1031  *
1032  * @param[in]  download_id   The download ID
1033  * @param[out] content_name  The content name for displaying to user
1034  *
1035  * @return  @c 0 on success,
1036  *          otherwise a negative error value
1037  *
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
1043  *
1044  * @pre The download state must be one of the states after #DOWNLOAD_STATE_DOWNLOADING.
1045  *
1046  * @see download_set_state_changed_cb()
1047  * @see download_unset_state_changed_cb()
1048  * @see download_start()
1049  */
1050 int download_get_content_name(int download_id, char **content_name);
1051
1052
1053 /**
1054  * @brief Gets the total size of downloaded content.
1055  *
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.
1057  *
1058  * @since_tizen 2.3
1059  * @privlevel public
1060  * @privilege %http://tizen.org/privilege/download
1061  *
1062  * @param[in]  download_id  The download ID
1063  * @param[out] content_size The content size for displaying to user
1064  *
1065  * @return  @c 0 on success,
1066  *          otherwise a negative error value
1067  *
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
1073  *
1074  * @pre The download state must be one of the states after #DOWNLOAD_STATE_DOWNLOADING.
1075  *
1076  * @see download_set_state_changed_cb()
1077  * @see download_unset_state_changed_cb()
1078  * @see download_start()
1079  */
1080 int download_get_content_size(int download_id, unsigned long long *content_size);
1081
1082
1083 /**
1084  * @brief Gets an error value when the download fails.
1085  *
1086  * @since_tizen 2.3
1087  * @privlevel public
1088  * @privilege %http://tizen.org/privilege/download
1089  *
1090  * @param[in]  download_id The download ID
1091  * @param[out] error       The error value
1092  *
1093  * @return @c 0 on success,
1094  *          otherwise a negative error value
1095  *
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
1101  *
1102  * @pre The download state must be #DOWNLOAD_STATE_FAILED.
1103  * @pre The download state must be #DOWNLOAD_STATE_CANCELED.
1104  *
1105  * @see download_set_state_changed_cb()
1106  * @see download_unset_state_changed_cb()
1107  * @see download_start()
1108  * @see download_error_e
1109  */
1110 int download_get_error(int download_id, download_error_e *error);
1111
1112
1113 /**
1114  * @brief Gets a HTTP status code when a download error occurs.
1115  *
1116  * @since_tizen 2.3
1117  * @privlevel public
1118  * @privilege %http://tizen.org/privilege/download
1119  *
1120  * @param[in]  download_id  The download ID
1121  * @param[out] HTTP_status  The HTTP status code defined in RFC 2616
1122  *
1123  * @return  @c 0 on success,
1124  *          otherwise a negative error value
1125  *
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
1131  *
1132  * @pre The download state must be #DOWNLOAD_STATE_FAILED.
1133  *
1134  * @see download_start()
1135  */
1136 int download_get_http_status(int download_id, int *HTTP_status);
1137
1138
1139 /**
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.
1142  *
1143  * @since_tizen 2.3
1144  * @privlevel public
1145  * @privilege %http://tizen.org/privilege/download
1146  *
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.
1153  *
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
1158  *
1159  * @return  @c 0 on success,
1160  *          otherwise a negative error value
1161  *
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
1167  *
1168  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
1169  *
1170  * @see download_set_notification_type()
1171  * @see download_get_notification_app_control()
1172  */
1173 int download_set_notification_app_control(int download_id, download_notification_app_control_type_e type, app_control_h handle);
1174
1175
1176 /**
1177  * @brief Gets the app control handle (used previously to register notification messages) which is set by download_set_notification_app_control().
1178  *
1179  * @details When the notification message is clicked, the action is decided by the app control handle.
1180  *
1181  * @since_tizen 2.3
1182  * @privlevel public
1183  * @privilege %http://tizen.org/privilege/download
1184  *
1185  * @remarks The app control handle MUST BE FREED by the client when it is not used any more.
1186  *
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
1191  *
1192  * @return  @c 0 on success,
1193  *          otherwise a negative error value
1194  *
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
1201  *
1202  * @see download_set_notification_app_control()
1203  */
1204 int download_get_notification_app_control(int download_id, download_notification_app_control_type_e type, app_control_h *handle);
1205
1206
1207 /**
1208  * @brief Sets the title of a notification.
1209  *
1210  * @details When registering a notification, the title is displayed in the title area of the notification message.
1211  *
1212  * @since_tizen 2.3
1213  * @privlevel public
1214  * @privilege %http://tizen.org/privilege/download
1215  *
1216  * @param[in] download_id The download ID
1217  * @param[in] title       The title for displaying to user
1218  *
1219  * @return  @c 0 on success,
1220  *          otherwise a negative error value
1221  *
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
1227  *
1228  * @pre If a notification option is not enabled, this title is not shown to user.
1229  *
1230  * @see download_set_notification_type()
1231  * @see download_get_notification_title()
1232  */
1233 int download_set_notification_title(int download_id, const char *title);
1234
1235
1236 /**
1237  * @brief Gets the title of the notification set by download_set_notification_title().
1238  *
1239  * @details When registering a notification, the title is displayed in the title area of the notification message.
1240  *
1241  * @since_tizen 2.3
1242  * @privlevel public
1243  * @privilege %http://tizen.org/privilege/download
1244  *
1245  * @param[in]  download_id  The download ID
1246  * @param[out] title        The title for displaying to user
1247  *
1248  * @return @c 0 on success,
1249  *          otherwise a negative error value
1250  *
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
1257  *
1258  * @pre It can get the title value before calling this API.
1259  *
1260  * @see download_set_notification_title()
1261   */
1262 int download_get_notification_title(int download_id, char **title);
1263
1264
1265 /**
1266  * @brief Sets the description of a notification.
1267  *
1268  * @details When registering a notification, the description is displayed in the description area of the notification message.
1269  *
1270  * @since_tizen 2.3
1271  * @privlevel public
1272  * @privilege %http://tizen.org/privilege/download
1273  *
1274  * @param[in] download_id  The download ID
1275  * @param[in] description  The description for displaying to user
1276  *
1277  * @return @c 0 on success,
1278  *          otherwise a negative error value
1279  *
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
1285  *
1286  * @pre If the notification option is not enabled, this description is not shown to user.
1287  *
1288  * @see download_set_notification_type()
1289  * @see download_get_notification_description()
1290   */
1291 int download_set_notification_description(int download_id, const char *description);
1292
1293
1294 /**
1295  * @brief Gets the description of a notification set by download_set_notification_description().
1296  *
1297  * @details When registering a notification, the description is displayed in the description area of the notification message.
1298  *
1299  * @since_tizen 2.3
1300  * @privlevel public
1301  * @privilege %http://tizen.org/privilege/download
1302  *
1303  * @param[in]  download_id  The download ID
1304  * @param[out] description  The description for displaying to user
1305  *
1306  * @return  @c 0 on success,
1307  *          otherwise a negative error value
1308  *
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
1315  *
1316  * @pre It can get the title value before calling this API.
1317  *
1318  * @see download_set_notification_description()
1319   */
1320 int download_get_notification_description(int download_id, char **description);
1321
1322
1323 /**
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.
1326  *
1327  * @since_tizen 2.3
1328  * @privlevel public
1329  * @privilege %http://tizen.org/privilege/download
1330  *
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.
1337  *
1338  * @param[in] download_id  The download ID
1339  * @param[in] type         The enumeration type \n
1340  *                         See #download_notification_type_e.
1341  *
1342  * @return @c 0 on success,
1343  *          otherwise a negative error value
1344  *
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
1350  *
1351  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, or #DOWNLOAD_STATE_CANCELED.
1352  *
1353  * @see download_set_notification_app_control()
1354  * @see download_get_notification_type()
1355  */
1356 int download_set_notification_type(int download_id, download_notification_type_e type);
1357
1358
1359 /**
1360  * @brief Gets an option value to register notification messages set by download_set_notification_type().
1361  *
1362  * @since_tizen 2.3
1363  * @privlevel public
1364  * @privilege %http://tizen.org/privilege/download
1365  *
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.
1368  *
1369  * @param[in]  download_id  The download ID
1370  * @param[out] type         The enumeration type \n
1371  *                          See #download_notification_type_e.
1372  *
1373  * @return  @c 0 on success,
1374  *          otherwise a negative error value
1375  *
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
1381  *
1382  * @see download_set_notification_type()
1383  */
1384 int download_get_notification_type(int download_id, download_notification_type_e *type);
1385
1386
1387 /**
1388  * @brief Gets an etag value from the HTTP response header when making a HTTP request for resume.
1389  *
1390  * @since_tizen 2.3
1391  * @privlevel public
1392  * @privilege %http://tizen.org/privilege/download
1393  *
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.
1396  *
1397  * @param[in]  download_id  The download ID
1398  * @param[out] etag         The etag value
1399  *
1400  * @return  @c 0 on success,
1401  *          otherwise a negative error value
1402  *
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
1408  *
1409  * @see download_set_temp_file_path()
1410  */
1411 int download_get_etag(int download_id, char **etag);
1412
1413
1414 /**
1415  * @brief Sets the 'enabled' state of the cache feature.
1416  *
1417  * @since_tizen 7.5
1418  * @privlevel public
1419  * @privilege %http://tizen.org/privilege/download
1420  *
1421  * @param[in] download_id  The download id
1422  * @param[in] enable       The enable value
1423  *
1424  * @return 0 on success, otherwise a negative error value
1425  *
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
1432  *
1433  * @see download_get_cache()
1434 */
1435 int download_set_cache(int download_id, bool enable);
1436
1437
1438 /**
1439  * @brief Gets the 'enabled' state of the cache feature.
1440  *
1441  * @since_tizen 7.5
1442  * @privlevel public
1443  * @privilege %http://tizen.org/privilege/download
1444  *
1445  * @param[in]  download_id  The download id
1446  * @param[out] enable       The enable value
1447  *
1448  * @return 0 on success, otherwise a negative error value
1449  *
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
1456  *
1457  * @see download_set_cache()
1458  */
1459 int download_get_cache(int download_id, bool *enable);
1460
1461
1462 /**
1463  * @brief Clears the cache.
1464  *
1465  * @since_tizen 7.5
1466  * @privlevel public
1467  * @privilege %http://tizen.org/privilege/download
1468  *
1469  * @return 0 on success, otherwise a negative error value
1470  *
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
1476  */
1477 int download_reset_cache(void);
1478
1479
1480 /**
1481  * @}
1482  */
1483
1484 #ifdef __cplusplus
1485 }
1486 #endif
1487
1488 #endif /* __TIZEN_WEB_DOWNLOAD_H__ */