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