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 269