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