Pepper_31_C_interfaces
ppb_url_request_info.h
Go to the documentation of this file.
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>). */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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 
263 /**
264  * @}
265  */
266 
267 #endif /* PPAPI_C_PPB_URL_REQUEST_INFO_H_ */
268 
PP_URLRequestProperty
double PP_Time
Definition: pp_time.h:29
PP_Resource(* Create)(PP_Instance instance)
PP_COMPILE_ASSERT_SIZE_IN_BYTES(PP_URLRequestProperty, 4)
PP_Bool(* IsURLRequestInfo)(PP_Resource resource)
int32_t PP_Resource
Definition: pp_resource.h:40
PP_Bool(* SetProperty)(PP_Resource request, PP_URLRequestProperty property, struct PP_Var value)
union PP_VarValue value
Definition: pp_var.h:169
Definition: pp_var.h:155
int32_t PP_Instance
Definition: pp_instance.h:34
PP_Bool
Definition: pp_bool.h:30
PP_Bool(* AppendDataToBody)(PP_Resource request, const void *data, uint32_t len)
PP_Bool(* AppendFileToBody)(PP_Resource request, PP_Resource file_ref, int64_t start_offset, int64_t number_of_bytes, PP_Time expected_last_modified_time)