/* 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 <strong>PPB_URLLoader</strong> interface for loading
 * URLs.
 */

label Chrome {
  M14 = 1.0
};

/**
 * The <strong>PPB_URLLoader</strong> interface contains pointers to functions
 * for loading URLs. The typical steps for loading a URL are:
 *
 * -# Call Create() to create a URLLoader object.
 * -# Create a <code>URLRequestInfo</code> object and set properties on it.
 * Refer to <code>PPB_URLRequestInfo</code> for further information.
 * -# Call Open() with the <code>URLRequestInfo</code> as an argument.
 * -# When Open() completes, call GetResponseInfo() to examine the response
 * headers. Refer to <code>PPB_URLResponseInfo</code> for further information.
 * -# Call ReadResponseBody() to stream the data for the response.
 *
 * Alternatively, if <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set on
 * the <code>URLRequestInfo</code> in step #2:
 * - Call FinishStreamingToFile(), after examining the response headers
 * (step #4),  to wait for the downloaded file to be complete.
 * - Then, access the downloaded file using the GetBodyAsFileRef() function of
 * the <code>URLResponseInfo</code> returned in step #4.
 */
interface PPB_URLLoader {
  /**
   * Create() creates a new <code>URLLoader</code> object. The
   * <code>URLLoader</code> is associated with a particular instance, so that
   * any UI dialogs that need to be shown to the user can be positioned
   * relative to the window containing the instance.
   *
   * @param[in] instance A <code>PP_Instance</code> identifying one instance
   * of a module.
   *
   * @return A <code>PP_Resource</code> corresponding to a URLLoader if
   * successful, 0 if the instance is invalid.
   */
  PP_Resource Create(
      [in] PP_Instance instance);

  /**
   * IsURLLoader() determines if a resource is an <code>URLLoader</code>.
   *
   * @param[in] resource A <code>PP_Resource</code> corresponding to a
   * <code>URLLoader</code>.
   *
   * @return <code>PP_TRUE</code> if the resource is a <code>URLLoader</code>,
   * <code>PP_FALSE</code> if the resource is invalid or some type other
   * than <code>URLLoader</code>.
   */
  PP_Bool IsURLLoader(
      [in] PP_Resource resource);

  /**
   * Open() begins loading the <code>URLRequestInfo</code>. The operation
   * completes when response headers are received or when an error occurs.  Use
   * GetResponseInfo() to access the response headers.
   *
   * @param[in] loader A <code>PP_Resource</code> corresponding to a
   * <code>URLLoader</code>.
   * @param[in] resource A <code>PP_Resource</code> corresponding to a
   * <code>URLRequestInfo</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to run on
   * asynchronous completion of Open(). This callback will run when response
   * headers for the url are received or error occurred. This callback
   * will only run if Open() returns <code>PP_OK_COMPLETIONPENDING</code>.
   *
   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
   */
  int32_t Open(
      [in] PP_Resource loader,
      [in] PP_Resource request_info,
      [in] PP_CompletionCallback callback);

  /**
   * FollowRedirect() can be invoked to follow a redirect after Open()
   * completed on receiving redirect headers.
   *
   * @param[in] loader A <code>PP_Resource</code> corresponding to a
   * <code>URLLoader</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to run on
   * asynchronous completion of FollowRedirect(). This callback will run when
   * response headers for the redirect url are received or error occurred. This
   * callback will only run if FollowRedirect() returns
   * <code>PP_OK_COMPLETIONPENDING</code>.
   *
   * @return An int32_t containing an error code from <code>pp_errors.h</code>.
   */
  int32_t FollowRedirect(
      [in] PP_Resource loader,
      [in] PP_CompletionCallback callback);

  /**
   * GetUploadProgress() returns the current upload progress (which is
   * meaningful after Open() has been called). Progress only refers to the
   * request body and does not include the headers.
   *
   * This data is only available if the <code>URLRequestInfo</code> passed
   * to Open() had the <code>PP_URLREQUESTPROPERTY_REPORTUPLOADPROGRESS</code>
   * property set to PP_TRUE.
   *
   * @param[in] loader A <code>PP_Resource</code> corresponding to a
   * <code>URLLoader</code>.
   * @param[in] bytes_sent The number of bytes sent thus far.
   * @param[in] total_bytes_to_be_sent The total number of bytes to be sent.
   *
   * @return <code>PP_TRUE</code> if the upload progress is available,
   * <code>PP_FALSE</code> if it is not available.
   */
  PP_Bool GetUploadProgress(
      [in] PP_Resource loader,
      [out] int64_t bytes_sent,
      [out] int64_t total_bytes_to_be_sent);

