ppapi/cpp/url_loader.h

   1 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef PPAPI_CPP_URL_LOADER_H_
   6 #define PPAPI_CPP_URL_LOADER_H_
   7
   8 #include "ppapi/c/pp_stdint.h"
   9 #include "ppapi/cpp/resource.h"
  10
  11 /// @file
  12 /// This file defines the API for loading URLs.
  13 namespace pp {
  14
  15 class CompletionCallback;
  16 class InstanceHandle;
  17 class URLRequestInfo;
  18 class URLResponseInfo;
  19
  20 /// URLLoader provides an API for loading URLs.
  21 /// Refer to <code>ppapi/examples/url_loader/streaming.cc</code>
  22 /// for an example of how to use this class.
  23 class URLLoader : public Resource {
  24  public:
  25   /// Default constructor for creating an is_null()
  26   /// <code>URLLoader</code> object.
  27   URLLoader() {}
  28
  29   /// A constructor used when a <code>PP_Resource</code> is provided as a
  30   /// return value whose reference count we need to increment.
  31   ///
  32   /// @param[in] resource A <code>PP_Resource</code> corresponding to a
  33   /// <code>URLLoader</code> resource.
  34   explicit URLLoader(PP_Resource resource);
  35
  36   /// A constructor used to allocate a new URLLoader in the browser. The
  37   /// resulting object will be <code>is_null</code> if the allocation failed.
  38   ///
  39   /// @param[in] instance The instance with which this resource will be
  40   /// associated.
  41   explicit URLLoader(const InstanceHandle& instance);
  42
  43   /// The copy constructor for <code>URLLoader</code>.
  44   ///
  45   /// @param other A <code>URLLoader</code> to be copied.
  46   URLLoader(const URLLoader& other);
  47
  48   /// This function begins loading the <code>URLRequestInfo</code>.
  49   /// The operation completes when response headers are received or when an
  50   /// error occurs.  Use GetResponseInfo() to access the response
  51   /// headers.
  52   ///
  53   /// @param[in] request_info A <code>URLRequestInfo</code> corresponding to a
  54   /// URLRequestInfo.
  55   /// @param[in] cc A <code>CompletionCallback</code> to run on asynchronous
  56   /// completion of Open(). This callback will run when response
  57   /// headers for the url are received or error occurred. This callback
  58   /// will only run if Open() returns <code>PP_OK_COMPLETIONPENDING</code>.
  59   ///
  60   /// @return An int32_t containing an error code from
  61   /// <code>pp_errors.h</code>.
  62   int32_t Open(const URLRequestInfo& request_info,
  63                const CompletionCallback& cc);
  64
  65   /// This function can be invoked to follow a
  66   /// redirect after Open() completed on receiving redirect headers.
  67   ///
  68   /// @param[in] cc A <code>CompletionCallback</code> to run on asynchronous
  69   /// completion of FollowRedirect(). This callback will run when response
  70   /// headers for the redirect url are received or error occurred. This callback
  71   /// will only run if FollowRedirect() returns
  72   /// <code>PP_OK_COMPLETIONPENDING</code>.
  73   ///
  74   /// @return An int32_t containing an error code from
  75   /// <code>pp_errors.h</code>.
  76   int32_t FollowRedirect(const CompletionCallback& cc);
  77
  78   /// This function returns the current upload progress (which is only
  79   /// meaningful after Open() has been called). Progress only refers to the
  80   /// request body and does not include the headers.
  81   ///
  82   /// This data is only available if the <code>URLRequestInfo</code> passed to
  83   /// Open() had the
  84   /// <code>PP_URLREQUESTPROPERTY_REPORTUPLOADPROGRESS</code> property set to
  85   /// <code>PP_TRUE</code>.
  86   ///
  87   /// @param[in] bytes_sent The number of bytes sent thus far.
  88   /// @param[in] total_bytes_to_be_sent The total number of bytes to be sent.
  89   ///
  90   /// @return true if the upload progress is available, false if it is not
  91   /// available.
  92   bool GetUploadProgress(int64_t* bytes_sent,
  93                          int64_t* total_bytes_to_be_sent) const;
  94
  95   /// This function returns the current download progress, which is meaningful
  96   /// after Open() has been called. Progress only refers to the response body
  97   /// and does not include the headers.
  98   ///
  99   /// This data is only available if the <code>URLRequestInfo</code> passed to
 100   /// Open() had the
 101   /// <code>PP_URLREQUESTPROPERTY_REPORTDOWNLOADPROGRESS</code> property set to
 102   /// PP_TRUE.
 103   ///
 104   /// @param[in] bytes_received The number of bytes received thus far.
 105   /// @param[in] total_bytes_to_be_received The total number of bytes to be
 106   /// received. The total bytes to be received may be unknown, in which case
 107   /// <code>total_bytes_to_be_received</code> will be set to -1.
 108   ///
 109   /// @return true if the download progress is available, false if it is
 110   /// not available.
 111   bool GetDownloadProgress(int64_t* bytes_received,
 112                            int64_t* total_bytes_to_be_received) const;
 113
 114   /// This is a function that returns the current
 115   /// <code>URLResponseInfo</code> object.
 116   ///
 117   /// @return A <code>URLResponseInfo</code> corresponding to the
 118   /// <code>URLResponseInfo</code> if successful, an <code>is_null</code>
 119   /// object if the loader is not a valid resource or if Open() has not been
 120   /// called.
 121   URLResponseInfo GetResponseInfo() const;
 122
 123   /// This function is used to read the response body. The size of the buffer
 124   /// must be large enough to hold the specified number of bytes to read.
 125   /// This function might perform a partial read.
 126   ///
 127   /// @param[in,out] buffer A pointer to the buffer for the response body.
 128   /// @param[in] bytes_to_read The number of bytes to read.
 129   /// @param[in] cc A <code>CompletionCallback</code> to run on asynchronous
 130   /// completion. The callback will run if the bytes (full or partial) are
 131   /// read or an error occurs asynchronously. This callback will run only if
 132   /// this function returns <code>PP_OK_COMPLETIONPENDING</code>.
 133   ///
 134   /// @return An int32_t containing the number of bytes read or an error code
 135   /// from <code>pp_errors.h</code>.
 136   int32_t ReadResponseBody(void* buffer,
 137                            int32_t bytes_to_read,
 138                            const CompletionCallback& cc);
 139
 140   /// This function is used to wait for the response body to be completely
 141   /// downloaded to the file provided by the GetBodyAsFileRef() in the current
 142   /// <code>URLResponseInfo</code>. This function is only used if
 143   /// <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set on the
 144   /// <code>URLRequestInfo</code> passed to Open().
 145   ///
 146   /// @param[in] cc A <code>CompletionCallback</code> to run on asynchronous
 147   /// completion. This callback will run when body is downloaded or an error
 148   /// occurs after FinishStreamingToFile() returns
 149   /// <code>PP_OK_COMPLETIONPENDING</code>.
 150   ///
 151   /// @return An int32_t containing the number of bytes read or an error code
 152   /// from <code>pp_errors.h</code>.
 153   int32_t FinishStreamingToFile(const CompletionCallback& cc);
 154
 155   /// This function is used to cancel any pending IO and close the URLLoader
 156   /// object. Any pending callbacks will still run, reporting
 157   /// <code>PP_ERROR_ABORTED</code> if pending IO was interrupted.  It is NOT
 158   /// valid to call Open() again after a call to this function.
 159   ///
 160   /// <strong>Note:</strong> If the <code>URLLoader</code> object is destroyed
 161   /// while it is still open, then it will be implicitly closed so you are not
 162   /// required to call Close().
 163   void Close();
 164 };
 165
 166 }  // namespace pp
 167
 168 #endif  // PPAPI_CPP_URL_LOADER_H_