ppapi/cpp/url_request_info.h

   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.
  24   URLRequestInfo() {}
  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.
 285   bool SetPrefetchBufferUpperThreshold(int32_t size) {
 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.
 307   bool SetPrefetchBufferLowerThreshold(int32_t size) {
 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_