Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 57 | /// headers for the url are received or error occurred. This callback |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 70 | /// headers for the redirect url are received or error occurred. This callback |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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_ |