Source/WebKit2/UIProcess/API/efl/ewk_download_job.h

   1 /*
   2  * Copyright (C) 2012 Intel Corporation. All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or without
   5  * modification, are permitted provided that the following conditions
   6  * are met:
   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.
  12  *
  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.
  24  */
  25
  26 /**
  27  * @file    ewk_download_job.h
  28  * @brief   Describes the Download Job API.
  29  *
  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, ...).
  33  */
  34
  35 #ifndef ewk_download_job_h
  36 #define ewk_download_job_h
  37
  38 #include "ewk_url_request.h"
  39 #include "ewk_url_response.h"
  40 #include <Eina.h>
  41
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 /** Creates a type name for Ewk_Download_Job */
  47 typedef struct Ewk_Download_Job Ewk_Download_Job;
  48
  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
  65 };
  66 /// Creates a type name for @a Ewk_Download_Job_State.
  67 typedef enum Ewk_Download_Job_State Ewk_Download_Job_State;
  68
  69 /**
  70  * Increases the reference count of the given object.
  71  *
  72  * @param download the download object to increase the reference count
  73  *
  74  * @return a pointer to the object on success, @c NULL otherwise.
  75  */
  76 EAPI Ewk_Download_Job *ewk_download_job_ref(Ewk_Download_Job *download);
  77
  78 /**
  79  * Decreases the reference count of the given object, possibly freeing it.
  80  *
  81  * When the reference count reaches 0, the download is freed.
  82  *
  83  * @param download the download object to decrease the reference count
  84  */
  85 EAPI void ewk_download_job_unref(Ewk_Download_Job *download);
  86
  87 /**
  88  * Query the state for this download.
  89  *
  90  * @param download a #Ewk_Download_Job to query.
  91  *
  92  * @return the download state.
  93  */
  94 EAPI Ewk_Download_Job_State ewk_download_job_state_get(const Ewk_Download_Job *download);
  95
  96 /**
  97  * Query the URL request for this download.
  98  *
  99  * @param download a #Ewk_Download_Job to query.
 100  *
 101  * @return the #Ewk_Url_Request for this download.
 102  */
 103 EAPI Ewk_Url_Request *ewk_download_job_request_get(const Ewk_Download_Job *download);
 104
 105 /**
 106  * Query the URL response for this download.
 107  *
 108  * @param download a #Ewk_Download_Job to query.
 109  *
 110  * @return the #Ewk_Url_Response for this download or @c NULL if it was not received yet.
 111  */
 112 EAPI Ewk_Url_Response *ewk_download_job_response_get(const Ewk_Download_Job *download);
 113
 114 /**
 115  * Query the URL to which the downloaded file will be written.
 116  *
 117  * @param download a #Ewk_Download_Job to query.
 118  *
 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
 123  *         strdup().
 124  */
 125 EAPI const char *ewk_download_job_destination_get(const Ewk_Download_Job *download);
 126
 127 /**
 128  * Sets the destination path for this download.
 129  *
 130  * Sets the path to which the downloaded file will be written.
 131  *
 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().
 137  *
 138  * @param download #Ewk_Download_Job to update.
 139  * @param destination the destination path.
 140  *
 141  * @return @c EINA_TRUE if successful, @c EINA_FALSE otherwise.
 142  *
 143  * @see ewk_download_job_suggested_filename_get
 144  */
 145 EAPI Eina_Bool ewk_download_job_destination_set(Ewk_Download_Job *download, const char *destination);
 146
 147 /**
 148  * Queries the suggested file name for this download.
 149  *
 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().
 152  *
 153  * @param download #Ewk_Download_Job to query.
 154  *
 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
 159  *         strdup().
 160  *
 161  * @see ewk_download_job_destination_set
 162  */
 163 EAPI const char *ewk_download_job_suggested_filename_get(const Ewk_Download_Job *download);
 164
 165 /**
 166  * Cancels the download asynchronously.
 167  *
 168  * When the ongoing download operation is effectively cancelled a "download,cancelled"
 169  * signal will be emitted on the view.
 170  *
 171  * @param download a #Ewk_Download_Job to cancel.
 172  *
 173  * @return @c EINA_TRUE if the cancellation request was taken into account, or
 174  *         @c EINA_FALSE otherwise.
 175  */
 176 EAPI Eina_Bool ewk_download_job_cancel(Ewk_Download_Job *download);
 177
 178 /**
 179  * Query the estimated progress for this download.
 180  *
 181  * @param download a #Ewk_Download_Job to query.
 182  *
 183  * @return an estimate of the of the percent complete for a download
 184  *         as a range from 0.0 to 1.0.
 185  */
 186 EAPI double ewk_download_job_estimated_progress_get(const Ewk_Download_Job *download);
 187
 188 /**
 189  * Gets the elapsed time in seconds, including any fractional part.
 190  *
 191  * If the download finished, had an error or was cancelled this is
 192  * the time between its start and the event.
 193  *
 194  * @param download a #Ewk_Download_Job
 195  *
 196  * @return seconds since the download was started or 0.0 in case of failure.
 197  */
 198 EAPI double ewk_download_job_elapsed_time_get(const Ewk_Download_Job *download);
 199
 200 #ifdef __cplusplus
 201 }
 202 #endif
 203
 204 #endif // ewk_download_job_h