Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 6 | /* From ppb_url_request_info.idl modified Thu Mar 28 10:19:35 2013. */ |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 51 | * Field Definitions</a> documentation for further information. |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 81 | * PPB_URLLoader.GetUploadProgress(). |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |