Pepper_31_C++_interfaces
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 #ifndef PPAPI_CPP_URL_REQUEST_INFO_H_
6 #define PPAPI_CPP_URL_REQUEST_INFO_H_
7 
8 #include "ppapi/c/ppb_url_request_info.h"
9 #include "ppapi/cpp/resource.h"
10 #include "ppapi/cpp/var.h"
11 
12 /// @file
13 /// This file defines the API for creating and manipulating URL requests.
14 namespace pp {
15 
16 class FileRef;
17 class InstanceHandle;
18 
19 /// URLRequestInfo provides an API for creating and manipulating URL requests.
20 class URLRequestInfo : public Resource {
21  public:
22  /// Default constructor. This constructor creates an
23  /// <code>is_null</code> resource.
25 
26  /// A constructor used to allocate a new <code>URLLoader</code> in the
27  /// browser. The resulting object will be <code>is_null</code> if the
28  /// allocation failed.
29  ///
30  /// @param[in] instance The instance with which this resource will be
31  /// associated.
32  explicit URLRequestInfo(const InstanceHandle& instance);
33 
34  /// The copy constructor for <code>URLRequestInfo</code>.
35  ///
36  /// @param[in] other A <code>URLRequestInfo</code> to be copied.
37  URLRequestInfo(const URLRequestInfo& other);
38 
39  /// SetProperty() sets a request property. The value of the property must be
40  /// the correct type according to the property being set.
41  ///
42  /// @param[in] property A <code>PP_URLRequestProperty</code> identifying the
43  /// property to set.
44  /// @param[in] value A <code>Var</code> containing the property value.
45  ///
46  /// @return true if successful, false if any of the
47  /// parameters are invalid.
48  bool SetProperty(PP_URLRequestProperty property, const Var& value);
49 
50  /// AppendDataToBody() appends data to the request body. A content-length
51  /// request header will be automatically generated.
52  ///
53  /// @param[in] data A pointer to a buffer holding the data.
54  /// @param[in] len The length, in bytes, of the data.
55  ///
56  /// @return true if successful, false if any of the
57  /// parameters are invalid.
58  bool AppendDataToBody(const void* data, uint32_t len);
59 
60  /// AppendFileToBody() is used to append an entire file, to be uploaded, to
61  /// the request body. A content-length request header will be automatically
62  /// generated.
63  ///
64  /// @param[in] file_ref A <code>FileRef</code> containing the file
65  /// reference.
66 
67  /// @param[in] expected_last_modified_time An optional (non-zero) last
68  /// modified time stamp used to validate that the file was not modified since
69  /// the given time before it was uploaded. The upload will fail with an error
70  /// code of <code>PP_ERROR_FILECHANGED</code> if the file has been modified
71  /// since the given time. If expected_last_modified_time is 0, then no
72  /// validation is performed.
73  ///
74  /// @return true if successful, false if any of the
75  /// parameters are invalid.
76  bool AppendFileToBody(const FileRef& file_ref,
77  PP_Time expected_last_modified_time = 0);
78 
79  /// AppendFileRangeToBody() is a pointer to a function used to append part or
80  /// all of a file, to be uploaded, to the request body. A content-length
81  /// request header will be automatically generated.
82  ///
83  /// @param[in] file_ref A <code>FileRef</code> containing the file
84  /// reference.
85  /// @param[in] start_offset An optional starting point offset within the
86  /// file.
87  /// @param[in] length An optional number of bytes of the file to
88  /// be included. If the value is -1, then the sub-range to upload extends
89  /// to the end of the file.
90  /// @param[in] expected_last_modified_time An optional (non-zero) last
91  /// modified time stamp used to validate that the file was not modified since
92  /// the given time before it was uploaded. The upload will fail with an error
93  /// code of <code>PP_ERROR_FILECHANGED</code> if the file has been modified
94  /// since the given time. If expected_last_modified_time is 0, then no
95  /// validation is performed.
96  ///
97  /// @return true if successful, false if any of the
98  /// parameters are invalid.
99  bool AppendFileRangeToBody(const FileRef& file_ref,
100  int64_t start_offset,
101  int64_t length,
102  PP_Time expected_last_modified_time = 0);
103 
104  /// SetURL() sets the <code>PP_URLREQUESTPROPERTY_URL</code>
105  /// property for the request.
106  ///
107  /// @param[in] url_string A <code>Var</code> containing the property value.
108  ///
109  /// @return true if successful, false if the parameter is invalid.
110  bool SetURL(const Var& url_string) {
111  return SetProperty(PP_URLREQUESTPROPERTY_URL, url_string);
112  }
113 
114  /// SetMethod() sets the <code>PP_URLREQUESTPROPERTY_METHOD</code>
115  /// (corresponding to a string of type <code>PP_VARTYPE_STRING</code>)
116  /// property for the request. This string is either a POST or GET. Refer to
117  /// the <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html">HTTP
118  /// Methods</a> documentation for further information.
119  ///
120  /// @param[in] method_string A <code>Var</code> containing the property
121  /// value.
122  ///
123  /// @return true if successful, false if the parameter is invalid.
124  bool SetMethod(const Var& method_string) {
125  return SetProperty(PP_URLREQUESTPROPERTY_METHOD, method_string);
126  }
127 
128  /// SetHeaders() sets the <code>PP_URLREQUESTPROPERTY_HEADERS</code>
129  /// (corresponding to a <code>\n</code> delimited string of type
130  /// <code>PP_VARTYPE_STRING</code>) property for the request.
131  /// Refer to the
132  /// <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html"Header
133  /// Field Definitions</a> documentation for further information.
134  ///
135  /// @param[in] headers_string A <code>Var</code> containing the property
136  /// value.
137  ///
138  /// @return true if successful, false if the parameter is invalid.
139  bool SetHeaders(const Var& headers_string) {
140  return SetProperty(PP_URLREQUESTPROPERTY_HEADERS, headers_string);
141  }
142 
143  /// SetStreamToFile() sets the
144  /// <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> (corresponding
145  /// to a bool of type <code>PP_VARTYPE_BOOL</code>). The default of the
146  /// property is false. Set this value to true if you want to download the
147  /// data to a file. Use URL_Loader::FinishStreamingToFile() to complete
148  /// the download.
149  ///
150  /// @param[in] enable A <code>bool</code> containing the property value.
151  ///
152  /// @return true if successful, false if the parameter is invalid.
153  bool SetStreamToFile(bool enable) {
154  return SetProperty(PP_URLREQUESTPROPERTY_STREAMTOFILE, enable);
155  }
156 
157  /// SetFollowRedirects() sets the
158  /// <code>PP_URLREQUESTPROPERTY_FOLLOWREDIRECT</code> (corresponding
159  /// to a bool of type <code>PP_VARTYPE_BOOL</code>). The default of the
160  /// property is true. Set this value to false if you want to use
161  /// URLLoader::FollowRedirects() to follow the redirects only after examining
162  /// redirect headers.
163  ///
164  /// @param[in] enable A <code>bool</code> containing the property value.
165  ///
166  /// @return true if successful, false if the parameter is invalid.
167  bool SetFollowRedirects(bool enable) {
168  return SetProperty(PP_URLREQUESTPROPERTY_FOLLOWREDIRECTS, enable);
169  }
170 
171  /// SetRecordDownloadProgress() sets the
172  /// <code>PP_URLREQUESTPROPERTY_RECORDDOWNLOADPROGESS</code>
173  /// (corresponding to a bool of type <code>PP_VARTYPE_BOOL</code>). The
174  /// default of the property is false. Set this value to true if you want to
175  /// be able to poll the download progress using
176  /// URLLoader::GetDownloadProgress().
177  ///
178  /// @param[in] enable A <code>bool</code> containing the property value.
179  ////
180  /// @return true if successful, false if the parameter is invalid.
181  bool SetRecordDownloadProgress(bool enable) {
182  return SetProperty(PP_URLREQUESTPROPERTY_RECORDDOWNLOADPROGRESS, enable);
183  }
184 
185  /// SetRecordUploadProgress() sets the
186  /// <code>PP_URLREQUESTPROPERTY_RECORDUPLOADPROGRESS</code>
187  /// (corresponding to a bool of type <code>PP_VARTYPE_BOOL</code>). The
188  /// default of the property is false. Set this value to true if you want to
189  /// be able to poll the upload progress using URLLoader::GetUploadProgress().
190  ///
191  /// @param[in] enable A <code>bool</code> containing the property value.
192  ///
193  /// @return true if successful, false if the parameter is invalid.
194  bool SetRecordUploadProgress(bool enable) {
195  return SetProperty(PP_URLREQUESTPROPERTY_RECORDUPLOADPROGRESS, enable);
196  }
197 
198  /// SetCustomReferrerURL() sets the
199  /// <code>PP_URLREQUESTPROPERTY_CUSTOMREFERRERURL</code>
200  /// (corresponding to a string of type <code>PP_VARTYPE_STRING</code> or
201  /// might be set to undefined as <code>PP_VARTYPE_UNDEFINED</code>). Set it
202  /// to a string to set a custom referrer (if empty, the referrer header will
203  /// be omitted), or to undefined to use the default referrer. Only loaders
204  /// with universal access (only available on trusted implementations) will
205  /// accept <code>URLRequestInfo</code> objects that try to set a custom
206  /// referrer; if given to a loader without universal access,
207  /// <code>PP_ERROR_BADARGUMENT</code> will result.
208  ///
209  /// @param[in] url A <code>Var</code> containing the property value.
210  ///
211  /// @return true if successful, false if the parameter is invalid.
212  bool SetCustomReferrerURL(const Var& url) {
213  return SetProperty(PP_URLREQUESTPROPERTY_CUSTOMREFERRERURL, url);
214  }
215 
216  /// SetAllowCrossOriginRequests() sets the
217  /// <code>PP_URLREQUESTPROPERTY_ALLOWCROSSORIGINREQUESTS</code>
218  /// (corresponding to a bool of type <code>PP_VARTYPE_BOOL</code>). The
219  /// default of the property is false. Whether cross-origin requests are
220  /// allowed. Cross-origin requests are made using the CORS (Cross-Origin
221  /// Resource Sharing) algorithm to check whether the request should be
222  /// allowed. For the complete CORS algorithm, refer to the
223  /// <a href="http://www.w3.org/TR/access-control">Cross-Origin Resource
224  /// Sharing</a> documentation.
225  ///
226  /// @param[in] enable A <code>bool</code> containing the property value.
227  ///
228  /// @return true if successful, false if the parameter is invalid.
229  bool SetAllowCrossOriginRequests(bool enable) {
230  return SetProperty(PP_URLREQUESTPROPERTY_ALLOWCROSSORIGINREQUESTS, enable);
231  }
232 
233  /// SetAllowCredentials() sets the
234  /// <code>PP_URLREQUESTPROPERTY_ALLOWCREDENTIALS</code>
235  /// (corresponding to a bool of type <code>PP_VARTYPE_BOOL</code>). The
236  /// default of the property is false. Whether HTTP credentials are sent with
237  /// cross-origin requests. If false, no credentials are sent with the request
238  /// and cookies are ignored in the response. If the request is not
239  /// cross-origin, this property is ignored.
240  ///
241  /// @param[in] enable A <code>bool</code> containing the property value.
242  ///
243  /// @return true if successful, false if the parameter is invalid.
244  bool SetAllowCredentials(bool enable) {
245  return SetProperty(PP_URLREQUESTPROPERTY_ALLOWCREDENTIALS, enable);
246  }
247 
248  /// SetCustomContentTransferEncoding() sets the
249  /// <code>PP_URLREQUESTPROPERTY_CUSTOMCONTENTTRANSFERENCODING</code>
250  /// (corresponding to a string of type <code>PP_VARTYPE_STRING</code> or
251  /// might be set to undefined as <code>PP_VARTYPE_UNDEFINED</code>). Set it
252  /// to a string to set a custom content-transfer-encoding header (if empty,
253  /// that header will be omitted), or to undefined to use the default (if
254  /// any). Only loaders with universal access (only available on trusted
255  /// implementations) will accept <code>URLRequestInfo</code> objects that try
256  /// to set a custom content transfer encoding; if given to a loader without
257  /// universal access, <code>PP_ERROR_BADARGUMENT</code> will result.
258  ///
259  /// @param[in] content_transfer_encoding A <code>Var</code> containing the
260  /// property value. To use the default content transfer encoding, set
261  /// <code>content_transfer_encoding</code> to an undefined <code>Var</code>.
262  ///
263  /// @return true if successful, false if the parameter is invalid.
264  bool SetCustomContentTransferEncoding(const Var& content_transfer_encoding) {
265  return SetProperty(PP_URLREQUESTPROPERTY_CUSTOMCONTENTTRANSFERENCODING,
266  content_transfer_encoding);
267  }
268 
269  /// SetPrefetchBufferUpperThreshold() sets the
270  /// <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code>
271  /// (corresponding to a integer of type <code>PP_VARTYPE_INT32</code>). The
272  /// default is not defined and is set by the browser possibly depending on
273  /// system capabilities. Set it to an integer to set an upper threshold for
274  /// the prefetched buffer of an asynchronous load. When exceeded, the browser
275  /// will defer loading until
276  /// <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> is hit,
277  /// at which time it will begin prefetching again. When setting this
278  /// property,
279  /// <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> must
280  /// also be set. Behavior is undefined if the former is <= the latter.
281  ///
282  /// @param[in] size An int32_t containing the property value.
283  ///
284  /// @return true if successful, false if the parameter is invalid.
286  return SetProperty(PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD,
287  size);
288  }
289 
290  /// SetPrefetchBufferLowerThreshold() sets the
291  /// <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERTHRESHOLD</code>
292  /// (corresponding to a integer of type <code>PP_VARTYPE_INT32</code>). The
293  /// default is not defined and is set by the browser to a value appropriate
294  /// for the default
295  /// <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code>.
296  /// Set it to an integer to set a lower threshold for the prefetched buffer
297  /// of an asynchronous load. When reached, the browser will resume loading if
298  /// If <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> had
299  /// previously been reached.
300  /// When setting this property,
301  /// <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code> must also
302  /// be set. Behavior is undefined if the former is >= the latter.
303  ///
304  /// @param[in] size An int32_t containing the property value.
305  ///
306  /// @return true if successful, false if the parameter is invalid.
308  return SetProperty(PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERTHRESHOLD,
309  size);
310  }
311 
312  /// SetCustomUserAgent() sets the
313  /// <code>PP_URLREQUESTPROPERTY_CUSTOMUSERAGENT</code> (corresponding to a
314  /// string of type <code>PP_VARTYPE_STRING</code> or might be set to undefined
315  /// as <code>PP_VARTYPE_UNDEFINED</code>). Set it to a string to set a custom
316  /// user-agent header (if empty, that header will be omitted), or to undefined
317  /// to use the default. Only loaders with universal access (only available on
318  /// trusted implementations) will accept <code>URLRequestInfo</code> objects
319  /// that try to set a custom user agent; if given to a loader without
320  /// universal access, <code>PP_ERROR_BADARGUMENT</code> will result.
321  ///
322  /// @param[in] user_agent A <code>Var</code> containing the property value. To
323  /// use the default user agent, set <code>user_agent</code> to an undefined
324  /// <code>Var</code>.
325  ///
326  /// @return true if successful, false if the parameter is invalid.
327  bool SetCustomUserAgent(const Var& user_agent) {
328  return SetProperty(PP_URLREQUESTPROPERTY_CUSTOMUSERAGENT, user_agent);
329  }
330 };
331 
332 } // namespace pp
333 
334 #endif // PPAPI_CPP_URL_REQUEST_INFO_H_
bool SetStreamToFile(bool enable)
bool SetAllowCredentials(bool enable)
bool SetPrefetchBufferLowerThreshold(int32_t size)
bool SetFollowRedirects(bool enable)
bool AppendFileRangeToBody(const FileRef &file_ref, int64_t start_offset, int64_t length, PP_Time expected_last_modified_time=0)
bool SetHeaders(const Var &headers_string)
bool SetCustomReferrerURL(const Var &url)
bool SetAllowCrossOriginRequests(bool enable)
bool AppendFileToBody(const FileRef &file_ref, PP_Time expected_last_modified_time=0)
bool SetCustomContentTransferEncoding(const Var &content_transfer_encoding)
bool SetCustomUserAgent(const Var &user_agent)
bool SetRecordUploadProgress(bool enable)
bool SetPrefetchBufferUpperThreshold(int32_t size)
bool SetRecordDownloadProgress(bool enable)
URLRequestInfo provides an API for creating and manipulating URL requests.
bool SetMethod(const Var &method_string)
bool AppendDataToBody(const void *data, uint32_t len)
A generic type used for passing data types between the module and the page.
Definition: var.h:20
bool SetProperty(PP_URLRequestProperty property, const Var &value)
A reference counted module resource.
Definition: resource.h:18
bool SetURL(const Var &url_string)