  /**
   * GetDownloadProgress() returns the current download progress, which is
   * meaningful after Open() has been called. Progress only refers to the
   * response body and does not include the headers.
   *
   * This data is only available if the <code>URLRequestInfo</code> passed to
   * Open() had the <code>PP_URLREQUESTPROPERTY_REPORTDOWNLOADPROGRESS</code>
   * property set to <code>PP_TRUE</code>.
   *
   * @param[in] loader A <code>PP_Resource</code> corresponding to a
   * <code>URLLoader</code>.
   * @param[in] bytes_received The number of bytes received thus far.
   * @param[in] total_bytes_to_be_received The total number of bytes to be
   * received. The total bytes to be received may be unknown, in which case
   * <code>total_bytes_to_be_received</code> will be set to -1.
   *
   * @return <code>PP_TRUE</code> if the download progress is available,
   * <code>PP_FALSE</code> if it is not available.
   */
  PP_Bool GetDownloadProgress(
      [in] PP_Resource loader,
      [out] int64_t bytes_received,
      [out] int64_t total_bytes_to_be_received);

  /**
   * GetResponseInfo() returns the current <code>URLResponseInfo</code> object.
   *
   * @param[in] instance A <code>PP_Resource</code> corresponding to a
   * <code>URLLoader</code>.
   *
   * @return A <code>PP_Resource</code> corresponding to the
   * <code>URLResponseInfo</code> if successful, 0 if the loader is not a valid
   * resource or if Open() has not been called.
   */
  PP_Resource GetResponseInfo(
      [in] PP_Resource loader);

  /**
   * ReadResponseBody() is used to read the response body. The size of the
   * buffer must be large enough to hold the specified number of bytes to read.
   * This function might perform a partial read.
   *
   * @param[in] loader A <code>PP_Resource</code> corresponding to a
   * <code>URLLoader</code>.
   * @param[in,out] buffer A pointer to the buffer for the response body.
   * @param[in] bytes_to_read The number of bytes to read.
   * @param[in] callback A <code>PP_CompletionCallback</code> to run on
   * asynchronous completion. The callback will run if the bytes (full or
   * partial) are read or an error occurs asynchronously. This callback will
   * run only if this function returns <code>PP_OK_COMPLETIONPENDING</code>.
   *
   * @return An int32_t containing the number of bytes read or an error code
   * from <code>pp_errors.h</code>.
   */
  int32_t ReadResponseBody(
      [in] PP_Resource loader,
      [out] mem_t buffer,
      [in] int32_t bytes_to_read,
      [in] PP_CompletionCallback callback);

  /**
   * FinishStreamingToFile() is used to wait for the response body to be
   * completely downloaded to the file provided by the GetBodyAsFileRef()
   * in the current <code>URLResponseInfo</code>. This function is only used if
   * <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set on the
   * <code>URLRequestInfo</code> passed to Open().
   *
   * @param[in] loader A <code>PP_Resource</code> corresponding to a
   * <code>URLLoader</code>.
   * @param[in] callback A <code>PP_CompletionCallback</code> to run on
   * asynchronous completion. This callback will run when body is downloaded
   * or an error occurs after FinishStreamingToFile() returns
   * <code>PP_OK_COMPLETIONPENDING</code>.
   *
   * @return An int32_t containing the number of bytes read or an error code
   * from <code>pp_errors.h</code>.
   */
  int32_t FinishStreamingToFile(
      [in] PP_Resource loader,
      [in] PP_CompletionCallback callback);

  /**
   * Close is a pointer to a function used to cancel any pending IO and close
   * the <code>URLLoader</code> object. Any pending callbacks will still run,
   * reporting <code>PP_ERROR_ABORTED</code> if pending IO was interrupted.
   * It is NOT valid to call Open() again after a call to this function.
   *
   * <strong>Note:</strong> If the <code>URLLoader</code> object is destroyed
   * while it is still open, then it will be implicitly closed so you are not
   * required to call Close().
   *
   * @param[in] loader A <code>PP_Resource</code> corresponding to a
   * <code>URLLoader</code>.
   */
  void Close(
      [in] PP_Resource loader);
};