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_ 169
