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