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 <bundle.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  * @addtogroup CAPI_WEB_DOWNLOAD_MODULE
  34  * @{
  35  */
  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_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Permission denied */
  50         DOWNLOAD_ERROR_INVALID_STATE = TIZEN_ERROR_WEB_CLASS | 0x21, /**< Invalid state */
  51         DOWNLOAD_ERROR_CONNECTION_FAILED = TIZEN_ERROR_WEB_CLASS | 0x22, /**< Connection failed */
  52         DOWNLOAD_ERROR_INVALID_URL = TIZEN_ERROR_WEB_CLASS | 0x24, /**< Invalid URL */
  53         DOWNLOAD_ERROR_INVALID_DESTINATION = TIZEN_ERROR_WEB_CLASS | 0x25, /**< Invalid destination */
  54         DOWNLOAD_ERROR_TOO_MANY_DOWNLOADS = TIZEN_ERROR_WEB_CLASS | 0x26, /**< Full of available simultaneous downloads */
  55         DOWNLOAD_ERROR_QUEUE_FULL = TIZEN_ERROR_WEB_CLASS | 0x27, /**< Full of available downloading items from server*/
  56         DOWNLOAD_ERROR_ALREADY_COMPLETED = TIZEN_ERROR_WEB_CLASS | 0x28, /**< The download is already completed */
  57         DOWNLOAD_ERROR_FILE_ALREADY_EXISTS = TIZEN_ERROR_WEB_CLASS | 0x29, /**< It is failed to rename the downloaded file */
  58         DOWNLOAD_ERROR_CANNOT_RESUME = TIZEN_ERROR_WEB_CLASS | 0x2a, /**< It cannot resume */
  59         DOWNLOAD_ERROR_TOO_MANY_REDIRECTS = TIZEN_ERROR_WEB_CLASS | 0x30, /**< In case of too may redirects from http response header*/
  60         DOWNLOAD_ERROR_UNHANDLED_HTTP_CODE = TIZEN_ERROR_WEB_CLASS | 0x31,  /**< The download cannot handle the http status value */
  61         DOWNLOAD_ERROR_REQUEST_TIMEOUT = TIZEN_ERROR_WEB_CLASS | 0x32, /**< There are no action after client create a download id*/
  62         DOWNLOAD_ERROR_RESPONSE_TIMEOUT = TIZEN_ERROR_WEB_CLASS | 0x33, /**< It does not call start API in some time although the download is created*/
  63         DOWNLOAD_ERROR_SYSTEM_DOWN = TIZEN_ERROR_WEB_CLASS | 0x34, /**< There are no response from client after rebooting download daemon*/
  64         DOWNLOAD_ERROR_ID_NOT_FOUND = TIZEN_ERROR_WEB_CLASS | 0x35, /**< The download id is not existed in download service module*/
  65         DOWNLOAD_ERROR_NO_DATA = TIZEN_ERROR_NO_DATA, /**< No data because the set API is not called */
  66         DOWNLOAD_ERROR_IO_ERROR = TIZEN_ERROR_IO_ERROR , /**< Internal I/O error */
  67 } download_error_e;
  68
  69
  70 /**
  71  * @brief Enumerations of state of download
  72  */
  73 typedef enum
  74 {
  75         DOWNLOAD_STATE_NONE, /**< It is ready to download */
  76         DOWNLOAD_STATE_READY, /**< It is ready to download */
  77         DOWNLOAD_STATE_QUEUED, /**< It is queued to start downloading */
  78         DOWNLOAD_STATE_DOWNLOADING, /**< The download is currently running */
  79         DOWNLOAD_STATE_PAUSED, /**< The download is waiting to resume */
  80         DOWNLOAD_STATE_COMPLETED, /**< The download is completed. */
  81         DOWNLOAD_STATE_FAILED, /**< The download failed. */
  82         DOWNLOAD_STATE_CANCELED, /**< User cancel the download item. */
  83 } download_state_e;
  84
  85 /**
  86  * @brief Enumerations of network type for download
  87  */
  88 typedef enum
  89 {
  90         DOWNLOAD_NETWORK_DATA_NETWORK, /**< Download is available through data network */
  91         DOWNLOAD_NETWORK_WIFI, /**< Download is available through WiFi */
  92         DOWNLOAD_NETWORK_WIFI_DIRECT, /**< Download is available through WiFi-Direct */
  93         DOWNLOAD_NETWORK_ALL /**< Download is available through either data network or WiFi */
  94 } download_network_type_e ;
  95
  96
  97 /**
  98  * @brief Enumerations of notification type when client want to register
  99  * @see #download_set_notification_type()
 100  * @see #download_get_notification_type()
 101  */
 102 typedef enum
 103 {
 104         DOWNLOAD_NOTIFICATION_TYPE_NONE = 0, /**< Do not register notification */
 105         DOWNLOAD_NOTIFICATION_TYPE_COMPLETE_ONLY, /**< For success state and failed state */
 106         DOWNLOAD_NOTIFICATION_TYPE_ALL /**< For ongoing state, success state and failed state */
 107 } download_notification_type_e;
 108
 109
 110 /**
 111  * @brief Enumerations of the type about notification bundle which client want to set when registering notification
 112  * @see #download_set_notification_bundle()
 113  * @see #download_get_notification_bundle()
 114  */
 115 typedef enum
 116 {
 117         DOWNLOAD_NOTIFICATION_BUNDLE_TYPE_ONGOING = 0, /**< For bundle for failed and ongoing notification */
 118         DOWNLOAD_NOTIFICATION_BUNDLE_TYPE_COMPLETE, /**< For bundle for completed notification */
 119         DOWNLOAD_NOTIFICATION_BUNDLE_TYPE_FAILED /**< For bundle for failed notification*/
 120 } download_notification_bundle_type_e;
 121
 122
 123 /**
 124  * @brief Called when the download status is changed.
 125  *
 126  * @param [in] download The download id
 127  * @param [in] state The state of download
 128  * @param [in] user_data The user data passed from download_set_state_changed_cb()
 129  * @pre download_start()  will cause this callback if you register this callback using download_set_state_changed_cb()
 130  * @see download_set_state_changed_cb()
 131  * @see download_unset_state_changed_cb()
 132  */
 133 typedef void (*download_state_changed_cb) (int download_id,
 134         download_state_e state, void *user_data);
 135
 136 /**
 137  * @brief Called when the progress of download changes.
 138  *
 139  * @remarks This callback function is only invoked in the downloading state.
 140  * @param [in] download The download id
 141  * @param [in] received The size of the data received in bytes
 142  * @param [in] user_data The user data passed from download_set_progress_cb()
 143  * @pre This callback function is invoked if you register this callback using download_set_progress_cb().
 144  * @see download_cancel()
 145  * @see download_set_progress_cb()
 146  * @see download_unset_progress_cb()
 147  */
 148 typedef void (*download_progress_cb) (int download_id, unsigned long long received, void *user_data);
 149
 150 /**
 151  * @brief Creates a download id.
 152  *
 153  * @remarks The @a download is released with download_destroy() by client.\n
 154  * @param [out] download A download id to be newly created on success
 155  * @return 0 on success, otherwise a negative error value.
 156  * @retval #DOWNLOAD_ERROR_NONE Successful
 157  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 158  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 159  * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
 160  * @retval #DOWNLOAD_ERROR_QUEUE_FULL Full of queue from download server
 161  * @post The download state will be #DOWNLOAD_STATE_READY
 162  * @see download_destroy()
 163  */
 164 int download_create(int *download_id);
 165
 166
 167 /**
 168  * @brief Unload all data concerning a download id from memory.
 169  *
 170  * @detail After calling this API, a download ID is existed at DB in certain time.\n
 171  * Within that time, it is able to use the other API with the download ID.
 172  * @remark If #DOWNLOAD_ERROR_ID_NOT_FOUND is returned, it means that the download ID is completely removed from DB.
 173  * @param [in] download The download id
 174  * @return 0 on success, otherwise a negative error value.
 175  * @retval #DOWNLOAD_ERROR_NONE Successful
 176  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 177  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 178  * @see download_create()
 179  */
 180 int download_destroy(int download_id);
 181
 182
 183 /**
 184  * @brief Sets the URL to download.
 185  *
 186  * @remarks This function should be called before downloading (See download_start())
 187  * @param [in] download The download id
 188  * @param [in] url The URL to download \n
 189  *  If the @a url is NULL, it clears the previous value.
 190  * @return 0 on success, otherwise a negative error value.
 191  * @retval #DOWNLOAD_ERROR_NONE Successful
 192  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 193  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 194  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 195  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 196  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
 197  * @see download_get_url()
 198  */
 199 int download_set_url(int download_id, const char *url);
 200
 201
 202 /**
 203  * @brief Gets the URL to download.
 204  *
 205  * @remarks The @a url must be released with free() by you.
 206  * @param [in] download The download id
 207  * @param [out] url The URL to download
 208  * @return 0 on success, otherwise a negative error value.
 209  * @retval #DOWNLOAD_ERROR_NONE Successful
 210  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 211  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 212  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 213  * @see download_set_url()
 214  */
 215 int download_get_url(int download_id, char **url);
 216
 217
 218 /**
 219  * @brief Sets the allowed network type for the downloaded file
 220  *
 221  * @details The file can be downloaded only under the allowed network.
 222  *
 223  * @remarks This function should be called before downloading (see download_start())
 224  * @param [in] download The download id
 225  * @param [in] net_type The network type which the client prefer
 226  * @return 0 on success, otherwise a negative error value.
 227  * @retval #DOWNLOAD_ERROR_NONE Successful
 228  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 229  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 230  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 231  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
 232  * @see download_get_network_type()
 233  * @see #download_network_type_e
 234  */
 235 int download_set_network_type(int download_id, download_network_type_e net_type);
 236
 237
 238 /**
 239  * @brief Gets the network type for the downloaded file
 240  *
 241  * @param [in] download The download id
 242  * @param [out] net_type The network type which is defined by client.
 243  * @return 0 on success, otherwise a negative error value.
 244  * @retval #DOWNLOAD_ERROR_NONE Successful
 245  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 246  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 247  * @see download_set_network_type()
 248  * @see #download_network_type_e
 249  */
 250 int download_get_network_type(int download_id, download_network_type_e *net_type);
 251
 252
 253 /**
 254  * @brief Sets the destination for the downloaded file.
 255  *
 256  * @details The file will be downloaded to the specified destination.
 257  * The downloaded file is saved to an auto-generated file name in the destination.
 258  * If the destination is not specified, the file will be downloaded to default storage. (See the @ref CAPI_STORAGE_MODULE API)
 259  *
 260  * @remarks This function should be called before downloading (see download_start())
 261  * @param [in] download The download id
 262  * @param [in] path The absolute path to the downloaded file
 263  *  If the @a path is NULL, it clears the previous value.
 264  * @return 0 on success, otherwise a negative error value.
 265  * @retval #DOWNLOAD_ERROR_NONE Successful
 266  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 267  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 268  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 269  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 270  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
 271  * @see download_get_destination()
 272  */
 273 int download_set_destination(int download_id, const char *path);
 274
 275
 276 /**
 277  * @brief Gets the destination for the downloaded file.
 278  *
 279  * @remarks The @a path must be released with free() by you.
 280  * @param [in] download The download id
 281  * @param [out] path The absolute path to the downloaded file
 282  * @return 0 on success, otherwise a negative error value.
 283  * @retval #DOWNLOAD_ERROR_NONE Successful
 284  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 285  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 286  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 287  * @see download_set_destination()
 288  */
 289 int download_get_destination(int download_id, char **path);
 290
 291
 292 /**
 293  * @brief Sets the name for the downloaded file.
 294  *
 295  * @details The file will be downloaded to the specified destination as the given file name.
 296  * If the file name is not specified, the downloaded file is saved to an auto-generated file name in the destination.
 297  *
 298  * @remarks This function should be called before downloading (see download_start())
 299  * @param [in] download The download id
 300  * @param [in] file_name The file name for the downloaded file
 301  *  If the @a name is NULL, it clears the previous value.
 302  * @return 0 on success, otherwise a negative error value.
 303  * @retval #DOWNLOAD_ERROR_NONE Successful
 304  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 305  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 306  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 307  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 308  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
 309  * @see download_get_file_name()
 310  */
 311 int download_set_file_name(int download_id, const char *file_name);
 312
 313
 314 /**
 315  * @brief Gets the name which is set by user.
 316  *
 317  * @details If user do not set any name, it returns NULL.
 318  *
 319  * @remarks The @a file_name must be released with free() by you.
 320  * @param [in] download The download id
 321  * @param [out] file_name The file name which is set by user.
 322  * @return 0 on success, otherwise a negative error value.
 323  * @retval #DOWNLOAD_ERROR_NONE Successful
 324  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 325  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 326  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 327  * @see download_set_file_name()
 328  */
 329 int download_get_file_name(int download_id, char **file_name);
 330
 331
 332 /**
 333  * @brief Sets the option value to register notification messages by download service module.
 334  * @details The three types of notification message can be posted. Those are completion, failed and ongoing type.
 335  * When the notification message of failed and ongoing types from the notification tray, \n
 336  * the client application which call this API will be launched. \n
 337  *
 338  * @remarks The extra param should be set together (See download_set_notification_extra_param()). \n
 339  * The downloading and failed notification can be registered only if the extra param for notification message is set. \n
 340  * If it is not, the client application can not know who request to launch itself. \n
 341  * It should be necessary to understand the action operation of notification click event.
 342  * @remarks If the competition notification message is selected from the notification tray,\n
 343  * the proper player application is launched automatically.
 344  * @remarks The default value is false. So if the client don't enable it, any notification messages are not registered.
 345  * @remarks This function should be called before downloading (See download_start())
 346  * @param[in] download The download id
 347  * @param[in] enable The boolean type. The true or false value is available.
 348  * @return 0 on success, otherwise a negative error value.
 349  * @retval #DOWNLOAD_ERROR_NONE Successful
 350  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 351  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 352  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
 353  * @see download_get_notification()
 354  * @see service_get_operation()
 355  * @deprecated This API can be replaced with download_set_notification_type()
 356  @code
 357  int ret = 0;
 358  //ret = download_set_notification(id, true);
 359  ret = download_set_notificationo_type(id, DOWNLOAD_NOTIFICATION_TYPE_ALL);
 360  //ret = download_set_notification(id, false);
 361  ret = download_set_notificationo_type(id, DOWNLOAD_NOTIFICATION_TYPE_NONE);
 362  @endcode
 363  */
 364 DEPRECATED int download_set_notification(int download_id, bool enable);
 365
 366 /**
 367  * @brief Gets the option value to register notification messages by download service module.
 368  * @param[in] download The download id
 369  * @param[out] enable The boolean type. The true or false value is returned
 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_set_notification()
 375  * @deprecated This API can be replaced with download_get_notification_type()
 376  @code
 377  int ret = 0;
 378  bool val = 0;
 379  download_notification_type_e type;
 380  //ret = download_get_notification(id, &val);
 381  ret = download_get_notification_type(id, &type);
 382  @endcode
 383  */
 384 DEPRECATED int download_get_notification(int download_id, bool *enable);
 385
 386 /**
 387  * @brief Sets the extra param data which pass by application service data when notification message is clicked
 388  * @details When client set the extra param data for ongoing notification action, \n
 389  * it can get the data through service_get_extra_data() when client application is launched by notification action.
 390  *
 391  * @remarks This function should be called before downloading (See download_start())
 392  *
 393  * @param[in] download The download id
 394  * @param[in] key The character pointer type. The extra param has a pair of key and value
 395  * @param[in] values The character pointer array type. The extra param has a pair of key and value array
 396  * @param[in] length The length of value array
 397  * @return 0 on success, otherwise a negative error value.
 398  * @retval #DOWNLOAD_ERROR_NONE Successful
 399  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 400  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 401  * @see download_get_notification_extra_param()
 402  * @see download_remove_notification_extra_param()
 403  * @deprecated This API can be replaced with download_set_notification_bundle()
 404  @code
 405  #include <bundle.h>
 406  int ret = 0;
 407  //ret = download_add_notification_extra_param(id, "specific_id", "12345");
 408  b = bundle_create();
 409  char buff[MAX_BUF_LEN] = {0,};
 410  appsvc_set_pkgname(b, "com.samsung.test-app");
 411  appsvc_add_data(b, "specific_id", "12345");
 412  ret = download_set_notification_bundle(id, DOWNLOAD_NOTIFICATION_BUNDLE_TYPE_ALL, b);
 413  bundle_free(b);
 414  @endcode
 415  */
 416 DEPRECATED int download_add_notification_extra_param(int download_id, const char *key, const char **values, const unsigned int length);
 417
 418 /**
 419  * @brief Remove the extra param data which pass by application service data when notification message is clicked
 420  *
 421  * @remarks This function should be called before downloading (See download_start())
 422  *
 423  * @param[in] download The download id
 424  * @param[in] key The character pointer type. The extra param has a pair of key and value
 425  * @return 0 on success, otherwise a negative error value.
 426  * @retval #DOWNLOAD_ERROR_NONE Successful
 427  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 428  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 429  * @see download_add_notification_extra_param()
 430  * @see download_get_notification_extra_param()
 431  */
 432 DEPRECATED int download_remove_notification_extra_param(int download_id, const char *key);
 433
 434 /**
 435  * @brief Gets the extra param value to set by download_set_notification_extra_param
 436  * @param[in] download The download id
 437  * @param[out] key The character pointer type. The extra param has a pair of key and value
 438  * @param[out] values param The character pointer array type. The extra param has a pair of key and value array
 439  * @param[out] length The length of value array
 440  * @return 0 on success, otherwise a negative error value.
 441  * @retval #DOWNLOAD_ERROR_NONE Successful
 442  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 443  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 444  * @see download_set_notification_extra_param()
 445  */
 446 int download_get_notification_extra_param(int download_id, const char *key, char ***values, unsigned int *length);
 447
 448 /**
 449  * @brief Gets the absolute path to save the downloaded file
 450  *
 451  * @remarks This function returns #DOWNLOAD_ERROR_INVALID_STATE if the download is not completed. \n
 452  * The @a path must be released with free() by you.
 453  * @param [in] download The download id
 454  * @param [out] path The absolute path to the downloaded file
 455  * @return 0 on success, otherwise a negative error value.
 456  * @retval #DOWNLOAD_ERROR_NONE Successful
 457  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 458  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 459  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 460  * @pre The download state must be #DOWNLOAD_STATE_COMPLETED.
 461  * @see download_set_file_name()
 462  * @see download_set_destination()
 463  */
 464 int download_get_downloaded_file_path(int download_id, char **path);
 465
 466
 467 /**
 468  * @brief Gets the mime type for downloading a content.
 469  *
 470  * @remarks This function returns #DOWNLOAD_ERROR_INVALID_STATE if the download has not been started. \n
 471  * The @a mime_type must be released with free() by you.
 472  * @param [in] download The download id
 473  * @param [out] mime_type The MIME type of the downloaded file
 474  * @return 0 on success, otherwise a negative error value.
 475  * @retval #DOWNLOAD_ERROR_NONE Successful
 476  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 477  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 478  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 479  * @see download_set_file_name()
 480  * @see download_set_destination()
 481  * @see download_get_downloaded_file_path()
 482  */
 483 int download_get_mime_type(int download_id, char **mime_type);
 484
 485
 486 /**
 487  * @brief Sets the option for auto download.
 488  * @details If this option is enabled, \n
 489  *  the previous downloading item is restarted automatically as soon as the download daemon is restarted. \n
 490  * And the download progress keep going after the client process is terminated.  \n
 491  * @remarks The client should call download_set_notification() and download_set_notification_extra_param() after call this API. \n
 492  *  If it is not, user do not receive the download result in case the client process is not alive.
 493  * @remarks The default value is false.
 494  * @param[in] download The download id
 495  * @param[in] enable The boolean value for auto download which is defined by client.
 496  * @return 0 on success, otherwise a negative error value.
 497  * @retval #DOWNLOAD_ERROR_NONE Successful
 498  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 499  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 500  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
 501  * @see download_get_auto_download()
 502  * @see download_set_notification()
 503  * @see download_set_notification_extra_param()
 504  *
 505  */
 506 int download_set_auto_download(int download_id, bool enable);
 507
 508
 509 /**
 510  * @brief Gets the value of option for auto download.
 511  *
 512  * @param [in] download The download id
 513  * @param [out] enable The boolean value for auto download which is defined by client.
 514  * @return 0 on success, otherwise a negative error value.
 515  * @retval #DOWNLOAD_ERROR_NONE Successful
 516  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 517  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 518  * @see download_set_auto_download()
 519  */
 520 int download_get_auto_download(int download_id, bool *enable);
 521
 522
 523 /**
 524  * @brief Adds an HTTP header field to the download request
 525  *
 526  * @details The given HTTP header field will be included with the HTTP request of the download request. \n
 527  * Refer to the <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec4.html#sec4.2">HTTP/1.1: HTTP Message Headers</a>
 528  * @remarks This function should be called before downloading (see download_start()) \n
 529  * This function replaces any existing value for the given key. \n
 530  * This function returns #DOWNLOAD_ERROR_INVALID_PARAMETER if field or value is zero-length string.
 531  * @param [in] download The download id
 532  * @param [in] field The name of the HTTP header field
 533  * @param [in] value The value associated with given field
 534  * @return 0 on success, otherwise a negative error value.
 535  * @retval #DOWNLOAD_ERROR_NONE Successful
 536  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 537  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 538  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 539  * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
 540  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 541  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
 542  * @see download_get_http_header_field()
 543  * @see download_remove_http_header_field()
 544  */
 545 int download_add_http_header_field(int download_id, const char *field, const char *value);
 546
 547
 548 /**
 549  * @brief Gets the value associated with given HTTP header field from the download
 550  *
 551  * @remarks This function returns #DOWNLOAD_ERROR_INVALID_PARAMETER if field is zero-length string. \n
 552  * The @a value must be released with free() by you.
 553  * @param [in] download The download id
 554  * @param [in] field The name of the HTTP header field
 555  * @param [out] value The value associated with given field
 556  * @return 0 on success, otherwise a negative error value.
 557  * @retval #DOWNLOAD_ERROR_NONE Successful
 558  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 559  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 560  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 561  * @retval #DOWNLOAD_ERROR_FIELD_NOT_FOUND Specified field not found
 562  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 563  * @see download_add_http_header_field()
 564  * @see download_remove_http_header_field()
 565  */
 566 int download_get_http_header_field(int download_id, const char *field, char **value);
 567
 568 /**
 569  * @brief Gets all of the field added to the download request
 570  *
 571  * @remarks The @a value must be released with free() by you.
 572  * @param [in] download The download id
 573  * @param [out] the array of the HTTP header fields
 574  * @param [out] the number of the HTTP header fields
 575  * @return 0 on success, otherwise a negative error value.
 576  * @retval #DOWNLOAD_ERROR_NONE Successful
 577  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 578  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 579  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 580  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 581  * @see download_add_http_header_field()
 582  * @see download_remove_http_header_field()
 583  */
 584 int download_get_http_header_field_list(int download_id, char ***fields, int *length);
 585
 586 /**
 587  * @brief Removes the given HTTP header field from the download
 588  *
 589  * @remarks This function should be called before downloading (see download_start()) \n
 590  * This function returns #DOWNLOAD_ERROR_INVALID_PARAMETER if field is zero-length string.
 591  * @param [in] download The download id
 592  * @param [in] field The name of the HTTP header field
 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_OUT_OF_MEMORY Out of memory
 597  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 598  * @retval #DOWNLOAD_ERROR_FIELD_NOT_FOUND Specified field not found
 599  * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
 600  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 601  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
 602  * @see download_add_http_header_field()
 603  * @see download_get_http_header_field()
 604  */
 605 int download_remove_http_header_field(int download_id, const char *field);
 606
 607
 608 /**
 609  * @brief Registers a callback function to be invoked when the download state is changed.
 610  *
 611  * @remarks This function should be called before downloading (see download_start())
 612  * @param [in] download The download id
 613  * @param [in] callback The callback function to register
 614  * @param [in] user_data The user data to be passed to the callback function
 615  * @return 0 on success, otherwise a negative error value.
 616  * @retval #DOWNLOAD_ERROR_NONE Successful
 617  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 618  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 619  * @post download_state_changed_cb() will be invoked.
 620  * @see download_unset_state_changed_cb()
 621  * @see download_state_changed_cb()
 622 */
 623 int download_set_state_changed_cb(int download_id, download_state_changed_cb callback, void* user_data);
 624
 625
 626 /**
 627  * @brief Unregisters the callback function.
 628  *
 629  * @remarks This function should be called before downloading (see download_start())
 630  * @param [in] download The download id
 631  * @return 0 on success, otherwise a negative error value.
 632  * @retval #DOWNLOAD_ERROR_NONE Successful
 633  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 634  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 635  * @see download_set_state_changed_cb()
 636  * @see download_state_changed_cb()
 637 */
 638 int download_unset_state_changed_cb(int download_id);
 639
 640
 641 /**
 642  * @brief Registers a callback function to be invoked when progress of the download changes
 643  *
 644  * @remarks This function should be called before downloading (see download_start())
 645  * @param [in] download The download id
 646  * @param [in] callback The callback function to register
 647  * @param [in] user_data The user data to be passed to the callback function
 648  * @return 0 on success, otherwise a negative error value.
 649  * @retval #DOWNLOAD_ERROR_NONE Successful
 650  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 651  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 652  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 653  * @post download_progress_cb() will be invoked.
 654  * @see download_unset_progress_cb()
 655  * @see download_progress_cb()
 656 */
 657 int download_set_progress_cb(int download_id, download_progress_cb callback, void *user_data);
 658
 659
 660 /**
 661  * @brief Unregisters the callback function.
 662  *
 663  * @remarks This function should be called before downloading (see download_start())
 664  * @param [in] download The download id
 665  * @return 0 on success, otherwise a negative error value.
 666  * @retval #DOWNLOAD_ERROR_NONE Successful
 667  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 668  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 669  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 670  * @see download_set_progress_cb()
 671  * @see download_progress_cb()
 672 */
 673 int download_unset_progress_cb(int download_id);
 674
 675
 676 /**
 677  * @brief Starts or resumes the download, asynchronously.
 678  *
 679  * @details This function starts to download the current URL, or resumes the download if paused.
 680  *
 681  * @remarks The URL is the mandatory information to start the download.
 682  * @remarks It should call download_set_progress_cb() and download_set_state_changed_cb() again \n
 683  *  after the client process is restarted or download_destry() is called
 684  * @param [in] download The download id
 685  * @return 0 on success, otherwise a negative error value.
 686  * @retval #DOWNLOAD_ERROR_NONE Successful
 687  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 688  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 689  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 690  * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
 691  * @retval #DOWNLOAD_ERROR_URL Invalid URL
 692  * @retval #DOWNLOAD_ERROR_DESTINATION Invalid destination
 693  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 694  * @retval #DOWNLOAD_ERROR_QUEUE_FULL Full of queue from download server
 695  * @pre The download state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_PAUSED, #DOWNLOAD_STATE_CANCELED, #DOWNLOAD_STATE_FAILED.
 696  * @post The download state will be #DOWNLOAD_STATE_QUEUED or #DOWNLOAD_STATE_DOWNLOADING
 697  * @see download_set_url()
 698  * @see download_pause()
 699  * @see download_cancel()
 700  */
 701 int download_start(int download_id);
 702
 703
 704 /**
 705  * @brief Pauses the download, asynchronously.
 706  *
 707  * @remarks The paused download can be restarted with download_start() or canceled with download_cancel()
 708  * @param [in] download The download id
 709  * @return 0 on success, otherwise a negative error value.
 710  * @retval #DOWNLOAD_ERROR_NONE Successful
 711  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 712  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 713  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 714  * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
 715  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 716  * @pre The download state must be #DOWNLOAD_STATE_DOWNLOADING.
 717  * @post The download state will be #DOWNLOAD_STATE_PAUSED.
 718  * @see download_start()
 719  * @see download_cancel()
 720  */
 721 int download_pause(int download_id);
 722
 723
 724 /**
 725  * @brief Cancel the download, asynchronously.
 726  *
 727  * @details This function cancels the running download and its state will be #DOWNLOAD_STATE_READY
 728  * @remarks The canceled download can be restarted with download_start().
 729  * @param [in] download The download id
 730  * @return 0 on success, otherwise a negative error value.
 731  * @retval #DOWNLOAD_ERROR_NONE Successful
 732  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 733  * @retval #DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory
 734  * @retval #DOWNLOAD_ERROR_INVALID_STATE Invalid state
 735  * @retval #DOWNLOAD_ERROR_IO_ERROR Internal I/O error
 736  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 737  * @pre The download state must be #DOWNLOAD_STATE_QUEUED, #DOWNLOAD_STATE_DOWNLOADING, #DOWNLOAD_STATE_PAUSED.
 738  * @post The download state will be #DOWNLOAD_STATE_CANCELED.
 739  * @see download_start()
 740  */
 741 int download_cancel(int download_id);
 742
 743
 744 /**
 745  * @brief Gets the download's current state.
 746  *
 747  * @param [in] download The download id
 748  * @param [out] state The current state of the download
 749  * @return 0 on success, otherwise a negative error value.
 750  * @retval #DOWNLOAD_ERROR_NONE Successful
 751  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 752  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 753  * @see #download_state_e
 754  */
 755 int download_get_state(int download_id, download_state_e *state);
 756
 757
 758 /**
 759  * @brief Gets the full path of temporary file for downloading a content.
 760  *
 761  * @param [in] download The download id
 762  * @param [out] temp_path The full path of temporary file
 763  * @return 0 on success, otherwise a negative error value.
 764  * @retval #DOWNLOAD_ERROR_NONE Successful
 765  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 766  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 767  * @pre The download state must be one of state after #DOWNLOAD_STATE_DOWNLOADING.
 768  * @see #download_set_state_changed_cb()
 769  * @see #download_unset_state_changed_cb()
 770  * @see download_start()
 771  */
 772 int download_get_temp_path(int download_id, char **temp_path);
 773
 774
 775 /**
 776  * @brief Gets the content name for downloading a file.
 777  *
 778  * @details This can be defined with reference of HTTP response header data.
 779  * The content name can be received when HTTP response header is received.
 780  *
 781  * @param [in] download The download id
 782  * @param [out] content_name The content name for displaying to user
 783  * @return 0 on success, otherwise a negative error value.
 784  * @retval #DOWNLOAD_ERROR_NONE Successful
 785  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 786  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 787  * @pre The download state must be one of state after #DOWNLOAD_STATE_DOWNLOADING.
 788  * @see #download_set_state_changed_cb()
 789  * @see #download_unset_state_changed_cb()
 790  * @see download_start()
 791  */
 792 int download_get_content_name(int download_id, char **content_name);
 793
 794
 795 /**
 796  * @brief Gets the total size for downloading a content.
 797  *
 798  * @details This data receive from content server. If the content sever don't send total size of the content, the value set as zero.
 799  *
 800  * @param [in] download The download id
 801  * @param [out] content_size The content size for displaying to user
 802  * @return 0 on success, otherwise a negative error value.
 803  * @retval #DOWNLOAD_ERROR_NONE Successful
 804  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 805  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 806  * @pre The download state must be one of state after #DOWNLOAD_STATE_DOWNLOADING.
 807  * @see #download_set_state_changed_cb()
 808  * @see #download_unset_state_changed_cb()
 809  * @see download_start()
 810  */
 811 int download_get_content_size(int download_id, unsigned long long *content_size);
 812
 813
 814 /**
 815  * @brief Gets the error value when the download is failed.
 816  *
 817  * @param [in] download The download id
 818  * @param [out] error The error value
 819  * @return 0 on success, otherwise a negative error value.
 820  * @retval #DOWNLOAD_ERROR_NONE Successful
 821  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 822  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 823  * @pre The download state must be #DOWNLOAD_STATE_FAILED.
 824  * @pre The download state must be #DOWNLOAD_STATE_CANCELED.
 825  * @see #download_set_state_changed_cb()
 826  * @see #download_unset_state_changed_cb()
 827  * @see download_start()
 828  * @see download_error_e
 829  */
 830 int download_get_error(int download_id, download_error_e *error);
 831
 832
 833 /**
 834  * @brief Gets the http status code when the download error is happened.
 835  *
 836  * @param [in] download The download id
 837  * @param [out] http_status The http status code which is defined in RFC 2616
 838  * @return 0 on success, otherwise a negative error value.
 839  * @retval #DOWNLOAD_ERROR_NONE Successful
 840  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 841  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 842  * @pre The download state must be #DOWNLOAD_STATE_FAILED.
 843  * @see #download_set_download_status_cb()
 844  * @see #download_unset_download_status_cb()
 845  * @see download_start()
 846  */
 847 int download_get_http_status(int download_id, int *http_status);
 848
 849 /**
 850  * @brief Sets bundle data to register notification messages.
 851  * @details The three types of notification message can be posted. Those are completion, failed and ongoing type.
 852  *
 853  * @remarks When the notification message is clicked, the action is decided by bundle data. \n
 854  * If the bundle data is not set, the following default operation is executed when the notification message is clicked. \n
 855  * 1) Download completed state : The viewer application is executed according to extension name of downloaded content. \n
 856  * 2) Download failed state and ongoing state : The client application is executed. \n
 857  * @remarks This function should be called before starting download.
 858  * @remarks The bundle data MUST BE FREED by client when it is not used any more.
 859  * @param[in] download The download id
 860  * @param[in] type The enumeration type. See #download_notification_bundle_type_e.
 861  * @param[in] bundle The bundle pointer value.
 862  * @return 0 on success, otherwise a negative error value.
 863  * @retval #DOWNLOAD_ERROR_NONE Successful
 864  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 865  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 866  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
 867  * @see download_set_notification_type()
 868  * @see download_get_notification_bundle()
 869  */
 870 int download_set_notification_bundle(int download_id, download_notification_bundle_type_e type, bundle *b);
 871
 872 /**
 873  * @brief Get the bundle data to register notification messages which is set in download_set_notification_bundle().
 874  *
 875  * @details When the notification message is clicked, the action is decided by bundle data. \n
 876  * @param[in] download The download id
 877  * @param[in] type The enumeration type. See #download_notification_bundle_type_e.
 878  * @param[out] bundle The bundle pointer value.
 879  * @remarks The bundle data MUST BE FREED by client when it is not used any more.
 880  * @return 0 on success, otherwise a negative error value.
 881  * @retval #DOWNLOAD_ERROR_NONE Successful
 882  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 883  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 884  * @retval #DOWNLOAD_ERROR_NO_DATA the bundle have not been set
 885  * @see download_set_notification_bundle()
 886  */
 887 int download_get_notification_bundle(int download_id, download_notification_bundle_type_e type, bundle **b);
 888
 889 /**
 890  * @brief Set the title of notification.
 891  *
 892  * @details When registering notification, the title is displayed at title area of notification message
 893  *
 894  * @param [in] download The download id
 895  * @param [in] title The title for displaying to user
 896  * @return 0 on success, otherwise a negative error value.
 897  * @retval #DOWNLOAD_ERROR_NONE Successful
 898  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 899  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 900  * @pre If the notification option is not enable, this title is not shown to user
 901  * @see #download_set_notification_type()
 902  * @see #download_get_notification_title()
 903   */
 904 int download_set_notification_title(int download_id, const char *title);
 905
 906 /**
 907  * @brief Gets the title of notification when set in #download_set_notification_title()
 908  *
 909  * @details When registering notification, the title is displayed at title area of notification message
 910  *
 911  * @param [in] download The download id
 912  * @param [out] title The title for displaying to user
 913  * @return 0 on success, otherwise a negative error value.
 914  * @retval #DOWNLOAD_ERROR_NONE Successful
 915  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 916  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 917  * @retval #DOWNLOAD_ERROR_NO_DATA the title have not been set
 918  * @pre It can get the title value before calling this API.
 919  * @see #download_set_notification_title()
 920   */
 921 int download_get_notification_title(int download_id, char **title);
 922
 923 /**
 924  * @brief Set the description of notification.
 925  *
 926  * @details When registering notification, the description is displayed at description area of notification message
 927  *
 928  * @param [in] download The download id
 929  * @param [in] description The description for displaying to user
 930  * @return 0 on success, otherwise a negative error value.
 931  * @retval #DOWNLOAD_ERROR_NONE Successful
 932  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 933  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 934  * @pre If the notification option is not enable, this description is not shown to user
 935  * @see #download_set_notification_type()
 936  * @see #download_get_notification_description()
 937   */
 938 int download_set_notification_description(int download_id, const char *description);
 939
 940 /**
 941  * @brief Gets the description of notification when set in #download_set_notification_description()
 942  *
 943  * @details When registering notification, the description is displayed at description area of notification message
 944  *
 945  * @param [in] download The download id
 946  * @param [out] description The description for displaying to user
 947  * @return 0 on success, otherwise a negative error value.
 948  * @retval #DOWNLOAD_ERROR_NONE Successful
 949  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 950  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 951  * @retval #DOWNLOAD_ERROR_NO_DATA the description have not been set
 952  * @pre It can get the title value before calling this API.
 953  * @see #download_set_notification_description()
 954   */
 955 int download_get_notification_description(int download_id, char **description);
 956
 957 /**
 958  * @brief Sets the option value to register notification messages.
 959  * @details The three types of notification message can be posted. Those are completion, failed and ongoing type.
 960  *
 961  * @remarks When the notification message is clicked, the action is decided by bundle data from download_set_notification_bundle(). \n
 962  * If the bundle data is not set, the following default operation is executed when the notification message is clicked. \n
 963  * 1) Download completed state : The viewer application is executed according to extension name of downloaded content. \n
 964  * 2) Download failed state and ongoing state : The client application is executed. \n
 965  * @remarks The default type is #DOWNLOAD_NOTIFICATION_TYPE_NONE.
 966  * @remarks This function should be called before starting download.
 967  * @param[in] download The download id
 968  * @param[in] type The enumeration type. See #download_notification_type_e.
 969  * @return 0 on success, otherwise a negative error value.
 970  * @retval #DOWNLOAD_ERROR_NONE Successful
 971  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 972  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 973  * @pre The state must be #DOWNLOAD_STATE_READY, #DOWNLOAD_STATE_FAILED, #DOWNLOAD_STATE_CANCELED
 974  * @see download_set_notification_bundle()
 975  * @see download_get_notification_type()
 976  */
 977 int download_set_notification_type(int download_id, download_notification_type_e type);
 978
 979 /**
 980  * @brief Get the option value to register notification messages which is set in download_set_notification_type().
 981  *
 982  * @remarks When the notification message is clicked, the action is decided by bundle data from download_set_notification_bundle(). \n
 983  * @remarks The default type is #DOWNLOAD_NOTIFICATION_TYPE_NONE.
 984  * @param[in] download The download id
 985  * @param[out] type The enumeration type. See #download_notification_type_e.
 986  * @return 0 on success, otherwise a negative error value.
 987  * @retval #DOWNLOAD_ERROR_NONE Successful
 988  * @retval #DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter
 989  * @retval #DOWNLOAD_ERROR_ID_NOT_FOUND No Download ID
 990  * @see download_set_notification_type()
 991  */
 992 int download_get_notification_type(int download_id, download_notification_type_e *type);
 993
 994 /**
 995  * @}
 996  */
 997
 998 #ifdef __cplusplus
 999 }
1000 #endif
1001
1002 #endif /* __TIZEN_WEB_DOWNLOAD_H__ */