Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 6 | /* From ppb_url_loader.idl modified Thu Mar 28 10:07:37 2013. */ |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 |
Torne (Richard Coles) | c2e0dbd | 2013-05-09 18:35:53 +0100 | [diff] [blame] | 87 | * headers for the url are received or error occurred. This callback |
Torne (Richard Coles) | 5821806 | 2012-11-14 11:43:16 +0000 | [diff] [blame] | 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 | |