Skip to content

Commit 2cf4646

Browse files
lflores-mslflores-ms
committed
WebResourceResponseReceived API v2 doc
1 parent e28f20f commit 2cf4646

1 file changed

Lines changed: 151 additions & 97 deletions

File tree

‎specs/WebResourceResponseReceived.md‎

Lines changed: 151 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -21,17 +21,15 @@ This event is raised when the WebView receives the response for a request for a
2121
web resource. It provides access to both the response as it was received and the
2222
request as it was committed, including modifications made by the network stack
2323
(such as the adding of HTTP Authorization headers). The app can use this event
24-
to view the actual request and response for a web resource. Modifications to
25-
these objects are set but have no effect on WebView processing them. There is no
24+
to view the actual request and response for a web resource. Modifications to the
25+
request object are set but have no effect on WebView processing it. There is no
2626
ordering guarantee between WebView processing the response and the host app's
2727
event handler running.
2828

2929
When the event is raised, the WebView will pass a
3030
`WebResourceResponseReceivedEventArgs`, which lets the app view the request and
31-
response. The additional `PopulateResponseContent` API is exposed from the event
32-
arguments so the app can get the response's body (if it has one). If the app
33-
tries to get the response content before the first call to
34-
`PopulateResponseContent` completes, the stream object returned will be null.
31+
response. To get the response content, call `TryGetContent` on the
32+
`CoreWebView2WebResourceResponseView` object from the event args.
3533

