Pepper_31_C_interfaces
ppb_url_loader.h
Go to the documentation of this file.
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  */
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  */
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  */
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  */
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  */
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  */
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  */
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 
221 /**
222  * @}
223  */
224 
225 #endif /* PPAPI_C_PPB_URL_LOADER_H_ */
226 
int32_t(* FinishStreamingToFile)(PP_Resource loader, struct PP_CompletionCallback callback)
void(* Close)(PP_Resource loader)
int32_t(* ReadResponseBody)(PP_Resource loader, void *buffer, int32_t bytes_to_read, struct PP_CompletionCallback callback)
PP_Resource(* Create)(PP_Instance instance)
int32_t PP_Resource
Definition: pp_resource.h:40
PP_Bool(* IsURLLoader)(PP_Resource resource)
int32_t(* Open)(PP_Resource loader, PP_Resource request_info, struct PP_CompletionCallback callback)
int32_t PP_Instance
Definition: pp_instance.h:34
PP_Bool
Definition: pp_bool.h:30
PP_Resource(* GetResponseInfo)(PP_Resource loader)
PP_Bool(* GetUploadProgress)(PP_Resource loader, int64_t *bytes_sent, int64_t *total_bytes_to_be_sent)
PP_Bool(* GetDownloadProgress)(PP_Resource loader, int64_t *bytes_received, int64_t *total_bytes_to_be_received)
int32_t(* FollowRedirect)(PP_Resource loader, struct PP_CompletionCallback callback)