Tizen Native API
5.5
|
The DOWNLOAD API provides functions to create and manage one or more download requests.
Required Header
#include <download.h>
Overview
The DOWNLOAD API provides functions to create and manage one or more download requests.
Major features :
- After getting download_id from download_create(), other APIs use download_id as parameter.
- Even if the device is off, download_id is available for 48 hours if the user does not call download_destroy().
- Supports the callback that is called whenever the status of download changes.
- Even if the client process is terminated, download is going on. If you want to stop a download, download_cancel() or download_destroy() should be called.
Related Features
This API is related with the following features:
- http://tizen.org/feature/download
- http://tizen.org/feature/network.telephony
- http://tizen.org/feature/network.wifi
- http://tizen.org/feature/network.wifi.direct
It is recommended to design feature related codes in your application for reliability.
You can check if a device supports the related features for this API by using System Information, thereby controlling the procedure of your application.
To ensure your application is only running on the device with specific features, please define the features in your manifest file using the manifest editor in the SDK.
More details on featuring your application can be found from Feature Element.
Functions | |
int | download_create (int *download_id) |
Creates a new download request and return its download ID. | |
int | download_destroy (int download_id) |
Unloads all data concerning a download ID from memory. | |
int | download_set_url (int download_id, const char *url) |
Sets the URL to download. | |
int | download_get_url (int download_id, char **url) |
Gets the URL to download. | |
int | download_set_network_type (int download_id, download_network_type_e net_type) |
Sets the allowed network type for the downloaded file. | |
int | download_get_network_type (int download_id, download_network_type_e *net_type) |
Gets the network type for the downloaded file. | |
int | download_set_destination (int download_id, const char *path) |
Sets the destination for the downloaded file. | |
int | download_get_destination (int download_id, char **path) |
Gets the destination path for the downloaded file. | |
int | download_set_file_name (int download_id, const char *file_name) |
Sets the name for the downloaded file. | |
int | download_get_file_name (int download_id, char **file_name) |
Gets the name of the downloaded file set previously by download_set_file_name(). | |
int | download_get_downloaded_file_path (int download_id, char **path) |
Gets the absolute path to save the downloaded file. | |
int | download_get_mime_type (int download_id, char **mime_type) |
Gets the MIME type of the downloaded content. | |
int | download_set_auto_download (int download_id, bool enable) |
Enables or disables auto download. | |
int | download_get_auto_download (int download_id, bool *enable) |
Checks whether auto download is enabled. | |
int | download_add_http_header_field (int download_id, const char *field, const char *value) |
Adds a HTTP header field to the download request. | |
int | download_get_http_header_field (int download_id, const char *field, char **value) |
Gets a value associated with a given HTTP header field from the download. | |
int | download_get_http_header_field_list (int download_id, char ***fields, int *length) |
Gets all the HTTP header fields added to the download request. | |
int | download_remove_http_header_field (int download_id, const char *field) |
Removes a given HTTP header field from the download. | |
int | download_set_state_changed_cb (int download_id, download_state_changed_cb callback, void *user_data) |
Registers a callback function to be invoked when a download state is changed. | |
int | download_unset_state_changed_cb (int download_id) |
Unregisters the download state change callback function. | |
int | download_set_progress_cb (int download_id, download_progress_cb callback, void *user_data) |
Registers a callback function to be invoked when progress of the download changes. | |
int | download_unset_progress_cb (int download_id) |
Unregisters the download progress change callback function. | |
int | download_start (int download_id) |
Starts or resumes the download, asynchronously. | |
int | download_pause (int download_id) |
Pauses the download, asynchronously. | |
int | download_cancel (int download_id) |
Cancels the download, asynchronously. | |
int | download_get_state (int download_id, download_state_e *state) |
Gets the current state of the download. | |
int | download_get_temp_path (int download_id, char **temp_path) |
Gets the full path of the temporary file to store downloaded content. | |
int | download_set_temp_file_path (int download_id, char *path) |
Sets the directory path of the temporary file used in the previous download request. | |
int | download_get_content_name (int download_id, char **content_name) |
Gets the content name of downloaded file. | |
int | download_get_content_size (int download_id, unsigned long long *content_size) |
Gets the total size of downloaded content. | |
int | download_get_error (int download_id, download_error_e *error) |
Gets an error value when the download fails. | |
int | download_get_http_status (int download_id, int *HTTP_status) |
Gets a HTTP status code when a download error occurs. | |
int | download_set_notification_app_control (int download_id, download_notification_app_control_type_e type, app_control_h handle) |
Sets an app control handle to register notification messages. | |
int | download_get_notification_app_control (int download_id, download_notification_app_control_type_e type, app_control_h *handle) |
Gets the app control handle (used previously to register notification messages) which is set by download_set_notification_app_control(). | |
int | download_set_notification_title (int download_id, const char *title) |
Sets the title of a notification. | |
int | download_get_notification_title (int download_id, char **title) |
Gets the title of the notification set by download_set_notification_title(). | |
int | download_set_notification_description (int download_id, const char *description) |
Sets the description of a notification. | |
int | download_get_notification_description (int download_id, char **description) |
Gets the description of a notification set by download_set_notification_description(). | |
int | download_set_notification_type (int download_id, download_notification_type_e type) |
Sets an option value to register notification messages. | |
int | download_get_notification_type (int download_id, download_notification_type_e *type) |
Gets an option value to register notification messages set by download_set_notification_type(). | |
int | download_get_etag (int download_id, char **etag) |
Gets an etag value from the HTTP response header when making a HTTP request for resume. | |
Typedefs | |
typedef void(* | download_state_changed_cb )(int download_id, download_state_e state, void *user_data) |
Called when a download state is changed. | |
typedef void(* | download_progress_cb )(int download_id, unsigned long long received, void *user_data) |
Called when the progress of download changes. |
Typedef Documentation
typedef void(* download_progress_cb)(int download_id, unsigned long long received, void *user_data) |
Called when the progress of download changes.
- Since :
- 2.3
- Remarks:
- This callback function is only invoked in the downloading state.
- Parameters:
-
[in] download_id The download ID [in] received The size of the data received in bytes [in] user_data The user data passed from download_set_progress_cb()
- Precondition:
- This callback function is invoked if you register this callback using download_set_progress_cb().
typedef void(* download_state_changed_cb)(int download_id, download_state_e state, void *user_data) |
Called when a download state is changed.
- Since :
- 2.3
- Parameters:
-
[in] download_id The download ID [in] state The state of download [in] user_data The user data passed from download_set_state_changed_cb()
- Precondition:
- download_start() will invoke this callback if you register this callback using download_set_state_changed_cb().
Enumeration Type Documentation
enum download_error_e |
Enumeration for error codes of URL download.
- Since :
- 2.3
- Enumerator:
Enumeration for network type for downloading.
- Since :
- 2.3
Enumeration for the type of notification app control action which the client wants to set when registering notification.
- Since :
- 2.3
Enumeration for notification types when a client wants to register.
- Since :
- 2.3
enum download_state_e |
Enumeration for download states.
- Since :
- 2.3
- Enumerator:
Function Documentation
int download_add_http_header_field | ( | int | download_id, |
const char * | field, | ||
const char * | value | ||
) |
Adds a HTTP header field to the download request.
The given HTTP header field will be included with the HTTP request of the download request. For more information, see HTTP/1.1: HTTP Message Headers.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function should be called before downloading (see download_start()). This function replaces any existing value for the given key. This function returns DOWNLOAD_ERROR_INVALID_PARAMETER if field or value is a zero-length string.
- Parameters:
-
[in] download_id The download ID [in] field The name of the HTTP header field [in] value The value associated with given field
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_IO_ERROR Internal I/O error DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state must be DOWNLOAD_STATE_READY, DOWNLOAD_STATE_FAILED, or DOWNLOAD_STATE_CANCELED.
int download_cancel | ( | int | download_id | ) |
Cancels the download, asynchronously.
This function cancels the running download and its state will be DOWNLOAD_STATE_READY.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- The canceled download can be restarted with download_start().
- Parameters:
-
[in] download_id The download ID
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_IO_ERROR Internal I/O error DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The download state must be DOWNLOAD_STATE_QUEUED, DOWNLOAD_STATE_DOWNLOADING, or DOWNLOAD_STATE_PAUSED.
- Postcondition:
- The download state will be DOWNLOAD_STATE_CANCELED.
- See also:
- download_start()
int download_create | ( | int * | download_id | ) |
Creates a new download request and return its download ID.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- The download_id is released with download_destroy() by client.
- Parameters:
-
[out] download_id The download ID that is newly created on success
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_IO_ERROR Internal I/O error DOWNLOAD_ERROR_QUEUE_FULL Download server queue is full DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Postcondition:
- The download state will be DOWNLOAD_STATE_READY.
- See also:
- download_destroy()
int download_destroy | ( | int | download_id | ) |
Unloads all data concerning a download ID from memory.
After calling this API, a download ID is existed at DB in certain time. Within that time, it is able to use the other API with the download ID.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- If DOWNLOAD_ERROR_ID_NOT_FOUND is returned, it means that the download ID is completely removed from DB.
- Parameters:
-
[in] download_id The download ID
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- See also:
- download_create()
int download_get_auto_download | ( | int | download_id, |
bool * | enable | ||
) |
Checks whether auto download is enabled.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Parameters:
-
[in] download_id The download ID [out] enable true
if auto download is enabled, otherwisefalse
if auto download is disabled
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- See also:
- download_set_auto_download()
int download_get_content_name | ( | int | download_id, |
char ** | content_name | ||
) |
Gets the content name of downloaded file.
This can be defined with reference of HTTP response header data. The content name can be received when HTTP response header is received.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Parameters:
-
[in] download_id The download ID [out] content_name The content name for displaying to user
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The download state must be one of the states after DOWNLOAD_STATE_DOWNLOADING.
int download_get_content_size | ( | int | download_id, |
unsigned long long * | content_size | ||
) |
Gets the total size of downloaded content.
This information is received from the server. If the server does not send the total size of the content, content_size is set to zero.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Parameters:
-
[in] download_id The download ID [out] content_size The content size for displaying to user
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The download state must be one of the states after DOWNLOAD_STATE_DOWNLOADING.
int download_get_destination | ( | int | download_id, |
char ** | path | ||
) |
Gets the destination path for the downloaded file.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- You must release path using free().
- Parameters:
-
[in] download_id The download ID [out] path The absolute path to the downloaded file
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- See also:
- download_set_destination()
int download_get_downloaded_file_path | ( | int | download_id, |
char ** | path | ||
) |
Gets the absolute path to save the downloaded file.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function returns DOWNLOAD_ERROR_INVALID_STATE if the download is not completed. You must release path using free().
- Parameters:
-
[in] download_id The download ID [out] path The absolute path to the downloaded file
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The download state must be DOWNLOAD_STATE_COMPLETED.
int download_get_error | ( | int | download_id, |
download_error_e * | error | ||
) |
Gets an error value when the download fails.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Parameters:
-
[in] download_id The download ID [out] error The error value
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The download state must be DOWNLOAD_STATE_FAILED.
- The download state must be DOWNLOAD_STATE_CANCELED.
int download_get_etag | ( | int | download_id, |
char ** | etag | ||
) |
Gets an etag value from the HTTP response header when making a HTTP request for resume.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- The etag value is available or not depending on the web server.
After download is started, it can get the etag value.
- Parameters:
-
[in] download_id The download ID [out] etag The etag value
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- See also:
- download_set_temp_file_path()
int download_get_file_name | ( | int | download_id, |
char ** | file_name | ||
) |
Gets the name of the downloaded file set previously by download_set_file_name().
If the name is not set, NULL
is returned.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- You must release file_name using free().
- Parameters:
-
[in] download_id The download ID [out] file_name The file name which is set by user
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- See also:
- download_set_file_name()
int download_get_http_header_field | ( | int | download_id, |
const char * | field, | ||
char ** | value | ||
) |
Gets a value associated with a given HTTP header field from the download.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function returns DOWNLOAD_ERROR_INVALID_PARAMETER if field is zero-length string. You must release value using free().
- Parameters:
-
[in] download_id The download ID [in] field The name of the HTTP header field [out] value The value associated with given field
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_FIELD_NOT_FOUND Specified field not found DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
int download_get_http_header_field_list | ( | int | download_id, |
char *** | fields, | ||
int * | length | ||
) |
Gets all the HTTP header fields added to the download request.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- You must release value using free().
- Parameters:
-
[in] download_id The download ID [out] fields The array of the HTTP header fields [out] length The number of the HTTP header fields
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
int download_get_http_status | ( | int | download_id, |
int * | HTTP_status | ||
) |
Gets a HTTP status code when a download error occurs.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Parameters:
-
[in] download_id The download ID [out] HTTP_status The HTTP status code defined in RFC 2616
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The download state must be DOWNLOAD_STATE_FAILED.
- See also:
- download_start()
int download_get_mime_type | ( | int | download_id, |
char ** | mime_type | ||
) |
Gets the MIME type of the downloaded content.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function returns DOWNLOAD_ERROR_INVALID_STATE if the download has not been started. You must release mime_type using free().
- Parameters:
-
[in] download_id The download ID [out] mime_type The MIME type of the downloaded file
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
int download_get_network_type | ( | int | download_id, |
download_network_type_e * | net_type | ||
) |
Gets the network type for the downloaded file.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Parameters:
-
[in] download_id The download ID [out] net_type The network type that is defined by client
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
int download_get_notification_app_control | ( | int | download_id, |
download_notification_app_control_type_e | type, | ||
app_control_h * | handle | ||
) |
Gets the app control handle (used previously to register notification messages) which is set by download_set_notification_app_control().
When the notification message is clicked, the action is decided by the app control handle.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- The app control handle MUST BE FREED by the client when it is not used any more.
- Parameters:
-
[in] download_id The download ID [in] type The enumeration type
See download_notification_app_control_type_e.[out] handle The app control handle pointer value
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_NO_DATA The app control handle has not been set DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
int download_get_notification_description | ( | int | download_id, |
char ** | description | ||
) |
Gets the description of a notification set by download_set_notification_description().
When registering a notification, the description is displayed in the description area of the notification message.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Parameters:
-
[in] download_id The download ID [out] description The description for displaying to user
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_NO_DATA The description has not been set DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- It can get the title value before calling this API.
int download_get_notification_title | ( | int | download_id, |
char ** | title | ||
) |
Gets the title of the notification set by download_set_notification_title().
When registering a notification, the title is displayed in the title area of the notification message.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Parameters:
-
[in] download_id The download ID [out] title The title for displaying to user
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_NO_DATA The title has not been set DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- It can get the title value before calling this API.
- See also:
- download_set_notification_title()
int download_get_notification_type | ( | int | download_id, |
download_notification_type_e * | type | ||
) |
Gets an option value to register notification messages set by download_set_notification_type().
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- When the notification message is clicked, the action is decided by the app control from download_set_notification_app_control().
The default type is DOWNLOAD_NOTIFICATION_TYPE_NONE.
- Parameters:
-
[in] download_id The download ID [out] type The enumeration type
See download_notification_type_e.
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- See also:
- download_set_notification_type()
int download_get_state | ( | int | download_id, |
download_state_e * | state | ||
) |
Gets the current state of the download.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Parameters:
-
[in] download_id The download ID [out] state The current state of the download
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- See also:
- download_state_e
int download_get_temp_path | ( | int | download_id, |
char ** | temp_path | ||
) |
Gets the full path of the temporary file to store downloaded content.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Parameters:
-
[in] download_id The download ID [out] temp_path The full path of temporary file
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The download state must be one of the states after DOWNLOAD_STATE_DOWNLOADING.
int download_get_url | ( | int | download_id, |
char ** | url | ||
) |
Gets the URL to download.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- You must release url using free().
- Parameters:
-
[in] download_id The download ID [out] url The URL to download
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- See also:
- download_set_url()
int download_pause | ( | int | download_id | ) |
Pauses the download, asynchronously.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- The paused download can be restarted with download_start() or cancelled with download_cancel().
- Parameters:
-
[in] download_id The download ID
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_IO_ERROR Internal I/O error DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The download state must be DOWNLOAD_STATE_DOWNLOADING.
- Postcondition:
- The download state will be DOWNLOAD_STATE_PAUSED.
- See also:
- download_start()
- download_cancel()
int download_remove_http_header_field | ( | int | download_id, |
const char * | field | ||
) |
Removes a given HTTP header field from the download.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function should be called before downloading (see download_start()). This function returns DOWNLOAD_ERROR_INVALID_PARAMETER if field is zero-length string.
- Parameters:
-
[in] download_id The download ID [in] field The name of the HTTP header field
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_FIELD_NOT_FOUND Specified field not found DOWNLOAD_ERROR_IO_ERROR Internal I/O error DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state must be DOWNLOAD_STATE_READY, DOWNLOAD_STATE_FAILED, or DOWNLOAD_STATE_CANCELED.
int download_set_auto_download | ( | int | download_id, |
bool | enable | ||
) |
Enables or disables auto download.
If this option is enabled, the previous downloading item is restarted automatically as soon as the download daemon is restarted. The download progress continues after the client process is terminated.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- The default value is
false
.
- Parameters:
-
[in] download_id The download ID [in] enable Set true
to enable auto download, otherwise setfalse
to disable auto download
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state must be DOWNLOAD_STATE_READY, DOWNLOAD_STATE_FAILED, or DOWNLOAD_STATE_CANCELED.
- See also:
- download_get_auto_download()
int download_set_destination | ( | int | download_id, |
const char * | path | ||
) |
Sets the destination for the downloaded file.
The file will be downloaded to the specified destination. The downloaded file is saved to an auto-generated file name in the destination. If the destination is not specified, the file will be downloaded to default storage (see the Storage API).
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function should be called before downloading (see download_start()).
The mediastorage privilege http://tizen.org/privilege/mediastorage is needed if path is relevant to media storage.
The externalstorage privilege http://tizen.org/privilege/externalstorage is needed if path is relevant to external storage.
- Parameters:
-
[in] download_id The download ID [in] path The absolute path to the downloaded file
If path isNULL
, it clears the previous value.
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_INVALID_DESTINATION Invalid destination DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state must be DOWNLOAD_STATE_READY, DOWNLOAD_STATE_FAILED, or DOWNLOAD_STATE_CANCELED.
- See also:
- download_get_destination()
int download_set_file_name | ( | int | download_id, |
const char * | file_name | ||
) |
Sets the name for the downloaded file.
The file will be saved in the specified destination with the given file name. If the file name is not specified, the downloaded file will be saved with an auto-generated file name in the destination.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function should be called before downloading (see download_start()).
- Parameters:
-
[in] download_id The download ID [in] file_name The file name for the downloaded file
If name isNULL
it clears the previous value.
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state must be DOWNLOAD_STATE_READY, DOWNLOAD_STATE_FAILED, or DOWNLOAD_STATE_CANCELED.
- See also:
- download_get_file_name()
int download_set_network_type | ( | int | download_id, |
download_network_type_e | net_type | ||
) |
Sets the allowed network type for the downloaded file.
The file can be downloaded only under the allowed network.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function should be called before downloading (see download_start()).
- Parameters:
-
[in] download_id The download ID [in] net_type The network type that the client prefers
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state must be DOWNLOAD_STATE_READY, DOWNLOAD_STATE_FAILED, or DOWNLOAD_STATE_CANCELED.
int download_set_notification_app_control | ( | int | download_id, |
download_notification_app_control_type_e | type, | ||
app_control_h | handle | ||
) |
Sets an app control handle to register notification messages.
Three types of notification message can be posted: completion, failed and ongoing type.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- When the notification message is clicked, the action to take is decided by the app control handle.
If the app control handle is not set, the following default operation is executed when the notification message is clicked:
1) download completed state - the viewer application is executed according to extension name of downloaded content,
2) download failed state and ongoing state - the client application is executed.
This function should be called before starting the download.
The app control handle MUST BE FREED by the client when it is not used any more.
- Parameters:
-
[in] download_id The download ID [in] type The enumeration type
See download_notification_app_control_type_e.[in] handle The app control handle pointer value
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state must be DOWNLOAD_STATE_READY, DOWNLOAD_STATE_FAILED, or DOWNLOAD_STATE_CANCELED.
int download_set_notification_description | ( | int | download_id, |
const char * | description | ||
) |
Sets the description of a notification.
When registering a notification, the description is displayed in the description area of the notification message.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Parameters:
-
[in] download_id The download ID [in] description The description for displaying to user
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- If the notification option is not enabled, this description is not shown to user.
int download_set_notification_title | ( | int | download_id, |
const char * | title | ||
) |
Sets the title of a notification.
When registering a notification, the title is displayed in the title area of the notification message.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Parameters:
-
[in] download_id The download ID [in] title The title for displaying to user
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- If a notification option is not enabled, this title is not shown to user.
int download_set_notification_type | ( | int | download_id, |
download_notification_type_e | type | ||
) |
Sets an option value to register notification messages.
Three types of notification message can be posted: completion, failed and ongoing type.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- 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()).
If the app control is not set, the following default operation is executed when the notification message is clicked:
1) download completed state - the viewer application is executed according to extension name of downloaded content,
2) download failed state and ongoing state - the client application is executed.
The default type is DOWNLOAD_NOTIFICATION_TYPE_NONE.
This function should be called before starting the download.
- Parameters:
-
[in] download_id The download ID [in] type The enumeration type
See download_notification_type_e.
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state must be DOWNLOAD_STATE_READY, DOWNLOAD_STATE_FAILED, or DOWNLOAD_STATE_CANCELED.
int download_set_progress_cb | ( | int | download_id, |
download_progress_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to be invoked when progress of the download changes.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function should be called before downloading (see download_start()).
- Parameters:
-
[in] download_id The download ID [in] callback The callback function to register [in] user_data The user data to be passed to the callback function
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Postcondition:
- download_progress_cb() will be invoked.
int download_set_state_changed_cb | ( | int | download_id, |
download_state_changed_cb | callback, | ||
void * | user_data | ||
) |
Registers a callback function to be invoked when a download state is changed.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function should be called before downloading (see download_start()).
- Parameters:
-
[in] download_id The download ID [in] callback The callback function to register [in] user_data The user data to be passed to the callback function
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Postcondition:
- download_state_changed_cb() will be invoked.
int download_set_temp_file_path | ( | int | download_id, |
char * | path | ||
) |
Sets the directory path of the temporary file used in the previous download request.
This is only useful when resuming download to make HTTP request header at the client side. Otherwise, the path should be ignored internally.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- If the etag value is not present in the download database, it is useless to set the temporary path.
When resuming download, the data is attached at the end of this temporary file.
The mediastorage privilege http://tizen.org/privilege/mediastorage is needed if path is relevant to media storage.
The externalstorage privilege http://tizen.org/privilege/externalstorage is needed if path is relevant to external storage.
- Parameters:
-
[in] download_id The download ID [out] path The full path of temporary file
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_INVALID_DESTINATION Invalid destination DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state must be DOWNLOAD_STATE_READY, DOWNLOAD_STATE_FAILED, or DOWNLOAD_STATE_CANCELED.
- See also:
- download_get_etag()
int download_set_url | ( | int | download_id, |
const char * | url | ||
) |
Sets the URL to download.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function should be called before downloading (see download_start()).
- Parameters:
-
[in] download_id The download ID [in] url The URL to download
If url isNULL
, it clears the previous value.
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The state must be DOWNLOAD_STATE_READY, DOWNLOAD_STATE_FAILED, or DOWNLOAD_STATE_CANCELED.
- See also:
- download_get_url()
int download_start | ( | int | download_id | ) |
Starts or resumes the download, asynchronously.
This function starts to download the current URL, or resumes the download if paused.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- The URL is the mandatory information to start the download.
- It should call download_set_progress_cb() and download_set_state_changed_cb() again after the client process is restarted or download_destroy() is called.
- Parameters:
-
[in] download_id The download ID
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_OUT_OF_MEMORY Out of memory DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_IO_ERROR Internal I/O error DOWNLOAD_ERROR_INVALID_URL Invalid URL DOWNLOAD_ERROR_INVALID_DESTINATION Invalid destination DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_QUEUE_FULL Download server queue is full DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
- Precondition:
- The download state must be DOWNLOAD_STATE_READY, DOWNLOAD_STATE_PAUSED, DOWNLOAD_STATE_CANCELED, or DOWNLOAD_STATE_FAILED.
- Postcondition:
- The download state will be DOWNLOAD_STATE_QUEUED or DOWNLOAD_STATE_DOWNLOADING.
int download_unset_progress_cb | ( | int | download_id | ) |
Unregisters the download progress change callback function.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function should be called before downloading (see download_start()).
- Parameters:
-
[in] download_id The download ID
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_INVALID_STATE Invalid state DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported
int download_unset_state_changed_cb | ( | int | download_id | ) |
Unregisters the download state change callback function.
- Since :
- 2.3
- Privilege Level:
- public
- Privilege:
- http://tizen.org/privilege/download
- Remarks:
- This function should be called before downloading (see download_start()).
- Parameters:
-
[in] download_id The download ID
- Returns:
0
on success, otherwise a negative error value
- Return values:
-
DOWNLOAD_ERROR_NONE Successful DOWNLOAD_ERROR_INVALID_PARAMETER Invalid parameter DOWNLOAD_ERROR_ID_NOT_FOUND No download ID DOWNLOAD_ERROR_PERMISSION_DENIED Permission denied DOWNLOAD_ERROR_NOT_SUPPORTED Not supported