blob: e6c7301afcbf088b9e03575d67e7009312053753 [file] [log] [blame]
[email protected]84d5b452011-04-14 16:51:251/* Copyright (c) 2011 The Chromium Authors. All rights reserved.
[email protected]6ea69542010-12-20 18:15:592 * Use of this source code is governed by a BSD-style license that can be
3 * found in the LICENSE file.
4 */
[email protected]9b37f4802011-07-19 00:09:285
[email protected]49aa13872011-08-17 20:45:576/* From ppb_url_request_info.idl modified Mon Aug 15 11:01:06 2011. */
[email protected]9b37f4802011-07-19 00:09:287
[email protected]5a3f62852010-11-10 21:43:018#ifndef PPAPI_C_PPB_URL_REQUEST_INFO_H_
9#define PPAPI_C_PPB_URL_REQUEST_INFO_H_
[email protected]1758e882010-11-01 16:16:5010
[email protected]6f2e3912010-11-05 14:45:4411#include "ppapi/c/pp_bool.h"
[email protected]859a7f32011-01-15 03:44:1312#include "ppapi/c/pp_instance.h"
[email protected]1ad2a1db2010-12-13 20:04:3113#include "ppapi/c/pp_macros.h"
[email protected]1758e882010-11-01 16:16:5014#include "ppapi/c/pp_resource.h"
15#include "ppapi/c/pp_stdint.h"
16#include "ppapi/c/pp_time.h"
[email protected]b2b420d72011-07-12 00:59:3117#include "ppapi/c/pp_var.h"
[email protected]1758e882010-11-01 16:16:5018
[email protected]49aa13872011-08-17 20:45:5719#define PPB_URLREQUESTINFO_INTERFACE_0_2 "PPB_URLRequestInfo;0.2"
20#define PPB_URLREQUESTINFO_INTERFACE_1_0 "PPB_URLRequestInfo;1.0"
21#define PPB_URLREQUESTINFO_INTERFACE PPB_URLREQUESTINFO_INTERFACE_1_0
22
[email protected]040d5e82011-01-28 15:38:3823/**
24 * @file
[email protected]8dd1f5772011-07-06 15:37:2825 * This file defines the <code>PPB_URLRequestInfo</code> API for creating and
26 * manipulating URL requests.
[email protected]040d5e82011-01-28 15:38:3827 */
28
[email protected]9b37f4802011-07-19 00:09:2829
[email protected]040d5e82011-01-28 15:38:3830/**
[email protected]040d5e82011-01-28 15:38:3831 * @addtogroup Enums
32 * @{
33 */
[email protected]897cddd2011-04-19 17:30:1534/**
35 * This enumeration contains properties that can be set on a URL request.
36 */
37typedef enum {
[email protected]8dd1f5772011-07-06 15:37:2838 /** This corresponds to a string (<code>PP_VARTYPE_STRING</code>). */
[email protected]897cddd2011-04-19 17:30:1539 PP_URLREQUESTPROPERTY_URL,
[email protected]897cddd2011-04-19 17:30:1540 /**
[email protected]8dd1f5772011-07-06 15:37:2841 * This corresponds to a string (<code>PP_VARTYPE_STRING</code>); either
42 * POST or GET. Refer to the
[email protected]897cddd2011-04-19 17:30:1543 * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html">HTTP
44 * Methods</a> documentation for further information.
45 *
46 */
47 PP_URLREQUESTPROPERTY_METHOD,
[email protected]897cddd2011-04-19 17:30:1548 /**
[email protected]8dd1f5772011-07-06 15:37:2849 * This corresponds to a string (<code>PP_VARTYPE_STRING</code>); \n
50 * delimited. Refer to the
[email protected]897cddd2011-04-19 17:30:1551 * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html"Header
52 * Field Definitions</a> documentaiton for further information.
53 */
54 PP_URLREQUESTPROPERTY_HEADERS,
[email protected]897cddd2011-04-19 17:30:1555 /**
[email protected]8dd1f5772011-07-06 15:37:2856 * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
57 * default=<code>PP_FALSE</code>).
58 * Set this value to <code>PP_TRUE</code> if you want to download the data
59 * to a file. Use PPB_URLLoader.FinishStreamingToFile() to complete the
60 * download.
[email protected]897cddd2011-04-19 17:30:1561 */
62 PP_URLREQUESTPROPERTY_STREAMTOFILE,
[email protected]897cddd2011-04-19 17:30:1563 /**
[email protected]8dd1f5772011-07-06 15:37:2864 * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
65 * default=<code>PP_TRUE</code>).
66 * Set this value to <code>PP_FALSE</code> if you want to use
[email protected]897cddd2011-04-19 17:30:1567 * PPB_URLLoader.FollowRedirects() to follow the redirects only after
68 * examining redirect headers.
69 */
70 PP_URLREQUESTPROPERTY_FOLLOWREDIRECTS,
[email protected]897cddd2011-04-19 17:30:1571 /**
[email protected]8dd1f5772011-07-06 15:37:2872 * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
73 * default=<code>PP_FALSE</code>).
74 * Set this value to <code>PP_TRUE</code> if you want to be able to poll the
75 * download progress using PPB_URLLoader.GetDownloadProgress().
[email protected]897cddd2011-04-19 17:30:1576 */
[email protected]51df0c712010-11-04 19:39:2977 PP_URLREQUESTPROPERTY_RECORDDOWNLOADPROGRESS,
[email protected]897cddd2011-04-19 17:30:1578 /**
[email protected]e6ce5e422011-08-15 17:23:1479 * This corresponds to a <code>PP_Bool</code>
80 * (default=<code>PP_FALSE</code>). Set this value to <code>PP_TRUE</code> if
81 * you want to be able to poll the upload progress using
82 * PPB_URLLoader.GetUplaodProgress().
[email protected]897cddd2011-04-19 17:30:1583 */
[email protected]5349184c2011-03-14 17:19:4984 PP_URLREQUESTPROPERTY_RECORDUPLOADPROGRESS,
[email protected]37ac29a2011-04-21 20:11:4485 /**
[email protected]8dd1f5772011-07-06 15:37:2886 * This corresponds to a string (<code>PP_VARTYPE_STRING)</code> or may be
87 * undefined (<code>PP_VARTYPE_UNDEFINED</code>; default).
[email protected]37ac29a2011-04-21 20:11:4488 * Set it to a string to set a custom referrer (if empty, the referrer header
89 * will be omitted), or to undefined to use the default referrer. Only loaders
90 * with universal access (only available on trusted implementations) will
[email protected]8dd1f5772011-07-06 15:37:2891 * accept <code>URLRequestInfo</code> objects that try to set a custom
92 * referrer; if given to a loader without universal access,
93 * <code>PP_ERROR_BADARGUMENT</code> will result.
[email protected]37ac29a2011-04-21 20:11:4494 */
[email protected]84d5b452011-04-14 16:51:2595 PP_URLREQUESTPROPERTY_CUSTOMREFERRERURL,
[email protected]37ac29a2011-04-21 20:11:4496 /**
[email protected]8dd1f5772011-07-06 15:37:2897 * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
98 * default=<code>PP_FALSE</code>). Whether cross-origin requests are allowed.
99 * Cross-origin requests are made using the CORS (Cross-Origin Resource
100 * Sharing) algorithm to check whether the request should be allowed. For the
101 * complete CORS algorithm, refer to
[email protected]37ac29a2011-04-21 20:11:44102 * the <a href="http://www.w3.org/TR/access-control">Cross-Origin Resource
103 * Sharing</a> documentation.
104 */
[email protected]84d5b452011-04-14 16:51:25105 PP_URLREQUESTPROPERTY_ALLOWCROSSORIGINREQUESTS,
[email protected]37ac29a2011-04-21 20:11:44106 /**
[email protected]8dd1f5772011-07-06 15:37:28107 * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
108 * default=<code>PP_FALSE</code>).
[email protected]37ac29a2011-04-21 20:11:44109 * Whether HTTP credentials are sent with cross-origin requests. If false,
110 * no credentials are sent with the request and cookies are ignored in the
111 * response. If the request is not cross-origin, this property is ignored.
112 */
113 PP_URLREQUESTPROPERTY_ALLOWCREDENTIALS,
[email protected]37ac29a2011-04-21 20:11:44114 /**
[email protected]8dd1f5772011-07-06 15:37:28115 * This corresponds to a string (<code>PP_VARTYPE_STRING</code>) or may be
116 * undefined (<code>PP_VARTYPE_UNDEFINED</code>; default).
[email protected]37ac29a2011-04-21 20:11:44117 * Set it to a string to set a custom content-transfer-encoding header (if
[email protected]8dd1f5772011-07-06 15:37:28118 * empty, that header will be omitted), or to undefined to use the default
119 * (if any). Only loaders with universal access (only available on trusted
120 * implementations) will accept <code>URLRequestInfo</code> objects that try
121 * to set a custom content transfer encoding; if given to a loader without
122 * universal access, <code>PP_ERROR_BADARGUMENT</code> will result.
[email protected]37ac29a2011-04-21 20:11:44123 */
[email protected]80c71de22011-05-04 16:19:14124 PP_URLREQUESTPROPERTY_CUSTOMCONTENTTRANSFERENCODING,
[email protected]80c71de22011-05-04 16:19:14125 /**
[email protected]8dd1f5772011-07-06 15:37:28126 * This corresponds to an integer (<code>PP_VARTYPE_INT32</code>); default
127 * is not defined and is set by the browser, possibly depending on system
128 * capabilities. Set it to an integer to set an upper threshold for the
129 * prefetched buffer of an asynchronous load. When exceeded, the browser will
130 * defer loading until
131 * <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> is hit,
132 * at which time it will begin prefetching again. When setting this property,
133 * <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> must also
134 * be set. Behavior is undefined if the former is <= the latter.
[email protected]80c71de22011-05-04 16:19:14135 */
136 PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD,
[email protected]80c71de22011-05-04 16:19:14137 /**
[email protected]8dd1f5772011-07-06 15:37:28138 * This corresponds to an integer (<code>PP_VARTYPE_INT32</code>); default is
139 * not defined and is set by the browser to a value appropriate for the
140 * default <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code>.
[email protected]80c71de22011-05-04 16:19:14141 * Set it to an integer to set a lower threshold for the prefetched buffer
142 * of an asynchronous load. When reached, the browser will resume loading if
[email protected]8dd1f5772011-07-06 15:37:28143 * If <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> had
144 * previously been reached.
[email protected]80c71de22011-05-04 16:19:14145 * When setting this property,
[email protected]8dd1f5772011-07-06 15:37:28146 * <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code> must also
147 * be set. Behavior is undefined if the former is >= the latter.
[email protected]80c71de22011-05-04 16:19:14148 */
149 PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERTHRESHOLD
[email protected]5a3f62852010-11-10 21:43:01150} PP_URLRequestProperty;
[email protected]1ad2a1db2010-12-13 20:04:31151PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_URLRequestProperty, 4);
[email protected]040d5e82011-01-28 15:38:38152/**
153 * @}
154 */
[email protected]51df0c712010-11-04 19:39:29155
[email protected]040d5e82011-01-28 15:38:38156/**
[email protected]040d5e82011-01-28 15:38:38157 * @addtogroup Interfaces
158 * @{
159 */
[email protected]897cddd2011-04-19 17:30:15160/**
[email protected]8dd1f5772011-07-06 15:37:28161 * The <code>PPB_URLRequestInfo</code> interface is used to create
162 * and handle URL requests. This API is used in conjunction with
[email protected]e6ce5e422011-08-15 17:23:14163 * <code>PPB_URLLoader</code>. Refer to <code>PPB_URLLoader</code> for further
[email protected]8dd1f5772011-07-06 15:37:28164 * information.
[email protected]897cddd2011-04-19 17:30:15165 */
[email protected]5a3f62852010-11-10 21:43:01166struct PPB_URLRequestInfo {
[email protected]897cddd2011-04-19 17:30:15167 /**
[email protected]8dd1f5772011-07-06 15:37:28168 * Create() creates a new <code>URLRequestInfo</code> object.
[email protected]897cddd2011-04-19 17:30:15169 *
[email protected]8dd1f5772011-07-06 15:37:28170 * @param[in] instance A <code>PP_Instance</code> indentifying 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.
[email protected]897cddd2011-04-19 17:30:15175 */
[email protected]859a7f32011-01-15 03:44:13176 PP_Resource (*Create)(PP_Instance instance);
[email protected]897cddd2011-04-19 17:30:15177 /**
[email protected]8dd1f5772011-07-06 15:37:28178 * IsURLRequestInfo() determines if a resource is a
179 * <code>URLRequestInfo</code>.
[email protected]897cddd2011-04-19 17:30:15180 *
[email protected]8dd1f5772011-07-06 15:37:28181 * @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>.
[email protected]897cddd2011-04-19 17:30:15187 */
[email protected]6f2e3912010-11-05 14:45:44188 PP_Bool (*IsURLRequestInfo)(PP_Resource resource);
[email protected]897cddd2011-04-19 17:30:15189 /**
[email protected]8dd1f5772011-07-06 15:37:28190 * SetProperty() sets a request property. The value of the property must be
191 * the correct type according to the property being set.
[email protected]897cddd2011-04-19 17:30:15192 *
[email protected]8dd1f5772011-07-06 15:37:28193 * @param[in] request A <code>PP_Resource</code> corresponding to a
194 * <code>URLRequestInfo</code>.
195 * @param[in] property A <code>PP_URLRequestProperty</code> identifying the
[email protected]897cddd2011-04-19 17:30:15196 * property to set.
[email protected]8dd1f5772011-07-06 15:37:28197 * @param[in] value A <code>PP_Var</code> containing the property value.
198 *
199 * @return <code>PP_TRUE</code> if successful, <code>PP_FALSE</code> if any
200 * of the parameters are invalid.
[email protected]897cddd2011-04-19 17:30:15201 */
[email protected]6f2e3912010-11-05 14:45:44202 PP_Bool (*SetProperty)(PP_Resource request,
[email protected]5a3f62852010-11-10 21:43:01203 PP_URLRequestProperty property,
[email protected]6f2e3912010-11-05 14:45:44204 struct PP_Var value);
[email protected]897cddd2011-04-19 17:30:15205 /**
[email protected]8dd1f5772011-07-06 15:37:28206 * AppendDataToBody() appends data to the request body. A Content-Length
207 * request header will be automatically generated.
[email protected]897cddd2011-04-19 17:30:15208 *
[email protected]8dd1f5772011-07-06 15:37:28209 * @param[in] request A <code>PP_Resource</code> corresponding to a
210 * <code>URLRequestInfo</code>.
[email protected]897cddd2011-04-19 17:30:15211 * @param[in] data A pointer to a buffer holding the data.
212 * @param[in] len The length, in bytes, of the data.
[email protected]8dd1f5772011-07-06 15:37:28213 *
214 * @return <code>PP_TRUE</code> if successful, <code>PP_FALSE</code> if any
215 * of the parameters are invalid.
[email protected]897cddd2011-04-19 17:30:15216 *
217 *
218 */
[email protected]6f2e3912010-11-05 14:45:44219 PP_Bool (*AppendDataToBody)(PP_Resource request,
[email protected]748ce712011-03-28 22:15:13220 const void* data,
[email protected]6f2e3912010-11-05 14:45:44221 uint32_t len);
[email protected]897cddd2011-04-19 17:30:15222 /**
[email protected]8dd1f5772011-07-06 15:37:28223 * AppendFileToBody() appends a file, to be uploaded, to the request body.
224 * A content-length request header will be automatically generated.
[email protected]897cddd2011-04-19 17:30:15225 *
[email protected]8dd1f5772011-07-06 15:37:28226 * @param[in] request A <code>PP_Resource</code> corresponding to a
227 * <code>URLRequestInfo</code>.
228 * @param[in] file_ref A <code>PP_Resource</code> containing the file
229 * reference.
[email protected]897cddd2011-04-19 17:30:15230 * @param[in] start_offset An optional starting point offset within the
231 * file.
232 * @param[in] number_of_bytes An optional number of bytes of the file to
[email protected]8dd1f5772011-07-06 15:37:28233 * be included. If <code>number_of_bytes</code> is -1, then the sub-range
234 * to upload extends to the end of the file.
[email protected]897cddd2011-04-19 17:30:15235 * @param[in] expected_last_modified_time An optional (non-zero) last
236 * modified time stamp used to validate that the file was not modified since
237 * the given time before it was uploaded. The upload will fail with an error
[email protected]8dd1f5772011-07-06 15:37:28238 * code of <code>PP_ERROR_FILECHANGED</code> if the file has been modified
239 * since the given time. If <code>expected_last_modified_time</code> is 0,
240 * then no validation is performed.
241 *
242 * @return <code>PP_TRUE</code> if successful, <code>PP_FALSE</code> if any
243 * of the parameters are invalid.
[email protected]897cddd2011-04-19 17:30:15244 */
[email protected]6f2e3912010-11-05 14:45:44245 PP_Bool (*AppendFileToBody)(PP_Resource request,
246 PP_Resource file_ref,
247 int64_t start_offset,
248 int64_t number_of_bytes,
249 PP_Time expected_last_modified_time);
[email protected]1758e882010-11-01 16:16:50250};
[email protected]040d5e82011-01-28 15:38:38251/**
252 * @}
253 */
[email protected]1758e882010-11-01 16:16:50254
[email protected]6ea69542010-12-20 18:15:59255#endif /* PPAPI_C_PPB_URL_REQUEST_INFO_H_ */
256