ppapi/c/ppb_url_loader.h

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