C++ documentation for URL Loading classes

ppapi/cpp/url_loader.h

Index: ppapi/cpp/url_loader.h
===================================================================
--- ppapi/cpp/url_loader.h	(revision 95625)
+++ ppapi/cpp/url_loader.h	(working copy)
@@ -8,6 +8,8 @@
 #include "ppapi/c/pp_stdint.h"
 #include "ppapi/cpp/resource.h"
 
+/// @file
+/// This file defines the API for loading URLs.
 namespace pp {
 
 class CompletionCallback;
@@ -15,35 +17,205 @@
 class URLRequestInfo;
 class URLResponseInfo;
 
-// URLLoader provides an API to download URLs.
-//
-// Please see the example in ppapi/examples/url_loader/url_loader.cc.
+/// URLLoader provides an API for loading URLs.
+///
+/// <strong>Example:</strong>
+///
+/// @code
+///
+///   class MyHandler {

[brettw, 2011/08/23 23:29:01]

This code example should not have been added back. The code doesn't compile and
some of the callback handling is subtly and dangerously incorrect. This is why I
made a separate example that's actually compiled in the build, so we can ensure
it actually works.

Can you please revert this part of this change?

In the future, can you please be extra careful when updating things that have
changed since starting working on the documentation? There have been several
cases of comment fixes getting reverted because a comment from an older revision
was rewritten and pasted over the updated version. It should be a huge red flag
when you get a merge conflict, and we always need to understand the conflicts
rather than overwriting the changes.

[jond, 2011/08/24 15:33:59]

I actually don't know how this example got in here if it wasn't there
previously. And, there doesn't seem to be a url_loader.cc at the location on the
left. Do you simply want me to remove the example?

 On 2011/08/23 23:29:01, brettw wrote:

[polina, 2011/08/24 19:52:01]

Jon, if you view the diff for patch sets 1 or 2, they will be compared against
the older revision that still had this example. Remember I even had you fix some
other merge-related omission in my first set of comments? Anyway, it looks like
after that you synced to a newer revision that no longer had the example. But
since your local copy still did, it got erroneously put back in a merge
conflict. After a sync and before a commit, it is always a good idea to look at
the most recent diff, to see how the merge conflicts got resolved, both
automatically and manually.

So at this point, you should just remove this example from line 22 to line 81
and replace it with the comment pointing to
ppapi/examples/url_loader/url_loader.cc on line 20 of the LHS.
 

[polina, 2011/08/24 19:55:53]

And I just verified that the file is there:

http://src.chromium.org/viewvc/chrome/trunk/src/ppapi/examples/url_loader/

You must have looked in the example/ dir instead of examples/ with an S.

[polina, 2011/08/24 20:06:14]

Sorry, I rushed with my "helpful" comment. The directory is there, but the .cc
file is not.

[polina, 2011/08/24 20:07:35]

Confirmed with Brett. Please point to streaming.cc. Thank you!

+///    public:
+///     MyHandler(Instance* instance)
+///         : factory_(this),
+///           loader_(instance),
+///           did_open_(false) {
+///     }
+///     void ProcessURL(const char* url) {
+///       CompletionCallback* cc = NewCallback();
+///       int32_t rv = loader_.Open(MakeRequest(url), cc);
+///       if (rv != PP_Error_WouldBlock)
+///         cc->Run(rv);
+///     }
+///    private:
+///     CompletionCallback* NewCallback() {
+///       return factory_.NewOptionalCallback(&MyHandler::DidCompleteIO);
+///     }
+///     URLRequestInfo MakeRequest(const char* url) {
+///       URLRequestInfo request;
+///       request.SetURL(url);
+///       request.SetMethod("GET");
+///       request.SetFollowRedirects(true);
+///       return request;
+///     }
+///     void DidCompleteIO(int32_t result) {
+///       if (result > 0) {
+///         // buf_ now contains 'result' number of bytes from the URL.
+///         ProcessBytes(buf_, result);
+///         ReadMore();
+///       } else if (result == PP_OK && !did_open_) {
+///         // Headers are available, and we can start reading the body.
+///         did_open_ = true;
+///         ProcessResponseInfo(loader_.GetResponseInfo());
+///         ReadMore();
+///       } else {
+///         // Done reading (possibly with an error given by 'result').
+///       }
+///     }
+///     void ReadMore() {
+///       CompletionCallback* cc = NewCallback();
+///       int32_t rv = fio_.Read(offset_, buf_, sizeof(buf_), cc);
+///       if (rv != PP_Error_WouldBlock)
+///         cc->Run(rv);
+///     }
+///     void ProcessResponseInfo(const URLResponseInfo& response_info) {
+///       // Read response headers, etc.
+///     }
+///     void ProcessBytes(const char* bytes, int32_t length) {
+///       // Do work ...
+///     }
+///     pp::CompletionCallbackFactory<MyHandler> factory_;
+///     pp::URLLoader loader_;
+///     char buf_[4096];
+///     bool did_open_;
+///   };
+/// @endcode
 class URLLoader : public Resource {
  public:
-  // Creates an is_null() URLLoader object.
+  /// Default constructor for creating an is_null()
+  /// <code>URLLoader</code> object.
   URLLoader() {}
 
   // TODO(brettw) remove this when NaCl is updated to use the new version
   // that takes a pointer.
   explicit URLLoader(const Instance& instance);
 
+  /// A constructor used when a <code>PP_Resource</code> is provided as a
+  /// return value whose reference count we need to increment.
+  ///
+  /// @param[in] resource A <code>PP_Resource</code>.
   explicit URLLoader(PP_Resource resource);
+
+  /// A constructor used to allocate a new URLLoader in the browser. The
+  /// resulting object will be <code>is_null</code> if the allocation failed.
+  ///
+  /// @param[in] instance An <code>Instance</code>.
   explicit URLLoader(Instance* instance);
+
+  /// The copy constructor for <code>URLLoader</code>.
+  ///
+  /// @param other A <code>URLLoader</code> to be copied.
   URLLoader(const URLLoader& other);
 
-  // PPB_URLLoader methods:
+  /// This function 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] request_info A <code>URLRequestInfo</code> corresponding to a
+  /// URLRequestInfo.
+  /// @param[in] cc A <code>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(const URLRequestInfo& request_info,
                const CompletionCallback& cc);
+
+  /// This function can be invoked to follow a
+  /// redirect after Open() completed on receiving redirect headers.
+  ///
+  /// @param[in] cc A <code>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(const CompletionCallback& cc);
+
+  /// This function returns the current upload progress (which is only
+  /// 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
+  /// <code>PP_TRUE</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 True if the upload progress is available, false if it is not
+  /// available.
   bool GetUploadProgress(int64_t* bytes_sent,
                          int64_t* total_bytes_to_be_sent) const;
+
+  /// This function 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
+  /// PP_TRUE.
+  ///
+  /// @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 True if the download progress is available, false if it is
+  /// not available.
   bool GetDownloadProgress(int64_t* bytes_received,
                            int64_t* total_bytes_to_be_received) const;
+
+  /// This is a function that returns the current
+  /// <code>URLResponseInfo</code> object.
+  ///
+  /// @return A <code>URLResponseInfo</code> corresponding to the
+  /// <code>URLResponseInfo</code> if successful, an <code>is_null</code>
+  /// object if the loader is not a valid resource or if Open() has not been
+  /// called.
   URLResponseInfo GetResponseInfo() const;
+
+  /// This function 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,out] buffer A pointer to the buffer for the response body.
+  /// @param[in] bytes_to_read The number of bytes to read.
+  /// @param[in] cc A <code>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(void* buffer,
                            int32_t bytes_to_read,
                            const CompletionCallback& cc);
+
+  /// This function 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] cc A <code>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(const CompletionCallback& cc);
+
+  /// This function is used to cancel any pending IO and close the URLLoader
+  /// 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().
   void Close();
 };