Update the IDL

Final update of the IDL so that we can switch to using
generated code for ppapi/c/ and ppapi/c/trusted.


BUG= http://code.google.com/p/chromium/issues/detail?id=74634
TEST= tryserver
TBR= dmichael@chromium.org
Review URL: http://codereview.chromium.org/7390023

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@92805 0039d316-1c4b-4281-b951-d872f2087c98

1 files changed, 159 insertions, 54 deletions

diff --git a/ppapi/api/ppb_url_loader.idl b/ppapi/api/ppb_url_loader.idl
index 6513881..486c3c0 100644
--- a/ppapi/api/ppb_url_loader.idl
+++ b/ppapi/api/ppb_url_loader.idl
@@ -3,92 +3,178 @@
  * found in the LICENSE file.
  */
 
-/* Defines the URL loader API. */
+/**
+ * This file defines the <strong>PPB_URLLoader</strong> interface for loading
+ * URLs.
+ */
+
+label Chrome {
+  M13 = 0.2,
+  M14 = 1.0
+};
 
-/* The interface for loading URLs.
+/**
+ * The <strong>PPB_URLLoader</strong> interface contains pointers to functions
+ * for loading URLs. The typical steps for loading a URL are:
  *
- * Typical steps for loading an URL:
- * 1- Create an URLLoader object.
- * 2- Create an URLRequestInfo object and set properties on it.
- * 3- Call URLLoader's Open method passing the URLRequestInfo.
- * 4- When Open completes, call GetResponseInfo to examine the response headers.
- * 5- Then call ReadResponseBody to stream the data for the response.
+ * -# 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 PP_URLREQUESTPROPERTY_STREAMTOFILE was set on the
- * URLRequestInfo, then call FinishStreamingToFile at step #5 to wait for the
- * downloaded file to be complete. The downloaded file may be accessed via the
- * GetBody method of the URLResponseInfo returned in step #4.
+ * 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_0_1 {
-  /* Create a new URLLoader object. Returns 0 if the instance is invalid. The
-   * URLLoader 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. It is also important for security reasons to
-   * know the origin of the URL request.
+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> indentifying 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);
 
-  /* Returns PP_TRUE if the given resource is an URLLoader. Returns PP_FALSE if
-   * the resource is invalid or some type other than an URLLoader.
+  /**
+   * 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);
 
-  /* Begins loading the URLRequestInfo. Completes when response headers are
-   * received or when an error occurs. Use the GetResponseInfo method to
-   * access the response headers.
+  /**
+   * 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 occured. 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);
 
-  /* If the current URLResponseInfo object corresponds to a redirect, then call
-   * this method to follow the redirect.
+  /**
+   * 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 occured. 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);
 
-  /* 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.
+  /**
+   * 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.
    *
-   * This data is only available if the URLRequestInfo passed to Open() had the
-   * PP_URLREQUESTPROPERTY_REPORTUPLOADPROGRESS flag 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.
    *
-   * This method returns PP_FALSE if upload progress is not available.
+   * @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);
 
-  /* 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.
+  /**
+   * 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 URLRequestInfo passed to Open() had the
-   * PP_URLREQUESTPROPERTY_REPORTDOWNLOADPROGRESS flag set to PP_TRUE.
+   * 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>.
    *
-   * The total bytes to be received may be unknown, in which case
-   * total_bytes_to_be_received will be set to -1. This method returns PP_FALSE
-   * if download progress is not available.
+   * @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);
 
-  /* Returns the current URLResponseInfo object. */
+  /**
+   * 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);
 
-  /* Call this method to read the response body. The size of the buffer must
-   * be large enough to hold the specified number of bytes to read. May
-   * perform a partial read. Returns the number of bytes read or an error
-   * code.
+  /**
+   * 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,
@@ -96,22 +182,41 @@ interface PPB_URLLoader_0_1 {
       [in] int32_t bytes_to_read,
       [in] PP_CompletionCallback callback);
 
-  /* If PP_URLREQUESTPROPERTY_STREAMTOFILE was set on the URLRequestInfo passed
-   * to the Open method, then this method may be used to wait for the response
-   * body to be completely downloaded to the file provided by URLResponseInfo's
-   * GetBody method.
+  /**
+   * 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);
 
-  /* Cancels any IO that may be pending, and closes the URLLoader object. Any
-   * pending callbacks will still run, reporting PP_ERROR_ABORTED if pending IO
-   * was interrupted. It is NOT valid to call Open again after a call to this
-   * method. Note: If the URLLoader object is destroyed, and it is still open,
-   * then it will be implicitly closed, so you are not required to call the
-   * Close method.
+  /**
+   * 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);
 };
+