ppapi/api/ppb_url_loader.idl - chromium/src - Git at Google

 /* 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.
  */

 [generate_thunk]

 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.
    */
   [always_set_output_parameters]
   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.
    */
   [always_set_output_parameters]
   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);
 };
	/* 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.
	*/

	[generate_thunk]

	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.
	*/
	[always_set_output_parameters]
	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.
	*/
	[always_set_output_parameters]
	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);
	};