2 * Copyright (C) 2012 Intel Corporation. All rights reserved.
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
7 * 1. Redistributions of source code must retain the above copyright
8 * notice, this list of conditions and the following disclaimer.
9 * 2. Redistributions in binary form must reproduce the above copyright
10 * notice, this list of conditions and the following disclaimer in the
11 * documentation and/or other materials provided with the distribution.
13 * THIS SOFTWARE IS PROVIDED BY APPLE INC. AND ITS CONTRIBUTORS ``AS IS''
14 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
15 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE INC. OR ITS CONTRIBUTORS
17 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
19 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
20 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
21 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
22 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
23 * THE POSSIBILITY OF SUCH DAMAGE.
27 * @file ewk_download_job.h
28 * @brief Describes the Download Job API.
30 * @note Ewk_Download_Job encapsulates a WebKit download job in order to provide
31 * information about it and interact with it (e.g. set the destination
32 * path, cancel the download, ...).
35 #ifndef ewk_download_job_h
36 #define ewk_download_job_h
38 #include "ewk_url_request.h"
39 #include "ewk_url_response.h"
46 /** Creates a type name for Ewk_Download_Job */
47 typedef struct Ewk_Download_Job Ewk_Download_Job;
49 /// Defines the possible states of a download.
50 enum Ewk_Download_Job_State {
51 /// The download state is unknown
52 EWK_DOWNLOAD_JOB_STATE_UNKNOWN = -1,
53 /// The download has not started yet
54 EWK_DOWNLOAD_JOB_STATE_NOT_STARTED,
55 /// The download has started
56 EWK_DOWNLOAD_JOB_STATE_DOWNLOADING,
57 /// The download stopped because of a failure
58 EWK_DOWNLOAD_JOB_STATE_FAILED,
59 /// The download is being cancelled
60 EWK_DOWNLOAD_JOB_STATE_CANCELLING,
61 /// The download stopped because it was cancelled
62 EWK_DOWNLOAD_JOB_STATE_CANCELLED,
63 /// The download completed successfully.
64 EWK_DOWNLOAD_JOB_STATE_FINISHED
66 /// Creates a type name for @a Ewk_Download_Job_State.
67 typedef enum Ewk_Download_Job_State Ewk_Download_Job_State;
70 * Increases the reference count of the given object.
72 * @param download the download object to increase the reference count
74 * @return a pointer to the object on success, @c NULL otherwise.
76 EAPI Ewk_Download_Job *ewk_download_job_ref(Ewk_Download_Job *download);
79 * Decreases the reference count of the given object, possibly freeing it.
81 * When the reference count reaches 0, the download is freed.
83 * @param download the download object to decrease the reference count
85 EAPI void ewk_download_job_unref(Ewk_Download_Job *download);
88 * Query the state for this download.
90 * @param download a #Ewk_Download_Job to query.
92 * @return the download state.
94 EAPI Ewk_Download_Job_State ewk_download_job_state_get(const Ewk_Download_Job *download);
97 * Query the URL request for this download.
99 * @param download a #Ewk_Download_Job to query.
101 * @return the #Ewk_Url_Request for this download.
103 EAPI Ewk_Url_Request *ewk_download_job_request_get(const Ewk_Download_Job *download);
106 * Query the URL response for this download.
108 * @param download a #Ewk_Download_Job to query.
110 * @return the #Ewk_Url_Response for this download or @c NULL if it was not received yet.
112 EAPI Ewk_Url_Response *ewk_download_job_response_get(const Ewk_Download_Job *download);
115 * Query the URL to which the downloaded file will be written.
117 * @param download a #Ewk_Download_Job to query.
119 * @return the destination pointer, that may be @c NULL. This pointer is
120 * guaranteed to be eina_stringshare, so whenever possible
121 * save yourself some cpu cycles and use
122 * eina_stringshare_ref() instead of eina_stringshare_add() or
125 EAPI const char *ewk_download_job_destination_get(const Ewk_Download_Job *download);
128 * Sets the destination path for this download.
130 * Sets the path to which the downloaded file will be written.
132 * This method needs to be called before the download transfer
133 * starts, by connecting to the "download,new" signal on the
134 * Ewk_View and setting the destination in the callback. To set
135 * the destination using the filename suggested by the server
136 * use ewk_download_job_suggested_filename_get().
138 * @param download #Ewk_Download_Job to update.
139 * @param destination the destination path.
141 * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise.
143 * @see ewk_download_job_suggested_filename_get
145 EAPI Eina_Bool ewk_download_job_destination_set(Ewk_Download_Job *download, const char *destination);
148 * Queries the suggested file name for this download.
150 * It can be useful to use the value returned by this function to construct
151 * the destination path to pass to ewk_download_job_destination_set().
153 * @param download #Ewk_Download_Job to query.
155 * @return The suggested file name for this download. This pointer is
156 * guaranteed to be eina_stringshare, so whenever possible
157 * save yourself some cpu cycles and use
158 * eina_stringshare_ref() instead of eina_stringshare_add() or
161 * @see ewk_download_job_destination_set
163 EAPI const char *ewk_download_job_suggested_filename_get(const Ewk_Download_Job *download);
166 * Cancels the download asynchronously.
168 * When the ongoing download operation is effectively cancelled a "download,cancelled"
169 * signal will be emitted on the view.
171 * @param download a #Ewk_Download_Job to cancel.
173 * @return @c EINA_TRUE if the cancellation request was taken into account, or
174 * @c EINA_FALSE otherwise.
176 EAPI Eina_Bool ewk_download_job_cancel(Ewk_Download_Job *download);
179 * Query the estimated progress for this download.
181 * @param download a #Ewk_Download_Job to query.
183 * @return an estimate of the of the percent complete for a download
184 * as a range from 0.0 to 1.0.
186 EAPI double ewk_download_job_estimated_progress_get(const Ewk_Download_Job *download);
189 * Gets the elapsed time in seconds, including any fractional part.
191 * If the download finished, had an error or was cancelled this is
192 * the time between its start and the event.
194 * @param download a #Ewk_Download_Job
196 * @return seconds since the download was started or 0.0 in case of failure.
198 EAPI double ewk_download_job_elapsed_time_get(const Ewk_Download_Job *download);
204 #endif // ewk_download_job_h