ppb_url_loader.h revision 5821806d5e7f356e8fa4b058a389a808ea183019 
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 Wed Oct  5 14:06:02 2011. */
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 */
51struct 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 occured. 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
220typedef struct PPB_URLLoader_1_0 PPB_URLLoader;
221/**
222 * @}
223 */
224
225#endif  /* PPAPI_C_PPB_URL_LOADER_H_ */
226
227