ppb_url_request_info.idl

/* Copyright (c) 2011 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 <code>PPB_URLRequestInfo</code> API for creating and
 * manipulating URL requests.
 */

label Chrome {
  M13 = 0.2,
  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 (<code>PP_VARTYPE_STRING</code>). */
  PP_URLREQUESTPROPERTY_URL,

  /**
   * This corresponds to a string (<code>PP_VARTYPE_STRING</code>); either
   * POST or GET. Refer to the
   * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec5.html">HTTP
   * Methods</a> documentation for further information.
   *
   */
  PP_URLREQUESTPROPERTY_METHOD,

  /**
   * This corresponds to a string (<code>PP_VARTYPE_STRING</code>); \n
   * delimited. Refer to the
   * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html"Header
   * Field Definitions</a> documentaiton for further information.
   */
  PP_URLREQUESTPROPERTY_HEADERS,

  /**
   * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
   * default=<code>PP_FALSE</code>).
   * Set this value to <code>PP_TRUE</code> if you want to download the data
   * to a file. Use PPB_URLLoader.FinishStreamingToFile() to complete the
   * download.
   */
  PP_URLREQUESTPROPERTY_STREAMTOFILE,

  /**
   * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
   * default=<code>PP_TRUE</code>).
   * Set this value to <code>PP_FALSE</code> if you want to use
   * PPB_URLLoader.FollowRedirects() to follow the redirects only after
   * examining redirect headers.
   */
  PP_URLREQUESTPROPERTY_FOLLOWREDIRECTS,

  /**
   * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
   * default=<code>PP_FALSE</code>).
   * Set this value to <code>PP_TRUE</code> if you want to be able to poll the
   * download progress using PPB_URLLoader.GetDownloadProgress().
   */
  PP_URLREQUESTPROPERTY_RECORDDOWNLOADPROGRESS,

  /**
   * This corresponds to a <code>PP_Bool</code>
   * (default=<code>PP_FALSE</code>). Set this value to <code>PP_TRUE</code> if
   * you want to be able to poll the upload progress using
   * PPB_URLLoader.GetUplaodProgress().
   */
  PP_URLREQUESTPROPERTY_RECORDUPLOADPROGRESS,

  /**
   * This corresponds to a string (<code>PP_VARTYPE_STRING)</code> or may be
   * undefined (<code>PP_VARTYPE_UNDEFINED</code>; 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 <code>URLRequestInfo</code> objects that try to set a custom
   * referrer; if given to a loader without universal access,
   * <code>PP_ERROR_BADARGUMENT</code> will result.
   */
  PP_URLREQUESTPROPERTY_CUSTOMREFERRERURL,

  /**
   * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
   * default=<code>PP_FALSE</code>). 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 <a href="http://www.w3.org/TR/access-control">Cross-Origin Resource
   * Sharing</a> documentation.
   */
  PP_URLREQUESTPROPERTY_ALLOWCROSSORIGINREQUESTS,

  /**
   * This corresponds to a <code>PP_Bool</code> (<code>PP_VARTYPE_BOOL</code>;
   * default=<code>PP_FALSE</code>).
   * 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,

  /**
   * This corresponds to a string (<code>PP_VARTYPE_STRING</code>) or may be
   * undefined (<code>PP_VARTYPE_UNDEFINED</code>; 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 <code>URLRequestInfo</code> objects that try
   * to set a custom content transfer encoding; if given to a loader without
   * universal access, <code>PP_ERROR_BADARGUMENT</code> will result.
   */
  PP_URLREQUESTPROPERTY_CUSTOMCONTENTTRANSFERENCODING,

  /**
   * This corresponds to an integer (<code>PP_VARTYPE_INT32</code>); 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
   * <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> is hit,
   * at which time it will begin prefetching again. When setting this property,
   * <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> must also
   * be set. Behavior is undefined if the former is <= the latter.
   */
  PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD,

  /**
   * This corresponds to an integer (<code>PP_VARTYPE_INT32</code>); default is
   * not defined and is set by the browser to a value appropriate for the
   * default <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code>.
   * 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 <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERERTHRESHOLD</code> had
   * previously been reached.
   * When setting this property,
   * <code>PP_URLREQUESTPROPERTY_PREFETCHBUFFERUPPERTHRESHOLD</code> must also
   * be set. Behavior is undefined if the former is >= the latter.
   */
  PP_URLREQUESTPROPERTY_PREFETCHBUFFERLOWERTHRESHOLD
};

/**
 * The <code>PPB_URLRequestInfo</code> interface is used to create
 * and handle URL requests. This API is used in conjunction with
 * <code>PPB_URLLoader</code>. Refer to <code>PPB_URLLoader</code> for further
 * information.
 */
interface PPB_URLRequestInfo {
  /**
   * Create() creates a new <code>URLRequestInfo</code> object.
   *
   * @param[in] instance A <code>PP_Instance</code> indentifying one instance
   * of a module.
   *
   * @return A <code>PP_Resource</code> identifying the
   * <code>URLRequestInfo</code> if successful, 0 if the instance is invalid.
   */
  PP_Resource Create(
      [in] PP_Instance instance);

  /**
   * IsURLRequestInfo() determines if a resource is a
   * <code>URLRequestInfo</code>.
   *
   * @param[in] resource A <code>PP_Resource</code> corresponding to a
   * <code>URLRequestInfo</code>.
   *
   * @return <code>PP_TRUE</code> if the resource is a
   * <code>URLRequestInfo</code>, <code>PP_FALSE</code> if the resource is
   * invalid or some type other than <code>URLRequestInfo</code>.
   */
  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 <code>PP_Resource</code> corresponding to a
   * <code>URLRequestInfo</code>.
   * @param[in] property A <code>PP_URLRequestProperty</code> identifying the
   * property to set.
   * @param[in] value A <code>PP_Var</code> containing the property value.
   *
   * @return <code>PP_TRUE</code> if successful, <code>PP_FALSE</code> 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 <code>PP_Resource</code> corresponding to a
   * <code>URLRequestInfo</code>.
   * @param[in] data A pointer to a buffer holding the data.
   * @param[in] len The length, in bytes, of the data.
   *
   * @return <code>PP_TRUE</code> if successful, <code>PP_FALSE</code> 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 <code>PP_Resource</code> corresponding to a
   * <code>URLRequestInfo</code>.
   * @param[in] file_ref A <code>PP_Resource</code> containing the 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 <code>number_of_bytes</code> 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 <code>PP_ERROR_FILECHANGED</code> if the file has been modified
   * since the given time. If <code>expected_last_modified_time</code> is 0,
   * then no validation is performed.
   *
   * @return <code>PP_TRUE</code> if successful, <code>PP_FALSE</code> 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);
};