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