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