C++ documentation for URL Loading classes

Review URL: http://codereview.chromium.org/7108044

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

ppapi/cpp/url_loader.h

@@ -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 Instance;
 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 {
+///    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();
 };
 

ppapi/cpp/url_response_info.h

@@ -9,42 +9,109 @@
 #include "ppapi/cpp/resource.h"
 #include "ppapi/cpp/var.h"
 
+/// @file
+/// This file defines the API for examining URL responses.
 namespace pp {
 
 class FileRef;
 
+/// URLResponseInfo provides an API for examaning URL responses.
 class URLResponseInfo : public Resource {
  public:
-  // Creates an is_null() URLResponseInfo object.
+  /// Default constructor. This constructor creates an <code>is_null</code>
+  /// resource.
   URLResponseInfo() {}
 
-  // This constructor is used when we've gotten a PP_Resource as a return value
-  // that has already been addref'ed for us.
+  /// A special structure used by the constructor that does not increment the
+  /// reference count of the underlying resource.
   struct PassRef {};
+
+  /// A constructor used when you have received a <code>PP_Resource</code> as a
+  /// return value that has already been reference counted.
+  ///
+  /// @param[in] resource A <code>PP_Resource</code>.
   URLResponseInfo(PassRef, PP_Resource resource);
 
+  /// The copy constructor for <code>URLResponseInfo</code>.
   URLResponseInfo(const URLResponseInfo& other);
 
-  // PPB_URLResponseInfo methods:
+  /// This function gets a response property.
+  ///
+  /// @param[in] property A <code>PP_URLResponseProperty</code> identifying the
+  /// type of property in the response.
+  /// @return A <code>Var</code> containing the response property value if
+  /// successful, <code>is_undefined Var</code> if an input parameter is
+  /// invalid.
   Var GetProperty(PP_URLResponseProperty property) const;
+
+  /// This function returns a <code>FileRef</code>
+  /// pointing to the file containing the response body.  This
+  /// is only valid if <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set
+  /// on the <code>URLRequestInfo</code> used to produce this response.  This
+  /// file remains valid until the <code>URLLoader</code> associated with this
+  /// <code>URLResponseInfo</code> is closed or destroyed.
+  ///
+  /// @return A <code>FileRef</code> corresponding to a
+  /// <code>FileRef</code> if successful, an <code>is_null</code> object if
+  /// <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was not requested or if
+  /// the <code>URLLoader</code> has not been opened yet.
   FileRef GetBodyAsFileRef() const;
 
-  // Convenient helpers for getting properties:
+  /// This function gets the <code>PP_URLRESPONSEPROPERTY_URL</code>
+  /// property for the response.
+  ///
+  /// @return An <code>is_string Var</code> containing the response property
+  /// value if successful, <code>is_undefined Var</code> if an input parameter
+  /// is invalid.
   Var GetURL() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_URL);
   }
+
+  /// This function gets the <code>PP_URLRESPONSEPROPERTY_REDIRECTURL</code>
+  /// property for the response.
+  ///
+  /// @return An <code>is_string Var</code> containing the response property
+  /// value if successful, <code>is_undefined Var</code> if an input parameter
+  /// is invalid.
   Var GetRedirectURL() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_REDIRECTURL);
   }
+
+  /// This function gets the <code>PP_URLRESPONSEPROPERTY_REDIRECTMETHOD</code>
+  /// property for the response.
+  ///
+  /// @return An <code>is_string Var</code> containing the response property
+  /// value if successful, <code>is_undefined Var</code> if an input parameter
+  /// is invalid.
   Var GetRedirectMethod() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_REDIRECTMETHOD);
   }
+
+  /// This function gets the <code>PP_URLRESPONSEPROPERTY_STATUSCODE</code>
+  /// property for the response.
+  ///
+  /// @return A int32_t containing the response property value if successful,
+  /// <code>is_undefined Var</code> if an input parameter is invalid.
   int32_t GetStatusCode() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_STATUSCODE).AsInt();
   }
+
+  /// This function gets the <code>PP_URLRESPONSEPROPERTY_STATUSLINE</code>
+  /// property for the response.
+  ///
+  /// @return An <code>is_string Var</code> containing the response property
+  /// value if successful, <code>is_undefined Var</code> if an input parameter
+  /// is invalid.
   Var GetStatusLine() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_STATUSLINE);
   }
+
+  /// This function gets the <code>PP_URLRESPONSEPROPERTY_HEADERS</code>
+  /// property for the response.
+  ///
+  /// @return An <code>is_string Var</code> containing the response property
+  /// value if successful, <code>is_undefined Var</code> if an input parameter
+  /// is invalid.
   Var GetHeaders() const {
     return GetProperty(PP_URLRESPONSEPROPERTY_HEADERS);
   }