ppapi/api/ppb_url_loader.idl

   1 /* Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2  * Use of this source code is governed by a BSD-style license that can be
   3  * found in the LICENSE file.
   4  */
   5
   6 /**
   7  * This file defines the <strong>PPB_URLLoader</strong> interface for loading
   8  * URLs.
   9  */
  10
  11 [generate_thunk]
  12
  13 label Chrome {
  14   M14 = 1.0
  15 };
  16
  17 /**
  18  * The <strong>PPB_URLLoader</strong> interface contains pointers to functions
  19  * for loading URLs. The typical steps for loading a URL are:
  20  *
  21  * -# Call Create() to create a URLLoader object.
  22  * -# Create a <code>URLRequestInfo</code> object and set properties on it.
  23  * Refer to <code>PPB_URLRequestInfo</code> for further information.
  24  * -# Call Open() with the <code>URLRequestInfo</code> as an argument.
  25  * -# When Open() completes, call GetResponseInfo() to examine the response
  26  * headers. Refer to <code>PPB_URLResponseInfo</code> for further information.
  27  * -# Call ReadResponseBody() to stream the data for the response.
  28  *
  29  * Alternatively, if <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set on
  30  * the <code>URLRequestInfo</code> in step #2:
  31  * - Call FinishStreamingToFile(), after examining the response headers
  32  * (step #4),  to wait for the downloaded file to be complete.
  33  * - Then, access the downloaded file using the GetBodyAsFileRef() function of
  34  * the <code>URLResponseInfo</code> returned in step #4.
  35  */
  36 interface PPB_URLLoader {
  37   /**
  38    * Create() creates a new <code>URLLoader</code> object. The
  39    * <code>URLLoader</code> is associated with a particular instance, so that
  40    * any UI dialogs that need to be shown to the user can be positioned
  41    * relative to the window containing the instance.
  42    *
  43    * @param[in] instance A <code>PP_Instance</code> identifying one instance
  44    * of a module.
  45    *
  46    * @return A <code>PP_Resource</code> corresponding to a URLLoader if
  47    * successful, 0 if the instance is invalid.
  48    */
  49   PP_Resource Create(
  50       [in] PP_Instance instance);
  51
  52   /**
  53    * IsURLLoader() determines if a resource is an <code>URLLoader</code>.
  54    *
  55    * @param[in] resource A <code>PP_Resource</code> corresponding to a
  56    * <code>URLLoader</code>.
  57    *
  58    * @return <code>PP_TRUE</code> if the resource is a <code>URLLoader</code>,
  59    * <code>PP_FALSE</code> if the resource is invalid or some type other
  60    * than <code>URLLoader</code>.
  61    */
  62   PP_Bool IsURLLoader(
  63       [in] PP_Resource resource);
  64
  65   /**
  66    * Open() begins loading the <code>URLRequestInfo</code>. The operation
  67    * completes when response headers are received or when an error occurs.  Use
  68    * GetResponseInfo() to access the response headers.
  69    *
  70    * @param[in] loader A <code>PP_Resource</code> corresponding to a
  71    * <code>URLLoader</code>.
  72    * @param[in] resource A <code>PP_Resource</code> corresponding to a
  73    * <code>URLRequestInfo</code>.
  74    * @param[in] callback A <code>PP_CompletionCallback</code> to run on
  75    * asynchronous completion of Open(). This callback will run when response
  76    * headers for the url are received or error occurred. This callback
  77    * will only run if Open() returns <code>PP_OK_COMPLETIONPENDING</code>.
  78    *
  79    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
  80    */
  81   int32_t Open(
  82       [in] PP_Resource loader,
  83       [in] PP_Resource request_info,
  84       [in] PP_CompletionCallback callback);
  85
  86   /**
  87    * FollowRedirect() can be invoked to follow a redirect after Open()
  88    * completed on receiving redirect headers.
  89    *
  90    * @param[in] loader A <code>PP_Resource</code> corresponding to a
  91    * <code>URLLoader</code>.
  92    * @param[in] callback A <code>PP_CompletionCallback</code> to run on
  93    * asynchronous completion of FollowRedirect(). This callback will run when
  94    * response headers for the redirect url are received or error occurred. This
  95    * callback will only run if FollowRedirect() returns
  96    * <code>PP_OK_COMPLETIONPENDING</code>.
  97    *
  98    * @return An int32_t containing an error code from <code>pp_errors.h</code>.
  99    */
 100   int32_t FollowRedirect(
 101       [in] PP_Resource loader,
 102       [in] PP_CompletionCallback callback);
 103
 104   /**
 105    * GetUploadProgress() returns the current upload progress (which is
 106    * meaningful after Open() has been called). Progress only refers to the
 107    * request body and does not include the headers.
 108    *
 109    * This data is only available if the <code>URLRequestInfo</code> passed
 110    * to Open() had the <code>PP_URLREQUESTPROPERTY_REPORTUPLOADPROGRESS</code>
 111    * property set to PP_TRUE.
 112    *
 113    * @param[in] loader A <code>PP_Resource</code> corresponding to a
 114    * <code>URLLoader</code>.
 115    * @param[in] bytes_sent The number of bytes sent thus far.
 116    * @param[in] total_bytes_to_be_sent The total number of bytes to be sent.
 117    *
 118    * @return <code>PP_TRUE</code> if the upload progress is available,
 119    * <code>PP_FALSE</code> if it is not available.
 120    */
 121   [always_set_output_parameters]
 122   PP_Bool GetUploadProgress(
 123       [in] PP_Resource loader,
 124       [out] int64_t bytes_sent,
 125       [out] int64_t total_bytes_to_be_sent);
 126
 127   /**
 128    * GetDownloadProgress() returns the current download progress, which is
 129    * meaningful after Open() has been called. Progress only refers to the
 130    * response body and does not include the headers.
 131    *
 132    * This data is only available if the <code>URLRequestInfo</code> passed to
 133    * Open() had the <code>PP_URLREQUESTPROPERTY_REPORTDOWNLOADPROGRESS</code>
 134    * property set to <code>PP_TRUE</code>.
 135    *
 136    * @param[in] loader A <code>PP_Resource</code> corresponding to a
 137    * <code>URLLoader</code>.
 138    * @param[in] bytes_received The number of bytes received thus far.
 139    * @param[in] total_bytes_to_be_received The total number of bytes to be
 140    * received. The total bytes to be received may be unknown, in which case
 141    * <code>total_bytes_to_be_received</code> will be set to -1.
 142    *
 143    * @return <code>PP_TRUE</code> if the download progress is available,
 144    * <code>PP_FALSE</code> if it is not available.
 145    */
 146   [always_set_output_parameters]
 147   PP_Bool GetDownloadProgress(
 148       [in] PP_Resource loader,
 149       [out] int64_t bytes_received,
 150       [out] int64_t total_bytes_to_be_received);
 151
 152   /**
 153    * GetResponseInfo() returns the current <code>URLResponseInfo</code> object.
 154    *
 155    * @param[in] instance A <code>PP_Resource</code> corresponding to a
 156    * <code>URLLoader</code>.
 157    *
 158    * @return A <code>PP_Resource</code> corresponding to the
 159    * <code>URLResponseInfo</code> if successful, 0 if the loader is not a valid
 160    * resource or if Open() has not been called.
 161    */
 162   PP_Resource GetResponseInfo(
 163       [in] PP_Resource loader);
 164
 165   /**
 166    * ReadResponseBody() is used to read the response body. The size of the
 167    * buffer must be large enough to hold the specified number of bytes to read.
 168    * This function might perform a partial read.
 169    *
 170    * @param[in] loader A <code>PP_Resource</code> corresponding to a
 171    * <code>URLLoader</code>.
 172    * @param[in,out] buffer A pointer to the buffer for the response body.
 173    * @param[in] bytes_to_read The number of bytes to read.
 174    * @param[in] callback A <code>PP_CompletionCallback</code> to run on
 175    * asynchronous completion. The callback will run if the bytes (full or
 176    * partial) are read or an error occurs asynchronously. This callback will
 177    * run only if this function returns <code>PP_OK_COMPLETIONPENDING</code>.
 178    *
 179    * @return An int32_t containing the number of bytes read or an error code
 180    * from <code>pp_errors.h</code>.
 181    */
 182   int32_t ReadResponseBody(
 183       [in] PP_Resource loader,
 184       [out] mem_t buffer,
 185       [in] int32_t bytes_to_read,
 186       [in] PP_CompletionCallback callback);
 187
 188   /**
 189    * FinishStreamingToFile() is used to wait for the response body to be
 190    * completely downloaded to the file provided by the GetBodyAsFileRef()
 191    * in the current <code>URLResponseInfo</code>. This function is only used if
 192    * <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set on the
 193    * <code>URLRequestInfo</code> passed to Open().
 194    *
 195    * @param[in] loader A <code>PP_Resource</code> corresponding to a
 196    * <code>URLLoader</code>.
 197    * @param[in] callback A <code>PP_CompletionCallback</code> to run on
 198    * asynchronous completion. This callback will run when body is downloaded
 199    * or an error occurs after FinishStreamingToFile() returns
 200    * <code>PP_OK_COMPLETIONPENDING</code>.
 201    *
 202    * @return An int32_t containing the number of bytes read or an error code
 203    * from <code>pp_errors.h</code>.
 204    */
 205   int32_t FinishStreamingToFile(
 206       [in] PP_Resource loader,
 207       [in] PP_CompletionCallback callback);
 208
 209   /**
 210    * Close is a pointer to a function used to cancel any pending IO and close
 211    * the <code>URLLoader</code> object. Any pending callbacks will still run,
 212    * reporting <code>PP_ERROR_ABORTED</code> if pending IO was interrupted.
 213    * It is NOT valid to call Open() again after a call to this function.
 214    *
 215    * <strong>Note:</strong> If the <code>URLLoader</code> object is destroyed
 216    * while it is still open, then it will be implicitly closed so you are not
 217    * required to call Close().
 218    *
 219    * @param[in] loader A <code>PP_Resource</code> corresponding to a
 220    * <code>URLLoader</code>.
 221    */
 222   void Close(
 223       [in] PP_Resource loader);
 224 };
 225