3634
# Examples
3735
The following code snippets demonstrate how the `WebResourceResponseReceived`
@@ -49,17 +47,17 @@ m_webview->add_WebResourceResponseReceived(
4947
wil::com_ptr<ICoreWebView2WebResourceRequest> webResourceRequest;
5048
CHECK_FAILURE(args->get_Request(&webResourceRequest));
5149
// The response object as received
52-
wil::com_ptr<ICoreWebView2WebResourceResponse> webResourceResponse;
50+
wil::com_ptr<ICoreWebView2WebResourceResponseView> webResourceResponse;
5351
CHECK_FAILURE(args->get_Response(&webResourceResponse));
5452
5553
// Get body content for the response. Redirect responses will
5654
// return an error HRESULT as their body (if any) is ignored.
57-
HRESULT populateCallResult = args->PopulateResponseContent(
55+
HRESULT getContentCallResult = webResourceResponse->TryGetContent(
5856
Callback<
59-
ICoreWebView2WebResourceResponseReceivedEventArgsPopulateResponseContentCompletedHandler>(
60-
[this, webResourceRequest, webResourceResponse](HRESULT result) {
61-
// The response might not have a body.
62-
bool populatedBody = SUCCEEDED(result);
57+
ICoreWebView2WebResourceResponseViewTryGetContentCompletedHandler>(
58+
[this, webResourceRequest, webResourceResponse](HRESULT result, IStream* content) {
59+
// The response might not have content, or it might have failed loading.
60+
bool gotContent = SUCCEEDED(result);
6361
6462
std::wstring message =
6563
L"{ \"kind\": \"event\", \"name\": "
@@ -68,7 +66,7 @@ m_webview->add_WebResourceResponseReceived(
6866
RequestToJsonString(webResourceRequest.get()) +
6967
L", "
7068
L"\"response\": " +
71-
ResponseToJsonString(webResourceResponse.get()) + L"}";
69+
ResponseToJsonString(webResourceResponse.get(), content) + L"}";
7270

7371
message +=
7472
WebViewPropertiesToJsonString(m_webview.get());
@@ -88,16 +86,20 @@ m_webview->add_WebResourceResponseReceived(
8886
```c#
8987
WebView.WebResourceResponseReceived += WebView_WebResourceResponseReceived;
9088
91-
// Note: modifications made to request and response are set but have no effect on WebView processing the objects.
89+
// Note: modifications made to request are set but have no effect on WebView processing it.
9290
private async void WebView_WebResourceResponseReceived(CoreWebView2 sender, CoreWebView2WebResourceResponseReceivedEventArgs e)
9391
{
9492
// Actual headers sent with request
9593
foreach (var current in e.Request.Headers)
94+
{
9695
Console.WriteLine(current);
96+
}
9797
9898
// Headers in response received
9999
foreach (var current in e.Response.Headers)
100+
{
100101
Console.WriteLine(current);
102+
}
101103
102104
// Status code from response received
103105
int status = e.Response.StatusCode;
@@ -109,21 +111,28 @@ private async void WebView_WebResourceResponseReceived(CoreWebView2 sender, Core
109111
// Get response body
110112
try
111113
{
112-
await e.PopulateResponseContentAsync();
113-
DoSomethingWithResponseBody(e.Response.Content);
114+
System.IO.Stream content = await e.Response.TryGetContentAsync();
115+
DoSomethingWithResponseContent(content);
114116
}
115117
catch (COMException ex)
116118
{
117-
// A COMException will be thrown if the request has no body.
119+
// A COMException will be thrown if no content was found for the
120+
// response, or if it failed to load.
118121
}
119122
}
120123
}
121124
```
122125

123126

124127
# Remarks
125-
Calling `PopulateResponseContent` will fail/throw a COMException if the response
126-
has no body. Note the body for redirect responses is ignored.
128+
Calling `ICoreWebView2WebResourceResponseView::TryGetContent` will return an
129+
error HRESULT for redirect responses, as their content (if any) is ignored.
130+
`ICoreWebView2WebResourceResponseViewTryGetContentCompletedHandler` will be
131+
invoked with a failure errorCode if no content was found for the response, or if
132+
the content failed to load.
133+
Calling `CoreWebView2WebResourceResponseView.TryGetContentAsync` will throw a
134+
`COMException` if the response has no body. As noted, the body for redirect
135+
responses is ignored.
127136

128137

129138
# API Notes
@@ -135,106 +144,151 @@ See [API Details](#api-details) section below for API reference.
135144
```cpp
136145
library WebView2
137146
{
138-
interface ICoreWebView2 : IUnknown
139-
{
140-
// ...
147+
// ...
141148

142-
/// Add an event handler for the WebResourceResponseReceived event.
143-
/// WebResourceResponseReceived event is raised after the WebView has received
144-
/// the response for a WebResource request. The event args include the
145-
/// WebResourceRequest as committed and the WebResourceResponse received,
146-
/// not including the Content, but including any additional headers added by
147-
/// the network stack that were not be included as part of the associated
148-
/// WebResourceRequested event, such as Authentication headers. There is no
149-
/// ordering guarantee between WebView processing the response and the host
150-
/// app's event handler running.
151-
HRESULT add_WebResourceResponseReceived(
152-
[in] ICoreWebView2WebResourceResponseReceivedEventHandler* eventHandler,
153-
[out] EventRegistrationToken* token);
154-
/// Removes the WebResourceResponseReceived event handler previously added
155-
/// with add_WebResourceResponseReceived
156-
HRESULT remove_WebResourceResponseReceived(
157-
[in] EventRegistrationToken token);
158-
}
149+
interface ICoreWebView2 : IUnknown
150+
{
151+
// ...
159152

160-
/// Raised when a response for a request is received for a Web resource in the webview.
161-
/// Host can use this event to view the actual request and response for a Web resource.
162-
/// This includes any request or response modifications made by the network stack (such as
163-
/// the adding of Authorization headers) after the WebResourceRequested event for
164-
/// the associated request has been raised. Modifications made to the request or
165-
/// response objects are set but have no effect on WebView processing them.
166-
interface ICoreWebView2WebResourceResponseReceivedEventHandler : IUnknown
167-
{
168-
/// Called to provide the implementer with the event args for the
169-
/// corresponding event.
170-
HRESULT Invoke(
171-
[in] ICoreWebView2* sender,
172-
[in] ICoreWebView2WebResourceResponseReceivedEventArgs* args);
173-
}
153+
/// Add an event handler for the WebResourceResponseReceived event.
154+
/// WebResourceResponseReceived is raised when the WebView receives the
155+
/// response for a request for a web resource (any URI resolution performed by
156+
/// the WebView; such as HTTP/HTTPS, file and data requests from redirects,
157+
/// navigations, declarations in HTML, implicit favicon lookups, and fetch API
158+
/// usage in the document). The host app can use this event to view the actual
159+
/// request and response for a web resource. There is no guarantee about the
160+
/// order in which the WebView processes the response and the host app's
161+
/// handler runs. The app's handler will not block the WebView from processing
162+
/// the response.
163+
HRESULT add_WebResourceResponseReceived(
164+
[in] ICoreWebView2WebResourceResponseReceivedEventHandler* eventHandler,
165+
[out] EventRegistrationToken* token);
166+
/// Remove an event handler previously added with
167+
/// add_WebResourceResponseReceived.
168+
HRESULT remove_WebResourceResponseReceived(
169+
[in] EventRegistrationToken token);
170+
}
174171

175-
/// Completion handler for PopulateResponseContent async method. It's invoked
176-
/// when the Content stream of the Response of a WebResourceResponseReceived
177-
/// event is available.
178-
interface ICoreWebView2WebResourceResponseReceivedEventArgsPopulateResponseContentCompletedHandler : IUnknown
179-
{
180-
/// Called to provide the implementer with the completion status
181-
/// of the corresponding asynchronous method call.
182-
HRESULT Invoke([in] HRESULT errorCode);
183-
}
172+
/// The caller implements this interface to receive WebResourceResponseReceived
173+
/// events.
174+
interface ICoreWebView2WebResourceResponseReceivedEventHandler : IUnknown
175+
{
176+
/// Called to provide the implementer with the event args for the
177+
/// corresponding event.
178+
HRESULT Invoke(
179+
[in] ICoreWebView2* sender,
180+
[in] ICoreWebView2WebResourceResponseReceivedEventArgs* args);
181+
}
182+
183+
/// Event args for the WebResourceResponseReceived event.
184+
interface ICoreWebView2WebResourceResponseReceivedEventArgs : IUnknown
185+
{
186+
/// The request object for the web resource, as committed. This includes
187+
/// headers added by the network stack that were not be included during the
188+
/// associated WebResourceRequested event, such as Authentication headers.
189+
/// Modifications to this object have no effect on how the request is
190+
/// processed as it has already been sent.
191+
[propget] HRESULT Request(
192+
[out, retval] ICoreWebView2WebResourceRequest** request);
193+
/// View of the response object received for the web resource.
194+
[propget] HRESULT Response(
195+
[out, retval] ICoreWebView2WebResourceResponseView** response);
196+
}
197+
198+
/// View of the HTTP representation for a web resource response. The properties
199+
/// of this object are not mutable. This response view is used with the
200+
/// WebResourceResponseReceived event.
201+
interface ICoreWebView2WebResourceResponseView : IUnknown
202+
{
203+
/// The HTTP response headers as received.
204+
[propget] HRESULT Headers(
205+
[out, retval] ICoreWebView2HttpResponseHeaders** headers);
206+
/// The HTTP response status code.
207+
[propget] HRESULT StatusCode([out, retval] int* statusCode);
208+
/// The HTTP response reason phrase.
209+
[propget] HRESULT ReasonPhrase([out, retval] LPWSTR* reasonPhrase);
210+
211+
/// Get the response content asynchronously. The handler will receive the
212+
/// the response content stream. Calling this method will return an error
213+
/// HRESULT for redirect responses, as their content (if any) is ignored.
214+
/// If this method is being called again before a first call has completed,
215+
/// the handler will be invoked at the same time the handlers from prior calls
216+
/// are invoked.
217+
/// If this method is being called after a first call has completed, the
218+
/// handler will be invoked immediately.
219+
HRESULT TryGetContent(
220+
[in] ICoreWebView2WebResourceResponseViewTryGetContentCompletedHandler* handler);
221+
}
222+
223+
/// The caller implements this interface to receive the result of the
224+
/// ICoreWebView2WebResourceResponseView::TryGetContent method.
225+
interface ICoreWebView2WebResourceResponseViewTryGetContentCompletedHandler : IUnknown
226+
{
227+
/// Called to provide the implementer with the completion status and result of
228+
/// the corresponding asynchronous method call. A failure errorCode indicates
229+
/// no content was found for the response, or the content failed to load. Null
230+
/// means empty content data.
231+
HRESULT Invoke([in] HRESULT errorCode, [in] IStream* content);
232+
}
184233

185-
/// Event args for the WebResourceResponseReceived event. Will contain the
186-
/// request as it was sent and the response as it was received.
187-
/// Note: To get the response content stream, first call PopulateResponseContent
188-
/// and wait for the async call to complete, otherwise the content stream object
189-
/// returned will be null.
190-
interface ICoreWebView2WebResourceResponseReceivedEventArgs : IUnknown
191-
{
192-
/// Web resource request object. Modifications to this object have no effect
193-
/// on how the request is processed as it has already been sent.
194-
[propget] HRESULT Request([out, retval] ICoreWebView2WebResourceRequest** request);
195-
/// Web resource response object. Modifications to this object have no effect
196-
/// on how the response is processed.
197-
[propget] HRESULT Response([out, retval] ICoreWebView2WebResourceResponse** response);
198-
199-
/// Async method to ensure that the Content property of the response contains the actual response body content.
200-
/// If this method is being called again before a first call has completed, all handlers are invoked at the same time.
201-
/// If this method is being called after a first call has completed, the handler is invoked immediately.
202-
HRESULT PopulateResponseContent(ICoreWebView2WebResourceResponseReceivedEventArgsPopulateResponseContentCompletedHandler* handler);
203-
}
204234
}
205235
```
206236

207237
## WinRT
208238
```c#
209239
namespace Microsoft.Web.WebView2.Core
210240
{
241+
// ...
242+
211243
runtimeclass CoreWebView2
212244
{
213245
// ...
214246
215-
/// WebResourceResponseReceived event is raised after the WebView has received and processed the response for a WebResource request.
216-
/// The event args include the WebResourceRequest as committed and the WebResourceResponse received,
217-
/// including any additional headers added by the network stack that were not be included as part of
218-
/// the associated WebResourceRequested event, such as Authentication headers.
247+
/// WebResourceResponseReceived is raised when the WebView receives the
248+
/// response for a request for a web resource (any URI resolution performed by
249+
/// the WebView; such as HTTP/HTTPS, file and data requests from redirects,
250+
/// navigations, declarations in HTML, implicit favicon lookups, and fetch API
251+
/// usage in the document). The host app can use this event to view the actual
252+
/// request and response for a web resource. There is no guarantee about the
253+
/// order in which the WebView processes the response and the host app's
254+
/// handler runs. The app's handler will not block the WebView from processing
255+
/// the response.
219256
event Windows.Foundation.TypedEventHandler<CoreWebView2, CoreWebView2WebResourceResponseReceivedEventArgs> WebResourceResponseReceived;
220257
}
221258

222259
/// Event args for the WebResourceResponseReceived event.
223-
/// Note: To get the response content stream, first call PopulateResponseContentAsync and
224-
/// wait for the call to complete, otherwise the content stream object returned will be null.
225260
runtimeclass CoreWebView2WebResourceResponseReceivedEventArgs
226261
{
227-
/// Web resource request object.
228-
/// Modifications to this object have no effect on how the request is processed as it has already been sent.
262+
/// The request object for the web resource, as committed. This includes
263+
/// headers added by the network stack that were not be included during the
264+
/// associated WebResourceRequested event, such as Authentication headers.
265+
/// Modifications to this object have no effect on how the request is
266+
/// processed as it has already been sent.
229267
CoreWebView2WebResourceRequest Request { get; };
230-
/// Web resource response object.
231-
/// Modifications to this object have no effect on how the response is processed.
232-
CoreWebView2WebResourceResponse Response { get; };
233-
234-
/// Async method to ensure that the Content property of the response contains the actual response body content.
235-
/// If this method is being called again before a first call has completed, it will complete at the same time all prior calls do.
236-
/// If this method is being called after a first call has completed, it will return immediately (asynchronously).
237-
Windows.Foundation.IAsyncAction PopulateResponseContentAsync();
268+
/// View of the response object received for the web resource.
269+
CoreWebView2WebResourceResponseView Response { get; };
270+
}
271+
272+
/// View of the HTTP representation for a web resource response. The properties
273+
/// of this object are not mutable. This response view is used with the
274+
/// WebResourceResponseReceived event.
275+
runtimeclass CoreWebView2WebResourceResponseView
276+
{
277+
/// The HTTP response headers as received.
278+
CoreWebView2HttpResponseHeaders Headers { get; };
279+
/// The HTTP response status code.
280+
Int32 StatusCode { get; };
281+
/// The HTTP response reason phrase.
282+
String ReasonPhrase { get; };
283+
/// Get the response content stream asynchronously.
284+
/// This method will throw a COM exception if no content was found for the
285+
/// response, or the content failed to load. Note the content (if any) for
286+
/// redirect responses is ignored. A null stream means empty data content.
287+
/// If this method is being called again before a first call has completed,
288+
/// it will complete at the same time all prior calls do.
289+
/// If this method is being called after a first call has completed, it will
290+
/// return immediately (asynchronously).
291+
Windows.Foundation.IAsyncOperation<Windows.Storage.Streams.IRandomAccessStream> TryGetContentAsync();
238292
}
239293
}
240294
```

0 commit comments

Comments
 (0)