1/* Copyright (c) 2012 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 6/** 7 * This file defines the <strong>PPB_URLLoader</strong> interface for loading 8 * URLs. 9 */ 10 11[generate_thunk] 12 13label Chrome { 14 M14 = 1.0 15}; 16 17/** 18 * The <strong>PPB_URLLoader</strong> interface contains pointers to functions 19 * for loading URLs. The typical steps for loading a URL are: 20 * 21 * -# Call Create() to create a URLLoader object. 22 * -# Create a <code>URLRequestInfo</code> object and set properties on it. 23 * Refer to <code>PPB_URLRequestInfo</code> for further information. 24 * -# Call Open() with the <code>URLRequestInfo</code> as an argument. 25 * -# When Open() completes, call GetResponseInfo() to examine the response 26 * headers. Refer to <code>PPB_URLResponseInfo</code> for further information. 27 * -# Call ReadResponseBody() to stream the data for the response. 28 * 29 * Alternatively, if <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set on 30 * the <code>URLRequestInfo</code> in step #2: 31 * - Call FinishStreamingToFile(), after examining the response headers 32 * (step #4), to wait for the downloaded file to be complete. 33 * - Then, access the downloaded file using the GetBodyAsFileRef() function of 34 * the <code>URLResponseInfo</code> returned in step #4. 35 */ 36interface PPB_URLLoader { 37 /** 38 * Create() creates a new <code>URLLoader</code> object. The 39 * <code>URLLoader</code> is associated with a particular instance, so that 40 * any UI dialogs that need to be shown to the user can be positioned 41 * relative to the window containing the instance. 42 * 43 * @param[in] instance A <code>PP_Instance</code> identifying one instance 44 * of a module. 45 * 46 * @return A <code>PP_Resource</code> corresponding to a URLLoader if 47 * successful, 0 if the instance is invalid. 48 */ 49 PP_Resource Create( 50 [in] PP_Instance instance); 51 52 /** 53 * IsURLLoader() determines if a resource is an <code>URLLoader</code>. 54 * 55 * @param[in] resource A <code>PP_Resource</code> corresponding to a 56 * <code>URLLoader</code>. 57 * 58 * @return <code>PP_TRUE</code> if the resource is a <code>URLLoader</code>, 59 * <code>PP_FALSE</code> if the resource is invalid or some type other 60 * than <code>URLLoader</code>. 61 */ 62 PP_Bool IsURLLoader( 63 [in] PP_Resource resource); 64 65 /** 66 * Open() begins loading the <code>URLRequestInfo</code>. The operation 67 * completes when response headers are received or when an error occurs. Use 68 * GetResponseInfo() to access the response headers. 69 * 70 * @param[in] loader A <code>PP_Resource</code> corresponding to a 71 * <code>URLLoader</code>. 72 * @param[in] resource A <code>PP_Resource</code> corresponding to a 73 * <code>URLRequestInfo</code>. 74 * @param[in] callback A <code>PP_CompletionCallback</code> to run on 75 * asynchronous completion of Open(). This callback will run when response 76 * headers for the url are received or error occurred. This callback 77 * will only run if Open() returns <code>PP_OK_COMPLETIONPENDING</code>. 78 * 79 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 80 */ 81 int32_t Open( 82 [in] PP_Resource loader, 83 [in] PP_Resource request_info, 84 [in] PP_CompletionCallback callback); 85 86 /** 87 * FollowRedirect() can be invoked to follow a redirect after Open() 88 * completed on receiving redirect headers. 89 * 90 * @param[in] loader A <code>PP_Resource</code> corresponding to a 91 * <code>URLLoader</code>. 92 * @param[in] callback A <code>PP_CompletionCallback</code> to run on 93 * asynchronous completion of FollowRedirect(). This callback will run when 94 * response headers for the redirect url are received or error occurred. This 95 * callback will only run if FollowRedirect() returns 96 * <code>PP_OK_COMPLETIONPENDING</code>. 97 * 98 * @return An int32_t containing an error code from <code>pp_errors.h</code>. 99 */ 100 int32_t FollowRedirect( 101 [in] PP_Resource loader, 102 [in] PP_CompletionCallback callback); 103 104 /** 105 * GetUploadProgress() returns the current upload progress (which is 106 * meaningful after Open() has been called). Progress only refers to the 107 * request body and does not include the headers. 108 * 109 * This data is only available if the <code>URLRequestInfo</code> passed 110 * to Open() had the <code>PP_URLREQUESTPROPERTY_REPORTUPLOADPROGRESS</code> 111 * property set to PP_TRUE. 112 * 113 * @param[in] loader A <code>PP_Resource</code> corresponding to a 114 * <code>URLLoader</code>. 115 * @param[in] bytes_sent The number of bytes sent thus far. 116 * @param[in] total_bytes_to_be_sent The total number of bytes to be sent. 117 * 118 * @return <code>PP_TRUE</code> if the upload progress is available, 119 * <code>PP_FALSE</code> if it is not available. 120 */ 121 [always_set_output_parameters] 122 PP_Bool GetUploadProgress( 123 [in] PP_Resource loader, 124 [out] int64_t bytes_sent, 125 [out] int64_t total_bytes_to_be_sent); 126 127 /** 128 * GetDownloadProgress() returns the current download progress, which is 129 * meaningful after Open() has been called. Progress only refers to the 130 * response body and does not include the headers. 131 * 132 * This data is only available if the <code>URLRequestInfo</code> passed to 133 * Open() had the <code>PP_URLREQUESTPROPERTY_REPORTDOWNLOADPROGRESS</code> 134 * property set to <code>PP_TRUE</code>. 135 * 136 * @param[in] loader A <code>PP_Resource</code> corresponding to a 137 * <code>URLLoader</code>. 138 * @param[in] bytes_received The number of bytes received thus far. 139 * @param[in] total_bytes_to_be_received The total number of bytes to be 140 * received. The total bytes to be received may be unknown, in which case 141 * <code>total_bytes_to_be_received</code> will be set to -1. 142 * 143 * @return <code>PP_TRUE</code> if the download progress is available, 144 * <code>PP_FALSE</code> if it is not available. 145 */ 146 [always_set_output_parameters] 147 PP_Bool GetDownloadProgress( 148 [in] PP_Resource loader, 149 [out] int64_t bytes_received, 150 [out] int64_t total_bytes_to_be_received); 151 152 /** 153 * GetResponseInfo() returns the current <code>URLResponseInfo</code> object. 154 * 155 * @param[in] instance A <code>PP_Resource</code> corresponding to a 156 * <code>URLLoader</code>. 157 * 158 * @return A <code>PP_Resource</code> corresponding to the 159 * <code>URLResponseInfo</code> if successful, 0 if the loader is not a valid 160 * resource or if Open() has not been called. 161 */ 162 PP_Resource GetResponseInfo( 163 [in] PP_Resource loader); 164 165 /** 166 * ReadResponseBody() is used to read the response body. The size of the 167 * buffer must be large enough to hold the specified number of bytes to read. 168 * This function might perform a partial read. 169 * 170 * @param[in] loader A <code>PP_Resource</code> corresponding to a 171 * <code>URLLoader</code>. 172 * @param[in,out] buffer A pointer to the buffer for the response body. 173 * @param[in] bytes_to_read The number of bytes to read. 174 * @param[in] callback A <code>PP_CompletionCallback</code> to run on 175 * asynchronous completion. The callback will run if the bytes (full or 176 * partial) are read or an error occurs asynchronously. This callback will 177 * run only if this function returns <code>PP_OK_COMPLETIONPENDING</code>. 178 * 179 * @return An int32_t containing the number of bytes read or an error code 180 * from <code>pp_errors.h</code>. 181 */ 182 int32_t ReadResponseBody( 183 [in] PP_Resource loader, 184 [out] mem_t buffer, 185 [in] int32_t bytes_to_read, 186 [in] PP_CompletionCallback callback); 187 188 /** 189 * FinishStreamingToFile() is used to wait for the response body to be 190 * completely downloaded to the file provided by the GetBodyAsFileRef() 191 * in the current <code>URLResponseInfo</code>. This function is only used if 192 * <code>PP_URLREQUESTPROPERTY_STREAMTOFILE</code> was set on the 193 * <code>URLRequestInfo</code> passed to Open(). 194 * 195 * @param[in] loader A <code>PP_Resource</code> corresponding to a 196 * <code>URLLoader</code>. 197 * @param[in] callback A <code>PP_CompletionCallback</code> to run on 198 * asynchronous completion. This callback will run when body is downloaded 199 * or an error occurs after FinishStreamingToFile() returns 200 * <code>PP_OK_COMPLETIONPENDING</code>. 201 * 202 * @return An int32_t containing the number of bytes read or an error code 203 * from <code>pp_errors.h</code>. 204 */ 205 int32_t FinishStreamingToFile( 206 [in] PP_Resource loader, 207 [in] PP_CompletionCallback callback); 208 209 /** 210 * Close is a pointer to a function used to cancel any pending IO and close 211 * the <code>URLLoader</code> object. Any pending callbacks will still run, 212 * reporting <code>PP_ERROR_ABORTED</code> if pending IO was interrupted. 213 * It is NOT valid to call Open() again after a call to this function. 214 * 215 * <strong>Note:</strong> If the <code>URLLoader</code> object is destroyed 216 * while it is still open, then it will be implicitly closed so you are not 217 * required to call Close(). 218 * 219 * @param[in] loader A <code>PP_Resource</code> corresponding to a 220 * <code>URLLoader</code>. 221 */ 222 void Close( 223 [in] PP_Resource loader); 224}; 225 226