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 261
