ppapi/c/ppb_url_request_info.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_request_info.idl modified Thu Mar 28 10:19:35 2013. */
   7
   8 #ifndef PPAPI_C_PPB_URL_REQUEST_INFO_H_
   9 #define PPAPI_C_PPB_URL_REQUEST_INFO_H_
  10
  11 #include "ppapi/c/pp_bool.h"
  12 #include "ppapi/c/pp_instance.h"
  13 #include "ppapi/c/pp_macros.h"
  14 #include "ppapi/c/pp_resource.h"
  15 #include "ppapi/c/pp_stdint.h"
  16 #include "ppapi/c/pp_time.h"
  17 #include "ppapi/c/pp_var.h"
  18
  19 #define PPB_URLREQUESTINFO_INTERFACE_1_0 "PPB_URLRequestInfo;1.0"
  20 #define PPB_URLREQUESTINFO_INTERFACE PPB_URLREQUESTINFO_INTERFACE_1_0
  21
  22 /**
  23  * @file
  24  * This file defines the <code>PPB_URLRequestInfo</code> API for creating and
  25  * manipulating URL requests.
  26  */
  27
  28
  29 /**
  30  * @addtogroup Enums
  31  * @{
  32  */
  33 /**
  34  * This enumeration contains properties that can be set on a URL request.
  35  */
  36 typedef enum {
  37   /** This corresponds to a string (<code>PP_VARTYPE_STRING</code>). */
  38   PP_URLREQUESTPROPERTY_URL = 0,
  39   /**
  40    * This corresponds to a string (<code>PP_VARTYPE_STRING</code>); either
  41    * POST or GET. Refer to the
  42    * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html">HTTP
  43    * Methods</a> documentation for further information.
  44    *
  45    */
  46   PP_URLREQUESTPROPERTY_METHOD = 1,
  47   /**
  48    * This corresponds to a string (<code>PP_VARTYPE_STRING</code>); \n
  49    * delimited. Refer to the
  50    * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html"Header
  51    * Field Definitions</a> documentation for further information.
  52    */
  53   PP_URLREQUESTPROPERTY_HEADERS = 2,
  54   /**
  55    * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
  56    * default=<code>PP_FALSE</code>).
  57    * Set this value to <code>PP_TRUE</code> if you want to download the data
  58    * to a file. Use PPB_URLLoader.FinishStreamingToFile() to complete the
  59    * download.
  60    */
  61   PP_URLREQUESTPROPERTY_STREAMTOFILE = 3,
  62   /**
  63    * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
  64    * default=<code>PP_TRUE</code>).
  65    * Set this value to <code>PP_FALSE</code> if you want to use
  66    * PPB_URLLoader.FollowRedirects() to follow the redirects only after
  67    * examining redirect headers.
  68    */
  69   PP_URLREQUESTPROPERTY_FOLLOWREDIRECTS = 4,
  70   /**
  71    * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
  72    * default=<code>PP_FALSE</code>).
  73    * Set this value to <code>PP_TRUE</code> if you want to be able to poll the
  74    * download progress using PPB_URLLoader.GetDownloadProgress().
  75    */
  76   PP_URLREQUESTPROPERTY_RECORDDOWNLOADPROGRESS = 5,
  77   /**
  78    * This corresponds to a <code>PP_Bool</code>
  79    * (default=<code>PP_FALSE</code>). Set this value to <code>PP_TRUE</code> if
  80    * you want to be able to poll the upload progress using
  81    * PPB_URLLoader.GetUploadProgress().
  82    */
  83   PP_URLREQUESTPROPERTY_RECORDUPLOADPROGRESS = 6,
  84   /**
  85    * This corresponds to a string (<code>PP_VARTYPE_STRING)</code> or may be
  86    * undefined (<code>PP_VARTYPE_UNDEFINED</code>; default).
  87    * Set it to a string to set a custom referrer (if empty, the referrer header
  88    * will be omitted), or to undefined to use the default referrer. Only loaders
  89    * with universal access (only available on trusted implementations) will
  90    * accept <code>URLRequestInfo</code> objects that try to set a custom
  91    * referrer; if given to a loader without universal access,
  92    * <code>PP_ERROR_NOACCESS</code> will result.
  93    */
  94   PP_URLREQUESTPROPERTY_CUSTOMREFERRERURL = 7,
  95   /**
  96    * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
  97    * default=<code>PP_FALSE</code>). Whether cross-origin requests are allowed.
  98    * Cross-origin requests are made using the CORS (Cross-Origin Resource
  99    * Sharing) algorithm to check whether the request should be allowed. For the
 100    * complete CORS algorithm, refer to
 101    * the <a href="http://www.w3.org/TR/access-control">Cross-Origin Resource
 102    * Sharing</a> documentation.
 103    */
 104   PP_URLREQUESTPROPERTY_ALLOWCROSSORIGINREQUESTS = 8,
 105   /**
 106    * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
 107    * default=<code>PP_FALSE</code>).
 108    * Whether HTTP credentials are sent with cross-origin requests. If false,
 109    * no credentials are sent with the request and cookies are ignored in the
 110    * response. If the request is not cross-origin, this property is ignored.
 111    */
 112   PP_URLREQUESTPROPERTY_ALLOWCREDENTIALS = 9,
 113   /**
 114    * This corresponds to a string (<code>PP_VARTYPE_STRING</code>) or may be
 115    * undefined (<code>PP_VARTYPE_UNDEFINED</code>; default).
 116    * Set it to a string to set a custom content-transfer-encoding header (if
 117    * empty, that header will be omitted), or to undefined to use the default
 118    * (if any). Only loaders with universal access (only available on trusted
 119    * implementations) will accept <code>URLRequestInfo</code> objects that try
 120    * to set a custom content transfer encoding; if given to a loader without
 121    * universal access, <code>PP_ERROR_NOACCESS</code> will result.
 122    */
 123   PP_URLREQUESTPROPERTY_CUSTOMCONTENTTRANSFERENCODING = 10,
 124   /**
 125    * This corresponds to an integer (<code>PP_VARTYPE_INT32</code>); default
 126    * is not defined and is set by the browser, possibly depending on system
 127    * capabilities. Set it to an integer to set an upper threshold for the
 128    * prefetched buffer of an asynchronous load. When exceeded, the browser will
 129    * defer loading until
 130    * <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> is hit,
 131    * at which time it will begin prefetching again. When setting this property,
 132    * <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> must also
 133    * be set. Behavior is undefined if the former is <= the latter.
 134    */
 135   PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD = 11,
 136   /**
 137    * This corresponds to an integer (<code>PP_VARTYPE_INT32</code>); default is
 138    * not defined and is set by the browser to a value appropriate for the
 139    * default <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code>.
 140    * Set it to an integer to set a lower threshold for the prefetched buffer
 141    * of an asynchronous load. When reached, the browser will resume loading if
 142    * If <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> had
 143    * previously been reached.
 144    * When setting this property,
 145    * <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code> must also
 146    * be set. Behavior is undefined if the former is >= the latter.
 147    */
 148   PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERTHRESHOLD = 12,
 149   /**
 150    * This corresponds to a string (<code>PP_VARTYPE_STRING</code>) or may be
 151    * undefined (<code>PP_VARTYPE_UNDEFINED</code>; default). Set it to a string
 152    * to set a custom user-agent header (if empty, that header will be omitted),
 153    * or to undefined to use the default. Only loaders with universal access
 154    * (only available on trusted implementations) will accept
 155    * <code>URLRequestInfo</code> objects that try to set a custom user agent; if
 156    * given to a loader without universal access, <code>PP_ERROR_NOACCESS</code>
 157    * will result.
 158    */
 159   PP_URLREQUESTPROPERTY_CUSTOMUSERAGENT = 13
 160 } PP_URLRequestProperty;
 161 PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_URLRequestProperty, 4);
 162 /**
 163  * @}
 164  */
 165
 166 /**
 167  * @addtogroup Interfaces
 168  * @{
 169  */
 170 /**
 171  * The <code>PPB_URLRequestInfo</code> interface is used to create
 172  * and handle URL requests. This API is used in conjunction with
 173  * <code>PPB_URLLoader</code>. Refer to <code>PPB_URLLoader</code> for further
 174  * information.
 175  */
 176 struct PPB_URLRequestInfo_1_0 {
 177   /**
 178    * Create() creates a new <code>URLRequestInfo</code> object.
 179    *
 180    * @param[in] instance A <code>PP_Instance</code> identifying one instance
 181    * of a module.
 182    *
 183    * @return A <code>PP_Resource</code> identifying the
 184    * <code>URLRequestInfo</code> if successful, 0 if the instance is invalid.
 185    */
 186   PP_Resource (*Create)(PP_Instance instance);
 187   /**
 188    * IsURLRequestInfo() determines if a resource is a
 189    * <code>URLRequestInfo</code>.
 190    *
 191    * @param[in] resource A <code>PP_Resource</code> corresponding to a
 192    * <code>URLRequestInfo</code>.
 193    *
 194    * @return <code>PP_TRUE</code> if the resource is a
 195    * <code>URLRequestInfo</code>, <code>PP_FALSE</code> if the resource is
 196    * invalid or some type other than <code>URLRequestInfo</code>.
 197    */
 198   PP_Bool (*IsURLRequestInfo)(PP_Resource resource);
 199   /**
 200    * SetProperty() sets a request property. The value of the property must be
 201    * the correct type according to the property being set.
 202    *
 203    * @param[in] request A <code>PP_Resource</code> corresponding to a
 204    * <code>URLRequestInfo</code>.
 205    * @param[in] property A <code>PP_URLRequestProperty</code> identifying the
 206    * property to set.
 207    * @param[in] value A <code>PP_Var</code> containing the property value.
 208    *
 209    * @return <code>PP_TRUE</code> if successful, <code>PP_FALSE</code> if any
 210    * of the parameters are invalid.
 211    */
 212   PP_Bool (*SetProperty)(PP_Resource request,
 213                          PP_URLRequestProperty property,
 214                          struct PP_Var value);
 215   /**
 216    * AppendDataToBody() appends data to the request body. A Content-Length
 217    * request header will be automatically generated.
 218    *
 219    * @param[in] request A <code>PP_Resource</code> corresponding to a
 220    * <code>URLRequestInfo</code>.
 221    * @param[in] data A pointer to a buffer holding the data.
 222    * @param[in] len The length, in bytes, of the data.
 223    *
 224    * @return <code>PP_TRUE</code> if successful, <code>PP_FALSE</code> if any
 225    * of the parameters are invalid.
 226    *
 227    *
 228    */
 229   PP_Bool (*AppendDataToBody)(PP_Resource request,
 230                               const void* data,
 231                               uint32_t len);
 232   /**
 233    * AppendFileToBody() appends a file, to be uploaded, to the request body.
 234    * A content-length request header will be automatically generated.
 235    *
 236    * @param[in] request A <code>PP_Resource</code> corresponding to a
 237    * <code>URLRequestInfo</code>.
 238    * @param[in] file_ref A <code>PP_Resource</code> corresponding to a file
 239    * reference.
 240    * @param[in] start_offset An optional starting point offset within the
 241    * file.
 242    * @param[in] number_of_bytes An optional number of bytes of the file to
 243    * be included. If <code>number_of_bytes</code> is -1, then the sub-range
 244    * to upload extends to the end of the file.
 245    * @param[in] expected_last_modified_time An optional (non-zero) last
 246    * modified time stamp used to validate that the file was not modified since
 247    * the given time before it was uploaded. The upload will fail with an error
 248    * code of <code>PP_ERROR_FILECHANGED</code> if the file has been modified
 249    * since the given time. If <code>expected_last_modified_time</code> is 0,
 250    * then no validation is performed.
 251    *
 252    * @return <code>PP_TRUE</code> if successful, <code>PP_FALSE</code> if any
 253    * of the parameters are invalid.
 254    */
 255   PP_Bool (*AppendFileToBody)(PP_Resource request,
 256                               PP_Resource file_ref,
 257                               int64_t start_offset,
 258                               int64_t number_of_bytes,
 259                               PP_Time expected_last_modified_time);
 260 };
 261
 262 typedef struct PPB_URLRequestInfo_1_0 PPB_URLRequestInfo;
 263 /**
 264  * @}
 265  */
 266
 267 #endif  /* PPAPI_C_PPB_URL_REQUEST_INFO_H_ */
 268