/* Copyright (c) 2012 The Chromium Authors. All rights reserved.
* Use of this source code is governed by a BSD-style license that can be
* found in the LICENSE file.
*/
/**
* This file defines the PPB_URLRequestInfo
API for creating and
* manipulating URL requests.
*/
[generate_thunk]
label Chrome {
M14 = 1.0
};
/**
* This enumeration contains properties that can be set on a URL request.
*/
[assert_size(4)]
enum PP_URLRequestProperty {
/** This corresponds to a string (PP_VARTYPE_STRING
). */
PP_URLREQUESTPROPERTY_URL = 0,
/**
* This corresponds to a string (PP_VARTYPE_STRING
); either
* POST or GET. Refer to the
* HTTP
* Methods documentation for further information.
*
*/
PP_URLREQUESTPROPERTY_METHOD = 1,
/**
* This corresponds to a string (PP_VARTYPE_STRING
); \n
* delimited. Refer to the
* documentation for further information.
*/
PP_URLREQUESTPROPERTY_HEADERS = 2,
/**
* This corresponds to a PP_Bool
(PP_VARTYPE_BOOL
;
* default=PP_FALSE
).
* Set this value to PP_TRUE
if you want to download the data
* to a file. Use PPB_URLLoader.FinishStreamingToFile() to complete the
* download.
*/
PP_URLREQUESTPROPERTY_STREAMTOFILE = 3,
/**
* This corresponds to a PP_Bool
(PP_VARTYPE_BOOL
;
* default=PP_TRUE
).
* Set this value to PP_FALSE
if you want to use
* PPB_URLLoader.FollowRedirects() to follow the redirects only after
* examining redirect headers.
*/
PP_URLREQUESTPROPERTY_FOLLOWREDIRECTS = 4,
/**
* This corresponds to a PP_Bool
(PP_VARTYPE_BOOL
;
* default=PP_FALSE
).
* Set this value to PP_TRUE
if you want to be able to poll the
* download progress using PPB_URLLoader.GetDownloadProgress().
*/
PP_URLREQUESTPROPERTY_RECORDDOWNLOADPROGRESS = 5,
/**
* This corresponds to a PP_Bool
* (default=PP_FALSE
). Set this value to PP_TRUE
if
* you want to be able to poll the upload progress using
* PPB_URLLoader.GetUploadProgress().
*/
PP_URLREQUESTPROPERTY_RECORDUPLOADPROGRESS = 6,
/**
* This corresponds to a string (PP_VARTYPE_STRING)
or may be
* undefined (PP_VARTYPE_UNDEFINED
; default).
* Set it to a string to set a custom referrer (if empty, the referrer header
* will be omitted), or to undefined to use the default referrer. Only loaders
* with universal access (only available on trusted implementations) will
* accept URLRequestInfo
objects that try to set a custom
* referrer; if given to a loader without universal access,
* PP_ERROR_NOACCESS
will result.
*/
PP_URLREQUESTPROPERTY_CUSTOMREFERRERURL = 7,
/**
* This corresponds to a PP_Bool
(PP_VARTYPE_BOOL
;
* default=PP_FALSE
). Whether cross-origin requests are allowed.
* Cross-origin requests are made using the CORS (Cross-Origin Resource
* Sharing) algorithm to check whether the request should be allowed. For the
* complete CORS algorithm, refer to
* the Cross-Origin Resource
* Sharing documentation.
*/
PP_URLREQUESTPROPERTY_ALLOWCROSSORIGINREQUESTS = 8,
/**
* This corresponds to a PP_Bool
(PP_VARTYPE_BOOL
;
* default=PP_FALSE
).
* Whether HTTP credentials are sent with cross-origin requests. If false,
* no credentials are sent with the request and cookies are ignored in the
* response. If the request is not cross-origin, this property is ignored.
*/
PP_URLREQUESTPROPERTY_ALLOWCREDENTIALS = 9,
/**
* This corresponds to a string (PP_VARTYPE_STRING
) or may be
* undefined (PP_VARTYPE_UNDEFINED
; default).
* Set it to a string to set a custom content-transfer-encoding header (if
* empty, that header will be omitted), or to undefined to use the default
* (if any). Only loaders with universal access (only available on trusted
* implementations) will accept URLRequestInfo
objects that try
* to set a custom content transfer encoding; if given to a loader without
* universal access, PP_ERROR_NOACCESS
will result.
*/
PP_URLREQUESTPROPERTY_CUSTOMCONTENTTRANSFERENCODING = 10,
/**
* This corresponds to an integer (PP_VARTYPE_INT32
); default
* is not defined and is set by the browser, possibly depending on system
* capabilities. Set it to an integer to set an upper threshold for the
* prefetched buffer of an asynchronous load. When exceeded, the browser will
* defer loading until
* PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD
is hit,
* at which time it will begin prefetching again. When setting this property,
* PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD
must also
* be set. Behavior is undefined if the former is <= the latter.
*/
PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD = 11,
/**
* This corresponds to an integer (PP_VARTYPE_INT32
); default is
* not defined and is set by the browser to a value appropriate for the
* default PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD
.
* Set it to an integer to set a lower threshold for the prefetched buffer
* of an asynchronous load. When reached, the browser will resume loading if
* If PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD
had
* previously been reached.
* When setting this property,
* PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD
must also
* be set. Behavior is undefined if the former is >= the latter.
*/
PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERTHRESHOLD = 12,
/**
* This corresponds to a string (PP_VARTYPE_STRING
) or may be
* undefined (PP_VARTYPE_UNDEFINED
; default). Set it to a string
* to set a custom user-agent header (if empty, that header will be omitted),
* or to undefined to use the default. Only loaders with universal access
* (only available on trusted implementations) will accept
* URLRequestInfo
objects that try to set a custom user agent; if
* given to a loader without universal access, PP_ERROR_NOACCESS
* will result.
*/
PP_URLREQUESTPROPERTY_CUSTOMUSERAGENT = 13
};
/**
* The PPB_URLRequestInfo
interface is used to create
* and handle URL requests. This API is used in conjunction with
* PPB_URLLoader
. Refer to PPB_URLLoader
for further
* information.
*/
interface PPB_URLRequestInfo {
/**
* Create() creates a new URLRequestInfo
object.
*
* @param[in] instance A PP_Instance
identifying one instance
* of a module.
*
* @return A PP_Resource
identifying the
* URLRequestInfo
if successful, 0 if the instance is invalid.
*/
PP_Resource Create(
[in] PP_Instance instance);
/**
* IsURLRequestInfo() determines if a resource is a
* URLRequestInfo
.
*
* @param[in] resource A PP_Resource
corresponding to a
* URLRequestInfo
.
*
* @return PP_TRUE
if the resource is a
* URLRequestInfo
, PP_FALSE
if the resource is
* invalid or some type other than URLRequestInfo
.
*/
PP_Bool IsURLRequestInfo(
[in] PP_Resource resource);
/**
* SetProperty() sets a request property. The value of the property must be
* the correct type according to the property being set.
*
* @param[in] request A PP_Resource
corresponding to a
* URLRequestInfo
.
* @param[in] property A PP_URLRequestProperty
identifying the
* property to set.
* @param[in] value A PP_Var
containing the property value.
*
* @return PP_TRUE
if successful, PP_FALSE
if any
* of the parameters are invalid.
*/
PP_Bool SetProperty(
[in] PP_Resource request,
[in] PP_URLRequestProperty property,
[in] PP_Var value);
/**
* AppendDataToBody() appends data to the request body. A Content-Length
* request header will be automatically generated.
*
* @param[in] request A PP_Resource
corresponding to a
* URLRequestInfo
.
* @param[in] data A pointer to a buffer holding the data.
* @param[in] len The length, in bytes, of the data.
*
* @return PP_TRUE
if successful, PP_FALSE
if any
* of the parameters are invalid.
*
*
*/
PP_Bool AppendDataToBody(
[in] PP_Resource request,
[in] mem_t data,
[in] uint32_t len);
/**
* AppendFileToBody() appends a file, to be uploaded, to the request body.
* A content-length request header will be automatically generated.
*
* @param[in] request A PP_Resource
corresponding to a
* URLRequestInfo
.
* @param[in] file_ref A PP_Resource
corresponding to a file
* reference.
* @param[in] start_offset An optional starting point offset within the
* file.
* @param[in] number_of_bytes An optional number of bytes of the file to
* be included. If number_of_bytes
is -1, then the sub-range
* to upload extends to the end of the file.
* @param[in] expected_last_modified_time An optional (non-zero) last
* modified time stamp used to validate that the file was not modified since
* the given time before it was uploaded. The upload will fail with an error
* code of PP_ERROR_FILECHANGED
if the file has been modified
* since the given time. If expected_last_modified_time
is 0,
* then no validation is performed.
*
* @return PP_TRUE
if successful, PP_FALSE
if any
* of the parameters are invalid.
*/
PP_Bool AppendFileToBody(
[in] PP_Resource request,
[in] PP_Resource file_ref,
[in] int64_t start_offset,
[in] int64_t number_of_bytes,
[in] PP_Time expected_last_modified_time);
};